]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
1dd72f9c | 3 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
4 | .\" This is free documentation; you can redistribute it and/or |
5 | .\" modify it under the terms of the GNU General Public License as | |
6 | .\" published by the Free Software Foundation; either version 2 of | |
7 | .\" the License, or (at your option) any later version. | |
8 | .\" | |
9 | .\" The GNU General Public License's references to "object code" | |
10 | .\" and "executables" are to be interpreted as the output of any | |
11 | .\" document formatting or typesetting system, including | |
12 | .\" intermediate and printed output. | |
13 | .\" | |
14 | .\" This manual is distributed in the hope that it will be useful, | |
15 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 | .\" GNU General Public License for more details. | |
18 | .\" | |
19 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
20 | .\" License along with this manual; if not, see |
21 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 22 | .\" %%%LICENSE_END |
fea681da | 23 | .\" |
4b8c67d9 | 24 | .TH AIO_READ 3 2017-09-15 "" "Linux Programmer's Manual" |
fea681da MK |
25 | .SH NAME |
26 | aio_read \- asynchronous read | |
27 | .SH SYNOPSIS | |
fea681da | 28 | .B "#include <aio.h>" |
68e4db0a | 29 | .PP |
fea681da | 30 | .BI "int aio_read(struct aiocb *" aiocbp ); |
68e4db0a | 31 | .PP |
0ad25472 | 32 | Link with \fI\-lrt\fP. |
fea681da MK |
33 | .SH DESCRIPTION |
34 | The | |
e511ffb6 | 35 | .BR aio_read () |
37bf1879 MK |
36 | function queues the I/O request described by the buffer pointed to by |
37 | .IR aiocbp . | |
38 | This function is the asynchronous analog of | |
39 | .BR read (2). | |
40 | The arguments of the call | |
847e0d88 | 41 | .PP |
37bf1879 | 42 | read(fd, buf, count) |
847e0d88 | 43 | .PP |
37bf1879 MK |
44 | correspond (in order) to the fields |
45 | .IR aio_fildes , | |
46 | .IR aio_buf , | |
47 | and | |
48 | .IR aio_nbytes | |
49 | of the structure pointed to by | |
50 | .IR aiocbp . | |
2b014d76 MK |
51 | (See |
52 | .BR aio (7) | |
53 | for a description of the | |
54 | .I aiocb | |
55 | structure.) | |
dd3568a1 | 56 | .PP |
c72249c5 | 57 | The data is read starting at the absolute position |
94e9d9fe | 58 | .IR aiocbp\->aio_offset , |
c72249c5 | 59 | regardless of the file offset. |
37bf1879 | 60 | After the call, |
c72249c5 | 61 | the value of the file offset is unspecified. |
dd3568a1 | 62 | .PP |
fea681da MK |
63 | The "asynchronous" means that this call returns as soon as the |
64 | request has been enqueued; the read may or may not have completed | |
c13182ef MK |
65 | when the call returns. |
66 | One tests for completion using | |
fea681da | 67 | .BR aio_error (3). |
609b89e9 | 68 | The return status of a completed I/O operation can be obtained by |
37bf1879 | 69 | .BR aio_return (3). |
8053c116 MK |
70 | Asynchronous notification of I/O completion can be obtained by setting |
71 | .IR aiocbp\->aio_sigevent | |
72 | appropriately; see | |
73 | .BR sigevent (7) | |
74 | for details. | |
dd3568a1 | 75 | .PP |
2f0af33b MK |
76 | If |
77 | .B _POSIX_PRIORITIZED_IO | |
78 | is defined, and this file supports it, | |
fea681da MK |
79 | then the asynchronous operation is submitted at a priority equal |
80 | to that of the calling process minus | |
94e9d9fe | 81 | .IR aiocbp\->aio_reqprio . |
dd3568a1 | 82 | .PP |
fea681da | 83 | The field |
94e9d9fe | 84 | .I aiocbp\->aio_lio_opcode |
fea681da | 85 | is ignored. |
dd3568a1 | 86 | .PP |
fea681da | 87 | No data is read from a regular file beyond its maximum offset. |
47297adb | 88 | .SH RETURN VALUE |
c13182ef | 89 | On success, 0 is returned. |
dec985f9 | 90 | On error, the request is not enqueued, \-1 |
fea681da MK |
91 | is returned, and |
92 | .I errno | |
c13182ef | 93 | is set appropriately. |
33a0ccb2 | 94 | If an error is detected only later, it will |
fea681da MK |
95 | be reported via |
96 | .BR aio_return (3) | |
97 | (returns status \-1) and | |
98 | .BR aio_error (3) | |
3696a917 | 99 | (error status\(emwhatever one would have gotten in |
fea681da | 100 | .IR errno , |
2f0af33b MK |
101 | such as |
102 | .BR EBADF ). | |
fea681da MK |
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 reading. | |
111 | .TP | |
112 | .B EINVAL | |
113 | One or more of | |
114 | .IR aio_offset , | |
115 | .IR aio_reqprio , | |
37bf1879 | 116 | or |
0daa9e92 | 117 | .I aio_nbytes |
fea681da MK |
118 | are invalid. |
119 | .TP | |
120 | .B ENOSYS | |
aea038d6 MK |
121 | .BR aio_read () |
122 | is not implemented. | |
fea681da MK |
123 | .TP |
124 | .B EOVERFLOW | |
125 | The file is a regular file, we start reading before end-of-file | |
126 | and want at least one byte, but the starting position is past | |
127 | the maximum offset for this file. | |
37bf1879 | 128 | .SH VERSIONS |
793514ae MK |
129 | The |
130 | .BR aio_read () | |
131 | function is available since glibc 2.1. | |
8e8637d7 MS |
132 | .SH ATTRIBUTES |
133 | For an explanation of the terms used in this section, see | |
134 | .BR attributes (7). | |
135 | .TS | |
136 | allbox; | |
137 | lb lb lb | |
138 | l l l. | |
139 | Interface Attribute Value | |
140 | T{ | |
141 | .BR aio_read () | |
142 | T} Thread safety MT-Safe | |
143 | .TE | |
47297adb | 144 | .SH CONFORMING TO |
793514ae | 145 | POSIX.1-2001, POSIX.1-2008. |
fea681da MK |
146 | .SH NOTES |
147 | It is a good idea to zero out the control block before use. | |
37bf1879 | 148 | The control block must not be changed while the read operation |
fea681da MK |
149 | is in progress. |
150 | The buffer area being read into | |
151 | .\" or the control block of the operation | |
37bf1879 | 152 | must not be accessed during the operation or undefined results may occur. |
c13182ef | 153 | The memory areas involved must remain valid. |
847e0d88 | 154 | .PP |
37bf1879 MK |
155 | Simultaneous I/O operations specifying the same |
156 | .I aiocb | |
157 | structure produce undefined results. | |
b44bee16 MK |
158 | .SH EXAMPLE |
159 | See | |
160 | .BR aio (7). | |
47297adb | 161 | .SH SEE ALSO |
fea681da MK |
162 | .BR aio_cancel (3), |
163 | .BR aio_error (3), | |
164 | .BR aio_fsync (3), | |
165 | .BR aio_return (3), | |
166 | .BR aio_suspend (3), | |
25fa6c3d | 167 | .BR aio_write (3), |
cd587df6 | 168 | .BR lio_listio (3), |
25fa6c3d | 169 | .BR aio (7) |