]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
1dd72f9c | 3 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
4 | .\" This is free documentation; you can redistribute it and/or |
5 | .\" modify it under the terms of the GNU General Public License as | |
6 | .\" published by the Free Software Foundation; either version 2 of | |
7 | .\" the License, or (at your option) any later version. | |
8 | .\" | |
9 | .\" The GNU General Public License's references to "object code" | |
10 | .\" and "executables" are to be interpreted as the output of any | |
11 | .\" document formatting or typesetting system, including | |
12 | .\" intermediate and printed output. | |
13 | .\" | |
14 | .\" This manual is distributed in the hope that it will be useful, | |
15 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 | .\" GNU General Public License for more details. | |
18 | .\" | |
19 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
20 | .\" License along with this manual; if not, see |
21 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 22 | .\" %%%LICENSE_END |
fea681da | 23 | .\" |
4b8c67d9 | 24 | .TH AIO_WRITE 3 2017-09-15 "" "Linux Programmer's Manual" |
fea681da MK |
25 | .SH NAME |
26 | aio_write \- asynchronous write | |
27 | .SH SYNOPSIS | |
fea681da | 28 | .B "#include <aio.h>" |
68e4db0a | 29 | .PP |
fea681da | 30 | .BI "int aio_write(struct aiocb *" aiocbp ); |
68e4db0a | 31 | .PP |
0ad25472 | 32 | Link with \fI\-lrt\fP. |
fea681da MK |
33 | .SH DESCRIPTION |
34 | The | |
e511ffb6 | 35 | .BR aio_write () |
c8cedd7e | 36 | function queues the I/O request described by the buffer pointed to by |
c0a2871b | 37 | .IR aiocbp . |
c8cedd7e MK |
38 | This function is the asynchronous analog of |
39 | .BR write (2). | |
40 | The arguments of the call | |
847e0d88 | 41 | .PP |
c8cedd7e | 42 | write(fd, buf, count) |
847e0d88 | 43 | .PP |
c8cedd7e MK |
44 | correspond (in order) to the fields |
45 | .IR aio_fildes , | |
46 | .IR aio_buf , | |
47 | and | |
48 | .IR aio_nbytes | |
49 | of the structure pointed to by | |
50 | .IR aiocbp . | |
2b014d76 MK |
51 | (See |
52 | .BR aio (7) | |
53 | for a description of the | |
54 | .I aiocb | |
55 | structure.) | |
dd3568a1 | 56 | .PP |
1274071a MK |
57 | If |
58 | .B O_APPEND | |
59 | is not set, the data is written starting at the | |
c72249c5 | 60 | absolute position |
94e9d9fe | 61 | .IR aiocbp\->aio_offset , |
c72249c5 | 62 | regardless of the file offset. |
1274071a MK |
63 | If |
64 | .B O_APPEND | |
c8cedd7e MK |
65 | is set, data is written at the end of the file in the same order as |
66 | .BR aio_write () | |
67 | calls are made. | |
c72249c5 | 68 | After the call, the value of the file offset is unspecified. |
dd3568a1 | 69 | .PP |
fea681da MK |
70 | The "asynchronous" means that this call returns as soon as the |
71 | request has been enqueued; the write may or may not have completed | |
c13182ef MK |
72 | when the call returns. |
73 | One tests for completion using | |
fea681da | 74 | .BR aio_error (3). |
c8cedd7e MK |
75 | The return status of a completed I/O operation can be obtained |
76 | .BR aio_return (3). | |
2c1c3c95 MK |
77 | Asynchronous notification of I/O completion can be obtained by setting |
78 | .IR aiocbp\->aio_sigevent | |
79 | appropriately; see | |
80 | .BR sigevent (7) | |
81 | for details. | |
dd3568a1 | 82 | .PP |
2f0af33b MK |
83 | If |
84 | .B _POSIX_PRIORITIZED_IO | |
85 | is defined, and this file supports it, | |
fea681da MK |
86 | then the asynchronous operation is submitted at a priority equal |
87 | to that of the calling process minus | |
94e9d9fe | 88 | .IR aiocbp\->aio_reqprio . |
dd3568a1 | 89 | .PP |
fea681da | 90 | The field |
94e9d9fe | 91 | .I aiocbp\->aio_lio_opcode |
fea681da | 92 | is ignored. |
dd3568a1 | 93 | .PP |
fea681da | 94 | No data is written to a regular file beyond its maximum offset. |
47297adb | 95 | .SH RETURN VALUE |
c13182ef | 96 | On success, 0 is returned. |
dec985f9 | 97 | On error, the request is not enqueued, \-1 |
fea681da MK |
98 | is returned, and |
99 | .I errno | |
c13182ef | 100 | is set appropriately. |
33a0ccb2 | 101 | If an error is detected only later, it will |
fea681da MK |
102 | be reported via |
103 | .BR aio_return (3) | |
104 | (returns status \-1) and | |
105 | .BR aio_error (3) | |
83f9759d | 106 | (error status\(emwhatever one would have gotten in |
fea681da | 107 | .IR errno , |
2f0af33b MK |
108 | such as |
109 | .BR EBADF ). | |
fea681da MK |
110 | .SH ERRORS |
111 | .TP | |
112 | .B EAGAIN | |
113 | Out of resources. | |
114 | .TP | |
115 | .B EBADF | |
116 | .I aio_fildes | |
117 | is not a valid file descriptor open for writing. | |
118 | .TP | |
119 | .B EFBIG | |
120 | The file is a regular file, we want to write at least one byte, | |
121 | but the starting position is at or beyond the maximum offset for this file. | |
122 | .TP | |
123 | .B EINVAL | |
124 | One or more of | |
125 | .IR aio_offset , | |
126 | .IR aio_reqprio , | |
0daa9e92 | 127 | .I aio_nbytes |
fea681da MK |
128 | are invalid. |
129 | .TP | |
130 | .B ENOSYS | |
aea038d6 MK |
131 | .BR aio_write () |
132 | is not implemented. | |
793514ae MK |
133 | .SH VERSIONS |
134 | The | |
135 | .BR aio_write () | |
136 | function is available since glibc 2.1. | |
7eab2fad MS |
137 | .SH ATTRIBUTES |
138 | For an explanation of the terms used in this section, see | |
139 | .BR attributes (7). | |
140 | .TS | |
141 | allbox; | |
142 | lb lb lb | |
143 | l l l. | |
144 | Interface Attribute Value | |
145 | T{ | |
146 | .BR aio_write () | |
147 | T} Thread safety MT-Safe | |
148 | .TE | |
47297adb | 149 | .SH CONFORMING TO |
793514ae | 150 | POSIX.1-2001, POSIX.1-2008. |
fea681da MK |
151 | .SH NOTES |
152 | It is a good idea to zero out the control block before use. | |
c8cedd7e | 153 | The control block must not be changed while the write operation |
fea681da MK |
154 | is in progress. |
155 | The buffer area being written out | |
156 | .\" or the control block of the operation | |
c8cedd7e | 157 | must not be accessed during the operation or undefined results may occur. |
c13182ef | 158 | The memory areas involved must remain valid. |
847e0d88 | 159 | .PP |
c8cedd7e MK |
160 | Simultaneous I/O operations specifying the same |
161 | .I aiocb | |
162 | structure produce undefined results. | |
47297adb | 163 | .SH SEE ALSO |
fea681da MK |
164 | .BR aio_cancel (3), |
165 | .BR aio_error (3), | |
166 | .BR aio_fsync (3), | |
167 | .BR aio_read (3), | |
168 | .BR aio_return (3), | |
25fa6c3d | 169 | .BR aio_suspend (3), |
cd587df6 | 170 | .BR lio_listio (3), |
25fa6c3d | 171 | .BR aio (7) |