lib/libc/sys/aio_write.2

   1 .\" Copyright (c) 1999 Softweyr LLC.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd November 15, 2023
  26 .Dt AIO_WRITE 2
  27 .Os
  28 .Sh NAME
  29 .Nm aio_write ,
  30 .Nm aio_writev
  31 .Nd asynchronous write to a file (REALTIME)
  32 .Sh LIBRARY
  33 .Lb libc
  34 .Sh SYNOPSIS
  35 .In aio.h
  36 .Ft int
  37 .Fn aio_write "struct aiocb *iocb"
  38 .In sys/uio.h
  39 .Ft int
  40 .Fn aio_writev "struct aiocb *iocb"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn aio_write
  44 and
  45 .Fn aio_writev
  46 system calls allow the calling process to write
  47 to the descriptor
  48 .Fa iocb->aio_fildes .
  49 .Fn aio_write
  50 will write
  51 .Fa iocb->aio_nbytes
  52 from the buffer pointed to by
  53 .Fa iocb->aio_buf ,
  54 whereas
  55 .Fn aio_writev
  56 gathers the data from the
  57 .Fa iocb->aio_iovcnt
  58 buffers specified by the members of the
  59 .Fa iocb->aio_iov
  60 array.
  61 Both syscalls return immediately after the write request has been enqueued
  62 to the descriptor; the write may or may not have completed at the time
  63 the call returns.
  64 If the request could not be enqueued, generally due
  65 to invalid arguments, the call returns without having enqueued the
  66 request.
  67 .Pp
  68 For
  69 .Fn aio_writev
  70 the
  71 .Fa iovec
  72 structure is defined in
  73 .Xr writev 2 .
  74 .Pp
  75 If
  76 .Dv O_APPEND
  77 is set for
  78 .Fa iocb->aio_fildes ,
  79 write operations append to the file in the same order as the calls were
  80 made.
  81 If
  82 .Dv O_APPEND
  83 is not set for the file descriptor, the write operation will occur at
  84 the absolute position from the beginning of the file plus
  85 .Fa iocb->aio_offset .
  86 .Pp
  87 The
  88 .Fa iocb
  89 pointer may be subsequently used as an argument to
  90 .Fn aio_return
  91 and
  92 .Fn aio_error
  93 in order to determine return or error status for the enqueued operation
  94 while it is in progress.
  95 .Pp
  96 If the request is successfully enqueued, the value of
  97 .Fa iocb->aio_offset
  98 can be modified during the request as context, so this value must not
  99 be referenced after the request is enqueued.
 100 .Pp
 101 The
 102 .Fa iocb->aio_sigevent
 103 structure can be used to request notification of the operation's
 104 completion as described in
 105 .Xr aio 4 .
 106 .Sh RESTRICTIONS
 107 The Asynchronous I/O Control Block structure pointed to by
 108 .Fa iocb
 109 and the buffer that the
 110 .Fa iocb->aio_buf
 111 member of that structure references must remain valid until the
 112 operation has completed.
 113 .Pp
 114 The asynchronous I/O control buffer
 115 .Fa iocb
 116 should be zeroed before the
 117 .Fn aio_write
 118 or
 119 .Fn aio_writev
 120 system call to avoid passing bogus context information to the kernel.
 121 .Pp
 122 Modifications of the Asynchronous I/O Control Block structure or the
 123 buffer contents are not allowed while the request is queued.
 124 .Pp
 125 If the file offset in
 126 .Fa iocb->aio_offset
 127 is past the offset maximum for
 128 .Fa iocb->aio_fildes ,
 129 no I/O will occur.
 130 .Sh RETURN VALUES
 131 .Rv -std aio_write aio_writev
 132 .Sh ERRORS
 133 The
 134 .Fn aio_write
 135 and
 136 .Fn aio_writev
 137 system calls will fail if:
 138 .Bl -tag -width Er
 139 .It Bq Er EAGAIN
 140 The request was not queued because of system resource limitations.
 141 .It Bq Er EFAULT
 142 Part of
 143 .Fa aio_iov
 144 points outside the process's allocated address space.
 145 .It Bq Er EINVAL
 146 The asynchronous notification method in
 147 .Fa iocb->aio_sigevent.sigev_notify
 148 is invalid or not supported.
 149 .It Bq Er EOPNOTSUPP
 150 Asynchronous write operations on the file descriptor
 151 .Fa iocb->aio_fildes
 152 are unsafe and unsafe asynchronous I/O operations are disabled.
 153 .El
 154 .Pp
 155 The following conditions may be synchronously detected when the
 156 .Fn aio_write
 157 or
 158 .Fn aio_writev
 159 system call is made, or asynchronously, at any time thereafter.
 160 If they
 161 are detected at call time,
 162 .Fn aio_write
 163 or
 164 .Fn aio_writev
 165 returns -1 and sets
 166 .Va errno
 167 appropriately; otherwise the
 168 .Fn aio_return
 169 system call must be called, and will return -1, and
 170 .Fn aio_error
 171 must be called to determine the actual value that would have been
 172 returned in
 173 .Va errno .
 174 .Bl -tag -width Er
 175 .It Bq Er EBADF
 176 The
 177 .Fa iocb->aio_fildes
 178 argument
 179 is invalid, or is not opened for writing.
 180 .It Bq Er EINVAL
 181 The offset
 182 .Fa iocb->aio_offset
 183 is not valid, the priority specified by
 184 .Fa iocb->aio_reqprio
 185 is not a valid priority, or the number of bytes specified by
 186 .Fa iocb->aio_nbytes
 187 is not valid.
 188 .El
 189 .Pp
 190 If the request is successfully enqueued, but subsequently canceled
 191 or an error occurs, the value returned by the
 192 .Fn aio_return
 193 system call is per the
 194 .Xr write 2
 195 system call, and the value returned by the
 196 .Fn aio_error
 197 system call is either one of the error returns from the
 198 .Xr write 2
 199 system call, or one of:
 200 .Bl -tag -width Er
 201 .It Bq Er EBADF
 202 The
 203 .Fa iocb->aio_fildes
 204 argument
 205 is invalid for writing.
 206 .It Bq Er ECANCELED
 207 The request was explicitly canceled via a call to
 208 .Fn aio_cancel .
 209 .It Bq Er EINVAL
 210 The offset
 211 .Fa iocb->aio_offset
 212 would be invalid.
 213 .El
 214 .Sh SEE ALSO
 215 .Xr aio_cancel 2 ,
 216 .Xr aio_error 2 ,
 217 .Xr aio_return 2 ,
 218 .Xr aio_suspend 2 ,
 219 .Xr aio_waitcomplete 2 ,
 220 .Xr sigevent 3 ,
 221 .Xr siginfo 3 ,
 222 .Xr aio 4
 223 .Sh STANDARDS
 224 The
 225 .Fn aio_write
 226 system call
 227 is expected to conform to the
 228 .St -p1003.1
 229 standard.
 230 .Pp
 231 The
 232 .Fn aio_writev
 233 system call is a FreeBSD extension, and should not be used in portable code.
 234 .Sh HISTORY
 235 The
 236 .Fn aio_write
 237 system call first appeared in
 238 .Fx 3.0 .
 239 The
 240 .Fn aio_writev
 241 system call first appeared in
 242 .Fx 13.0 .
 243 .Sh AUTHORS
 244 This manual page was written by
 245 .An Wes Peters Aq Mt wes@softweyr.com .
 246 .Sh BUGS
 247 Invalid information in
 248 .Fa iocb->_aiocb_private
 249 may confuse the kernel.