[apple/xnu.git] / bsd / sys / aio.h

/*
 * Copyright (c) 2003-2005 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 * 
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */
/* 
 *	File:	sys/aio.h
 *	Author:	Umesh Vaishampayan [umeshv@apple.com]
 *			05-Feb-2003	umeshv	Created.
 *
 *	Header file for POSIX Asynchronous IO APIs
 *
 */ 

#ifndef _SYS_AIO_H_
#define	_SYS_AIO_H_

#include <sys/signal.h>
#include <sys/cdefs.h>

struct aiocb {
	int					aio_fildes;		/* File descriptor */
	off_t				aio_offset;		/* File offset */
	volatile void		*aio_buf;		/* Location of buffer */
	size_t				aio_nbytes;		/* Length of transfer */
	int					aio_reqprio;	/* Request priority offset */
	struct sigevent		aio_sigevent;	/* Signal number and value */
	int					aio_lio_opcode;	/* Operation to be performed */
};

// LP64todo - should this move?
#ifdef KERNEL

struct user_aiocb {
	int					aio_fildes;		/* File descriptor */
	off_t				aio_offset;		/* File offset */
	user_addr_t			aio_buf __attribute((aligned(8)));		/* Location of buffer */
	user_size_t			aio_nbytes;		/* Length of transfer */
	int					aio_reqprio;	/* Request priority offset */
	struct user_sigevent aio_sigevent __attribute((aligned(8)));	/* Signal number and value */
	int					aio_lio_opcode;	/* Operation to be performed */
};

#endif // KERNEL

/*
 * aio_cancel() return values
 */

/*
 * none of the requested operations could be canceled since they are
 * already complete.
 */
#define	AIO_ALLDONE			0x1

/* all requested operations have been canceled */
#define	AIO_CANCELED		0x2

/*
 * some of the requested operations could not be canceled since
 * they are in progress
 */
#define	AIO_NOTCANCELED		0x4


/*
 * lio_listio operation options
 */

#define	LIO_NOP			0x0 	/* option indicating that no transfer is requested */
#define	LIO_READ		0x1		/* option requesting a read */
#define	LIO_WRITE		0x2		/* option requesting a write */

/*
 * lio_listio() modes
 */

/*
 * A lio_listio() synchronization operation indicating
 * that the calling thread is to continue execution while
 * the lio_listio() operation is being performed, and no
 * notification is given when the operation is complete
 */
#define	LIO_NOWAIT		0x1

/*
 * A lio_listio() synchronization operation indicating
 * that the calling thread is to suspend until the
 * lio_listio() operation is complete.
 */
#define	LIO_WAIT		0x2

/*
 * Maximum number of operations in single lio_listio call
 */
#define	AIO_LISTIO_MAX		16

/*
 * A aio_fsync() options
 * that the calling thread is to continue execution while
 * the lio_listio() operation is being performed, and no
 * notification is given when the operation is complete
 */

#ifndef O_SYNC	/* XXX investigate documentation error */
#define	O_SYNC			0x0080 	/* queued IO is completed as if by fsync() */
#endif
#if 0 /* O_DSYNC - NOT SUPPORTED */
#define	O_DSYNC			0x1		/* queued async IO is completed as if by fdatasync() */
#endif

#ifndef KERNEL
/*
 * Prototypes
 */

__BEGIN_DECLS

/*
 * Attempt to cancel one or more asynchronous I/O requests currently outstanding 
 * against file descriptor fd. The aiocbp argument points to the asynchronous I/O 
 * control block for a particular request to be canceled.  If aiocbp is NULL, then 
 * all outstanding cancelable asynchronous I/O requests against fd shall be canceled.
 */
int		aio_cancel( int fd, 
					struct aiocb * aiocbp );
					
/*
 * Return the error status associated with the aiocb structure referenced by the 
 * aiocbp argument. The error status for an asynchronous I/O operation is the errno 
 * value that would be set by the corresponding read(), write(),  or fsync()
 * operation.  If the operation has not yet completed, then the error status shall 
 * be equal to [EINPROGRESS].
 */
int		aio_error( const struct aiocb * aiocbp );

