bsd/sys/aio.h

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