fflistio

Date:: 10-20-2011

NAME

fflistio - Initiates a list of I/O requests using flexible file I/O

SYNOPSIS

#include <sys/types.h>
#include <sys/iosw.h>
#include <sys/listio.h>
#include <ffio.h>

int fflistio (int cmd, struct fflistreq *list, int nent
[, struct ffstat *stat]);

IMPLEMENTATION

Cray Linux Environment (CLE)

DESCRIPTION

The fflistio function provides a way to initiate a list of distinct I/O requests and, optionally, to wait for all of them to complete. Each I/O request in the list provides for maximum control over the desired I/O characteristics. As much as possible, the operation of this function is the same as the listio system call. The purpose of this function is to provide the functionality of listio(2) combined with the facilities provided by flexible file I/O (FFIO).

Arguments to fflistio are as follows:

cmd

Any of the following commands:

LC_START: Initiates the I/O requests and returns control as soon as possible.
LC_WAIT: Initiates the I/O requests and returns when all requests have been completed.

list

Pointer to an array of fflistreq structures.

nent

The number of requests in the list to process.

The fflistreq structure includes the following members:

int li_opcode: Operation code for the request: LO_READ for read and LO_WRITE for write.
unsigned li_drvr:32: Driver dependent; not used.
unsigned li_flags:32: Special request flags: LF_LSEEK to set initial file offset to li_offset.
long li_offset: Initial file byte offset, if LF_LSEEK is set in flags.
int li_fildes: fdinfo pointer, obtained from ffopen(3c) or ffopens(3c).
char *li_buf: Pointer to an I/O data buffer in memory.
unsigned li_nbyte: Number of bytes to read or write for each stride.
struct ffsw *li_status: Pointer to an I/O status structure where the FFIO functions will put completion status for this request. See fffcntl(3c).
int li_signo: This value must be zero. Signals are not supported.
int li_nstride: Number of strides; defaults to 1.
long li_filstride: File stride in bytes; default is for contiguous data flow to/from the file.
long li_memstride: Memory stride in bytes; default is for contiguous data flow to/from the memory buffer.

When reading or writing an n-dimensional array on a disk, the desired data I/O occurs at regular intervals, but it may not be contiguous. The last three variables in the fflistreq structure can be used to specify a compound request, causing multiple sections of data to be transferred. The distance from the start of one section of data on disk to the start of the next section is called the file stride. There is an analogous stride through memory.

The operation of the stride parameters are the same as listio(2). See listio(2) for more information on the details of operation.

When a particular request is complete, the associated ffsw structure is filled in whenever an fffcntl function is given an opportunity with an FC_RECALL or FC_ASPOLL function code. In the ffsw structure, sw_stat is set to a non-zero value upon completion, sw_error may contain a system or library error number, and sw_count contains the number of bytes actually moved. For a successful compound request, sw_count would be li_nstride * li_nbyte.

If one or more of the I/O requests are ill-formed and cannot be started, an LC_WAIT type command returns immediately.

RETURN VALUES

If fflistio completes successfully, a nonnegative integer is returned, indicating the number of requests that were successfully started. Otherwise, a value of -1 is returned, and errno is set to indicate the error.

Errors

The fflistio system call fails on a variety of conditions including the set of errors returned by listio(2) and those returned by the FFIO functions.

EXAMPLES

The following example shows how to use the fflistio system call to initiate a list of input requests. The fflistio request reads every tenth block (that is, blocks 1, 11, 21, 31, and so on) from file datafile. fffcntl(3c) is used to determine when the request is complete.

The request is initiated asynchronously (LC_START), and the data is stored in the buffer buf contiguously. Since input is performed asynchronously, the program can complete other work in parallel with the request.

#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <sys/types.h>
#include <signal.h>
#include <sys/iosw.h>
#include <sys/listio.h>
#inlcude <ffio>

#define BLK_SIZ 4096
struct blk {
     char    blk_data[BLK_SIZ];
};

main()
{
    struct fflistreq request;
    struct ffsw reqstat, dumstat;
    struct blk buf[10];
    int fd;

    if ((fd = ffopen("datafile", O_RDONLY)) == -1) {
         perror("open (datafile) failed");
         exit(1);
    }
    memset (&reqstat, 0, sizeof(reqstat));
    memset (&reqstat, 0, sizeof (request));

    /* Set up the I/O request */
    request.li_opcode = LO_READ;          /*request read*/
    request.li_fildes = fd;               /*file descriptor*/
    request.li_buf = (char *) buf;        /*store input data here*/
    request.li_nbyte = BLK_SIZ;           /*each stride = 1 block*/
    request.li_status = &reqstat          /*status for this request*/
    request.li_signo = 0;                 /*do not send signal upon completion*/
    request.li_nstride = 10;              /*read 10 strides*/
    request.li_memstride = 0;             /*default (contiguous) memstride*/
    request.li_filstride = 10 * BLK_SIZ;  /*file stride=10 blocks*/

    if (fflistio(LC_START, &reqstat, 1) != 1) {
         perror("fflistio failed");
         exit(1);
    }

    /* other work can be performed here while fflistio request completes */

    fffcntl(fd, FC_RECALL, &reqstat, &dumstat); /* waits for I/O completion */

    printf("Number of bytes read = %d\n\n", reqstat.sw_count);
}