usr/src/man/man3c/aio_write.3c

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
   4 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   7 .\"  This notice shall appear on any product containing this material.
   8 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  10 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  11 .TH AIO_WRITE 3C "Feb 5, 2008"
  12 .SH NAME
  13 aio_write \- asynchronous write to a file
  14 .SH SYNOPSIS
  15 .LP
  16 .nf
  17 #include <aio.h>
  18
  19 \fBint\fR \fBaio_write\fR(\fBstruct aiocb *\fR\fIaiocbp\fR);
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 The \fBaio_write()\fR function allows the calling process to write
  26 \fIaiocbp\fR\(->\fBaio_nbytes\fR to the file associated with
  27 \fIaiocbp\fR\(->\fBaio_fildes\fR from the buffer pointed to by
  28 \fIaiocbp\fR\(->\fBaio_buf\fR. The function call returns when the write request
  29 has been initiated or, at a minimum, queued to the file or device. If
  30 \fB_POSIX_PRIORITIZED_IO\fR is defined and prioritized I/O is supported for
  31 this file, then the asynchronous operation is submitted at a priority equal to
  32 the scheduling priority of the process minus \fIaiocbp\fR\(->\fBaio_reqprio\fR.
  33 The \fIaiocbp\fR may be used as an argument to \fBaio_error\fR(3C) and
  34 \fBaio_return\fR(3C) in order to determine the error status and return status,
  35 respectively, of the asynchronous operation while it is proceeding.
  36 .sp
  37 .LP
  38 The \fIaiocbp\fR argument points to an \fBaiocb\fR structure. If the buffer
  39 pointed to by \fIaiocbp\fR\(->\fBaio_buf\fR or the control block pointed to by
  40 \fIaiocbp\fR becomes an illegal address prior to asynchronous I/O completion,
  41 then the behavior is undefined.
  42 .sp
  43 .LP
  44 If \fBO_APPEND\fR is not set for the file descriptor \fIaio_fildes\fR, then the
  45 requested operation takes place at the absolute position in the file as given
  46 by \fIaio_offset\fR, as if \fBlseek\fR(2) were called immediately prior to the
  47 operation with an \fIoffset\fR equal to \fIaio_offset\fR and a \fIwhence\fR
  48 equal to \fBSEEK_SET\fR. If \fBO_APPEND\fR is set for the file descriptor,
  49 write operations append to the file in the same order as the calls were made.
  50 After a successful call to enqueue an asynchronous I/O operation, the value of
  51 the file offset for the file is unspecified.
  52 .sp
  53 .LP
  54 The \fIaiocbp\fR\(->\fBaio_sigevent\fR structure defines what asynchronous
  55 notification is to occur when the asynchronous operation completes, as
  56 specified in \fBsignal.h\fR(3HEAD).
  57 .sp
  58 .LP
  59 The \fIaiocbp\fR\(->\fBaio_lio_opcode\fR field is ignored by \fBaio_write()\fR.
  60 .sp
  61 .LP
  62 Simultaneous asynchronous operations using the same \fIaiocbp\fR produce
  63 undefined results.
  64 .sp
  65 .LP
  66 If \fB_POSIX_SYNCHRONIZED_IO\fR is defined and synchronized I/O is enabled on
  67 the file associated with \fIaiocbp\fR\(->\fBaio_fildes\fR, the behavior of this
  68 function shall be according to the definitions of synchronized I/O data
  69 integrity completion and synchronized I/O file integrity completion.
  70 .sp
  71 .LP
  72 For any system action that changes the process memory space while an
  73 asynchronous I/O is outstanding to the address range being changed, the result
  74 of that action is undefined.
  75 .sp
  76 .LP
  77 For regular files, no data transfer will occur past the offset maximum
  78 established in the open file description associated with
  79 \fIaiocbp\fR\(->\fBaio_fildes\fR.
  80 .SH RETURN VALUES
  81 .sp
  82 .LP
  83 The \fBaio_write()\fR function returns \fB0\fR to the calling process if the
  84 I/O operation is successfully queued; otherwise, the function returns
  85 \fB\(mi1\fR and sets \fBerrno\fR to indicate the error.
  86 .SH ERRORS
  87 .sp
  88 .LP
  89 The  \fBaio_write()\fR function will fail if:
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fBEAGAIN\fR\fR
  94 .ad
  95 .RS 10n
  96 The requested asynchronous I/O operation was not queued due to system resource
  97 limitations.
  98 .RE
  99
 100 .sp
 101 .LP
 102 Each of the following conditions may be detected synchronously at the time of
 103 the call to \fBaio_write()\fR, or asynchronously. If any of the conditions
 104 below are detected synchronously, the \fBaio_write()\fR function returns
 105 \fB\(mi1\fR and sets \fBerrno\fR to the corresponding value. If any of the
 106 conditions below are detected asynchronously, the return status of the
 107 asynchronous operation is set to \fB\(mi1\fR, and the error status of the
 108 asynchronous operation will be set to the corresponding value.
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fBEBADF\fR\fR
 113 .ad
 114 .RS 10n
 115 The \fIaiocbp\fR\(->\fBaio_fildes\fR argument is not a valid file descriptor
 116 open for writing.
 117 .RE
 118
 119 .sp
 120 .ne 2
 121 .na
 122 \fB\fBEINVAL\fR\fR
 123 .ad
 124 .RS 10n
 125 The file offset value implied by \fIaiocbp\fR->\fBaio_offset\fR would be
 126 invalid, \fIaiocbp->\fR\fBaio_reqprio\fR is not a valid value, or
 127 \fIaiocbp\fR\(->\fBaio_nbytes\fR is an invalid value.
 128 .RE
 129
 130 .sp
 131 .LP
 132 In the case that the \fBaio_write()\fR successfully queues the I/O operation,
 133 the return status of the asynchronous operation will be one of the values
 134 normally returned by the \fBwrite\fR(2) function call. If the operation is
 135 successfully queued but is subsequently canceled or encounters an error, the
 136 error status for the asynchronous operation contains one of the values normally
 137 set by the \fBwrite()\fR function call, or one of the following:
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBEBADF\fR\fR
 142 .ad
 143 .RS 13n
 144 The \fIaiocbp\fR\(->\fBaio_fildes\fR argument is not a valid file descriptor
 145 open for writing.
 146 .RE
 147
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBEINVAL\fR\fR
 152 .ad
 153 .RS 13n
 154 The file offset value implied by \fIaiocbp\fR->\fBaio_offset\fR would be
 155 invalid.
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBECANCELED\fR\fR
 162 .ad
 163 .RS 13n
 164 The requested I/O was canceled before the I/O completed due to an explicit
 165 \fBaio_cancel\fR(3C) request.
 166 .RE
 167
 168 .sp
 169 .LP
 170 The following condition may be detected synchronously or asynchronously:
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fBEFBIG\fR\fR
 175 .ad
 176 .RS 9n
 177 The file is a regular file, \fIaiobcp\fR\(->\fBaio_nbytes\fR is greater than 0
 178 and the starting offset in \fIaiobcp\fR\(->\fBaio_offset\fR is at or beyond the
 179 offset maximum in the open file description associated with
 180 \fIaiocbp\fR\(->\fBaio_fildes\fR.
 181 .RE
 182
 183 .SH USAGE
 184 .sp
 185 .LP
 186 The \fBaio_write()\fR function has a transitional interface for 64-bit file
 187 offsets.  See \fBlf64\fR(5).
 188 .SH ATTRIBUTES
 189 .sp
 190 .LP
 191 See \fBattributes\fR(5) for descriptions of the following attributes:
 192 .sp
 193
 194 .sp
 195 .TS
 196 box;
 197 c | c
 198 l | l .
 199 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 200 _
 201 Interface Stability     Committed
 202 _
 203 MT-Level        MT-Safe
 204 _
 205 Standard        See \fBstandards\fR(5).
 206 .TE
 207
 208 .SH SEE ALSO
 209 .sp
 210 .LP
 211 \fBaio_cancel\fR(3C), \fBaio_error\fR(3C), \fBaio_read\fR(3C),
 212 \fBaio_return\fR(3C), \fBlio_listio\fR(3C), \fBclose\fR(2), \fB_Exit\fR(2),
 213 \fBfork\fR(2), \fBlseek\fR(2), \fBwrite\fR(2), \fBaio.h\fR(3HEAD),
 214 \fBsignal.h\fR(3HEAD), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5)