man3/aio_write.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .TH AIO_WRITE 3 2012-05-08  "" "Linux Programmer's Manual"
  24 .SH NAME
  25 aio_write \- asynchronous write
  26 .SH SYNOPSIS
  27 .B "#include <aio.h>"
  28 .sp
  29 .BI "int aio_write(struct aiocb *" aiocbp );
  30 .sp
  31 Link with \fI\-lrt\fP.
  32 .SH DESCRIPTION
  33 The
  34 .BR aio_write ()
  35 function queues the I/O request described by the buffer pointed to by
  36 .IR aiocb .
  37 This function is the asynchronous analog of
  38 .BR write (2).
  39 The arguments of the call
  40
  41     write(fd, buf, count)
  42
  43 correspond (in order) to the fields
  44 .IR aio_fildes ,
  45 .IR aio_buf ,
  46 and
  47 .IR aio_nbytes
  48 of the structure pointed to by
  49 .IR aiocbp .
  50 (See
  51 .BR aio (7)
  52 for a description of the
  53 .I aiocb
  54 structure.)
  55 .LP
  56 If
  57 .B O_APPEND
  58 is not set, the data is written starting at the
  59 absolute file offset
  60 .IR aiocbp\->aio_offset ,
  61 regardless of the current file offset.
  62 If
  63 .B O_APPEND
  64 is set, data is written at the end of the file in the same order as
  65 .BR aio_write ()
  66 calls are made.
  67 After the call, the value of the current file offset is unspecified.
  68 .LP
  69 The "asynchronous" means that this call returns as soon as the
  70 request has been enqueued; the write may or may not have completed
  71 when the call returns.
  72 One tests for completion using
  73 .BR aio_error (3).
  74 The return status of a completed I/O operation can be obtained
  75 .BR aio_return (3).
  76 Asynchronous notification of I/O completion can be obtained by setting
  77 .IR aiocbp\->aio_sigevent
  78 appropriately; see
  79 .BR sigevent (7)
  80 for details.
  81 .LP
  82 If
  83 .B _POSIX_PRIORITIZED_IO
  84 is defined, and this file supports it,
  85 then the asynchronous operation is submitted at a priority equal
  86 to that of the calling process minus
  87 .IR aiocbp\->aio_reqprio .
  88 .LP
  89 The field
  90 .I aiocbp\->aio_lio_opcode
  91 is ignored.
  92 .LP
  93 No data is written to a regular file beyond its maximum offset.
  94 .SH "RETURN VALUE"
  95 On success, 0 is returned.
  96 On error the request is not enqueued, \-1
  97 is returned, and
  98 .I errno
  99 is set appropriately.
 100 If an error is only detected later, it will
 101 be reported via
 102 .BR aio_return (3)
 103 (returns status \-1) and
 104 .BR aio_error (3)
 105 (error status\(emwhatever one would have gotten in
 106 .IR errno ,
 107 such as
 108 .BR EBADF ).
 109 .SH ERRORS
 110 .TP
 111 .B EAGAIN
 112 Out of resources.
 113 .TP
 114 .B EBADF
 115 .I aio_fildes
 116 is not a valid file descriptor open for writing.
 117 .TP
 118 .B EFBIG
 119 The file is a regular file, we want to write at least one byte,
 120 but the starting position is at or beyond the maximum offset for this file.
 121 .TP
 122 .B EINVAL
 123 One or more of
 124 .IR aio_offset ,
 125 .IR aio_reqprio ,
 126 .I aio_nbytes
 127 are invalid.
 128 .TP
 129 .B ENOSYS
 130 .BR aio_write ()
 131 is not implemented.
 132 .SH VERSIONS
 133 The
 134 .BR aio_write ()
 135 function is available since glibc 2.1.
 136 .SH "CONFORMING TO"
 137 POSIX.1-2001, POSIX.1-2008.
 138 .SH NOTES
 139 It is a good idea to zero out the control block before use.
 140 The control block must not be changed while the write operation
 141 is in progress.
 142 The buffer area being written out
 143 .\" or the control block of the operation
 144 must not be accessed during the operation or undefined results may occur.
 145 The memory areas involved must remain valid.
 146
 147 Simultaneous I/O operations specifying the same
 148 .I aiocb
 149 structure produce undefined results.
 150 .SH "SEE ALSO"
 151 .BR aio_cancel (3),
 152 .BR aio_error (3),
 153 .BR aio_fsync (3),
 154 .BR aio_read (3),
 155 .BR aio_return (3),
 156 .BR aio_suspend (3),
 157 .BR lio_listio (3),
 158 .BR aio (7)