diff options
Diffstat (limited to 'upstream/archlinux/man3p/lio_listio.3p')
| -rw-r--r-- | upstream/archlinux/man3p/lio_listio.3p | 356 |
1 files changed, 356 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/lio_listio.3p b/upstream/archlinux/man3p/lio_listio.3p new file mode 100644 index 00000000..3621e209 --- /dev/null +++ b/upstream/archlinux/man3p/lio_listio.3p @@ -0,0 +1,356 @@ +'\" et +.TH LIO_LISTIO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lio_listio +\(em list directed I/O +.SH SYNOPSIS +.LP +.nf +#include <aio.h> +.P +int lio_listio(int \fImode\fP, struct aiocb *restrict const \fIlist\fP[restrict], + int \fInent\fP, struct sigevent *restrict \fIsig\fP); +.fi +.SH DESCRIPTION +The +\fIlio_listio\fR() +function shall initiate a list of I/O requests with a single +function call. +.P +The +.IR mode +argument takes one of the values LIO_WAIT or LIO_NOWAIT declared in +.IR <aio.h> +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 +.IR mode +argument is LIO_WAIT, the function shall wait until all I/O is +complete and the +.IR sig +argument shall be ignored. +.P +If the +.IR mode +argument is LIO_NOWAIT, the function shall return immediately, and +asynchronous notification shall occur, according to the +.IR sig +argument, when all the I/O operations complete. If +.IR sig +is NULL, then no asynchronous notification shall occur. If +.IR sig +is not NULL, asynchronous notification occurs as specified in +.IR "Section 2.4.1" ", " "Signal Generation and Delivery" +when all the requests in +.IR list +have completed. +.P +The I/O requests enumerated by +.IR list +are submitted in an unspecified order. +.P +The +.IR list +argument is an array of pointers to +.BR aiocb +structures. The array contains +.IR nent +elements. The array may contain NULL elements, which shall be ignored. +.P +If the buffer pointed to by +.IR list +or the +.BR aiocb +structures pointed to by the elements of the array +.IR list +become illegal addresses before all asynchronous I/O completed and, if +necessary, the notification is sent, then the behavior is undefined. If +the buffers pointed to by the +.IR aio_buf +member of the +.BR aiocb +structure pointed to by the elements of the array +.IR list +become illegal addresses prior to the asynchronous I/O associated with +that +.BR aiocb +structure being completed, the behavior is undefined. +.P +The +.IR aio_lio_opcode +field of each +.BR aiocb +structure specifies the operation to be performed. The supported +operations are LIO_READ, LIO_WRITE, and LIO_NOP; +these symbols are defined in +.IR <aio.h> . +The LIO_NOP operation causes the list entry to be ignored. If the +.IR aio_lio_opcode +element is equal to LIO_READ, then an I/O operation is submitted as if +by a call to +\fIaio_read\fR() +with the +.IR aiocbp +equal to the address of the +.BR aiocb +structure. If the +.IR aio_lio_opcode +element is equal to LIO_WRITE, then an I/O operation is submitted as if +by a call to +\fIaio_write\fR() +with the +.IR aiocbp +equal to the address of the +.BR aiocb +structure. +.P +The +.IR aio_fildes +member specifies the file descriptor on which the operation is to be +performed. +.P +The +.IR aio_buf +member specifies the address of the buffer to or from which the data is +transferred. +.P +The +.IR aio_nbytes +member specifies the number of bytes of data to be transferred. +.P +The members of the +.BR aiocb +structure further describe the I/O operation to be performed, in a +manner identical to that of the corresponding +.BR aiocb +structure when used by the +\fIaio_read\fR() +and +\fIaio_write\fR() +functions. +.P +The +.IR nent +argument specifies how many elements are members of the list; that is, +the length of the array. +.P +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 +.IR aio_fildes . +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fR\->\fIaio_fildes\fR. +.P +If \fIsig\fR\->\fIsigev_notify\fR is SIGEV_THREAD and +\fIsig\fR\->\fIsigev_notify_attributes\fR is a non-null pointer and the +block pointed to by this pointer becomes an illegal address prior to +all asynchronous I/O being completed, then the behavior is undefined. +.SH "RETURN VALUE" +If the +.IR mode +argument has the value LIO_NOWAIT, the +\fIlio_listio\fR() +function shall return the value zero if the I/O operations are +successfully queued; otherwise, the function shall return the value +\-1 and set +.IR errno +to indicate the error. +.P +If the +.IR mode +argument has the value LIO_WAIT, the +\fIlio_listio\fR() +function shall return the value zero when all the indicated I/O has +completed successfully. Otherwise, +\fIlio_listio\fR() +shall return a value of \-1 and set +.IR errno +to indicate the error. +.P +In either case, the return value only indicates the success or failure +of the +\fIlio_listio\fR() +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 +.BR aiocb +control block. The error statuses so returned are identical to those +returned as the result of an +\fIaio_read\fR() +or +\fIaio_write\fR() +function. +.SH ERRORS +The +\fIlio_listio\fR() +function shall fail if: +.TP +.BR EAGAIN +The resources necessary to queue all the I/O requests were not +available. The application may check the error status for each +.BR aiocb +to determine the individual request(s) that failed. +.TP +.BR EAGAIN +The number of entries indicated by +.IR nent +would cause the system-wide limit +{AIO_MAX} +to be exceeded. +.TP +.BR EINVAL +The +.IR mode +argument is not a proper value, or the value of +.IR nent +was greater than +{AIO_LISTIO_MAX}. +.TP +.BR 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\fR() +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 +.BR EIO +One or more of the individual I/O operations failed. The application +may check the error status for each +.BR aiocb +structure to determine the individual request(s) that failed. +.P +In addition to the errors returned by the +\fIlio_listio\fR() +function, if the +\fIlio_listio\fR() +function succeeds or fails with errors of +.BR [EAGAIN] , +.BR [EINTR] , +or +.BR [EIO] , +then some of the I/O specified by the list may have been initiated. If +the +\fIlio_listio\fR() +function fails with an error code other than +.BR [EAGAIN] , +.BR [EINTR] , +or +.BR [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 +.BR aiocb +control block contains the associated error code. The error codes that +can be set are the same as would be set by a +\fIread\fR() +or +\fIwrite\fR() +function, with the following additional error codes possible: +.TP +.BR EAGAIN +The requested I/O operation was not queued due to resource limitations. +.TP +.BR ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit +\fIaio_cancel\fR() +request. +.TP +.BR 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 +.BR EINPROGRESS +The requested I/O is in progress. +.TP +.BR 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. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Although it may appear that there are inconsistencies in the specified +circumstances for error codes, the +.BR [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 +.IR aio_lio_opcode +field is invalid, and +\fIaio_error\fR() +returns +.BR [EINVAL] ) +or might arise from application behavior (for example, the file +descriptor is closed before the operation is initiated, and +\fIaio_error\fR() +returns +.BR [EBADF] ). +.P +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\fR() +is valid for a specific operation. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIread\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<aio.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |