1/*
2 * Copyright (c) 2003-2006 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_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. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28/*
29 * File: sys/aio.h
30 * Author: Umesh Vaishampayan [umeshv@apple.com]
31 * 05-Feb-2003 umeshv Created.
32 *
33 * Header file for POSIX Asynchronous IO APIs
34 *
35 */
36
37#ifndef _SYS_AIO_H_
38#define _SYS_AIO_H_
39
40#include <sys/signal.h>
41#include <sys/_types.h>
42#include <sys/cdefs.h>
43
44/*
45 * [XSI] Inclusion of the <aio.h> header may make visible symbols defined
46 * in the headers <fcntl.h>, <signal.h>, <sys/types.h>, and <time.h>.
47 *
48 * In our case, this is limited to struct timespec, off_t and ssize_t.
49 */
50#include <sys/_types/_timespec.h>
51#ifdef KERNEL
52#include <sys/_types/_user64_timespec.h>
53#include <sys/_types/_user32_timespec.h>
54#endif /* KERNEL */
55
56#include <sys/_types/_off_t.h>
57#include <sys/_types/_ssize_t.h>
58
59/*
60 * A aio_fsync() options that the calling thread is to continue execution
61 * while the lio_listio() operation is being performed, and no notification
62 * is given when the operation is complete
63 *
64 * [XSI] from <fcntl.h>
65 */
66#include <sys/_types/_o_sync.h>
67#include <sys/_types/_o_dsync.h>
68
69#ifndef KERNEL
70struct aiocb {
71 int aio_fildes; /* File descriptor */
72 off_t aio_offset; /* File offset */
73 volatile void *aio_buf; /* Location of buffer */
74 size_t aio_nbytes; /* Length of transfer */
75 int aio_reqprio; /* Request priority offset */
76 struct sigevent aio_sigevent; /* Signal number and value */
77 int aio_lio_opcode; /* Operation to be performed */
78};
79#endif /* KERNEL */
80
81#ifdef KERNEL
82
83struct user_aiocb {
84 int aio_fildes; /* File descriptor */
85 off_t aio_offset; /* File offset */
86 user_addr_t aio_buf; /* Location of buffer */
87 user_size_t aio_nbytes; /* Length of transfer */
88 int aio_reqprio; /* Request priority offset */
89 struct user_sigevent aio_sigevent; /* Signal number and value */
90 int aio_lio_opcode; /* Operation to be performed */
91};
92
93struct user64_aiocb {
94 int aio_fildes; /* File descriptor */
95 user64_off_t aio_offset; /* File offset */
96 user64_addr_t aio_buf; /* Location of buffer */
97 user64_size_t aio_nbytes; /* Length of transfer */
98 int aio_reqprio; /* Request priority offset */
99 struct user64_sigevent aio_sigevent; /* Signal number and value */
100 int aio_lio_opcode; /* Operation to be performed */
101};
102
103struct user32_aiocb {
104 int aio_fildes; /* File descriptor */
105 user32_off_t aio_offset; /* File offset */
106 user32_addr_t aio_buf; /* Location of buffer */
107 user32_size_t aio_nbytes; /* Length of transfer */
108 int aio_reqprio; /* Request priority offset */
109 struct user32_sigevent aio_sigevent; /* Signal number and value */
110 int aio_lio_opcode; /* Operation to be performed */
111};
112
113#endif // KERNEL
114
115/*
116 * aio_cancel() return values
117 */
118
119/*
120 * none of the requested operations could be canceled since they are
121 * already complete.
122 */
123#define AIO_ALLDONE 0x1
124
125/* all requested operations have been canceled */
126#define AIO_CANCELED 0x2
127
128/*
129 * some of the requested operations could not be canceled since
130 * they are in progress
131 */
132#define AIO_NOTCANCELED 0x4
133
134
135/*
136 * lio_listio operation options
137 */
138
139#define LIO_NOP 0x0 /* option indicating that no transfer is requested */
140#define LIO_READ 0x1 /* option requesting a read */
141#define LIO_WRITE 0x2 /* option requesting a write */
142
143/*
144 * lio_listio() modes
145 */
146
147/*
148 * A lio_listio() synchronization operation indicating
149 * that the calling thread is to continue execution while
150 * the lio_listio() operation is being performed, and no
151 * notification is given when the operation is complete
152 */
153#define LIO_NOWAIT 0x1
154
155/*
156 * A lio_listio() synchronization operation indicating
157 * that the calling thread is to suspend until the
158 * lio_listio() operation is complete.
159 */
160#define LIO_WAIT 0x2
161
162/*
163 * Maximum number of operations in single lio_listio call
164 */
165#define AIO_LISTIO_MAX 16
166
167
168#ifndef KERNEL
169/*
170 * Prototypes
171 */
172
173__BEGIN_DECLS
174
175/*
176 * Attempt to cancel one or more asynchronous I/O requests currently outstanding
177 * against file descriptor fd. The aiocbp argument points to the asynchronous I/O
178 * control block for a particular request to be canceled. If aiocbp is NULL, then
179 * all outstanding cancelable asynchronous I/O requests against fd shall be canceled.
180 */
181int aio_cancel( int fd,
182 struct aiocb * aiocbp );
183
184/*
185 * Return the error status associated with the aiocb structure referenced by the
186 * aiocbp argument. The error status for an asynchronous I/O operation is the errno
187 * value that would be set by the corresponding read(), write(), or fsync()
188 * operation. If the operation has not yet completed, then the error status shall
189 * be equal to [EINPROGRESS].
190 */
191int aio_error( const struct aiocb * aiocbp );
192
193/*
194 * Asynchronously force all I/O operations associated with the file indicated by
195 * the file descriptor aio_fildes member of the aiocb structure referenced by the
196 * aiocbp argument and queued at the time of the call to aio_fsync() to the
197 * synchronized I/O completion state. The function call shall return when the
198 * synchronization request has been initiated or queued. op O_SYNC is the only
199 * supported opertation at this time.
200 * The aiocbp argument refers to an asynchronous I/O control block. The aiocbp
201 * value may be used as an argument to aio_error() and aio_return() in order to
202 * determine the error status and return status, respectively, of the asynchronous
203 * operation while it is proceeding. When the request is queued, the error status
204 * for the operation is [EINPROGRESS]. When all data has been successfully
205 * transferred, the error status shall be reset to reflect the success or failure
206 * of the operation.
207 */
208int aio_fsync( int op,
209 struct aiocb * aiocbp );
210
211/*
212 * Read aiocbp->aio_nbytes from the file associated with aiocbp->aio_fildes into
213 * the buffer pointed to by aiocbp->aio_buf. The function call shall return when
214 * the read request has been initiated or queued.
215 * The aiocbp value may be used as an argument to aio_error() and aio_return() in
216 * order to determine the error status and return status, respectively, of the
217 * asynchronous operation while it is proceeding. If an error condition is
218 * encountered during queuing, the function call shall return without having
219 * initiated or queued the request. The requested operation takes place at the
220 * absolute position in the file as given by aio_offset, as if lseek() were called
221 * immediately prior to the operation with an offset equal to aio_offset and a
222 * whence equal to SEEK_SET. After a successful call to enqueue an asynchronous
223 * I/O operation, the value of the file offset for the file is unspecified.
224 */
225int aio_read( struct aiocb * aiocbp );
226
227/*
228 * Return the return status associated with the aiocb structure referenced by
229 * the aiocbp argument. The return status for an asynchronous I/O operation is
230 * the value that would be returned by the corresponding read(), write(), or
231 * fsync() function call. If the error status for the operation is equal to
232 * [EINPROGRESS], then the return status for the operation is undefined. The
233 * aio_return() function may be called exactly once to retrieve the return status
234 * of a given asynchronous operation; thereafter, if the same aiocb structure
235 * is used in a call to aio_return() or aio_error(), an error may be returned.
236 * When the aiocb structure referred to by aiocbp is used to submit another
237 * asynchronous operation, then aio_return() may be successfully used to
238 * retrieve the return status of that operation.
239 */
240ssize_t aio_return( struct aiocb * aiocbp );
241
242/*
243 * Suspend the calling thread until at least one of the asynchronous I/O
244 * operations referenced by the aiocblist argument has completed, until a signal
245 * interrupts the function, or, if timeout is not NULL, until the time
246 * interval specified by timeout has passed. If any of the aiocb structures
247 * in the aiocblist correspond to completed asynchronous I/O operations (that is,
248 * the error status for the operation is not equal to [EINPROGRESS]) at the
249 * time of the call, the function shall return without suspending the calling
250 * thread. The aiocblist argument is an array of pointers to asynchronous I/O
251 * control blocks. The nent argument indicates the number of elements in the
252 * array. Each aiocb structure pointed to has been used in initiating an
253 * asynchronous I/O request via aio_read(), aio_write(), or lio_listio(). This
254 * array may contain NULL pointers, which are ignored.
255 */
256int aio_suspend( const struct aiocb *const aiocblist[],
257 int nent,
258 const struct timespec * timeoutp ) __DARWIN_ALIAS_C(aio_suspend);
259
260/*
261 * Write aiocbp->aio_nbytes to the file associated with aiocbp->aio_fildes from
262 * the buffer pointed to by aiocbp->aio_buf. The function shall return when the
263 * write request has been initiated or, at a minimum, queued.
264 * The aiocbp argument may be used as an argument to aio_error() and aio_return()
265 * in order to determine the error status and return status, respectively, of the
266 * asynchronous operation while it is proceeding.
267 */
268int aio_write( struct aiocb * aiocbp );
269
270/*
271 * Initiate a list of I/O requests with a single function call. The mode
272 * argument takes one of the values LIO_WAIT or LIO_NOWAIT and determines whether
273 * the function returns when the I/O operations have been completed, or as soon
274 * as the operations have been queued. If the mode argument is LIO_WAIT, the
275 * function shall wait until all I/O is complete and the sig argument shall be
276 * ignored.
277 * If the mode argument is LIO_NOWAIT, the function shall return immediately, and
278 * asynchronous notification shall occur, according to the sig argument, when all
279 * the I/O operations complete. If sig is NULL, then no asynchronous notification
280 * shall occur.
281 */
282int lio_listio( int mode,
283 struct aiocb *const aiocblist[],
284 int nent,
285 struct sigevent *sigp );
286__END_DECLS
287
288#endif /* KERNEL */
289#endif /* _SYS_AIO_H_ */
290