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 [[email protected]] 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 70 struct 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 83 struct 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 93 struct 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 103 struct 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 */ 181 int 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 */ 191 int 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 */ 208 int 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 */ 225 int 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 */ 240 ssize_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 */ 256 int 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 */ 268 int 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 */ 282 int 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