[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

aio_read or aio_read64 Subroutine

The aio_read or aio_read64 subroutine includes information for the POSIX AIO aio_read subroutine (as defined in the IEEE std 1003.1-2001), and the Legacy AIO aio_read subroutine.

POSIX AIO aio_read Subroutine

Purpose

Asynchronously reads a file.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h>

int aio_read (aiocbp)
struct aiocb *aiocbp;

Description

The aio_read subroutine reads aio_nbytes from the file associated with aio_fildes into the buffer pointed to by aio_buf. The subroutine returns when the read request has been initiated or queued to the file or device (even when the data cannot be delivered immediately).

The aiocbp value may be used as an argument to the aio_error and aio_return subroutines in order to determine the error status and return status, respectively, of the asynchronous operation while it is proceeding. If an error condition is encountered during queuing, the function call returns without having initiated or queued the request. The requested operation takes place at the absolute position in the file as given by aio_offset , as if the lseek subroutine were called immediately prior to the operation with an offset equal to aio_offset and a whence equal to SEEK_SET. After a successful call to enqueue an asynchronous I/O operation, the value of the file offset for the file is unspecified.

The aio_lio_opcode field is ignored by the aio_read subroutine.

Since prioritized I/O is not supported at this time the aio_reqprio field of the aiocb structure is not presently used.

The aiocbp parameter points to an aiocb structure. If the buffer pointed to by aio_buf or the control block pointed to by aiocbp becomes an illegal address prior to asynchronous I/O completion, the behavior is undefined.

Simultaneous asynchronous operations using the same aiocbp produce undefined results.

If synchronized I/O is enabled on the file associated with aio_fildes, the behavior of this subroutine is according to the definitions of synchronized I/O data integrity completion and synchronized I/O file integrity completion.

For any system action that changes the process memory space while an asynchronous I/O is outstanding, the result of that action is undefined.

For regular files, no data transfer occurs past the offset maximum established in the open file description.

Parameters

aiocbp Points to the aiocb structure associated with the I/O operation.

aiocb Structure

The aiocb structure is defined in the /usr/include/aio.h file and contains the following members:

int               aio_fildes
off_t             aio_offset
char             *aio_buf
size_t            aio_nbytes
int               aio_reqprio
struct sigevent   aio_sigevent
int               aio_lio_opcode

Execution Environment

The aio_read and aio_read64 subroutines can be called from the process environment only.

Return Values

The aio_read subroutine returns 0 to the calling process if the I/O operation is successfully queued. Otherwise, it returns a -1 and sets the errno global variable to indicate the error.

Error Codes

EAGAIN The requested asynchronous I/O operation was not queued due to system resource limitations.

Each of the following conditions may be detected synchronously at the time of the call to the aio_read subroutine, or asynchronously. If any of the conditions below are detected synchronously, the aio_read subroutine returns -1 and sets the errno global variable to the corresponding value. If any of the conditions below are detected asynchronously, the return status of the asynchronous operation is set to -1, and the error status of the asynchronous operation is set to the corresponding value.

EBADF The aio_fildes parameter is not a valid file descriptor open for reading.
EINVAL The file offset value implied by aio_offset is invalid, aio_reqprio is an invalid value, or aio_nbytes is an invalid value.

If the aio_read subroutine successfully queues the I/O operation but the operation is subsequently canceled or encounters an error, the return status of the asynchronous operation is one of the values normally returned by the read subroutine. In addition, the error status of the asynchronous operation is set to one of the error statuses normally set by the read subroutine, or one of the following values:

EBADF The aio_fildes argument is not a valid file descriptor open for reading.
ECANCELED The requested I/O was canceled before the I/O completed due to an explicit aio_cancel request.
EINVAL The file offset value implied by aio_offset is invalid.

The following condition may be detected synchronously or asynchronously:

EOVERFLOW The file is a regular file, aio_nbytes is greater than 0, and the starting offset in aio_offset is before the end-of-file and is at or beyond the offset maximum in the open file description associated with aio_fildes.

Related Information

aio_cancel or aio_cancel64 Subroutine, aio_error or aio_error64 Subroutine, lio_listio or lio_listio64 Subroutine, aio_return or aio_return64 Subroutine, aio_suspend or aio_suspend64 Subroutine, aio_write or aio_write64 Subroutine, close Subroutine, exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine, exit, atexit, _exit, or _Exit Subroutine, fork, f_fork, or vfork Subroutine, and lseek, llseek or lseek64 Subroutine.

The read, readx, readv, readvx, or pread Subroutine in AIX 5L Version 5.2 Technical Reference: Base Operating System and Extensions Volume 2.

Legacy AIO aio_read Subroutine

Purpose

Reads asynchronously from a file.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h>


int aio_read( FileDescriptor, aiocbp)
int FileDescriptor;
struct aiocb *aiocbp;


int aio_read64( FileDescriptor, aiocbp)
int FileDescriptor;
struct aiocb64 *aiocbp;

Description

The aio_read subroutine reads asynchronously from a file. Specifically, the aio_read subroutine reads from the file associated with the FileDescriptor parameter into a buffer.

The aio_read64 subroutine is similar to the aio_read subroutine execpt that it takes an aiocb64 reference parameter. This allows the aio_read64 subroutine to specify offsets in excess of OFF_MAX (2 gigbytes minus 1).

In the large file enabled programming environment, aio_read is redefined to be aio_read64 .

The details of the read are provided by information in the aiocb structure, which is pointed to by the aiocbp parameter. This information includes the following fields:

aio_buf Indicates the buffer to use.
aio_nbytes Indicates the number of bytes to read.

When the read request has been queued, the aio_read subroutine updates the file pointer specified by the aio_whence and aio_offset fields in the aiocb structure as if the requested I/O were already completed. It then returns to the calling program. The aio_whence and aio_offset fields have the same meaning as the whence and offset parameters in the lseek (lseek, llseek or lseek64 Subroutine) subroutine. The subroutine ignores them for file objects that are not capable of seeking.

If an error occurs during the call, the read request is not queued. To determine the status of a request, use the aio_error (aio_error or aio_error64 Subroutine) subroutine.

To have the calling process receive the SIGIO signal when the I/O operation completes, set the AIO_SIGNAL bit in the aio_flag field in the aiocb structure.

Note
The event structure in the aiocb structure is currently not in use but is included for future compatibility.
Note
The _AIO_AIX_SOURCE macro used in aio.h must be defined when using aio.h to compile an aio application with the Legacy AIO function definitions. The default compile using the aio.h file is for an application with the POSIX AIO definitions. In the source file enter:
#define _AIO_AIX_SOURCE
#include <sys/aio.h>
or, on the command line when compiling enter:
->xlc ... -D_AIO_AIX_SOURCE ... legacy_aio_program.c 

Parameters

FileDescriptor Identifies the object to be read as returned from a call to open.
aiocbp Points to the asynchronous I/O control block structure associated with the I/O operation.

aiocb Structure

The aiocb and the aiocb64 structures are defined in the aio.h file and contains the following members:

int               aio_whence
off_t             aio_offset
char             *aio_buf
size_t            aio_nbytes
int               aio_reqprio
struct event      aio_event
struct osigevent  aio_event
int               aio_flag
aiohandle_t       aio_handle

Execution Environment

The aio_read and aio_read64 subroutines can be called from the process environment only.

Return Values

When the read request queues successfully, the aio_read subroutine returns a value of 0. Otherwise, it returns a value of -1 and sets the global variable errno to identify the error.

Return codes can be set to the following errno values:

EAGAIN Indicates that the system resources required to queue the request are not available. Specifically, the transmit queue may be full, or the maximum number of opens may be reached.
EBADF Indicates that the FileDescriptor parameter is not valid.
EFAULT Indicates that the address specified by the aiocbp parameter is not valid.
EINVAL Indicates that the aio_whence field does not have a valid value, or that the resulting pointer is not valid.
Note
Other error codes defined in the sys/errno.h file can be returned by aio_error if an error during the I/O operation is encountered.

Related Information

The aio_cancel or aio_cancel64 (aio_cancel or aio_cancel64 Subroutine) subroutine, aio_error or aio_error64 (aio_error or aio_error64 Subroutine) subroutine, aio_return or aio_return64 (aio_return or aio_return64 Subroutine) subroutine, aio_suspend or aio_suspend64 (aio_suspend or aio_suspend64 Subroutine) subroutine, aio_write (aio_write or aio_write64 Subroutine) subroutine, lio_listio or lio_listo64 (lio_listio or lio_listio64 Subroutine) subroutine.

The Asynchronous I/O Overview and the Communications I/O Subsystem: Programming Introduction in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

The Input and Output Handling Programmer's Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs describes the files, commands, and subroutines used for low-level, stream, terminal, and asynchronous I/O interfaces.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]