bsd/sys/aio.h

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