Index for Section 3

Alphabetical listing for A

Bottom of page

aio_read(3)
NAME
  aio_read - Queues a single asynchronous read request

SYNOPSIS
  #include <aio.h>

  int aio_read (
	  struct aiocb *aiocbp );

LIBRARY
  Asynchronous I/O Library (libaio, libaio_raw)

PARAMETERS
  *aiocbp
      A pointer to an aiocb structure.

DESCRIPTION
  The aio_read function allows the calling process to asynchronously read
  aiocbp->aio_nbytes from the file associated with aiocbp->aio_fildes into
  the buffer pointed to by aiocbp->aio_buf.

  The aio_read function issues a read request and returns even when the data
  cannot be delivered immediately. If the request cannot be initiated, the
  aio_read function returns with an error status. If an error condition
  occurs during queuing, the function call returns without initiating the
  queue request. The aiocbp value may be used as an argument to the aio_error
  and aio_return functions to determine the error or return status of the
  asynchronous read operation.

  The requested operation takes place at the absolute position in the file as
  given by aio_offset, as if lseek() were called immediately prior to the
  operation with an offset equal to aio_offset and a whence equal to
  SEEK_SET.

  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 file offset for
  the read 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 on which the asynchronous
  operation is to be performed. After any asynchronous I/O operation, the
  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 POSIX.1 read and write 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 read operation has completed.

  The aio_lio_opcode and aio_reqprio members are ignored by aio_read().

  Pending asynchronous 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_read 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
      reading.

  [EINVAL]
      The file offset value implied by aiocbp->aio_offset would be invalid.

  On a successful call, a value of 0 (zero) is returned and the I/O operation
  is queued. After successful queuing of aio_read, return and error values
  are the same as for a call to the read 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_results_np(3), aio_return(3), aio_suspend(3), aio_write(3),
  lio_listio(3)

  Guide to Realtime Programming

Index for Section 3

Alphabetical listing for A

Top of page