unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



 aio_write(2)							aio_write(2)




 NAME
      aio_write() - start asynchronous write operation

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

      int aio_write(struct aiocb *aiocbp);

 DESCRIPTION
      The aio_write() function allows the calling process to perform an
      asynchronous write to a previously opened file.  The function call
      returns when the write operation has been enqueued for processing.  At
      this point, processing of the write operation may proceed concurrently
      with execution of the calling process or thread.

      If an error condition is detected that prevents the write request from
      being enqueued, aio_write() returns -1 and sets errno to indicate the
      cause of the failure.  Once the write operation has been successfully
      enqueued, an aio_error() and aio_return() function referencing the
      aiocb referred to by aiocbp must be used to determine its status and
      any error conditions, including those normally reported by write().
      The request remains enqueued and consumes process and system resources
      until aio_return() is called.

      The aio_write() function allows the calling process to write aiocbp-
      >&gt&gt&gt;aio_nbytes to the file associated with aiocbp->&gt&gt&gt;aio_fildes from the
      buffer pointed to by aiocbp->&gt&gt&gt;aio_buf.  The priority of the write
      operation is reduced by the value of aiocbp->&gt&gt&gt;aio_reqprio, which must
      be a value between 0 (zero) and a maximum value which can be obtained
      using the sysconf() call with the argument _SC_AIO_PRIO_DELTA_MAX.  A
      value of 0 (zero) yields no reduction in priority. The aiocbp-
      >&gt&gt&gt;aio_lio_opcode field is ignored.

      When the O_APPEND flag is not set for the file, the write operation
      takes place at the absolute position in the file given by aiocbp-
      >&gt&gt&gt;aio_offset, as if lseek() were called immediately prior to the
      operation with offset equal to aiocbp->&gt&gt&gt;aio_offset and whence set to
      SEEK_SET.	 When the O_APPEND flag is set for the file, aiocbp-
      >&gt&gt&gt;aio_offset is ignored, and asynchronous write operations append to
      the file in the same order as the requests were enqueued.	 The value
      of the file offset is never changed by asynchronous I/O operations.

      Deallocating or altering the contents of memory referred to by aiocbp
      while an asynchronous write operation is outstanding (i.e. before
      aio_return() has been called) may produce unpredictable results.

      If aiocbp->&gt&gt&gt;aio_sigevent is a valid signal event structure, then the
      designated signal will be delivered when the requested asynchronous
      write operation completes.





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






 aio_write(2)							aio_write(2)




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

 RETURN VALUE
      aio_write() returns the following values:

	    0	Successful completion, the operation has been enqueued.

	   -1	Failure.  The requested operation was not enqueued.  errno
		is set to indicate the error.

      The return value from aio_write() reflects the success or failure of
      enqueuing the requested write operation for asynchronous processing.
      aio_write() fails if an error in the function call is immediately
      detected, or if system resource limits prevent the request from being
      enqueued.	 All other error conditions are reported asynchronously and
      must be retrieved with aio_error() and aio_return().

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

	   [EAGAIN]	  The 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.

	   [EEXIST]	  The aiocbp is already in use for another
			  asynchronous I/O operation.

      Once the write request has been enqueued by aio_write(), the following
      errors, in addition to all of the errors normally reported by the
      write() function, may be reported asynchronously by a subsequent call
      to aio_error() or aio_return() referencing its aiocb.

	   [EBADF]	  The aiocbp->&gt&gt&gt;aio_fildes was not a valid file
			  descriptor open for writing.

	   [EINVAL]	  The aiocb->&gt&gt&gt;aio_sigevent is not a valid address in
			  the process virtual address space.

	   [EINVAL]	  The parameters of the indicated sigevent in
			  aiocb->&gt&gt&gt;aio_sigevent are invalid.

	   [EINVAL]	  The value of aiocbp->&gt&gt&gt;aio_reqprio is not valid.

	   [EINVAL]	  The value of aiocbp->&gt&gt&gt;aio_nbytes is invalid.

	   [EINVAL]	  The file offset implied by aiocbp->&gt&gt&gt;aio_offset or
			  aiocbp->&gt&gt&gt;aio_offset+ aiocbp->&gt&gt&gt;aio_nbytes are not
			  valid for the file at the time the request is



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






 aio_write(2)							aio_write(2)




			  processed.

	   [ECANCELED]	  The write operation was canceled due to a
			  subsequent call to aio_cancel() referencing the
			  same aiocb that was used to start the operation.

 EXAMPLE
      The following code sequence and call to aio_write() starts an
      asynchronous write operation.

	   #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 buf[4096];
	   int retval; ssize_t nbytes;
	   struct aiocb myaiocb;
	   bzero( &&amp&amp&amp;myaiocb, sizeof (struct aiocb));
	   bzero( &&amp&amp&amp;buf, sizeof (buf));
	   myaiocb.aio_fildes = open( "/dev/null", O_RDWR);
	   myaiocb.aio_offset = 0;
	   myaiocb.aio_buf = (void *) buf;
	   myaiocb.aio_nbytes = sizeof (buf);
	   myaiocb.aio_sigevent.sigev_notify = SIGEV_NONE;
	   retval = aio_write( &&amp&amp&amp;myaiocb );
	   if (retval) perror("aio_write:");
	   /* continue processing */
	    ...
	   /* wait for completion */
	   while ( (retval = aio_error( &&amp&amp&amp;myaiocb) ) == EINPROGRESS) ;
	   /* free the aiocb */
	   nbytes = aio_return( &&amp&amp&amp;myaiocb);

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

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
















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