unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 lio_listio(2)						       lio_listio(2)




 NAME
      lio_listio() - start a list of asynchronous I/O operations

 SYNOPSIS
      #include <&lt&lt&lt;aio.h>&gt&gt&gt;

      int lio_listio(int mode, struct aiocb * const list[], int nent, struct
	   sigevent *sig);

 DESCRIPTION
      The lio_listio() function allows the calling process to request a list
      of asynchronous I/O operations with a single function call.  The
      function call returns when all operation requests have been enqueued
      for processing.  At this point, processing of the operations may
      proceed concurrently with execution of the calling process or thread.

      The list argument is an array of nent pointers to aiocb structures.
      Each aiocb in list is treated as if it were being handled in a
      separate call to aio_read() or aio_write() depending on the value of
      its aio_lio_opcode.  When aio_lio_opcode is LIO_READ, the aiocb is
      treated as though it had been referenced in a call to aio_read(), and
      the aio_fildes, aio_buf, and aio_nbytes fields are interpreted
      accordingly.  When aio_lio_opcode is LIO_WRITE, the aiocb is treated
      as though it had been referenced in a call to aio_write(), and the
      aio_fildes, aio_buf, and aio_nbytes fields are interpreted
      accordingly.  If aio_lio_opcode is LIO_NOP, nothing is enqueued.

      If an error condition is detected that prevents the list from being
      processed, lio_listio() returns -1 and sets errno to indicate the
      cause of the failure.  If any requests are enqueued by the call to
      lio_listio(), and mode is LIO_WAIT, then the function returns only
      after all enqueued operation requests have completed.  The sig
      argument of the call is ignored.	If mode is LIO_NOWAIT, the function
      returns as soon as all requests are enqueued.  The sigevent action
      specified by sig is performed after all enqueued requests have
      completed.

      Once the requested operations have been successfully enqueued, an
      aio_error() and aio_return() function referencing the corresponding
      aiocb from list must be used to determine their status and any error
      conditions, including those normally reported by read() or write(), as
      appropriate.  Requests remain enqueued and consume process and system
      resources until aio_return() is called for each one.

      Re-using or deallocating memory referred to by the list or any aiocb
      referenced in the list while an asynchronous I/O operation is
      outstanding (i.e. before aio_return() has been called) may produce
      unpredictable results.

      To use this function, link in the realtime library by specifying -lrt
      on the compiler or linker command line.



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 lio_listio(2)						       lio_listio(2)




 RETURN VALUE
      When LIO_NOWAIT is set, lio_listio() returns the following values:

	    0		  Success.  All of the non-empty operations, if any,
			  were successfully enqueued.

	   -1		  Failure or partial success.  At least one
			  requested operation was either not enqueued or
			  completed with an error before the lio_listio()
			  function call returned.  errno is set to indicate
			  the error.

      When LIO_WAIT is set, lio_listio() returns the following values:

	    0		  Success.  All of the non-empty operations, if any,
			  were successfully enqueued and completed.

	   -1		  Failure or partial success.  At least one
			  requested operation was either not enqueued or
			  completed with an error.  errno is set to indicate
			  the error.

      The three errno values EAGAIN, EINTR, and EIO are the only ones
      associated with partial success.	aio_error() and aio_return() must be
      used to determine the outcomes of individual requests.

 ERRORS
      If lio_listio() detects one of the following error conditions, errno
      is set to the indicated value:

	   [EAGAIN]	  At least one request could not be queued either
			  because of a resource shortage or because the
			  per-process or system-wide limit on asynchronous
			  I/O operations or asynchronous threads would have
			  been exceeded.

	   [EINVAL]	  The sigevent specified by sig is not valid.

	   [EINVAL]	  The mode argument is neither LIO_WAIT nor
			  LIO_NOWAIT.

	   [EINVAL]	  The value of the nent argument is negative or
			  greater than the maximum value allowed. The
			  maximum value allowed can be obtained using the
			  sysconf() call with the argument
			  _SC_AIO_LISTIO_MAX.

	   [EINTR]	  The mode argument was LIO_WAIT and a signal was
			  delivered while waiting for the requested
			  operations to complete.  This signal may result
			  from completion of one or more of the requested



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 lio_listio(2)						       lio_listio(2)




			  operations and other requests may still be pending
			  or completed.

      Once an operation has been enqueued by lio_listio(), the following
      errors, in addition to all of the errors normally reported by the
      appropriate read() or write() function, may be reported asynchronously
      by a subsequent call to aio_error() or aio_return() referencing its
      aiocbp.

	   [EBADF]	  The aiocbp->&gt&gt&gt;aio_fildes was not a valid file
			  descriptor open for reading or writing as
			  appropriate to the aio_lio_opcode.

	   [EINVAL]	  The value of aiocbp->&gt&gt&gt;aio_reqprio is not valid, or
			  the value of aiocbp->&gt&gt&gt;aio_nbytes is invalid, or the
			  file offset implied by aiocbp->&gt&gt&gt;aio_offset or
			  aiocbp->&gt&gt&gt;aio_offset+aiocbp->&gt&gt&gt;aio_nbytes is not
			  valid.

	   [EIO]	  One or more of the enqueued operations did not
			  complete successfully.

 EXAMPLE
      The following code sequence and call to lio_listio() starts two
      asynchronous write operations and one asynchronous read operation and
      waits for all operations to complete.

	   #include <&lt&lt&lt;fcntl.h>&gt&gt&gt;
	   #include <&lt&lt&lt;errno.h>&gt&gt&gt;
	   #include <&lt&lt&lt;aio.h>&gt&gt&gt;
	   char buf1[4096], buf2[4096], buf3[4096];
	   int nent;
	   struct aiocb myaiocb1, myaiocb2, myaiocb3;
	   struct aiocb *list[] = { &&amp&amp&amp;myaiocb1, &&amp&amp&amp;myaiocb2, &&amp&amp&amp;myaiocb3 };
	   bzero( &&amp&amp&amp;myaiocb1, sizeof (struct aiocb));
	   bzero( &&amp&amp&amp;myaiocb2, sizeof (struct aiocb));
	   bzero( &&amp&amp&amp;myaiocb3, sizeof (struct aiocb));
	   myaiocb1.aio_fildes = open( "/dev/null", O_RDWR);
	   myaiocb3.aio_fildes = myaiocb2.aio_fildes = myaiocb1.aio_fildes;
	   myaiocb1.aio_offset = 0;
	   myaiocb3.aio_offset = myaiocb2.aio_offset = myaiocb1.aio_offset;
	   myaiocb1.aio_buf = (void *) buf1;
	   myaiocb2.aio_buf = (void *) buf2;
	   myaiocb3.aio_buf = (void *) buf3;
	   myaiocb3.aio_nbytes = sizeof (buf3);
	   myaiocb2.aio_nbytes = sizeof (buf2);
	   myaiocb1.aio_nbytes = sizeof (buf1);
	   myaiocb1.aio_lio_opcode = myaiocb3.aio_lio_opcode = LIO_WRITE;
	   myaiocb2.aio_lio_opcode = LIO_READ;
	   myaiocb1.aio_sigevent.sigev_notify = SIGEV_NONE;
	   myaiocb2.aio_sigevent.sigev_notify = SIGEV_NONE;



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 lio_listio(2)						       lio_listio(2)




	   myaiocb3.aio_sigevent.sigev_notify = SIGEV_NONE;
	   retval = lio_listio( LIO_WAIT, list, 3, NULL );
	   if (retval) perror("lio_listio:");
	   while ( nent-- ) { (void) aio_return( list[nent] ); }

 SEE ALSO
      aio_cancel(2), aio_error(2), aio_fsync(2), aio_read(2), aio_return(2),
      aio_suspend(2), aio_write(2), read(2), write(2), aio(5).

 STANDARDS CONFORMANCE
      lio_listio(): POSIX Realtime Extensions, IEEE Std 1003.1b











































 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000