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

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved
   5 .\" 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
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" 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.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" 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.
  10 .\" 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.
  11 .\" 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]
  12 .TH AIO_READ 3C "Feb 5, 2008"
  13 .SH NAME
  14 aio_read \- asynchronous read from a file
  15 .SH SYNOPSIS
  16 .LP
  17 .nf
  18 #include <aio.h>
  19
  20 \fBint\fR \fBaio_read\fR(\fBstruct aiocb *\fR\fIaiocbp\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBaio_read()\fR function allows the calling process to read
  27 \fIaiocbp\fR->\fBaio_nbytes\fR from the file associated with
  28 \fIaiocbp\fR->\fBaio_fildes\fR into the buffer pointed to by
  29 \fIaiocbp\fR->\fBaio_buf\fR. The function call returns when the read request
  30 has been initiated or queued to the file or device (even when the data cannot
  31 be delivered immediately). If \fB_POSIX_PRIORITIZED_IO\fR is defined and
  32 prioritized I/O is supported for this file, then the asynchronous operation is
  33 submitted at a priority equal to the scheduling priority of the process minus
  34 \fIaiocbp\fR->\fBaio_reqprio\fR. The \fIaiocbp\fR value may be used as an
  35 argument to \fBaio_error\fR(3C) and \fBaio_return\fR(3C) in order to determine
  36 the error status and return status, respectively, of the asynchronous operation
  37 while it is proceeding. If an error condition is encountered during queuing,
  38 the function call returns without having initiated or queued the request. The
  39 requested operation takes place at the absolute position in the file as given
  40 by \fIaio_offset\fR, as if \fBlseek\fR(2) were called immediately prior to the
  41 operation with an \fIoffset\fR equal to \fIaio_offset\fR and a \fBwhence\fR
  42 equal to \fBSEEK_SET\fR. After a successful call to enqueue an asynchronous I/O
  43 operation, the value of the file offset for the file is unspecified.
  44 .sp
  45 .LP
  46 The \fIaiocbp\fR->\fBaio_sigevent\fR structure defines what asynchronous
  47 notification is to occur when the asynchronous operation completes, as
  48 specified in \fBsignal.h\fR(3HEAD).
  49 .sp
  50 .LP
  51 The \fIaiocbp\fR->\fBaio_lio_opcode\fR field is ignored by \fBaio_read()\fR.
  52 .sp
  53 .LP
  54 The \fIaiocbp\fR argument points to an \fBaiocb\fR structure. If the buffer
  55 pointed to by \fIaiocbp\fR->\fBaio_buf\fR or the control block pointed to by
  56 \fIaiocbp\fR becomes an illegal address prior to asynchronous I/O completion,
  57 then the behavior is undefined.
  58 .sp
  59 .LP
  60 Simultaneous asynchronous operations using the same \fIaiocbp\fR produce
  61 undefined results.
  62 .sp
  63 .LP
  64 If \fB_POSIX_SYNCHRONIZED_IO\fR is defined and synchronized I/O is enabled on
  65 the file associated with \fIaiocbp\fR->\fBaio_fildes,\fR the behavior of this
  66 function is according to the definitions of synchronized I/O data integrity
  67 completion and synchronized I/O file integrity completion.
  68 .sp
  69 .LP
  70 For any system action that changes the process memory space while an
  71 asynchronous I/O is outstanding to the address range being changed, the result
  72 of that action is undefined.
  73 .sp
  74 .LP
  75 For regular files, no data transfer will occur past the offset maximum
  76 established in the open file description associated with
  77 \fIaiocbp\fR->\fBaio_fildes\fR.
  78 .SH RETURN VALUES
  79 .sp
  80 .LP
  81 The \fBaio_read()\fR function returns \fB0\fR to the calling process if the I/O
  82 operation is successfully queued; otherwise, the function returns \fB\(mi1\fR
  83 and sets \fBerrno\fR to indicate the error.
  84 .SH ERRORS
  85 .sp
  86 .LP
  87 The \fBaio_read()\fR function will fail if:
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBEAGAIN\fR\fR
  92 .ad
  93 .RS 10n
  94 The requested asynchronous I/O operation was not queued due to system resource
  95 limitations.
  96 .RE
  97
  98 .sp
  99 .LP
 100 Each of the following conditions may be detected synchronously at the time of
 101 the call to \fBaio_read()\fR, or asynchronously. If any of the conditions below
 102 are detected synchronously, the \fBaio_read()\fR function returns \fB-1\fR and
 103 sets \fBerrno\fR to the corresponding value. If any of the conditions below are
 104 detected asynchronously, the return status of the asynchronous operation is set
 105 to \(mi1, and the error status of the asynchronous operation will be set to the
 106 corresponding value.
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBEBADF\fR\fR
 111 .ad
 112 .RS 10n
 113 The \fIaiocbp\fR->\fBaio_fildes\fR argument is not a valid file descriptor open
 114 for reading.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBEINVAL\fR\fR
 121 .ad
 122 .RS 10n
 123 The file offset value implied by \fIaiocbp\fR->\fBaio_offset\fR would be
 124 invalid, \fIaiocbp->\fR\fBaio_reqprio\fR is not a valid value, or
 125 \fIaiocbp\fR->\fBaio_nbytes\fR is an invalid value.
 126 .RE
 127
 128 .sp
 129 .LP
 130 In the case that the \fBaio_read()\fR successfully queues the I/O operation but
 131 the operation is subsequently canceled or encounters an error, the return
 132 status of the asynchronous operation is one of the values normally returned by
 133 the \fBread\fR(2) function call. In addition, the error status of the
 134 asynchronous operation will be set to one of the error statuses normally set by
 135 the \fBread()\fR function call, or one of the following values:
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBEBADF\fR\fR
 140 .ad
 141 .RS 13n
 142 The \fIaiocbp\fR->\fBaio_fildes\fR argument is not a valid file descriptor open
 143 for reading.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBECANCELED\fR\fR
 150 .ad
 151 .RS 13n
 152 The requested I/O was canceled before the I/O completed due to an explicit
 153 \fBaio_cancel\fR(3C) request.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fBEINVAL\fR\fR
 160 .ad
 161 .RS 13n
 162 The file offset value implied by \fIaiocbp\fR->\fBaio_offset\fR would be
 163 invalid.
 164 .RE
 165
 166 .sp
 167 .LP
 168 The following condition may be detected synchronously or asynchronously:
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBEOVERFLOW\fR\fR
 173 .ad
 174 .RS 13n
 175 The file is a regular file, \fIaiobcp\fR->\fBaio_nbytes\fR is greater than 0
 176 and the starting offset in \fIaiobcp\fR->\fBaio_offset\fR is before the
 177 end-of-file and is at or beyond the offset maximum in the open file description
 178 associated with \fIaiocbp\fR->\fBaio_fildes\fR.
 179 .RE
 180
 181 .SH USAGE
 182 .sp
 183 .LP
 184 For portability, the application should set \fIaiocb->\fR\fBaio_reqprio\fR to
 185 \fB0\fR.
 186 .sp
 187 .LP
 188 The \fBaio_read()\fR function has a transitional interface for 64-bit file
 189 offsets.  See \fBlf64\fR(5).
 190 .SH ATTRIBUTES
 191 .sp
 192 .LP
 193 See \fBattributes\fR(5) for descriptions of the following attributes:
 194 .sp
 195
 196 .sp
 197 .TS
 198 box;
 199 c | c
 200 l | l .
 201 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 202 _
 203 Interface Stability     Committed
 204 _
 205 MT-Level        MT-Safe
 206 _
 207 Standard        See \fBstandards\fR(5).
 208 .TE
 209
 210 .SH SEE ALSO
 211 .sp
 212 .LP
 213 \fBclose\fR(2), \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBlseek\fR(2),
 214 \fBread\fR(2), \fBwrite\fR(2), \fBaio_cancel\fR(3C), \fBaio_return\fR(3C),
 215 \fBaio.h\fR(3HEAD), \fBlio_listio\fR(3C), \fBsiginfo.h\fR(3HEAD),
 216 \fBsignal.h\fR(3HEAD), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5)