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 2003-11-14  "" "Linux Programmer's Manual"
  24 .SH NAME
  25 aio_write \- asynchronous write
  26 .SH SYNOPSIS
  27 .sp
  28 .B "#include <aio.h>"
  29 .sp
  30 .BI "int aio_write(struct aiocb *" aiocbp );
  31 .SH DESCRIPTION
  32 The
  33 .BR aio_write ()
  34 function requests an asynchronous "n = write(fd, buf, count)"
  35 with fd, buf, count given by
  36 .IR aiocbp->aio_fildes ,
  37 .IR aiocbp->aio_buf ,
  38 .IR aiocbp->aio_nbytes ,
  39 respectively.
  40 The return status n can be retrieved upon completion using
  41 .BR aio_return (3).
  42 .LP
  43 If
  44 .B O_APPEND
  45 is not set, the data is written starting at the
  46 absolute file offset
  47 .IR aiocbp->aio_offset ,
  48 regardless of the current file position.
  49 If
  50 .B O_APPEND
  51 is set, the data is written at the end of the file.
  52 After this request, the value of the current file position is unspecified.
  53 .LP
  54 The "asynchronous" means that this call returns as soon as the
  55 request has been enqueued; the write may or may not have completed
  56 when the call returns.
  57 One tests for completion using
  58 .BR aio_error (3).
  59 .LP
  60 If
  61 .B _POSIX_PRIORITIZED_IO
  62 is defined, and this file supports it,
  63 then the asynchronous operation is submitted at a priority equal
  64 to that of the calling process minus
  65 .IR aiocbp->aio_reqprio .
  66 .LP
  67 The field
  68 .I aiocbp->aio_lio_opcode
  69 is ignored.
  70 .LP
  71 No data is written to a regular file beyond its maximum offset.
  72 .SH "RETURN VALUE"
  73 On success, 0 is returned.
  74 On error the request is not enqueued, \-1
  75 is returned, and
  76 .I errno
  77 is set appropriately.
  78 If an error is first detected later, it will
  79 be reported via
  80 .BR aio_return (3)
  81 (returns status \-1) and
  82 .BR aio_error (3)
  83 (error status whatever one would have gotten in
  84 .IR errno ,
  85 such as
  86 .BR EBADF ).
  87 .SH ERRORS
  88 .TP
  89 .B EAGAIN
  90 Out of resources.
  91 .TP
  92 .B EBADF
  93 .I aio_fildes
  94 is not a valid file descriptor open for writing.
  95 .TP
  96 .B EFBIG
  97 The file is a regular file, we want to write at least one byte,
  98 but the starting position is at or beyond the maximum offset for this file.
  99 .TP
 100 .B EINVAL
 101 One or more of
 102 .IR aio_offset ,
 103 .IR aio_reqprio ,
 104 .IR aio_nbytes
 105 are invalid.
 106 .TP
 107 .B ENOSYS
 108 This function is not supported.
 109 .SH "CONFORMING TO"
 110 POSIX.1-2001
 111 .SH NOTES
 112 It is a good idea to zero out the control block before use.
 113 This control block must not be changed while the write operation
 114 is in progress.
 115 The buffer area being written out
 116 .\" or the control block of the operation
 117 must not be accessed during the operation or undefined results may
 118 occur.
 119 The memory areas involved must remain valid.
 120 .SH "SEE ALSO"
 121 .BR aio_cancel (3),
 122 .BR aio_error (3),
 123 .BR aio_fsync (3),
 124 .BR aio_read (3),
 125 .BR aio_return (3),
 126 .BR aio_suspend (3)