bsd/man/man2/aio_return.2

   1 .\"
   2 .\" Copyright (c) 2008 Apple Inc.  All rights reserved.
   3 .\"
   4 .\" @APPLE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. Please obtain a copy of the License at
  10 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  11 .\" file.
  12 .\"
  13 .\" The Original Code and all software distributed under the License are
  14 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18 .\" Please see the License for the specific language governing rights and
  19 .\" limitations under the License.
  20 .\"
  21 .\" @APPLE_LICENSE_HEADER_END@
  22 .\"
  23 .\"
  24 .\" Copyright (c) 1999 Softweyr LLC.
  25 .\" All rights reserved.
  26 .\"
  27 .\" Redistribution and use in source and binary forms, with or without
  28 .\" modification, are permitted provided that the following conditions
  29 .\" are met:
  30 .\" 1. Redistributions of source code must retain the above copyright
  31 .\"    notice, this list of conditions and the following disclaimer.
  32 .\" 2. Redistributions in binary form must reproduce the above copyright
  33 .\"    notice, this list of conditions and the following disclaimer in the
  34 .\"    documentation and/or other materials provided with the distribution.
  35 .\"
  36 .\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND
  37 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  38 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  39 .\" ARE DISCLAIMED.  IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE
  40 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  41 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  42 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  43 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  44 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  45 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46 .\" SUCH DAMAGE.
  47 .\"
  48 .\" $FreeBSD: src/lib/libc/sys/aio_return.2,v 1.17 2003/01/13 10:37:11 tjr Exp $
  49 .\"
  50 .Dd September 26, 2008
  51 .Dt AIO_RETURN 2
  52 .Os
  53 .Sh NAME
  54 .Nm aio_return
  55 .Nd retrieve return status of asynchronous I/O operation (REALTIME)
  56 .Sh LIBRARY
  57 .Lb libc
  58 .Sh SYNOPSIS
  59 .In aio.h
  60 .Ft ssize_t
  61 .Fo aio_return
  62 .Fa "struct aiocb *aiocbp"
  63 .Fc
  64 .Sh DESCRIPTION
  65 The
  66 .Fn aio_return
  67 system call returns the final status of the asynchronous I/O request
  68 associated with the structure pointed to by
  69 .Fa aiocbp .
  70 .Pp
  71 The
  72 .Fn aio_return
  73 system call
  74 should only be called once, to obtain the final status of an asynchronous
  75 I/O operation (once
  76 .Xr aio_error 2
  77 returns something other than
  78 .Er EINPROGRESS) and to clean up system resources.
  79 However, if
  80 .Fn aio_return
  81 is not called at all,
  82 .Xr aio 4
  83 will leak resources.
  84 .Sh RETURN VALUES
  85 If the asynchronous I/O request has completed,
  86 the status is returned as described in
  87 .Xr read 2 ,
  88 .Xr write 2 ,
  89 or
  90 .Xr fsync 2 .
  91 On failure,
  92 .Fn aio_return
  93 returns
  94 .Dv -1
  95 and sets
  96 .Dv errno
  97 to indicate the error condition.
  98 .Sh ERRORS
  99 The
 100 .Fn aio_return
 101 system call will fail if:
 102 .Bl -tag -width Er
 103 .\" ==========
 104 .It Bq Er EINVAL
 105 The
 106 .Fa aiocbp
 107 argument
 108 does not reference an outstanding asynchronous I/O request.
 109 .\" ==========
 110 .It Bq Er EINPROGRESS
 111 The asynchronous I/O request is still in progress.
 112 .El
 113 .Sh LEGACY SYNOPSIS
 114 .Fd #include <aio.h>
 115 .Pp
 116 .Ft int
 117 .br
 118 .Fo aio_return
 119 .Fa "struct aiocb *aiocbp"
 120 .Fc ;
 121 .Pp
 122 The type of the return value has changed.
 123 .Sh SEE ALSO
 124 .Xr aio_cancel 2 ,
 125 .Xr aio_error 2 ,
 126 .Xr aio_suspend 2 ,
 127 .Xr aio_write 2 ,
 128 .Xr fsync 2 ,
 129 .Xr read 2 ,
 130 .Xr write 2 ,
 131 .Xr aio 4 ,
 132 .Xr compat 5
 133 .Sh STANDARDS
 134 The
 135 .Fn aio_return
 136 system call
 137 is expected to conform to the
 138 .St -p1003.1
 139 standard.
 140 .Sh HISTORY
 141 The
 142 .Fn aio_return
 143 system call first appeared in
 144 .Fx 3.0 .
 145 .Sh AUTHORS
 146 This
 147 manual page was written by
 148 .An Wes Peters Aq wes@softweyr.com .