bsd/sys/aio.h

   1 /*
   2  * Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*
  23  *      File:   sys/aio.h
  24  *      Author: Umesh Vaishampayan [umeshv@apple.com]
  25  *                      05-Feb-2003     umeshv  Created.
  26  *
  27  *      Header file for POSIX Asynchronous IO APIs
  28  *
  29  */
  30
  31 #ifndef _SYS_AIO_H_
  32 #define _SYS_AIO_H_
  33
  34 #include <sys/signal.h>
  35
  36 struct aiocb {
  37         int                                     aio_fildes;             /* File descriptor */
  38         off_t                           aio_offset;             /* File offset */
  39         volatile void           *aio_buf;               /* Location of buffer */
  40         size_t                          aio_nbytes;             /* Length of transfer */
  41         int                                     aio_reqprio;    /* Request priority offset */
  42         struct sigevent         aio_sigevent;   /* Signal number and value */
  43         int                                     aio_lio_opcode; /* Operation to be performed */
  44 };
  45
  46 /*
  47  * aio_cancel() return values
  48  */
  49
  50 /*
  51  * none of the requested operations could be canceled since they are
  52  * already complete.
  53  */
  54 #define AIO_ALLDONE                     0x1
  55
  56 /* all requested operations have been canceled */
  57 #define AIO_CANCELED            0x2
  58
  59 /*
  60  * some of the requested operations could not be canceled since
  61  * they are in progress
  62  */
  63 #define AIO_NOTCANCELED         0x4
  64
  65
  66 /*
  67  * lio_listio operation options
  68  */
  69
  70 #define LIO_NOP                 0x0     /* option indicating that no transfer is requested */
  71 #define LIO_READ                0x1             /* option requesting a read */
  72 #define LIO_WRITE               0x2             /* option requesting a write */
  73
  74 /*
  75  * lio_listio() modes
  76  */
  77
  78 /*
  79  * A lio_listio() synchronization operation indicating
  80  * that the calling thread is to continue execution while
  81  * the lio_listio() operation is being performed, and no
  82  * notification is given when the operation is complete
  83  */
  84 #define LIO_NOWAIT              0x1
  85
  86 /*
  87  * A lio_listio() synchronization operation indicating
  88  * that the calling thread is to suspend until the
  89  * lio_listio() operation is complete.
  90  */
  91 #define LIO_WAIT                0x2
  92
  93 /*
  94  * Maximum number of operations in single lio_listio call
  95  */
  96 #define AIO_LISTIO_MAX          16
  97
  98 /*
  99  * A aio_fsync() options
 100  * that the calling thread is to continue execution while
 101  * the lio_listio() operation is being performed, and no
 102  * notification is given when the operation is complete
 103  */
 104
 105 #define O_SYNC                  0x0     /* queued IO is completed as if by fsync() */
 106 #if 0 /* O_DSYNC - NOT SUPPORTED */
 107 #define O_DSYNC                 0x1             /* queued async IO is completed as if by fdatasync() */
 108 #endif
 109
 110 #ifndef KERNEL
 111 /*
 112  * Prototypes
 113  */
 114
 115 /*
 116  * Attempt to cancel one or more asynchronous I/O requests currently outstanding
 117  * against file descriptor fd. The aiocbp argument points to the asynchronous I/O
 118  * control block for a particular request to be canceled.  If aiocbp is NULL, then
 119  * all outstanding cancelable asynchronous I/O requests against fd shall be canceled.
 120  */
 121 int             aio_cancel( int fd,
 122                                         struct aiocb * aiocbp );
 123
 124 /*
 125  * Return the error status associated with the aiocb structure referenced by the
 126  * aiocbp argument. The error status for an asynchronous I/O operation is the errno
 127  * value that would be set by the corresponding read(), write(),  or fsync()
 128  * operation.  If the operation has not yet completed, then the error status shall
 129  * be equal to [EINPROGRESS].
 130  */
 131 int             aio_error( const struct aiocb * aiocbp );
 132
 133 /*
 134  * Asynchronously force all I/O operations associated with the file indicated by
 135  * the file descriptor aio_fildes member of the aiocb structure referenced by the
 136  * aiocbp argument and queued at the time of the call to aio_fsync() to the
 137  * synchronized I/O completion state.  The function call shall return when the
 138  * synchronization request has been initiated or queued.  op O_SYNC is the only
 139  * supported opertation at this time.
 140  * The aiocbp argument refers to an asynchronous I/O control block. The aiocbp
 141  * value may be used as an argument to aio_error() and aio_return() in order to
 142  * determine the error status and return status, respectively, of the asynchronous
 143  * operation while it is proceeding.  When the request is queued, the error status
 144  * for the operation is [EINPROGRESS]. When all data has been successfully
 145  * transferred, the error status shall be reset to reflect the success or failure
 146  * of the operation.
 147  */
 148 int             aio_fsync( int op,
 149                                    struct aiocb * aiocbp );
 150
 151 /*
 152  * Read aiocbp->aio_nbytes from the file associated with aiocbp->aio_fildes into
 153  * the buffer pointed to by aiocbp->aio_buf.  The function call shall return when
 154  * the read request has been initiated or queued.
 155  * The aiocbp value may be used as an argument to aio_error() and aio_return() in
 156  * order to determine the error status and return status, respectively, of the
 157  * asynchronous operation while it is proceeding. If an error condition is
 158  * encountered during queuing, the function call shall return without having
 159  * initiated or queued the request. The requested operation takes place at the
 160  * absolute position in the file as given by aio_offset, as if lseek() were called
 161  * immediately prior to the operation with an offset equal to aio_offset and a
 162  * whence equal to SEEK_SET.  After a successful call to enqueue an asynchronous
 163  * I/O operation, the value of the file offset for the file is unspecified.
 164  */
 165 int             aio_read( struct aiocb * aiocbp );
 166
 167 /*
 168  * Return the return status associated with the aiocb structure referenced by
 169  * the aiocbp argument.  The return status for an asynchronous I/O operation is
 170  * the value that would be returned by the corresponding read(), write(), or
 171  * fsync() function call.  If the error status for the operation is equal to
 172  * [EINPROGRESS], then the return status for the operation is undefined.  The
 173  * aio_return() function may be called exactly once to retrieve the return status
 174  * of a given asynchronous operation; thereafter, if the same aiocb structure
 175  * is used in a call to aio_return() or aio_error(), an error may be returned.
 176  * When the aiocb structure referred to by aiocbp is used to submit another
 177  * asynchronous operation, then aio_return() may be successfully used to
 178  * retrieve the return status of that operation.
 179  */
 180 ssize_t aio_return( struct aiocb * aiocbp );
 181
 182 /*
 183  * Suspend the calling thread until at least one of the asynchronous I/O
 184  * operations referenced by the aiocblist argument has completed, until a signal
 185  * interrupts the function, or, if timeout is not NULL, until the time
 186  * interval specified by timeout has passed.  If any of the aiocb structures
 187  * in the aiocblist correspond to completed asynchronous I/O operations (that is,
 188  * the error status for the operation is not equal to [EINPROGRESS]) at the
 189  * time of the call, the function shall return without suspending the calling
 190  * thread.  The aiocblist argument is an array of pointers to asynchronous I/O
 191  * control blocks.  The nent argument indicates the number of elements in the
 192  * array.  Each aiocb structure pointed to has been used in initiating an
 193  * asynchronous I/O request via aio_read(), aio_write(), or lio_listio(). This
 194  * array may contain NULL pointers, which are ignored.
 195  */
 196 int             aio_suspend( const struct aiocb *const aiocblist[],
 197                                          int nent,
 198                                          const struct timespec * timeoutp );
 199
 200 /*
 201  * Write aiocbp->aio_nbytes to the file associated with aiocbp->aio_fildes from
 202  * the buffer pointed to by aiocbp->aio_buf.  The function shall return when the
 203  * write request has been initiated or, at a minimum, queued.
 204  * The aiocbp argument may be used as an argument to aio_error() and aio_return()
 205  * in order to determine the error status and return status, respectively, of the
 206  * asynchronous operation while it is proceeding.
 207  */
 208 int             aio_write( struct aiocb * aiocbp );
 209
 210 /*
 211  * Initiate a list of I/O requests with a single function call.  The mode
 212  * argument takes one of the values LIO_WAIT or LIO_NOWAIT and determines whether
 213  * the function returns when the I/O operations have been completed, or as soon
 214  * as the operations have been queued.  If the mode argument is LIO_WAIT, the
 215  * function shall wait until all I/O is complete and the sig argument shall be
 216  * ignored.
 217  * If the mode argument is LIO_NOWAIT, the function shall return immediately, and
 218  * asynchronous notification shall occur, according to the sig argument, when all
 219  * the I/O operations complete.  If sig is NULL, then no asynchronous notification
 220  * shall occur.
 221  */
 222 int             lio_listio( int mode,
 223                                         struct aiocb *const aiocblist[],
 224                                         int nent,
 225                                         struct sigevent *sigp );
 226 #endif /* KERNEL */
 227 #endif /* _SYS_AIO_H_ */