1 | .TH aio_read 3 2002-09-12 "Linux 2.4" Linux AIO" |
---|
2 | .SH NAME |
---|
3 | aio_read \- Initiate an asynchronous read operation |
---|
4 | .SH SYNOPSYS |
---|
5 | .nf |
---|
6 | .B #include <errno.h> |
---|
7 | .sp |
---|
8 | .br |
---|
9 | .B #include <aio.h> |
---|
10 | .sp |
---|
11 | .br |
---|
12 | .BI "int aio_read (struct aiocb *aiocbp)" |
---|
13 | .fi |
---|
14 | .SH DESCRIPTION |
---|
15 | This function initiates an asynchronous read operation. It |
---|
16 | immediately returns after the operation was enqueued or when an |
---|
17 | error was encountered. |
---|
18 | |
---|
19 | The first |
---|
20 | .IR "aiocbp->aio_nbytes" |
---|
21 | bytes of the file for which |
---|
22 | .IR "aiocbp->aio_fildes" |
---|
23 | is a descriptor are written to the buffer |
---|
24 | starting at |
---|
25 | .IR "aiocbp->aio_buf" |
---|
26 | . Reading starts at the absolute |
---|
27 | position |
---|
28 | .IR "aiocbp->aio_offset" |
---|
29 | in the file. |
---|
30 | |
---|
31 | If prioritized I/O is supported by the platform the |
---|
32 | .IR "aiocbp->aio_reqprio" |
---|
33 | value is used to adjust the priority before |
---|
34 | the request is actually enqueued. |
---|
35 | |
---|
36 | The calling process is notified about the termination of the read |
---|
37 | request according to the |
---|
38 | .IR "aiocbp->aio_sigevent" |
---|
39 | value. |
---|
40 | |
---|
41 | .SH "RETURN VALUES" |
---|
42 | When |
---|
43 | .IR "aio_read" |
---|
44 | returns, the return value is zero if no error |
---|
45 | occurred that can be found before the process is enqueued. If such an |
---|
46 | early error is found, the function returns |
---|
47 | .IR -1 |
---|
48 | and sets |
---|
49 | .IR "errno". |
---|
50 | |
---|
51 | .PP |
---|
52 | If |
---|
53 | .IR "aio_read" |
---|
54 | returns zero, the current status of the request |
---|
55 | can be queried using |
---|
56 | .IR "aio_error" |
---|
57 | and |
---|
58 | .IR "aio_return" |
---|
59 | functions. |
---|
60 | As long as the value returned by |
---|
61 | .IR "aio_error" |
---|
62 | is |
---|
63 | .IR "EINPROGRESS" |
---|
64 | the operation has not yet completed. If |
---|
65 | .IR "aio_error" |
---|
66 | returns zero, |
---|
67 | the operation successfully terminated, otherwise the value is to be |
---|
68 | interpreted as an error code. If the function terminated, the result of |
---|
69 | the operation can be obtained using a call to |
---|
70 | .IR "aio_return" |
---|
71 | . The |
---|
72 | returned value is the same as an equivalent call to |
---|
73 | .IR "read" |
---|
74 | would |
---|
75 | have returned. |
---|
76 | When the sources are compiled with |
---|
77 | .IR "_FILE_OFFSET_BITS == 64" |
---|
78 | this |
---|
79 | function is in fact |
---|
80 | .IR "aio_read64" |
---|
81 | since the LFS interface transparently |
---|
82 | replaces the normal implementation. |
---|
83 | |
---|
84 | .SH ERRORS |
---|
85 | In the case of an early error: |
---|
86 | .TP |
---|
87 | .B EAGAIN |
---|
88 | The request was not enqueued due to (temporarily) exceeded resource |
---|
89 | limitations. |
---|
90 | .TP |
---|
91 | .B ENOSYS |
---|
92 | The |
---|
93 | .IR "aio_read" |
---|
94 | function is not implemented. |
---|
95 | .TP |
---|
96 | .B EBADF |
---|
97 | The |
---|
98 | .IR "aiocbp->aio_fildes" |
---|
99 | descriptor is not valid. This condition |
---|
100 | need not be recognized before enqueueing the request and so this error |
---|
101 | might also be signaled asynchronously. |
---|
102 | .TP |
---|
103 | .B EINVAL |
---|
104 | The |
---|
105 | .IR "aiocbp->aio_offset" |
---|
106 | or |
---|
107 | .IR "aiocbp->aio_reqpiro" |
---|
108 | value is |
---|
109 | invalid. This condition need not be recognized before enqueueing the |
---|
110 | request and so this error might also be signaled asynchronously. |
---|
111 | |
---|
112 | .PP |
---|
113 | In the case of a normal return, possible error codes returned by |
---|
114 | .IR "aio_error" |
---|
115 | are: |
---|
116 | .TP |
---|
117 | .B EBADF |
---|
118 | The |
---|
119 | .IR "aiocbp->aio_fildes" |
---|
120 | descriptor is not valid. |
---|
121 | .TP |
---|
122 | .B ECANCELED |
---|
123 | The operation was canceled before the operation was finished |
---|
124 | .TP |
---|
125 | .B EINVAL |
---|
126 | The |
---|
127 | .IR "aiocbp->aio_offset" |
---|
128 | value is invalid. |
---|
129 | .PP |
---|
130 | .SH "SEE ALSO" |
---|
131 | .BR aio(3), |
---|
132 | .BR aio_cancel(3), |
---|
133 | .BR aio_cancel64(3), |
---|
134 | .BR aio_error(3), |
---|
135 | .BR aio_error64(3), |
---|
136 | .BR aio_fsync(3), |
---|
137 | .BR aio_fsync64(3), |
---|
138 | .BR aio_init(3), |
---|
139 | .BR aio_read64(3), |
---|
140 | .BR aio_return(3), |
---|
141 | .BR aio_return64(3), |
---|
142 | .BR aio_suspend(3), |
---|
143 | .BR aio_suspend64(3), |
---|
144 | .BR aio_write(3), |
---|
145 | .BR aio_write64(3), |
---|
146 | .BR errno(3), |
---|