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