aiowrite(3c)

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

NAME

6       aioread, aiowrite - read or write asynchronous I/O operations
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/asynch.h>
11
12       int aioread(int fildes, char *bufp, int bufs, off_t offset,
13            int whence, aio_result_t *resultp);
14
15
16       int aiowrite(int fildes, const char *bufp, int bufs, off_t offset,
17            int whence, aio_result_t *resultp);
18
19

DESCRIPTION

21       The  aioread()  function initiates one asynchronous read(2) and returns
22       control to the calling program. The read  continues  concurrently  with
23       other activity of the process. An attempt is made to read bufs bytes of
24       data from the object referenced by the descriptor fildes into the  buf‐
25       fer pointed to by bufp.
26
27
28       The aiowrite() function initiates one asynchronous write(2) and returns
29       control to the calling program. The write continues  concurrently  with
30       other  activity  of the process. An attempt is made to write bufs bytes
31       of data from the buffer pointed to by bufp to the object referenced  by
32       the descriptor fildes.
33
34
35       On objects capable of seeking, the I/O operation starts at the position
36       specified by whence and offset. These parameters have the same  meaning
37       as  the  corresponding parameters to the llseek(2) function. On objects
38       not capable of seeking the I/O operation always start from the  current
39       position  and  the  parameters  whence and offset are ignored. The seek
40       pointer for objects capable of seeking is not updated by  aioread()  or
41       aiowrite(). Sequential asynchronous operations on these devices must be
42       managed by the application using the whence and offset parameters.
43
44
45       The result of the asynchronous operation is  stored  in  the  structure
46       pointed to by resultp:
47
48         int aio_return;          /* return value of read() or write() */
49         int aio_errno;          /* value of errno for read() or write() */
50
51
52
53       Upon  completion of the operation both aio_return and aio_errno are set
54       to reflect the result of the operation. Since AIO_INPROGRESS is  not  a
55       value  used  by  the system, the client can detect a change in state by
56       initializing aio_return to this value.
57
58
59       The application-supplied buffer bufp should not be  referenced  by  the
60       application  until  after the operation has completed. While the opera‐
61       tion is in progress, this buffer is in use by the operating system.
62
63
64       Notification of the completion of an asynchronous I/O  operation can be
65       obtained  synchronously  through  the   aiowait(3C)  function, or asyn‐
66       chronously by installing a signal handler for the SIGIO signal.   Asyn‐
67       chronous  notification  is  accomplished by sending the process a SIGIO
68       signal. If a signal handler is not  installed  for  the  SIGIO  signal,
69       asynchronous notification is disabled. The delivery of this instance of
70       the SIGIO signal is reliable in that a signal delivered while the  han‐
71       dler  is  executing  is  not lost. If the client ensures that aiowait()
72       returns nothing (using a polling timeout)  before  returning  from  the
73       signal  handler,  no  asynchronous  I/O  notifications  are  lost.  The
74       aiowait() function is the only way to dequeue an asynchronous notifica‐
75       tion.  The  SIGIO  signal can have several meanings simultaneously. For
76       example, it can signify that a descriptor generated SIGIO and an  asyn‐
77       chronous  operation completed. Further, issuing an asynchronous request
78       successfully guarantees that space exists to queue the completion noti‐
79       fication.
80
81
82       The  close(2), exit(2) and execve(2)) functions block until all pending
83       asynchronous I/O operations can be canceled by the system.
84
85
86       It is an error to use the same result buffer in more than one outstand‐
87       ing  request.  These structures can be reused only after the system has
88       completed the operation.
89

RETURN VALUES

91       Upon successful completion,  aioread() and aiowrite()  return  0.  Upon
92       failure,  aioread()  and aiowrite() return −1 and set errno to indicate
93       the error.
94

ERRORS

96       The aioread() and aiowrite() functions will fail if:
97
98       EAGAIN    The number of asynchronous requests that the system can  han‐
99                 dle at any one time has been exceeded
100
101
102       EBADF     The  fildes  argument is not a valid file descriptor open for
103                 reading.
104
105
106       EFAULT    At least one of bufp or resultp points to an address  outside
107                 the  address  space of the requesting process. This condition
108                 is reported only if detected by the application process.
109
110
111       EINVAL    The resultp argument is currently being used by an  outstand‐
112                 ing asynchronous request.
113
114
115       EINVAL    The  offset argument is not a valid offset for this file sys‐
116                 tem type.
117
118
119       ENOMEM    Memory resources are unavailable to initiate request.
120
121

USAGE

123       The aioread() and aiowrite() functions have transitional interfaces for
124       64-bit file offsets.  See lf64(5).
125

ATTRIBUTES

127       See attributes(5) for descriptions of the following attributes:
128
129
130
131
132       ┌─────────────────────────────┬─────────────────────────────┐
133       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
134       ├─────────────────────────────┼─────────────────────────────┤
135       │MT-Level                     │Safe                         │
136       └─────────────────────────────┴─────────────────────────────┘
137