Index for Section 3

Alphabetical listing for A

Bottom of page

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

SYNOPSIS
  #include <aio.h>

  int aio_write (
	  struct aiocb *aiocbp );

LIBRARY
  Asynchronous I/O Library (libaio, libaio_raw)

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 initiated, the
  function returns with an error status. If an error condition occurs during
  queuing, the function call returns without initiating 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_write
  functions to determine the error or return status of the asynchronous 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:

    ·  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.

    ·  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 values
  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.

SEE ALSO
  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

Index for Section 3

Alphabetical listing for A

Top of page