Debian Codegraph @

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