]> git.saurik.com Git - apple/xnu.git/blob - bsd/man/man2/aio_return.2
xnu-2782.30.5.tar.gz
[apple/xnu.git] / 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 .