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

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH AIOREAD 3C "May 13, 2017"
   7 .SH NAME
   8 aioread, aiowrite \- read or write asynchronous I/O operations
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/asynch.h>
  14
  15 \fBint\fR \fBaioread\fR(\fBint\fR \fIfildes\fR, \fBchar *\fR\fIbufp\fR, \fBint\fR \fIbufs\fR, \fBoff_t\fR \fIoffset\fR,
  16      \fBint\fR \fIwhence\fR, \fBaio_result_t *\fR\fIresultp\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBaiowrite\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIbufp\fR, \fBint\fR \fIbufs\fR, \fBoff_t\fR \fIoffset\fR,
  22      \fBint\fR \fIwhence\fR, \fBaio_result_t *\fR\fIresultp\fR);
  23 .fi
  24
  25 .SH DESCRIPTION
  26 .LP
  27 The \fBaioread()\fR function initiates one asynchronous \fBread\fR(2) and
  28 returns control to the calling program. The read continues concurrently with
  29 other activity of the process. An attempt is made to read \fIbufs\fR bytes of
  30 data from the object referenced by the descriptor \fIfildes\fR into the buffer
  31 pointed to by \fIbufp\fR.
  32 .sp
  33 .LP
  34 The \fBaiowrite()\fR function initiates one asynchronous \fBwrite\fR(2) and
  35 returns control to the calling program. The write continues concurrently with
  36 other activity of the process. An attempt is made to write \fIbufs\fR bytes of
  37 data from the buffer pointed to by \fIbufp\fR to the object referenced by the
  38 descriptor \fIfildes\fR.
  39 .sp
  40 .LP
  41 On objects capable of seeking, the I/O operation starts at the position
  42 specified by \fIwhence\fR and \fIoffset\fR. These parameters have the same
  43 meaning as the corresponding parameters to the \fBllseek\fR(2) function. On
  44 objects not capable of seeking the I/O operation always start from the current
  45 position and the parameters \fBwhence\fR and \fIoffset\fR are ignored. The seek
  46 pointer for objects capable of seeking is not updated by \fBaioread()\fR or
  47 \fBaiowrite()\fR. Sequential asynchronous operations on these devices must be
  48 managed by the application using the \fIwhence\fR and \fIoffset\fR parameters.
  49 .sp
  50 .LP
  51 The result of the asynchronous operation is stored in the structure pointed to
  52 by \fIresultp\fR:
  53 .sp
  54 .in +2
  55 .nf
  56 int aio_return;          /* return value of read() or write() */
  57 int aio_errno;          /* value of errno for read() or write() */
  58 .fi
  59 .in -2
  60
  61 .sp
  62 .LP
  63 Upon completion of the operation both \fBaio_return\fR and \fBaio_errno\fR are
  64 set to reflect the result of the operation. Since \fBAIO_INPROGRESS\fR is not a
  65 value used by the system, the client can detect a change in state by
  66 initializing \fBaio_return\fR to this value.
  67 .sp
  68 .LP
  69 The application-supplied buffer \fIbufp\fR should not be referenced by the
  70 application until after the operation has completed. While the operation is in
  71 progress, this buffer is in use by the operating system.
  72 .sp
  73 .LP
  74 Notification of the completion of an asynchronous I/O operation can be
  75 obtained synchronously through the \fBaiowait\fR(3C) function, or
  76 asynchronously by installing a signal handler for the \fBSIGIO\fR signal.
  77 Asynchronous notification is accomplished by sending the process a \fBSIGIO\fR
  78 signal. If a signal handler is not installed for the \fBSIGIO\fR signal,
  79 asynchronous notification is disabled. The delivery of this instance of the
  80 \fBSIGIO\fR signal is reliable in that a signal delivered while the handler is
  81 executing is not lost. If the client ensures that \fBaiowait()\fR returns
  82 nothing (using a polling timeout) before returning from the signal handler, no
  83 asynchronous I/O notifications are lost. The \fBaiowait()\fR function is the
  84 only way to dequeue an asynchronous notification. The \fBSIGIO\fR signal can
  85 have several meanings simultaneously. For example, it can signify that a
  86 descriptor generated \fBSIGIO\fR and an asynchronous operation completed.
  87 Further, issuing an asynchronous request successfully guarantees that space
  88 exists to queue the completion notification.
  89 .sp
  90 .LP
  91 The \fBclose\fR(2), \fBexit\fR(2) and \fBexecve\fR(2)) functions block until
  92 all pending asynchronous I/O operations can be canceled by the system.
  93 .sp
  94 .LP
  95 It is an error to use the same result buffer in more than one outstanding
  96 request. These structures can be reused only after the system has completed the
  97 operation.
  98 .SH RETURN VALUES
  99 .LP
 100 Upon successful completion, \fBaioread()\fR and \fBaiowrite()\fR return
 101 \fB0\fR. Upon failure, \fBaioread()\fR and \fBaiowrite()\fR return \fB\(mi1\fR
 102 and set \fBerrno\fR to indicate the error.
 103 .SH ERRORS
 104 .LP
 105 The \fBaioread()\fR and \fBaiowrite()\fR functions will fail if:
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBEAGAIN\fR\fR
 110 .ad
 111 .RS 10n
 112 The number of asynchronous requests that the system can handle at any one time
 113 has been exceeded
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBEBADF\fR\fR
 120 .ad
 121 .RS 10n
 122 The \fIfildes\fR argument is not a valid file descriptor open for reading.
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBEFAULT\fR\fR
 129 .ad
 130 .RS 10n
 131 At least one of \fIbufp\fR or \fIresultp\fR points to an address outside the
 132 address space of the requesting process. This condition is reported only if
 133 detected by the application process.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBEINVAL\fR\fR
 140 .ad
 141 .RS 10n
 142 The \fIresultp\fR argument is currently being used by an outstanding
 143 asynchronous request.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBEINVAL\fR\fR
 150 .ad
 151 .RS 10n
 152 The \fIoffset\fR argument is not a valid offset for this file system type.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBENOMEM\fR\fR
 159 .ad
 160 .RS 10n
 161 Memory resources are unavailable to initiate request.
 162 .RE
 163
 164 .SH USAGE
 165 .LP
 166 The \fBaioread()\fR and \fBaiowrite()\fR functions have transitional interfaces
 167 for 64-bit file offsets.  See \fBlf64\fR(5).
 168 .SH ATTRIBUTES
 169 .LP
 170 See \fBattributes\fR(5) for descriptions of the following attributes:
 171 .sp
 172
 173 .sp
 174 .TS
 175 box;
 176 c | c
 177 l | l .
 178 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 179 _
 180 MT-Level        Safe
 181 .TE
 182
 183 .SH SEE ALSO
 184 .LP
 185 \fBclose\fR(2), \fBexecve\fR(2), \fBexit\fR(2), \fBllseek\fR(2),
 186 \fBlseek\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2),
 187 \fBaiocancel\fR(3C), \fBaiowait\fR(3C),
 188 \fBattributes\fR(5), \fBlf64\fR(5)