aio_write.3p (7064B)
- '\" et
- .TH AIO_WRITE "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_write
- \(em asynchronous write to a file
- .SH SYNOPSIS
- .LP
- .nf
- #include <aio.h>
- .P
- int aio_write(struct aiocb *\fIaiocbp\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIaio_write\fR()
- function shall write \fIaiocbp\fP\->\fIaio_nbytes\fR to the file
- associated with \fIaiocbp\fP\->\fIaio_fildes\fR from the buffer pointed
- to by \fIaiocbp\fP\->\fIaio_buf\fR. The function shall return when
- the write request has been initiated or, at a minimum, queued to the
- file or device.
- .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
- argument 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.
- .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
- If O_APPEND is not set for the file descriptor
- .IR aio_fildes ,
- then the requested operation shall take 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.
- If O_APPEND is set for the file descriptor, or if
- .IR aio_fildes
- is associated with a device that is incapable of seeking, write operations
- append to the file in the same order as the calls were made, except
- under circumstances described in
- .IR "Section 2.8.2" ", " "Asynchronous I/O".
- 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_write\fR().
- .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_write\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_write\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_write\fR(),
- or asynchronously. If any of the conditions below are detected
- synchronously, the
- \fIaio_write\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 shall
- be 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\fR argument is not a valid file
- descriptor open for writing.
- .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_write\fR()
- successfully queues the I/O operation, the return status of the
- asynchronous operation shall be one of the values normally returned
- by the
- \fIwrite\fR()
- function call. If the operation is successfully queued but is
- subsequently canceled or encounters an error, the error status for the
- asynchronous operation contains one of the values normally set by the
- \fIwrite\fR()
- function call, or one of the following:
- .TP
- .BR EBADF
- The \fIaiocbp\fP\->\fIaio_fildes\fR argument is not a valid file
- descriptor open for writing.
- .TP
- .BR EINVAL
- The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would
- be invalid.
- .TP
- .BR ECANCELED
- The requested I/O was canceled before the I/O completed due to an
- explicit
- \fIaio_cancel\fR()
- request.
- .P
- The following condition may be detected synchronously or asynchronously:
- .TP
- .BR EFBIG
- 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
- 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 "Section 2.8.2" ", " "Asynchronous I/O",
- .IR "\fIaio_cancel\fR\^(\|)",
- .IR "\fIaio_error\fR\^(\|)",
- .IR "\fIaio_read\fR\^(\|)",
- .IR "\fIaio_return\fR\^(\|)",
- .IR "\fIclose\fR\^(\|)",
- .IR "\fIexec\fR\^",
- .IR "\fIexit\fR\^(\|)",
- .IR "\fIfork\fR\^(\|)",
- .IR "\fIlio_listio\fR\^(\|)",
- .IR "\fIlseek\fR\^(\|)",
- .IR "\fIwrite\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 .