diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/aio_read.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/aio_read.3p | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/aio_read.3p b/man-pages-posix-2017/man3p/aio_read.3p new file mode 100644 index 0000000..37b034b --- /dev/null +++ b/man-pages-posix-2017/man3p/aio_read.3p @@ -0,0 +1,210 @@ +'\" et +.TH AIO_READ "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 +aio_read +\(em asynchronous read from a file +.SH SYNOPSIS +.LP +.nf +#include <aio.h> +.P +int aio_read(struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_read\fR() +function shall read \fIaiocbp\fP\->\fIaio_nbytes\fR from the file +associated with \fIaiocbp\fP\->\fIaio_fildes\fR into the buffer pointed +to by \fIaiocbp\fP\->\fIaio_buf\fR. 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). +.P +If prioritized I/O is supported for this file, then the asynchronous +operation shall be submitted at a priority equal to a base scheduling +priority minus \fIaiocbp\fP\->\fIaio_reqprio\fR. If Thread Execution +Scheduling is not supported, then the base scheduling priority is that +of the calling process; +.br +otherwise, the base scheduling priority is that of the calling thread. +.P +The +.IR aiocbp +value may be used as an argument to +\fIaio_error\fR() +and +\fIaio_return\fR() +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 +.IR aio_offset , +as if +\fIlseek\fR() +were called immediately prior to the operation with an +.IR offset +equal to +.IR aio_offset +and a +.IR whence +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. +.P +The +.IR aio_sigevent +member specifies the notification which occurs when the request is +completed. +.P +The \fIaiocbp\fP\->\fIaio_lio_opcode\fR field shall be ignored by +\fIaio_read\fR(). +.P +The +.IR aiocbp +argument points to an +.BR aiocb +structure. If the buffer pointed to by \fIaiocbp\fP\->\fIaio_buf\fR or +the control block pointed to by +.IR aiocbp +becomes an illegal address prior to asynchronous I/O completion, then +the behavior is undefined. +.P +Simultaneous asynchronous operations using the same +.IR aiocbp +produce undefined results. +.P +If synchronized I/O is enabled on the file associated with +\fIaiocbp\fP\->\fIaio_fildes\fR, 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. +.P +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. +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fP\->\fIaio_fildes\fR. +.SH "RETURN VALUE" +The +\fIaio_read\fR() +function shall return the value zero if the I/O operation is +successfully queued; otherwise, the function shall return the value +\-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_read\fR() +function shall fail if: +.TP +.BR EAGAIN +The requested asynchronous I/O operation was not queued due to system +resource limitations. +.P +Each of the following conditions may be detected synchronously at the +time of the call to +\fIaio_read\fR(), +or asynchronously. If any of the conditions below are detected +synchronously, the +\fIaio_read\fR() +function shall return \-1 and set +.IR errno +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 +.BR EBADF +The \fIaiocbp\fP\->\fIaio_fildes\fP argument is not a valid file +descriptor open for reading. +.TP +.BR EINVAL +The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would +be invalid, +.br +\fIaiocbp\fP\->\fIaio_reqprio\fR is not a valid value, +or \fIaiocbp\fP\->\fIaio_nbytes\fR is an invalid value. +.P +In the case that the +\fIaio_read\fR() +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\fR() +function call. In addition, the error status of the asynchronous +operation is set to one of the error statuses normally set by the +\fIread\fR() +function call, or one of the following values: +.TP +.BR EBADF +The \fIaiocbp\fP\->\fIaio_fildes\fR argument is not a valid file +descriptor open for reading. +.TP +.BR ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit +\fIaio_cancel\fR() +request. +.TP +.BR EINVAL +The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would +be invalid. +.P +The following condition may be detected synchronously or asynchronously: +.TP +.BR EOVERFLOW +The file is a regular file, \fIaiobcp\fP\->\fIaio_nbytes\fR is greater +than 0, and the starting offset in \fIaiobcp\fP\->\fIaio_offset\fR 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\fR. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIaio_write\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 . |