1aio_read(3C)             Standard C Library Functions             aio_read(3C)
2
3
4

NAME

6       aio_read - asynchronous read from a file
7

SYNOPSIS

9       #include <aio.h>
10
11       int aio_read(struct aiocb *aiocbp);
12
13

DESCRIPTION

15       The   aio_read()   function   allows   the   calling  process  to  read
16       aiocbp->aio_nbytes from the  file  associated  with  aiocbp->aio_fildes
17       into  the  buffer  pointed  to  by  aiocbp->aio_buf.  The function call
18       returns when the read request has been initiated or queued to the  file
19       or  device  (even  when  the  data cannot be delivered immediately). If
20       _POSIX_PRIORITIZED_IO is defined and prioritized I/O is  supported  for
21       this  file,  then the asynchronous operation is submitted at a priority
22       equal   to   the   scheduling   priority   of   the    process    minus
23       aiocbp->aio_reqprio.  The  aiocbp  value  may be used as an argument to
24       aio_error(3C) and aio_return(3C) in order to determine the error status
25       and return status, respectively, of the asynchronous operation while it
26       is proceeding. If an error condition is encountered during queuing, the
27       function  call  returns without having initiated or queued the request.
28       The requested operation takes place at the  absolute  position  in  the
29       file  as  given  by  aio_offset, as if lseek(2) were called immediately
30       prior to the operation with an offset equal to aio_offset and a  whence
31       equal  to  SEEK_SET. After a successful call to enqueue an asynchronous
32       I/O operation, the value of the file offset for the  file  is  unspeci‐
33       fied.
34
35
36       The  aiocbp->aio_sigevent structure defines what asynchronous notifica‐
37       tion is to occur when the asynchronous operation completes,  as  speci‐
38       fied in signal.h(3HEAD).
39
40
41       The aiocbp->aio_lio_opcode field is ignored by aio_read().
42
43
44       The aiocbp argument points to an aiocb structure. If the buffer pointed
45       to by aiocbp->aio_buf or the control block pointed to by aiocbp becomes
46       an  illegal  address  prior  to  asynchronous  I/O completion, then the
47       behavior is undefined.
48
49
50       Simultaneous asynchronous operations  using  the  same  aiocbp  produce
51       undefined results.
52
53
54       If _POSIX_SYNCHRONIZED_IO is defined and synchronized I/O is enabled on
55       the file associated with aiocbp->aio_fildes, the behavior of this func‐
56       tion is according to the definitions of synchronized I/O data integrity
57       completion and synchronized I/O file integrity completion.
58
59
60       For any system action that changes the process memory  space  while  an
61       asynchronous I/O is outstanding to the address range being changed, the
62       result of that action is undefined.
63
64
65       For regular files, no data transfer will occur past the offset  maximum
66       established    in   the   open   file   description   associated   with
67       aiocbp->aio_fildes.
68

RETURN VALUES

70       The aio_read() function returns 0 to the calling  process  if  the  I/O
71       operation  is  successfully  queued; otherwise, the function returns −1
72       and sets errno to indicate the error.
73

ERRORS

75       The aio_read() function will fail if:
76
77       EAGAIN    The requested asynchronous I/O operation was not  queued  due
78                 to system resource limitations.
79
80
81
82       Each  of  the following conditions may be detected synchronously at the
83       time of the call to aio_read(), or asynchronously. If any of the condi‐
84       tions below are detected synchronously, the aio_read() function returns
85       -1 and sets errno to the corresponding value. If any of the  conditions
86       below  are  detected asynchronously, the return status of the asynchro‐
87       nous operation is set to −1, and the error status of  the  asynchronous
88       operation will be set to the corresponding value.
89
90       EBADF     The  aiocbp->aio_fildes argument is not a valid file descrip‐
91                 tor open for reading.
92
93
94       EINVAL    The file offset value implied by aiocbp->aio_offset would  be
95                 invalid,   aiocbp->aio_reqprio  is  not  a  valid  value,  or
96                 aiocbp->aio_nbytes is an invalid value.
97
98
99
100       In the case that the aio_read() successfully queues the  I/O  operation
101       but  the operation is subsequently canceled or encounters an error, the
102       return status of the asynchronous operation is one of the  values  nor‐
103       mally  returned  by  the  read(2) function call. In addition, the error
104       status of the asynchronous operation will be set to one  of  the  error
105       statuses  normally  set by the read() function call, or one of the fol‐
106       lowing values:
107
108       EBADF        The  aiocbp->aio_fildes  argument  is  not  a  valid  file
109                    descriptor open for reading.
110
111
112       ECANCELED    The  requested  I/O  was canceled before the I/O completed
113                    due to an explicit aio_cancel(3C) request.
114
115
116       EINVAL       The file offset value implied by aiocbp->aio_offset  would
117                    be invalid.
118
119
120
121       The   following  condition  may  be  detected  synchronously  or  asyn‐
122       chronously:
123
124       EOVERFLOW    The file is a regular file, aiobcp->aio_nbytes is  greater
125                    than  0  and  the starting offset in aiobcp->aio_offset is
126                    before the end-of-file and is at or beyond the offset max‐
127                    imum   in   the  open  file  description  associated  with
128                    aiocbp->aio_fildes.
129
130

USAGE

132       For portability, the application should set aiocb->aio_reqprio to 0.
133
134
135       The aio_read() function has a transitional interface  for  64-bit  file
136       offsets.  See lf64(5).
137

ATTRIBUTES

139       See attributes(5) for descriptions of the following attributes:
140
141
142
143
144       ┌─────────────────────────────┬─────────────────────────────┐
145       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
146       ├─────────────────────────────┼─────────────────────────────┤
147       │Interface Stability          │Committed                    │
148       ├─────────────────────────────┼─────────────────────────────┤
149       │MT-Level                     │MT-Safe                      │
150       ├─────────────────────────────┼─────────────────────────────┤
151       │Standard                     │See standards(5).            │
152       └─────────────────────────────┴─────────────────────────────┘
153

SEE ALSO

155       close(2),  exec(2),  exit(2),  fork(2),  lseek(2),  read(2),  write(2),
156       aio_cancel(3C),  aio_return(3C),  aio.h(3HEAD),  lio_listio(3C),   sig‐
157       info.h(3HEAD), signal.h(3HEAD), attributes(5), lf64(5), standards(5)
158
159
160
161SunOS 5.11                        5 Feb 2008                      aio_read(3C)
Impressum