master
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
52#include <sys/_types/_off_t.h>
53#include <sys/_types/_ssize_t.h>
54
55/*
56 * A aio_fsync() options that the calling thread is to continue execution
57 * while the lio_listio() operation is being performed, and no notification
58 * is given when the operation is complete
59 *
60 * [XSI] from <fcntl.h>
61 */
62#include <sys/_types/_o_sync.h>
63#include <sys/_types/_o_dsync.h>
64
65struct aiocb {
66 int aio_fildes; /* File descriptor */
67 off_t aio_offset; /* File offset */
68 volatile void *aio_buf; /* Location of buffer */
69 size_t aio_nbytes; /* Length of transfer */
70 int aio_reqprio; /* Request priority offset */
71 struct sigevent aio_sigevent; /* Signal number and value */
72 int aio_lio_opcode; /* Operation to be performed */
73};
74
75
76/*
77 * aio_cancel() return values
78 */
79
80/*
81 * none of the requested operations could be canceled since they are
82 * already complete.
83 */
84#define AIO_ALLDONE 0x1
85
86/* all requested operations have been canceled */
87#define AIO_CANCELED 0x2
88
89/*
90 * some of the requested operations could not be canceled since
91 * they are in progress
92 */
93#define AIO_NOTCANCELED 0x4
94
95
96/*
97 * lio_listio operation options
98 */
99
100#define LIO_NOP 0x0 /* option indicating that no transfer is requested */
101#define LIO_READ 0x1 /* option requesting a read */
102#define LIO_WRITE 0x2 /* option requesting a write */
103
104/*
105 * lio_listio() modes
106 */
107
108/*
109 * A lio_listio() synchronization operation indicating
110 * that the calling thread is to continue execution while
111 * the lio_listio() operation is being performed, and no
112 * notification is given when the operation is complete
113 */
114#define LIO_NOWAIT 0x1
115
116/*
117 * A lio_listio() synchronization operation indicating
118 * that the calling thread is to suspend until the
119 * lio_listio() operation is complete.
120 */
121#define LIO_WAIT 0x2
122
123/*
124 * Maximum number of operations in single lio_listio call
125 */
126#define AIO_LISTIO_MAX 16
127
128
129/*
130 * Prototypes
131 */
132
133__BEGIN_DECLS
134
135/*
136 * Attempt to cancel one or more asynchronous I/O requests currently outstanding
137 * against file descriptor fd. The aiocbp argument points to the asynchronous I/O
138 * control block for a particular request to be canceled. If aiocbp is NULL, then
139 * all outstanding cancelable asynchronous I/O requests against fd shall be canceled.
140 */
141int aio_cancel( int fd,
142 struct aiocb * aiocbp );
143
144/*
145 * Return the error status associated with the aiocb structure referenced by the
146 * aiocbp argument. The error status for an asynchronous I/O operation is the errno
147 * value that would be set by the corresponding read(), write(), or fsync()
148 * operation. If the operation has not yet completed, then the error status shall
149 * be equal to [EINPROGRESS].
150 */
151int aio_error( const struct aiocb * aiocbp );
152
153/*
154 * Asynchronously force all I/O operations associated with the file indicated by
155 * the file descriptor aio_fildes member of the aiocb structure referenced by the
156 * aiocbp argument and queued at the time of the call to aio_fsync() to the
157 * synchronized I/O completion state. The function call shall return when the
158 * synchronization request has been initiated or queued. op O_SYNC is the only
159 * supported opertation at this time.
160 * The aiocbp argument refers to an asynchronous I/O control block. The aiocbp
161 * value may be used as an argument to aio_error() and aio_return() in order to
162 * determine the error status and return status, respectively, of the asynchronous
163 * operation while it is proceeding. When the request is queued, the error status
164 * for the operation is [EINPROGRESS]. When all data has been successfully
165 * transferred, the error status shall be reset to reflect the success or failure
166 * of the operation.
167 */
168int aio_fsync( int op,
169 struct aiocb * aiocbp );
170
171/*
172 * Read aiocbp->aio_nbytes from the file associated with aiocbp->aio_fildes into
173 * the buffer pointed to by aiocbp->aio_buf. The function call shall return when
174 * the read request has been initiated or queued.
175 * The aiocbp value may be used as an argument to aio_error() and aio_return() in
176 * order to determine the error status and return status, respectively, of the
177 * asynchronous operation while it is proceeding. If an error condition is
178 * encountered during queuing, the function call shall return without having
179 * initiated or queued the request. The requested operation takes place at the
180 * absolute position in the file as given by aio_offset, as if lseek() were called
181 * immediately prior to the operation with an offset equal to aio_offset and a
182 * whence equal to SEEK_SET. After a successful call to enqueue an asynchronous
183 * I/O operation, the value of the file offset for the file is unspecified.
184 */
185int aio_read( struct aiocb * aiocbp );
186
187/*
188 * Return the return status associated with the aiocb structure referenced by
189 * the aiocbp argument. The return status for an asynchronous I/O operation is
190 * the value that would be returned by the corresponding read(), write(), or
191 * fsync() function call. If the error status for the operation is equal to
192 * [EINPROGRESS], then the return status for the operation is undefined. The
193 * aio_return() function may be called exactly once to retrieve the return status
194 * of a given asynchronous operation; thereafter, if the same aiocb structure
195 * is used in a call to aio_return() or aio_error(), an error may be returned.
196 * When the aiocb structure referred to by aiocbp is used to submit another
197 * asynchronous operation, then aio_return() may be successfully used to
198 * retrieve the return status of that operation.
199 */
200ssize_t aio_return( struct aiocb * aiocbp );
201
202/*
203 * Suspend the calling thread until at least one of the asynchronous I/O
204 * operations referenced by the aiocblist argument has completed, until a signal
205 * interrupts the function, or, if timeout is not NULL, until the time
206 * interval specified by timeout has passed. If any of the aiocb structures
207 * in the aiocblist correspond to completed asynchronous I/O operations (that is,
208 * the error status for the operation is not equal to [EINPROGRESS]) at the
209 * time of the call, the function shall return without suspending the calling
210 * thread. The aiocblist argument is an array of pointers to asynchronous I/O
211 * control blocks. The nent argument indicates the number of elements in the
212 * array. Each aiocb structure pointed to has been used in initiating an
213 * asynchronous I/O request via aio_read(), aio_write(), or lio_listio(). This
214 * array may contain NULL pointers, which are ignored.
215 */
216int aio_suspend( const struct aiocb *const aiocblist[],
217 int nent,
218 const struct timespec * timeoutp ) __DARWIN_ALIAS_C(aio_suspend);
219
220/*
221 * Write aiocbp->aio_nbytes to the file associated with aiocbp->aio_fildes from
222 * the buffer pointed to by aiocbp->aio_buf. The function shall return when the
223 * write request has been initiated or, at a minimum, queued.
224 * The aiocbp argument may be used as an argument to aio_error() and aio_return()
225 * in order to determine the error status and return status, respectively, of the
226 * asynchronous operation while it is proceeding.
227 */
228int aio_write( struct aiocb * aiocbp );
229
230/*
231 * Initiate a list of I/O requests with a single function call. The mode
232 * argument takes one of the values LIO_WAIT or LIO_NOWAIT and determines whether
233 * the function returns when the I/O operations have been completed, or as soon
234 * as the operations have been queued. If the mode argument is LIO_WAIT, the
235 * function shall wait until all I/O is complete and the sig argument shall be
236 * ignored.
237 * If the mode argument is LIO_NOWAIT, the function shall return immediately, and
238 * asynchronous notification shall occur, according to the sig argument, when all
239 * the I/O operations complete. If sig is NULL, then no asynchronous notification
240 * shall occur.
241 */
242int lio_listio( int mode,
243 struct aiocb *const aiocblist[],
244 int nent,
245 struct sigevent *sigp );
246__END_DECLS
247
248#endif /* _SYS_AIO_H_ */