aread(2)

NAME

aread − asynchronous read from file

SYNOPSIS

id = aread (fildes, buf, nbyte, reqid, status, bytecnt)
int fildes;
char ∗buf;
unsigned nbyte;
int reqid;
int ∗status;
int ∗bytecnt;

DESCRIPTION

aread attempts to read nbyte bytes from the open file associated with the file descriptor fildes into the buffer pointed to by buf. aread returns control to its caller before the I/O operation completes. While the I/O operation is in progress, the caller must not reference the buffer.

Reqid is a user-supplied identifier which may be used to wait for the I/O operation to complete (see await(2)). If reqid is specified as −1, the system will select an identifier. Otherwise, reqid must be between 0 and 31 inclusive.

If status is not zero, the value EINPROGRESS is stored in ∗status until the I/O operation completes. At that time, it is updated with the operation’s final completion status (a value other than EINPROGRESS). Status may be specified as zero if the completion status is not of interest.

If bytecnt is not zero, the number of bytes actually read is stored in ∗bytecnt when the I/O operation completes. This number may be less than the number of bytes requested if the file is associated with a communication line (see ioctl(2) and termio(7)), or there is insufficient space left in the file. A value of zero is returned in ∗bytecnt when an end-of-file has been reached. Bytecnt may be specified as zero if the number of bytes actually read is not of interest.

The SIGIO signal is sent to the calling process when the I/O operation completes.

On devices capable of seeking, the read starts at a position in the file given by the file pointer associated with fildes. Upon initiation of the read operation, the file pointer is incremented by nbyte. Devices that are incapable of seeking always read from the current position. The value of a file pointer associated with such a file is undefined.

When attempting to read from an empty pipe (or FIFO):

If O_NDELAY is set, the read will result in 0 bytes being read.

If O_NDELAY is clear, the read will not complete until data is written to the file or the file is no longer open for writing.

When attempting to read a file associated with a tty that has no data currently available:

If O_NDELAY is set, the read will result in 0 bytes being read.

If O_NDELAY is clear, the read will not complete until data becomes available.

When attempting to read a file that has been opened in direct mode (i.e. O_DIRECT is set) the buffer pointed to by buf must be 4-byte aligned. Additionally nbyte must be a multiple of 4 bytes and less than the maximum physical transfer size of the machine (see the CX/UX Programmer’s Guide for details). Lastly, the file pointer associated with fildes must be aligned to a multiple of the disk block size (1024 bytes). For maximum performance, applications are advised to segregate high-use data and O_DIRECT I/O buffers into separate pages.

RETURN VALUE

Upon successful completion an identifier is returned (if reqid was not specified as −1 the returned identifier is reqid). Otherwise, a −1 is returned and errno is set to indicate the error.

ERRORS

aread will fail and the file pointer will remain unchanged if one or more of the following are true:

[EBADF] Fildes is not a valid file descriptor open for reading.

[EFAULT] Buf, status, or bytecnt points outside the allocated address space.

[EINVAL] Reqid is not −1 and reqid is less than 0 or larger than 31.

[EINVAL] Reqid is not −1 and an asynchronous I/O operation is already in progress for reqid.

[EINVAL] Reqid is −1 and the maximum number of asynchronous I/O operations for the process (32) are pending.

[EINTR] A signal was caught during the system call.

[EAREQ] No asynchronous request blocks were available to queue the I/O request.

[ENOBUFS] There are not enough disk cache buffers available to handle this request.

[EINVAL] O_DIRECT was set and either buf was not 4-byte aligned, nbyte was not a multiple of 4 bytes, nbyte was greater than the maximum physical transfer size of the machine, or the file pointer was not aligned to a multiple of the disk block size.

Museum