diff options
Diffstat (limited to 'man3p/lio_listio.3p')
-rw-r--r-- | man3p/lio_listio.3p | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/man3p/lio_listio.3p b/man3p/lio_listio.3p new file mode 100644 index 000000000..26a9b96b7 --- /dev/null +++ b/man3p/lio_listio.3p @@ -0,0 +1,225 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LIO_LISTIO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lio_listio +.SH NAME +lio_listio \- list directed I/O (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include <aio.h> +.br +.sp +int lio_listio(int\fP \fImode\fP\fB, struct aiocb *restrict const\fP +\fIlist\fP\fB[restrict], +.br +\ \ \ \ \ \ int\fP \fInent\fP\fB, struct sigevent *restrict\fP \fIsig\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIlio_listio\fP() function shall initiate a list of I/O requests +with a single function call. +.LP +The \fImode\fP argument takes one of the values LIO_WAIT or LIO_NOWAIT +declared in \fI<aio.h>\fP and determines whether the function returns +when the I/O operations have been +completed, or as soon as the operations have been queued. If the \fImode\fP +argument is LIO_WAIT, the function shall wait until +all I/O is complete and the \fIsig\fP argument shall be ignored. +.LP +If the \fImode\fP argument is LIO_NOWAIT, the function shall return +immediately, and asynchronous notification shall occur, +according to the \fIsig\fP argument, when all the I/O operations complete. +If \fIsig\fP is NULL, then no asynchronous +notification shall occur. If \fIsig\fP is not NULL, asynchronous notification +occurs as specified in \fISignal Generation and Delivery\fP when all +the requests in \fIlist\fP have +completed. +.LP +The I/O requests enumerated by \fIlist\fP are submitted in an unspecified +order. +.LP +The \fIlist\fP argument is an array of pointers to \fBaiocb\fP structures. +The array contains \fInent\fP elements. The array +may contain NULL elements, which shall be ignored. +.LP +The \fIaio_lio_opcode\fP field of each \fBaiocb\fP structure specifies +the operation to be performed. The supported operations +are LIO_READ, LIO_WRITE, and LIO_NOP; these symbols are defined in +\fI<aio.h>\fP. The +LIO_NOP operation causes the list entry to be ignored. If the \fIaio_lio_opcode\fP +element is equal to LIO_READ, then an I/O +operation is submitted as if by a call to \fIaio_read\fP() with the +\fIaiocbp\fP equal +to the address of the \fBaiocb\fP structure. If the \fIaio_lio_opcode\fP +element is equal to LIO_WRITE, then an I/O operation is +submitted as if by a call to \fIaio_write\fP() with the \fIaiocbp\fP +equal to the +address of the \fBaiocb\fP structure. +.LP +The \fIaio_fildes\fP member specifies the file descriptor on which +the operation is to be performed. +.LP +The \fIaio_buf\fP member specifies the address of the buffer to or +from which the data is transferred. +.LP +The \fIaio_nbytes\fP member specifies the number of bytes of data +to be transferred. +.LP +The members of the \fBaiocb\fP structure further describe the I/O +operation to be performed, in a manner identical to that of +the corresponding \fBaiocb\fP structure when used by the \fIaio_read\fP() +and \fIaio_write\fP() functions. +.LP +The \fInent\fP argument specifies how many elements are members of +the list; that is, the length of the array. +.LP +The behavior of this function is altered according to the definitions +of synchronized I/O data integrity completion and +synchronized I/O file integrity completion if synchronized I/O is +enabled on the file associated with \fIaio_fildes\fP. +.LP +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fP->\fIaio_fildes\fP. +.SH RETURN VALUE +.LP +If the \fImode\fP argument has the value LIO_NOWAIT, the \fIlio_listio\fP() +function shall return the value zero if the I/O +operations are successfully queued; otherwise, the function shall +return the value -1 and set \fIerrno\fP to indicate the +error. +.LP +If the \fImode\fP argument has the value LIO_WAIT, the \fIlio_listio\fP() +function shall return the value zero when all the +indicated I/O has completed successfully. Otherwise, \fIlio_listio\fP() +shall return a value of -1 and set \fIerrno\fP to +indicate the error. +.LP +In either case, the return value only indicates the success or failure +of the \fIlio_listio\fP() call itself, not the status of +the individual I/O requests. In some cases one or more of the I/O +requests contained in the list may fail. Failure of an individual +request does not prevent completion of any other individual request. +To determine the outcome of each I/O request, the application +shall examine the error status associated with each \fBaiocb\fP control +block. The error statuses so returned are identical to +those returned as the result of an \fIaio_read\fP() or \fIaio_write\fP() +function. +.SH ERRORS +.LP +The \fIlio_listio\fP() function shall fail if: +.TP 7 +.B EAGAIN +The resources necessary to queue all the I/O requests were not available. +The application may check the error status for each +\fBaiocb\fP to determine the individual request(s) that failed. +.TP 7 +.B EAGAIN +The number of entries indicated by \fInent\fP would cause the system-wide +limit {AIO_MAX} to be exceeded. +.TP 7 +.B EINVAL +The \fImode\fP argument is not a proper value, or the value of \fInent\fP +was greater than {AIO_LISTIO_MAX}. +.TP 7 +.B EINTR +A signal was delivered while waiting for all I/O requests to complete +during an LIO_WAIT operation. Note that, since each I/O +operation invoked by \fIlio_listio\fP() may possibly provoke a signal +when it completes, this error return may be caused by the +completion of one (or more) of the very I/O operations being awaited. +Outstanding I/O requests are not canceled, and the +application shall examine each list element to determine whether the +request was initiated, canceled, or completed. +.TP 7 +.B EIO +One or more of the individual I/O operations failed. The application +may check the error status for each \fBaiocb\fP structure +to determine the individual request(s) that failed. +.sp +.LP +In addition to the errors returned by the \fIlio_listio\fP() function, +if the \fIlio_listio\fP() function succeeds or fails +with errors of [EAGAIN], [EINTR], or [EIO], then some of the I/O specified +by the list may have been initiated. If the +\fIlio_listio\fP() function fails with an error code other than [EAGAIN], +[EINTR], or [EIO], no operations from the list shall +have been initiated. The I/O operation indicated by each list element +can encounter errors specific to the individual read or write +function being performed. In this event, the error status for each +\fBaiocb\fP control block contains the associated error code. +The error codes that can be set are the same as would be set by a +\fIread\fP() or \fIwrite\fP() function, with the following additional +error codes possible: +.TP 7 +.B EAGAIN +The requested I/O operation was not queued due to resource limitations. +.TP 7 +.B ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit \fIaio_cancel\fP() request. +.TP 7 +.B EFBIG +The \fIaiocbp\fP->\fIaio_lio_opcode\fP is LIO_WRITE, the file is a +regular file, \fIaiocbp\fP->\fIaio_nbytes\fP is +greater than 0, and the \fIaiocbp\fP->\fIaio_offset\fP is greater +than or equal to the offset maximum in the open file +description associated with \fIaiocbp\fP->\fIaio_fildes\fP. +.TP 7 +.B EINPROGRESS +The requested I/O is in progress. +.TP 7 +.B EOVERFLOW +The \fIaiocbp\fP->\fIaio_lio_opcode\fP is LIO_READ, the file is a +regular file, \fIaiocbp\fP->\fIaio_nbytes\fP is +greater than 0, and the \fIaiocbp\fP->\fIaio_offset\fP is before the +end-of-file and is greater than or equal to the offset +maximum in the open file description associated with \fIaiocbp\fP->\fIaio_fildes\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Although it may appear that there are inconsistencies in the specified +circumstances for error codes, the [EIO] error condition +applies when any circumstance relating to an individual operation +makes that operation fail. This might be due to a badly +formulated request (for example, the \fIaio_lio_opcode\fP field is +invalid, and \fIaio_error\fP() returns [EINVAL]) or might arise from +application behavior (for example, the +file descriptor is closed before the operation is initiated, and \fIaio_error\fP() +returns [EBADF]). +.LP +The limitation on the set of error codes returned when operations +from the list shall have been initiated enables applications +to know when operations have been started and whether \fIaio_error\fP() +is valid for a +specific operation. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaio_read\fP() , \fIaio_write\fP() , \fIaio_error\fP() , \fIaio_return\fP() +, \fIaio_cancel\fP() , \fIclose\fP() , \fIexec\fP() , \fIexit\fP() +, \fIfork\fP() , \fIlseek\fP() , \fIread\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI<aio.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |