diff options
Diffstat (limited to 'man-pages-posix-2003/man3p/aio_read.3p')
| -rw-r--r-- | man-pages-posix-2003/man3p/aio_read.3p | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/aio_read.3p b/man-pages-posix-2003/man3p/aio_read.3p new file mode 100644 index 0000000..a8a1a2a --- /dev/null +++ b/man-pages-posix-2003/man3p/aio_read.3p @@ -0,0 +1,169 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "AIO_READ" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" aio_read +.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 +aio_read \- asynchronous read from a file (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include <aio.h> +.br +.sp +int aio_read(struct aiocb *\fP\fIaiocbp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIaio_read\fP() function shall read \fIaiocbp\fP->\fIaio_nbytes\fP +from the file associated with +\fIaiocbp\fP->\fIaio_fildes\fP into the buffer pointed to by \fIaiocbp\fP->\fIaio_buf\fP. +The function call shall return +when the read request has been initiated or queued to the file or +device (even when the data cannot be delivered immediately). +.LP +If prioritized I/O is supported for this file, then the asynchronous +operation shall be submitted at a priority equal to the +scheduling priority of the process minus \fIaiocbp\fP->\fIaio_reqprio\fP. +.LP +The \fIaiocbp\fP value may be used as an argument to \fIaio_error\fP() +and \fIaio_return\fP() in order to determine the error status and +return status, respectively, of +the asynchronous operation while it is proceeding. If an error condition +is encountered during queuing, the function call shall +return without having initiated or queued the request. The requested +operation takes place at the absolute position in the file as +given by \fIaio_offset\fP, as if \fIlseek\fP() were called immediately +prior to the +operation with an \fIoffset\fP equal to \fIaio_offset\fP and a \fIwhence\fP +equal to SEEK_SET. After a successful call to +enqueue an asynchronous I/O operation, the value of the file offset +for the file is unspecified. +.LP +The \fIaiocbp\fP->\fIaio_lio_opcode\fP field shall be ignored by \fIaio_read\fP(). +.LP +The \fIaiocbp\fP argument points to an \fBaiocb\fP structure. If the +buffer pointed to by \fIaiocbp\fP->\fIaio_buf\fP or +the control block pointed to by \fIaiocbp\fP becomes an illegal address +prior to asynchronous I/O completion, then the behavior is +undefined. +.LP +Simultaneous asynchronous operations using the same \fIaiocbp\fP produce +undefined results. +.LP +If synchronized I/O is enabled on the file associated with \fIaiocbp\fP->\fIaio_fildes\fP, +the behavior of this function shall +be according to the definitions of synchronized I/O data integrity +completion and synchronized I/O file integrity completion. +.LP +For any system action that changes the process memory space while +an asynchronous I/O is outstanding to the address range being +changed, the result of that action is undefined. +.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 +The \fIaio_read\fP() function shall return the value zero to the calling +process if the I/O operation is successfully queued; +otherwise, the function shall return the value -1 and set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIaio_read\fP() function shall fail if: +.TP 7 +.B EAGAIN +The requested asynchronous I/O operation was not queued due to system +resource limitations. +.sp +.LP +Each of the following conditions may be detected synchronously at +the time of the call to \fIaio_read\fP(), or asynchronously. +If any of the conditions below are detected synchronously, the \fIaio_read\fP() +function shall return -1 and set \fIerrno\fP to +the corresponding value. If any of the conditions below are detected +asynchronously, the return status of the asynchronous +operation is set to -1, and the error status of the asynchronous operation +is set to the corresponding value. +.TP 7 +.B EBADF +The \fIaiocbp\fP->\fIaio_fildes\fP argument is not a valid file descriptor +open for reading. +.TP 7 +.B EINVAL +The file offset value implied by \fIaiocbp\fP->\fIaio_offset\fP would +be invalid, \fIaiocbp\fP->\fIaio_reqprio\fP is +not a valid value, or \fIaiocbp\fP->\fIaio_nbytes\fP is an invalid +value. +.sp +.LP +In the case that the \fIaio_read\fP() successfully queues the I/O +operation but the operation is subsequently canceled or +encounters an error, the return status of the asynchronous operation +is one of the values normally returned by the \fIread\fP() function +call. In addition, the error status of the asynchronous operation +is set to one +of the error statuses normally set by the \fIread\fP() function call, +or one of the following +values: +.TP 7 +.B EBADF +The \fIaiocbp\fP->\fIaio_fildes\fP argument is not a valid file descriptor +open for reading. +.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 EINVAL +The file offset value implied by \fIaiocbp\fP->\fIaio_offset\fP would +be invalid. +.sp +.LP +The following condition may be detected synchronously or asynchronously: +.TP 7 +.B EOVERFLOW +The file is a regular file, \fIaiobcp\fP->\fIaio_nbytes\fP is greater +than 0, and the starting offset in +\fIaiobcp\fP->\fIaio_offset\fP is before the end-of-file and is at +or beyond 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 +The \fIaio_read\fP() function is part of the Asynchronous Input and +Output option and need not be available on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaio_cancel\fP(), \fIaio_error\fP(), \fIlio_listio\fP(), \fIaio_return\fP(), +\fIaio_write\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 . |