Debian Codegraph @

upstream/debian-unstable/man3/aio_read.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_read 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 aio_read \- asynchronous read
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_read(struct aiocb *" aiocbp );
18 .fi
19 .SH DESCRIPTION
20 The
21 .BR aio_read ()
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 read (2).
26 The arguments of the call
27 .P
28 .in +4n
29 .EX
30 read(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 The data is read starting at the absolute position
48 .IR aiocbp\->aio_offset ,
49 regardless of the file offset.
50 After the call,
51 the value of the file offset is unspecified.
52 .P
53 The "asynchronous" means that this call
54 returns as soon as the
55 request has been enqueued;
56 the read may or may not have completed
57 when the call returns.
58 One tests for completion using
59 .BR aio_error (3).
60 The return status of a completed I/O operation can be obtained by
61 .BR aio_return (3).
62 Asynchronous notification of I/O completion can be obtained by setting
63 .I aiocbp\->aio_sigevent
64 appropriately;
65 see
66 .BR sigevent (3type)
67 for details.
68 .P
69 If
70 .B _POSIX_PRIORITIZED_IO
71 is defined, and this file supports it,
72 then the asynchronous operation is submitted at a priority equal
73 to that of the calling process minus
74 .IR aiocbp\->aio_reqprio .
75 .P
76 The field
77 .I aiocbp\->aio_lio_opcode
78 is ignored.
79 .P
80 No data is read from a regular file beyond its maximum offset.
81 .SH RETURN VALUE
82 On success, 0 is returned.
83 On error, the request is not enqueued, \-1
84 is returned, and
85 .I errno
86 is set to indicate the error.
87 If an error is detected only later, it will
88 be reported via
89 .BR aio_return (3)
90 (returns status \-1) and
91 .BR aio_error (3)
92 (error status\[em]whatever one would have gotten in
93 .IR errno ,
94 such as
95 .BR EBADF ).
96 .SH ERRORS
97 .TP
98 .B EAGAIN
99 Out of resources.
100 .TP
101 .B EBADF
102 .I aio_fildes
103 is not a valid file descriptor open for reading.
104 .TP
105 .B EINVAL
106 One or more of
107 .IR aio_offset ,
108 .IR aio_reqprio ,
109 or
110 .I aio_nbytes
111 are invalid.
112 .TP
113 .B ENOSYS
114 .BR aio_read ()
115 is not implemented.
116 .TP
117 .B EOVERFLOW
118 The file is a regular file, we start reading before end-of-file
119 and want at least one byte, but the starting position is past
120 the maximum offset for this file.
121 .SH ATTRIBUTES
122 For an explanation of the terms used in this section, see
123 .BR attributes (7).
124 .TS
125 allbox;
126 lbx lb lb
127 l l l.
128 Interface Attribute Value
129 T{
130 .na
131 .nh
132 .BR aio_read ()
133 T} Thread safety MT-Safe
134 .TE
135 .SH STANDARDS
136 POSIX.1-2008.
137 .SH HISTORY
138 glibc 2.1.
139 POSIX.1-2001.
140 .SH NOTES
141 It is a good idea to zero out the control block before use.
142 The control block must not be changed while the read operation
143 is in progress.
144 The buffer area being read into
145 .\" or the control block of the operation
146 must not be accessed during the operation or undefined results may occur.
147 The memory areas involved must remain valid.
148 .P
149 Simultaneous I/O operations specifying the same
150 .I aiocb
151 structure produce undefined results.
152 .SH EXAMPLES
153 See
154 .BR aio (7).
155 .SH SEE ALSO
156 .BR aio_cancel (3),
157 .BR aio_error (3),
158 .BR aio_fsync (3),
159 .BR aio_return (3),
160 .BR aio_suspend (3),
161 .BR aio_write (3),
162 .BR lio_listio (3),
163 .BR aio (7)