aio_write(3c)

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

NAME

6       aio_write - asynchronous write to a file
7

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUES

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

ERRORS

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

USAGE

133       The aio_write() function has a transitional interface for  64-bit  file
134       offsets.  See lf64(5).
135

ATTRIBUTES

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