]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
6a8d8745 | 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 | .\" |
aea038d6 | 24 | .TH AIO_READ 3 2012-05-08 "" "Linux Programmer's Manual" |
fea681da MK |
25 | .SH NAME |
26 | aio_read \- asynchronous read | |
27 | .SH SYNOPSIS | |
fea681da MK |
28 | .B "#include <aio.h>" |
29 | .sp | |
30 | .BI "int aio_read(struct aiocb *" aiocbp ); | |
0ad25472 MK |
31 | .sp |
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 | |
41 | ||
42 | read(fd, buf, count) | |
43 | ||
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.) | |
fea681da MK |
56 | .LP |
57 | The data is read starting at the absolute file offset | |
94e9d9fe | 58 | .IR aiocbp\->aio_offset , |
37bf1879 MK |
59 | regardless of the current file offset. |
60 | After the call, | |
61 | the value of the current file offset is unspecified. | |
fea681da MK |
62 | .LP |
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. | |
fea681da | 75 | .LP |
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 . |
fea681da MK |
82 | .LP |
83 | The field | |
94e9d9fe | 84 | .I aiocbp\->aio_lio_opcode |
fea681da MK |
85 | is ignored. |
86 | .LP | |
87 | No data is read from a regular file beyond its maximum offset. | |
47297adb | 88 | .SH RETURN VALUE |
c13182ef MK |
89 | On success, 0 is returned. |
90 | On error the request is not enqueued, \-1 | |
fea681da MK |
91 | is returned, and |
92 | .I errno | |
c13182ef | 93 | is set appropriately. |
37bf1879 | 94 | If an error is only detected 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. | |
47297adb | 132 | .SH CONFORMING TO |
793514ae | 133 | POSIX.1-2001, POSIX.1-2008. |
fea681da MK |
134 | .SH NOTES |
135 | It is a good idea to zero out the control block before use. | |
37bf1879 | 136 | The control block must not be changed while the read operation |
fea681da MK |
137 | is in progress. |
138 | The buffer area being read into | |
139 | .\" or the control block of the operation | |
37bf1879 | 140 | must not be accessed during the operation or undefined results may occur. |
c13182ef | 141 | The memory areas involved must remain valid. |
37bf1879 MK |
142 | |
143 | Simultaneous I/O operations specifying the same | |
144 | .I aiocb | |
145 | structure produce undefined results. | |
b44bee16 MK |
146 | .SH EXAMPLE |
147 | See | |
148 | .BR aio (7). | |
47297adb | 149 | .SH SEE ALSO |
fea681da MK |
150 | .BR aio_cancel (3), |
151 | .BR aio_error (3), | |
152 | .BR aio_fsync (3), | |
153 | .BR aio_return (3), | |
154 | .BR aio_suspend (3), | |
25fa6c3d | 155 | .BR aio_write (3), |
cd587df6 | 156 | .BR lio_listio (3), |
25fa6c3d | 157 | .BR aio (7) |