man3/aio_write.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" SPDX-License-Identifier: GPL-2.0-or-later
   4 .\"
   5 .TH aio_write 3 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 aio_write \- asynchronous write
   8 .SH LIBRARY
   9 Real-time library
  10 .RI ( librt ", " \-lrt )
  11 .SH SYNOPSIS
  12 .nf
  13 .B "#include <aio.h>"
  14 .PP
  15 .BI "int aio_write(struct aiocb *" aiocbp );
  16 .fi
  17 .SH DESCRIPTION
  18 The
  19 .BR aio_write ()
  20 function queues the I/O request described by the buffer pointed to by
  21 .IR aiocbp .
  22 This function is the asynchronous analog of
  23 .BR write (2).
  24 The arguments of the call
  25 .PP
  26 .in +4n
  27 .EX
  28 write(fd, buf, count)
  29 .EE
  30 .in
  31 .PP
  32 correspond (in order) to the fields
  33 .IR aio_fildes ,
  34 .IR aio_buf ,
  35 and
  36 .I aio_nbytes
  37 of the structure pointed to by
  38 .IR aiocbp .
  39 (See
  40 .BR aio (7)
  41 for a description of the
  42 .I aiocb
  43 structure.)
  44 .PP
  45 If
  46 .B O_APPEND
  47 is not set, the data is written starting at the
  48 absolute position
  49 .IR aiocbp\->aio_offset ,
  50 regardless of the file offset.
  51 If
  52 .B O_APPEND
  53 is set, data is written at the end of the file in the same order as
  54 .BR aio_write ()
  55 calls are made.
  56 After the call, the value of the file offset is unspecified.
  57 .PP
  58 The "asynchronous" means that this call returns as soon as the
  59 request has been enqueued; the write may or may not have completed
  60 when the call returns.
  61 One tests for completion using
  62 .BR aio_error (3).
  63 The return status of a completed I/O operation can be obtained
  64 .BR aio_return (3).
  65 Asynchronous notification of I/O completion can be obtained by setting
  66 .I aiocbp\->aio_sigevent
  67 appropriately; see
  68 .BR sigevent (7)
  69 for details.
  70 .PP
  71 If
  72 .B _POSIX_PRIORITIZED_IO
  73 is defined, and this file supports it,
  74 then the asynchronous operation is submitted at a priority equal
  75 to that of the calling process minus
  76 .IR aiocbp\->aio_reqprio .
  77 .PP
  78 The field
  79 .I aiocbp\->aio_lio_opcode
  80 is ignored.
  81 .PP
  82 No data is written to a regular file beyond its maximum offset.
  83 .SH RETURN VALUE
  84 On success, 0 is returned.
  85 On error, the request is not enqueued, \-1
  86 is returned, and
  87 .I errno
  88 is set to indicate the error.
  89 If an error is detected only later, it will
  90 be reported via
  91 .BR aio_return (3)
  92 (returns status \-1) and
  93 .BR aio_error (3)
  94 (error status\(emwhatever one would have gotten in
  95 .IR errno ,
  96 such as
  97 .BR EBADF ).
  98 .SH ERRORS
  99 .TP
 100 .B EAGAIN
 101 Out of resources.
 102 .TP
 103 .B EBADF
 104 .I aio_fildes
 105 is not a valid file descriptor open for writing.
 106 .TP
 107 .B EFBIG
 108 The file is a regular file, we want to write at least one byte,
 109 but the starting position is at or beyond the maximum offset for this file.
 110 .TP
 111 .B EINVAL
 112 One or more of
 113 .IR aio_offset ,
 114 .IR aio_reqprio ,
 115 .I aio_nbytes
 116 are invalid.
 117 .TP
 118 .B ENOSYS
 119 .BR aio_write ()
 120 is not implemented.
 121 .SH VERSIONS
 122 The
 123 .BR aio_write ()
 124 function is available since glibc 2.1.
 125 .SH ATTRIBUTES
 126 For an explanation of the terms used in this section, see
 127 .BR attributes (7).
 128 .ad l
 129 .nh
 130 .TS
 131 allbox;
 132 lbx lb lb
 133 l l l.
 134 Interface       Attribute       Value
 135 T{
 136 .BR aio_write ()
 137 T}      Thread safety   MT-Safe
 138 .TE
 139 .hy
 140 .ad
 141 .sp 1
 142 .SH STANDARDS
 143 POSIX.1-2001, POSIX.1-2008.
 144 .SH NOTES
 145 It is a good idea to zero out the control block before use.
 146 The control block must not be changed while the write operation
 147 is in progress.
 148 The buffer area being written out
 149 .\" or the control block of the operation
 150 must not be accessed during the operation or undefined results may occur.
 151 The memory areas involved must remain valid.
 152 .PP
 153 Simultaneous I/O operations specifying the same
 154 .I aiocb
 155 structure produce undefined results.
 156 .SH SEE ALSO
 157 .BR aio_cancel (3),
 158 .BR aio_error (3),
 159 .BR aio_fsync (3),
 160 .BR aio_read (3),
 161 .BR aio_return (3),
 162 .BR aio_suspend (3),
 163 .BR lio_listio (3),
 164 .BR aio (7)