1AIO_WRITE(3P)              POSIX Programmer's Manual             AIO_WRITE(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       aio_write — asynchronous write to a file
14

SYNOPSIS

16       #include <aio.h>
17
18       int aio_write(struct aiocb *aiocbp);
19

DESCRIPTION

21       The aio_write() function shall write  aiocbp->aio_nbytes  to  the  file
22       associated  with  aiocbp->aio_fildes  from  the  buffer  pointed  to by
23       aiocbp->aio_buf. The function shall return when the write  request  has
24       been initiated or, at a minimum, queued to the file or device.
25
26       If  prioritized  I/O  is supported for this file, then the asynchronous
27       operation shall be submitted at a priority equal to a  base  scheduling
28       priority  minus  aiocbp->aio_reqprio. If Thread Execution Scheduling is
29       not supported, then the base scheduling priority is that of the calling
30       process;
31       otherwise, the base scheduling priority is that of the calling thread.
32
33       The  aiocbp  argument  may  be  used  as an argument to aio_error() and
34       aio_return() in order to determine the error status and return  status,
35       respectively, of the asynchronous operation while it is proceeding.
36
37       The aiocbp argument points to an aiocb structure. If the buffer pointed
38       to by aiocbp->aio_buf or the control block pointed to by aiocbp becomes
39       an  illegal  address  prior  to  asynchronous  I/O completion, then the
40       behavior is undefined.
41
42       If O_APPEND is not set for the file  descriptor  aio_fildes,  then  the
43       requested  operation  shall  take place at the absolute position in the
44       file as given by aio_offset, as  if  lseek()  were  called  immediately
45       prior  to the operation with an offset equal to aio_offset and a whence
46       equal to SEEK_SET.  If O_APPEND is set for the file descriptor,  or  if
47       aio_fildes  is  associated  with a device that is incapable of seeking,
48       write operations append to the file in the same order as the calls were
49       made,  except under circumstances described in Section 2.8.2, Asynchro‐
50       nous I/O.  After a successful call to enqueue an asynchronous I/O oper‐
51       ation, the value of the file offset for the file is unspecified.
52
53       The  aio_sigevent  member  specifies the notification which occurs when
54       the request is completed.
55
56       The aiocbp->aio_lio_opcode field shall be ignored by aio_write().
57
58       Simultaneous asynchronous operations  using  the  same  aiocbp  produce
59       undefined results.
60
61       If   synchronized   I/O   is   enabled  on  the  file  associated  with
62       aiocbp->aio_fildes, the behavior of this function shall be according to
63       the definitions of synchronized I/O data integrity completion, and syn‐
64       chronized I/O file integrity completion.
65
66       For any system action that changes the process memory  space  while  an
67       asynchronous I/O is outstanding to the address range being changed, the
68       result of that action is undefined.
69
70       For regular files, no data transfer shall occur past the offset maximum
71       established    in   the   open   file   description   associated   with
72       aiocbp->aio_fildes.
73

RETURN VALUE

75       The aio_write() function shall return the value zero if the I/O  opera‐
76       tion  is  successfully queued; otherwise, the function shall return the
77       value −1 and set errno to indicate the error.
78

ERRORS

80       The aio_write() function shall fail if:
81
82       EAGAIN The requested asynchronous I/O operation was not queued  due  to
83              system resource limitations.
84
85       Each  of  the following conditions may be detected synchronously at the
86       time of the call to aio_write(), or asynchronously. If any of the  con‐
87       ditions  below  are  detected  synchronously,  the aio_write() function
88       shall return −1 and set errno to the corresponding value. If any of the
89       conditions  below are detected asynchronously, the return status of the
90       asynchronous operation shall be set to −1, and the error status of  the
91       asynchronous operation is set to the corresponding value.
92
93       EBADF  The  aiocbp->aio_fildes  argument is not a valid file descriptor
94              open for writing.
95
96       EINVAL The file offset value implied  by  aiocbp->aio_offset  would  be
97              invalid,
98              aiocbp->aio_reqprio  is not a valid value, or aiocbp->aio_nbytes
99              is an invalid value.
100
101       In the case that the aio_write() successfully queues the I/O operation,
102       the  return  status  of  the asynchronous operation shall be one of the
103       values normally returned by the write() function call. If the operation
104       is  successfully  queued  but is subsequently canceled or encounters an
105       error, the error status for the asynchronous operation contains one  of
106       the  values  normally  set  by the write() function call, or one of the
107       following:
108
109       EBADF  The aiocbp->aio_fildes argument is not a valid  file  descriptor
110              open for writing.
111
112       EINVAL The  file  offset  value  implied by aiocbp->aio_offset would be
113              invalid.
114
115       ECANCELED
116              The requested I/O was canceled before the I/O completed  due  to
117              an explicit aio_cancel() request.
118
119       The   following  condition  may  be  detected  synchronously  or  asyn‐
120       chronously:
121
122       EFBIG  The file is a regular file, aiobcp->aio_nbytes is  greater  than
123              0, and the starting offset in aiobcp->aio_offset is at or beyond
124              the offset maximum in the open file description associated  with
125              aiocbp->aio_fildes.
126
127       The following sections are informative.
128

EXAMPLES

130       None.
131

APPLICATION USAGE

133       None.
134

RATIONALE

136       None.
137

FUTURE DIRECTIONS

139       None.
140

SEE ALSO

142       Section 2.8.2, Asynchronous I/O, aio_cancel(), aio_error(), aio_read(),
143       aio_return(), close(), exec,  exit(),  fork(),  lio_listio(),  lseek(),
144       write()
145
146       The Base Definitions volume of POSIX.1‐2008, <aio.h>
147
149       Portions  of  this text are reprinted and reproduced in electronic form
150       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
151       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
152       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
153       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
154       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
155       event of any discrepancy between this version and the original IEEE and
156       The Open Group Standard, the original IEEE and The Open Group  Standard
157       is  the  referee document. The original Standard can be obtained online
158       at http://www.unix.org/online.html .
159
160       Any typographical or formatting errors that appear  in  this  page  are
161       most likely to have been introduced during the conversion of the source
162       files to man page format. To report such errors,  see  https://www.ker
163       nel.org/doc/man-pages/reporting_bugs.html .
164
165
166
167IEEE/The Open Group                  2013                        AIO_WRITE(3P)
Impressum