mirror of https://github.com/mkerrisk/man-pages
167 lines
6.1 KiB
Plaintext
167 lines
6.1 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "AIO_WRITE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" aio_write
|
||
|
.SH NAME
|
||
|
aio_write \- asynchronous write to a file (\fBREALTIME\fP)
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <aio.h>
|
||
|
.br
|
||
|
.sp
|
||
|
int aio_write(struct aiocb *\fP\fIaiocbp\fP\fB); \fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIaio_write\fP() function shall write \fIaiocbp\fP->\fIaio_nbytes\fP
|
||
|
to the file associated with
|
||
|
\fIaiocbp\fP->\fIaio_fildes\fP from the buffer pointed to by \fIaiocbp\fP->\fIaio_buf\fP.
|
||
|
The function shall return when
|
||
|
the write request has been initiated or, at a minimum, queued to the
|
||
|
file or device.
|
||
|
.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 argument 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.
|
||
|
.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
|
||
|
If O_APPEND is not set for the file descriptor \fIaio_fildes\fP, then
|
||
|
the requested operation shall take 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. If
|
||
|
O_APPEND is set for the file descriptor, write operations append to
|
||
|
the file in the same order as the calls were made. 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_write\fP().
|
||
|
.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_write\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_write\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_write\fP(), or asynchronously.
|
||
|
If any of the conditions below are detected synchronously, the \fIaio_write\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 shall be 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 writing.
|
||
|
.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_write\fP() successfully queues the I/O
|
||
|
operation, the return status of the asynchronous operation
|
||
|
shall be one of the values normally returned by the \fIwrite\fP()
|
||
|
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\fP()
|
||
|
function call, or one
|
||
|
of the following:
|
||
|
.TP 7
|
||
|
.B EBADF
|
||
|
The \fIaiocbp\fP->\fIaio_fildes\fP argument is not a valid file descriptor
|
||
|
open for writing.
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The file offset value implied by \fIaiocbp\fP->\fIaio_offset\fP would
|
||
|
be invalid.
|
||
|
.TP 7
|
||
|
.B ECANCELED
|
||
|
The requested I/O was canceled before the I/O completed due to an
|
||
|
explicit \fIaio_cancel\fP() request.
|
||
|
.sp
|
||
|
.LP
|
||
|
The following condition may be detected synchronously or asynchronously:
|
||
|
.TP 7
|
||
|
.B EFBIG
|
||
|
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 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_write\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() , \fIaio_read\fP() , \fIaio_return\fP()
|
||
|
, \fIclose\fP()
|
||
|
, \fIexec\fP() , \fIexit\fP() , \fIfork\fP() , \fIlio_listio\fP()
|
||
|
, \fIlseek\fP() , \fIwrite\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 .
|