/*
 * Asynchronously force all I/O operations associated with the file indicated by 
 * the file descriptor aio_fildes member of the aiocb structure referenced by the 
 * aiocbp argument and queued at the time of the call to aio_fsync() to the 
 * synchronized I/O completion state.  The function call shall return when the
 * synchronization request has been initiated or queued.  op O_SYNC is the only
 * supported opertation at this time.
 * The aiocbp argument refers to an asynchronous I/O control block. The aiocbp 
 * value may be used as an argument to aio_error() and aio_return() in order to 
 * determine the error status and return status, respectively, of the asynchronous 
 * operation while it is proceeding.  When the request is queued, the error status 
 * for the operation is [EINPROGRESS]. When all data has been successfully 
 * transferred, the error status shall be reset to reflect the success or failure 
 * of the operation.
 */
int		aio_fsync( int op, 
				   struct aiocb * aiocbp );
				   
/*
 * Read aiocbp->aio_nbytes from the file associated with aiocbp->aio_fildes into 
 * the buffer pointed to by aiocbp->aio_buf.  The function call shall return when 
 * the read request has been initiated or queued.
 * The aiocbp value may be used as an argument to aio_error() and aio_return() in 
 * order to determine the error status and return status, respectively, of the 
 * asynchronous operation while it is proceeding. If an error condition is 
 * encountered during queuing, the function call shall return without having 
 * initiated or queued the request. The requested operation takes place at the 
 * absolute position in the file as given by aio_offset, as if lseek() were called 
 * immediately prior to the operation with an offset equal to aio_offset and a 
 * whence equal to SEEK_SET.  After a successful call to enqueue an asynchronous 
 * I/O operation, the value of the file offset for the file is unspecified.
 */
int		aio_read( struct aiocb * aiocbp );

/*
 * Return the return status associated with the aiocb structure referenced by 
 * the aiocbp argument.  The return status for an asynchronous I/O operation is 
 * the value that would be returned by the corresponding read(), write(), or 
 * fsync() function call.  If the error status for the operation is equal to 
 * [EINPROGRESS], then the return status for the operation is undefined.  The 
 * aio_return() function may be called exactly once to retrieve the return status 
 * of a given asynchronous operation; thereafter, if the same aiocb structure 
 * is used in a call to aio_return() or aio_error(), an error may be returned. 
 * When the aiocb structure referred to by aiocbp is used to submit another
 * asynchronous operation, then aio_return() may be successfully used to 
 * retrieve the return status of that operation.
 */
ssize_t	aio_return( struct aiocb * aiocbp );

/*
 * Suspend the calling thread until at least one of the asynchronous I/O 
 * operations referenced by the aiocblist argument has completed, until a signal 
 * interrupts the function, or, if timeout is not NULL, until the time 
 * interval specified by timeout has passed.  If any of the aiocb structures 
 * in the aiocblist correspond to completed asynchronous I/O operations (that is, 
 * the error status for the operation is not equal to [EINPROGRESS]) at the 
 * time of the call, the function shall return without suspending the calling 
 * thread.  The aiocblist argument is an array of pointers to asynchronous I/O 
 * control blocks.  The nent argument indicates the number of elements in the 
 * array.  Each aiocb structure pointed to has been used in initiating an 
 * asynchronous I/O request via aio_read(), aio_write(), or lio_listio(). This 
 * array may contain NULL pointers, which are ignored.
 */
int		aio_suspend( const struct aiocb *const aiocblist[], 
					 int nent,
	 				 const struct timespec * timeoutp );
	 				 
/*
 * Write aiocbp->aio_nbytes to the file associated with aiocbp->aio_fildes from 
 * the buffer pointed to by aiocbp->aio_buf.  The function shall return when the 
 * write request has been initiated or, at a minimum, queued.
 * The aiocbp argument may be used as an argument to aio_error() and aio_return() 
 * in order to determine the error status and return status, respectively, of the 
 * asynchronous operation while it is proceeding.
 */
int		aio_write( struct aiocb * aiocbp );

/*
 * Initiate a list of I/O requests with a single function call.  The mode 
 * argument takes one of the values LIO_WAIT or LIO_NOWAIT and determines whether 
 * the function returns when the I/O operations have been completed, or as soon 
 * as the operations have been queued.  If the mode argument is LIO_WAIT, the 
 * function shall wait until all I/O is complete and the sig argument shall be 
 * ignored. 
 * If the mode argument is LIO_NOWAIT, the function shall return immediately, and 
 * asynchronous notification shall occur, according to the sig argument, when all 
 * the I/O operations complete.  If sig is NULL, then no asynchronous notification
 * shall occur.
 */
int		lio_listio( int mode, 
					struct aiocb *const aiocblist[],
	 				int nent, 
	 				struct sigevent *sigp );
__END_DECLS

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