Debian Codegraph @

upstream/debian-trixie/man3/aio_write.3

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