aio_read.3p (6839B)
- '\" 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 .