source: trunk/packages/xen-3.1/xen-3.1/tools/libaio/man/aio_read.3 @ 34

Last change on this file since 34 was 34, checked in by hartmans, 18 years ago

Add xen and xen-common

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