Debian Codegraph @

upstream/debian-unstable/man3/aio_write.3

raw
1 '\" t
2 .\" Copyright 2003, Andries E. Brouwer <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH aio_write 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 aio_write \- asynchronous write
10 .SH LIBRARY
11 Real-time library
12 .RI ( librt ,\~ \-lrt )
13 .SH SYNOPSIS
14 .nf
15 .B "#include <aio.h>"
16 .P
17 .BI "int aio_write(struct aiocb *" aiocbp );
18 .fi
19 .SH DESCRIPTION
20 The
21 .BR aio_write ()
22 function queues the I/O request described by the buffer pointed to by
23 .IR aiocbp .
24 This function is the asynchronous analog of
25 .BR write (2).
26 The arguments of the call
27 .P
28 .in +4n
29 .EX
30 write(fd, buf, count)
31 .EE
32 .in
33 .P
34 correspond (in order) to the fields
35 .IR aio_fildes ,
36 .IR aio_buf ,
37 and
38 .I aio_nbytes
39 of the structure pointed to by
40 .IR aiocbp .
41 (See
42 .BR aio (7)
43 for a description of the
44 .I aiocb
45 structure.)
46 .P
47 If
48 .B O_APPEND
49 is not set, the data is written starting at the
50 absolute position
51 .IR aiocbp\->aio_offset ,
52 regardless of the file offset.
53 If
54 .B O_APPEND
55 is set, data is written at the end of the file in the same order as
56 .BR aio_write ()
57 calls are made.
58 After the call, the value of the file offset is unspecified.
59 .P
60 The "asynchronous" means that this call
61 returns as soon as the
62 request has been enqueued;
63 the write may or may not have completed
64 when the call returns.
65 One tests for completion using
66 .BR aio_error (3).
67 The return status of a completed I/O operation can be obtained
68 .BR aio_return (3).
69 Asynchronous notification of I/O completion can be obtained by setting
70 .I aiocbp\->aio_sigevent
71 appropriately;
72 see
73 .BR sigevent (3type)
74 for details.
75 .P
76 If
77 .B _POSIX_PRIORITIZED_IO
78 is defined, and this file supports it,
79 then the asynchronous operation is submitted at a priority equal
80 to that of the calling process minus
81 .IR aiocbp\->aio_reqprio .
82 .P
83 The field
84 .I aiocbp\->aio_lio_opcode
85 is ignored.
86 .P
87 No data is written to a regular file beyond its maximum offset.
88 .SH RETURN VALUE
89 On success, 0 is returned.
90 On error, the request is not enqueued, \-1
91 is returned, and
92 .I errno
93 is set to indicate the error.
94 If an error is detected only later, it will
95 be reported via
96 .BR aio_return (3)
97 (returns status \-1) and
98 .BR aio_error (3)
99 (error status\[em]whatever one would have gotten in
100 .IR errno ,
101 such as
102 .BR EBADF ).
103 .SH ERRORS
104 .TP
105 .B EAGAIN
106 Out of resources.
107 .TP
108 .B EBADF
109 .I aio_fildes
110 is not a valid file descriptor open for writing.
111 .TP
112 .B EFBIG
113 The file is a regular file, we want to write at least one byte,
114 but the starting position is at or beyond the maximum offset for this file.
115 .TP
116 .B EINVAL
117 One or more of
118 .IR aio_offset ,
119 .IR aio_reqprio ,
120 .I aio_nbytes
121 are invalid.
122 .TP
123 .B ENOSYS
124 .BR aio_write ()
125 is not implemented.
126 .SH ATTRIBUTES
127 For an explanation of the terms used in this section, see
128 .BR attributes (7).
129 .TS
130 allbox;
131 lbx lb lb
132 l l l.
133 Interface Attribute Value
134 T{
135 .na
136 .nh
137 .BR aio_write ()
138 T} Thread safety MT-Safe
139 .TE
140 .SH STANDARDS
141 POSIX.1-2008.
142 .SH HISTORY
143 glibc 2.1.
144 POSIX.1-2001.
145 .SH NOTES
146 It is a good idea to zero out the control block before use.
147 The control block must not be changed while the write operation
148 is in progress.
149 The buffer area being written out
150 .\" or the control block of the operation
151 must not be accessed during the operation or undefined results may occur.
152 The memory areas involved must remain valid.
153 .P
154 Simultaneous I/O operations specifying the same
155 .I aiocb
156 structure produce undefined results.
157 .SH SEE ALSO
158 .BR aio_cancel (3),
159 .BR aio_error (3),
160 .BR aio_fsync (3),
161 .BR aio_read (3),
162 .BR aio_return (3),
163 .BR aio_suspend (3),
164 .BR lio_listio (3),
165 .BR aio (7)