]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
3 | .\" This is free documentation; you can redistribute it and/or | |
4 | .\" modify it under the terms of the GNU General Public License as | |
5 | .\" published by the Free Software Foundation; either version 2 of | |
6 | .\" the License, or (at your option) any later version. | |
7 | .\" | |
8 | .\" The GNU General Public License's references to "object code" | |
9 | .\" and "executables" are to be interpreted as the output of any | |
10 | .\" document formatting or typesetting system, including | |
11 | .\" intermediate and printed output. | |
12 | .\" | |
13 | .\" This manual is distributed in the hope that it will be useful, | |
14 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
16 | .\" GNU General Public License for more details. | |
17 | .\" | |
18 | .\" You should have received a copy of the GNU General Public | |
19 | .\" License along with this manual; if not, write to the Free | |
20 | .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, | |
21 | .\" USA. | |
22 | .\" | |
25fa6c3d | 23 | .TH AIO_WRITE 3 2010-10-02 "" "Linux Programmer's Manual" |
fea681da MK |
24 | .SH NAME |
25 | aio_write \- asynchronous write | |
26 | .SH SYNOPSIS | |
fea681da MK |
27 | .B "#include <aio.h>" |
28 | .sp | |
29 | .BI "int aio_write(struct aiocb *" aiocbp ); | |
0ad25472 MK |
30 | .sp |
31 | Link with \fI\-lrt\fP. | |
fea681da MK |
32 | .SH DESCRIPTION |
33 | The | |
e511ffb6 | 34 | .BR aio_write () |
fea681da MK |
35 | function requests an asynchronous "n = write(fd, buf, count)" |
36 | with fd, buf, count given by | |
94e9d9fe MK |
37 | .IR aiocbp\->aio_fildes , |
38 | .IR aiocbp\->aio_buf , | |
39 | .IR aiocbp\->aio_nbytes , | |
c13182ef MK |
40 | respectively. |
41 | The return status n can be retrieved upon completion using | |
fea681da MK |
42 | .BR aio_return (3). |
43 | .LP | |
1274071a MK |
44 | If |
45 | .B O_APPEND | |
46 | is not set, the data is written starting at the | |
fea681da | 47 | absolute file offset |
94e9d9fe | 48 | .IR aiocbp\->aio_offset , |
fea681da | 49 | regardless of the current file position. |
1274071a MK |
50 | If |
51 | .B O_APPEND | |
52 | is set, the data is written at the end of the file. | |
fea681da MK |
53 | After this request, the value of the current file position is unspecified. |
54 | .LP | |
55 | The "asynchronous" means that this call returns as soon as the | |
56 | request has been enqueued; the write may or may not have completed | |
c13182ef MK |
57 | when the call returns. |
58 | One tests for completion using | |
fea681da MK |
59 | .BR aio_error (3). |
60 | .LP | |
2f0af33b MK |
61 | If |
62 | .B _POSIX_PRIORITIZED_IO | |
63 | is defined, and this file supports it, | |
fea681da MK |
64 | then the asynchronous operation is submitted at a priority equal |
65 | to that of the calling process minus | |
94e9d9fe | 66 | .IR aiocbp\->aio_reqprio . |
fea681da MK |
67 | .LP |
68 | The field | |
94e9d9fe | 69 | .I aiocbp\->aio_lio_opcode |
fea681da MK |
70 | is ignored. |
71 | .LP | |
72 | No data is written to a regular file beyond its maximum offset. | |
73 | .SH "RETURN VALUE" | |
c13182ef MK |
74 | On success, 0 is returned. |
75 | On error the request is not enqueued, \-1 | |
fea681da MK |
76 | is returned, and |
77 | .I errno | |
c13182ef MK |
78 | is set appropriately. |
79 | If an error is first detected later, it will | |
fea681da MK |
80 | be reported via |
81 | .BR aio_return (3) | |
82 | (returns status \-1) and | |
83 | .BR aio_error (3) | |
84 | (error status whatever one would have gotten in | |
85 | .IR errno , | |
2f0af33b MK |
86 | such as |
87 | .BR EBADF ). | |
fea681da MK |
88 | .SH ERRORS |
89 | .TP | |
90 | .B EAGAIN | |
91 | Out of resources. | |
92 | .TP | |
93 | .B EBADF | |
94 | .I aio_fildes | |
95 | is not a valid file descriptor open for writing. | |
96 | .TP | |
97 | .B EFBIG | |
98 | The file is a regular file, we want to write at least one byte, | |
99 | but the starting position is at or beyond the maximum offset for this file. | |
100 | .TP | |
101 | .B EINVAL | |
102 | One or more of | |
103 | .IR aio_offset , | |
104 | .IR aio_reqprio , | |
0daa9e92 | 105 | .I aio_nbytes |
fea681da MK |
106 | are invalid. |
107 | .TP | |
108 | .B ENOSYS | |
109 | This function is not supported. | |
793514ae MK |
110 | .SH VERSIONS |
111 | The | |
112 | .BR aio_write () | |
113 | function is available since glibc 2.1. | |
2b2581ee | 114 | .SH "CONFORMING TO" |
793514ae | 115 | POSIX.1-2001, POSIX.1-2008. |
fea681da MK |
116 | .SH NOTES |
117 | It is a good idea to zero out the control block before use. | |
118 | This control block must not be changed while the write operation | |
119 | is in progress. | |
120 | The buffer area being written out | |
121 | .\" or the control block of the operation | |
122 | must not be accessed during the operation or undefined results may | |
c13182ef MK |
123 | occur. |
124 | The memory areas involved must remain valid. | |
fea681da MK |
125 | .SH "SEE ALSO" |
126 | .BR aio_cancel (3), | |
127 | .BR aio_error (3), | |
128 | .BR aio_fsync (3), | |
129 | .BR aio_read (3), | |
130 | .BR aio_return (3), | |
25fa6c3d MK |
131 | .BR aio_suspend (3), |
132 | .BR aio (7) |