aio_write(3)						     Library Functions Manual						      aio_write(3)

NAME

       aio_write - Queues a single asynchronous write request (P1003.1b)

LIBRARY

       Asynchronous I/O Library (libaio, libaio_raw)

SYNOPSIS

       #include <aio.h>

       int aio_write (	    struct aiocb *aiocbp );

PARAMETERS

       *aiocbp	   A pointer to an aiocb structure.

DESCRIPTION

       The  aio_write function allows the calling process to asynchronously write aiocbp->aio_nbytes to the file, raw disk partition, or connected
       socket associated with aiocbp->aio_fildes from the buffer pointed to by aiocbp->aio_buf.

       The aio_write function issues a write request and returns, even when the data cannot be written immediately. If the request cannot be  ini-
       tiated,	the function returns with an error status. If an error condition occurs during queuing, the function call returns without initiat-
       ing the queue request.

       The aiocbp argument points to an asynchronous control block structure, aiocb, used in the asynchronous I/O interfaces.  The aiocb structure
       contains  asynchronous  operation information, such as the number of bytes for the write operation and the buffer containing the data to be
       written to the file descriptor specified in the aio_fildes member of the aiocb structure.

       The aiocbp value can be used as an argument to the aio_error and aio_return functions to determine the error or return status of the  asyn-
       chronous write operation.

       The aiocb structure has the following members:

       int	      aio_fildes;

       off_t	      aio_offset;

       volatile void  *aio_buf;

       size_t	      aio_nbytes;

       int	      aio_reqprio;

       struct sigevent
		      aio_sigevent;

       int	      aio_lio_opcode

       The  aio_fildes	member is the file descriptor (file, raw disk partition, or connected socket) on which the asynchronous operation is to be
       performed.

       If the file descriptor is for a file or raw disk partition and O_APPEND is set for the file descriptor, write operations append to the file
       in the same order as the calls were made.  If O_APPEND is not set, the requested operation takes place at the position in the file given by
       aio_offset (as if the lseek function were called prior to the operation with an offset equal to aio_offset and a whence set  to	SEEK_SET).
       After any asynchronous I/O operation, aio_offset member is undefined and must be set explicitly for every asynchronous I/O request.

       The aio_nbytes and aio_buf members are the same as the nbyte and buf arguments defined by the read, write, and fsync functions.

       The   aio_sigevent   member   of   the	aiocb	structure   defines  the  signal  generated  when  the	I/O  operation	is  complete.	If
       aio_sigevent.sigev_notify equals SIGEV_SIGNAL and aio_sigevent.sigev_signo is non-zero, a signal is generated when the  asynchronous  write
       operation has completed.

       The aio_lio_opcode and the aio_reqprio members are ignored by aio_write().

       Pending I/O operations are handled as follows:

	  o	 On  close,  _exit,  or exec, any I/O that was directed to a file system file, a tty device, or a streams device is canceled.  Any
		 I/O that was directed to any raw character device, excluding terminal and streams devices, is not canceled.

	  o	 On fork, no asynchronous I/O is inherited.

RETURN VALUES

       On an unsuccessful call, a value of -1 is returned and errno is set to indicate the type of error that occurred.

ERRORS

       The aio_write function fails under the following conditions:

       [EAGAIN]       The requested asynchronous I/O operation was not queued due to system resource limitations.

       [EBADF]	      The aiocbp->aio_fildes argument is not a valid file descriptor open for writing.

       [EINVAL]       The file offset value implied by aiocbp->aio_offset would be invalid, or aiocbp->aio_nbytes is an invalid value.

       If the I/O operation is successfully queued, a value of 0 (zero) is returned.  After successful queuing of aio_write, return and error val-
       ues are the same as for a call to the write function. One of the following additional errors may occur:

       [ECANCELED]	 The operation was canceled by aio_cancel.

       [EINVAL] 	 The offset in aio_offset is invalid for the file specified.

RELATED INFORMATION

       Functions:  close(2),  exec(2),	_exit(2),  fork(2),  lseek(2), read(2), write(2), aio_cancel(3), aio_error(3), aio_group_completion_np(3),
       aio_read(3), aio_results_np(3),	aio_suspend(3), aio_return(3), lio_listio(3)

       Guide to Realtime Programming delim off

																      aio_write(3)