bsd/sys/aio.h

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