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 65 struct 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 */ 141 int 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 */ 151 int 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 */ 168 int 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 */ 185 int 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 */ 200 ssize_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 */ 216 int 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 */ 228 int 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 */ 242 int 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_ */