search..
No manual entry for -- in section 3
aio_read(3)		    Library Functions Manual		    aio_read(3)

NAME
       aio_read - asynchronous read

LIBRARY
       Real-time library (librt, -lrt)

SYNOPSIS
       #include <aio.h>

       int aio_read(struct aiocb *aiocbp);

DESCRIPTION
       The  aio_read()	function queues the I/O request described by the buffer
       pointed to by aiocbp.  This  function  is  the  asynchronous  analog  of
       read(2).	 The arguments of the call

	   read(fd, buf, count)

       correspond  (in order) to the fields aio_fildes, aio_buf, and aio_nbytes
       of the structure pointed to by aiocbp.  (See aio(7) for a description of
       the aiocb structure.)

       The data is read starting at the absolute  position  aiocbp->aio_offset,
       regardless  of  the  file offset.  After the call, the value of the file
       offset is unspecified.

       The "asynchronous" means that this call returns as soon as  the	request
       has  been enqueued; the read may or may not have completed when the call
       returns.	 One tests for completion using aio_error(3).  The return  sta-
       tus  of	a  completed  I/O  operation  can be obtained by aio_return(3).
       Asynchronous notification of I/O completion can be obtained  by	setting
       aiocbp->aio_sigevent appropriately; see sigevent(3type) for details.

       If _POSIX_PRIORITIZED_IO is defined, and this file supports it, then the
       asynchronous  operation	is submitted at a priority equal to that of the
       calling process minus aiocbp->aio_reqprio.

       The field aiocbp->aio_lio_opcode is ignored.

       No data is read from a regular file beyond its maximum offset.

RETURN VALUE
       On success, 0 is returned.  On error, the request is not enqueued, -1 is
       returned, and errno is set to indicate the error.  If an	 error	is  de-
       tected only later, it will be reported via aio_return(3) (returns status
       -1)  and	 aio_error(3)  (error status--whatever one would have gotten in
       errno, such as EBADF).

ERRORS
       EAGAIN Out of resources.

       EBADF  aio_fildes is not a valid file descriptor open for reading.

       EINVAL One or more of aio_offset, aio_reqprio,  or  aio_nbytes  are  in-
	      valid.

       ENOSYS aio_read() is not implemented.

       EOVERFLOW
	      The  file	 is a regular file, we start reading before end-of-file
	      and want at least one byte, but the starting position is past the
	      maximum offset for this file.

ATTRIBUTES
       For an explanation of the terms used in this section, see attributes(7).
       +--------------------------------------------+---------------+---------+
       | Interface				    | Attribute	    | Value   |
       +--------------------------------------------+---------------+---------+
       | aio_read()				    | Thread safety | MT-Safe |
       +--------------------------------------------+---------------+---------+

STANDARDS
       POSIX.1-2008.

HISTORY
       glibc 2.1.  POSIX.1-2001.

NOTES
       It is a good idea to zero out the control block before use.  The control
       block must not be changed while the read operation is in progress.   The
       buffer area being read into must not be accessed during the operation or
       undefined  results  may	occur.	 The  memory areas involved must remain
       valid.

       Simultaneous I/O operations specifying the same aiocb structure	produce
       undefined results.

EXAMPLES
       See aio(7).

SEE ALSO
       aio_cancel(3),	aio_error(3),	aio_fsync(3),  aio_return(3),  aio_sus-
       pend(3), aio_write(3), lio_listio(3), aio(7)

Linux man-pages 6.9.1		   2024-05-02			    aio_read(3)