*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> lio_listio (3)              



NAME    [Toc]    [Back]

     lio_listio, lio_listio64 -	linked asynchronous I/O	operations

C SYNOPSIS    [Toc]    [Back]

     #include <aio.h>

     int lio_listio(int	mode, aiocb_t *	const list[], int nent,	sigevent_t *sig);

     int lio_listio64(int mode,	aiocb64_t * const list[], int nent, sigevent_t *sig);

DESCRIPTION    [Toc]    [Back]

     The lio_listio function allows the	calling	process	to initiate a list of
     I/O requests with a single	function call.

     The lio_listio64()	function is identical to lio_listio() except that it
     takes an  array of	aiocb64_t * (see <aio.h>).  This structure allows for
     the specification of a file offset	greater	than 2 Gigabytes.

     The mode argument takes a value of	either 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	waits until all	I/O is complete	and
     the sig argument is ignored.

     If	the mode argument is LIO_NOWAIT, the function returns immediately, and
     signal delivery shall occur, according to the sig argument, when all the
     I/O operations complete. If sig is	NULL, then no signal delivery occurs
     at	the completion of all the items	in the list, however notifications for
     each item in the list will	happen according to their aiocb->aio_sigevent
     structures.  If sig is not	NULL then notification will happen according
     to	sig->sigev_notify when all items in the	list have completed their I/O

     If	sigev_notify is	SIGEV_NONE, then no notification will be posted	to the
     calling application.

     If	sigev_notify is	SIGEV_SIGNAL, then the signal specified	in sigev_signo
     will be sent to the calling process. If SA_SIGINFO	is set for the signal
     (see sigaction(2))	and the	signal is in the range of SIGRTMIN and
     SIGRTMAX then the signal will be queued to	the process and	the value in
     sigev_value will be the si_value in the generated signal.

     If	sigev_notify is	SIGEV_CALLBACK then the	function sigev_func will be
     called with sigev_value as	the argument. Only one callback	will be	called
     at	a time,	however	programs should	be careful to note that	a callback may
     be	run in parallel	with the calling process.

     If	sigev_notify is	SIGEV_THREAD then the function sigev_notify_function
     will be called by a new thread (see pthreads(5)) with sigev_value as the
     argument.	This thread is created when the	event arrives with the
     attributes	specified in sigev_notify_attributes except that it is
     automatically detached.  The calling process should ensure	there are

									Page 1


     sufficient	resources to create the	thread.

     The list argument is a pointer to an array	of pointers to aiocb
     structures. The array contains nent elements.

     The I/O requests enumerated by list are submitted in an unspecified order
     unless the	file was opened	with the O_APPEND in which case	the write
     operations	will happen in the order that they appear in the list.

     The aio_lio_opcode	field of each aiocb structure specifies	the operation
     to	be performed. The supported operations are LIO_READ, LIO_WRITE,	and
     LIO_NOP.  The LIO_NOP operation causes that list entry to be ignored. If
     the aio_lio_opcode	element	is equal to LIO_READ, then an I/O operation is
     submitted as if by	a call to aio_read() with the aiocbp equal to the
     address of	the aiocb structure. If	the aio_lio_opcode element is equal to
     LIO_WRITE,	then an	I/O operation is submitted as if by a call to
     aio_write() with the aiocbp equal to the address of the aiocb structure.

SEE ALSO    [Toc]    [Back]

     aio_read(3), aio_write(3),	aio_error(3), aio_return(3), aio_cancel(3),
     aio_sgi_init(3), aio_hold(3), aio_fsync(3), read(2), lseek(2), close(2),
     _exit(2), exec(2),	fork(2), pthreads(5).

DIAGNOSTICS    [Toc]    [Back]

     If	the mode argument has the value	LIO_NOWAIT, the	lio_listio() function
     returns the value 0 to the	calling	process	if the I/O operations are
     successfully queued; otherwise, the function shall	return the value -1
     and set errno to indicate the error.

     If	the mode argument has the value	LIO_WAIT, the lio_listio()function
     returns the value 0 to the	calling	process	when all the indicated I/O has
     completed successfully. Otherwise,	lio_listio() returns -1	to the calling
     process, and sets errno to	indicate the error.

     In	either case, the return	value only indicates the success or failure of
     the lio_listio() call itself, not the status of the individual I/O
     requests. In some cases one or more of the	I/O requests contained in the
     list may fail. Failure of an individual request does not prevent
     completion	of any other individual	request. To determine the outcome of
     each I/O request, the application shall examine the error status
     associated	with each aiocb	control	block.	The error statuses returned
     are identical to those returned as	the result of an aio_read(3) or
     aio_write(3) function.

     If	any of the following conditions	occur, the lio_listio()	function shall
     return -1 and set errno to	the corresponding value:

     [EAGAIN]	    The	resources necessary to queue all the I/O requests were
		    not	available. The application may check the error status
		    for	each aiocb to determine	the individual request(s) that

									Page 2


     [EAGAIN]	    The	number of entries indicated by nent would cause	the
		    system wide	limit _AIO_MAX to be exceeded.

     [EINVAL]	    The	mode argument is not a proper value. The value of nent
		    was	greater	than _AIO_LISTIO_MAX.

     [EINTR]	    A signal was delivered while waiting for all I/O requests
		    to complete	during a LIO_WAIT operation. Note that,	since
		    each I/O operation invoked by lio_listio() may possibly
		    provoke a signal when it completes,	this error return may
		    be caused by the completion	of one (or more) of the	very
		    I/O	operations being awaited. Outstanding I/O requests are
		    not	canceled, and the application shall examine each list
		    element to determine whether the request was initiated,
		    canceled or	completed.

     [EIO]	    One	or more	of the individual I/O operations failed. The
		    application	may check the error status for each aiocb
		    structure to determine the individual request(s) that
		    failed. It is not possible to receive this error return
		    when the mode argument to the lio_listio() request was

     In	addition to the	errors returned	by the lio_listio() function, if the
     lio_listio() function succeeds or fails with errors of EAGAIN, EINTR or
     ERIO, then	some of	the I/O	operations specified by	the list may have been
     initiated.	The I/O	operation indicated by each list element can encounter
     errors specific to	the individual read or write function being performed.
     In	this event, the	error status for each aiocb control block contains the
     associated	error code. The	error codes which can be set are the same as
     would be set by a read(2) or write(2) function, with the following	error
     codes possible:

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

     [ECANCELED]    The	requested I/O was canceled before the I/O completed
		    due	to an explicit aio_cancel(3) request.

     [EINPROGRESS]  The	requested I/O is in progress.

									PPPPaaaaggggeeee 3333
[ Back ]
 Similar pages
Name OS Title
lio_listio HP-UX start a list of asynchronous I/O operations
aio_results_np Tru64 Returns results for completed asynchronous I/O operations
aio_suspend FreeBSD suspend until asynchronous I/O operations or timeout complete (REALTIME)
aio_listio_max HP-UX the maximum number of POSIX asynchronous I/O operations that can be specified in a listio() call
aio_fsync HP-UX force outstanding asynchronous operations on a file to the synchronized state
SSL_get_rbio NetBSD get BIO linked to an SSL object
SSL_get_rbio OpenBSD get BIO linked to an SSL object
SSL_get_wbio OpenBSD get BIO linked to an SSL object
SSL_get_rbio Tru64 Get BIO linked to an SSL object
aio FreeBSD asynchronous I/O
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service