NAME

zkRead - read from a file

 SYNOPSIS

#include "zkUnistd.h"

ssize_t zkRead(int fildes, void *buf, size_t nbyte);

DESCRIPTION

The zkRead() function attempts to read nbyte bytes from the regular file associated with the open file descriptor, fildes, into the buffer pointed to by buf.

If nbyte is 0, zkRead() will return 0 and have no other results.

The zkRead() function starts at a position in the file given by the file offset associated with fildes. The file offset is incremented by the number of bytes actually read.

No data transfer will occur past the current end-of-file. If the starting position is at or after the end-of-file, 0 will be returned.

If the value of nbyte is greater than {SSIZE_MAX}, the result is implementation-dependent.

Upon successful completion, where nbyte is greater than 0, zkRead() will return the number of bytes read. This number will never be greater than nbyte. The value returned may be less than nbyte if the number of bytes left in the file is less than nbyte. The value may also be less than nbyte under additional, implementation-defined circumstances. Consult your target platform's documentation for more information.

If a zkRead() is interrupted by a signal before it reads any data, it will return -1 with errno set to [EINTR].

If a zkRead() is interrupted by a signal after it has successfully read some data, it will return the number of bytes read.

RETURN VALUE

Upon successful completion, zkRead() returns a non-negative integer indicating the number of bytes actually read. Otherwise, the functions return -1 and set errno to indicate the error.

ERRORS

The zkRead() functions will fail if:

[EAGAIN]
The O_NONBLOCK flag is set for the file descriptor and the process would be delayed.
[EBADF]
The fildes argument is not a valid file descriptor open for reading.
[EBADMSG]
The file is a STREAM file that is set to control-normal mode and the message waiting to be read includes a control part.
[EINTR]
The read operation was terminated due to the receipt of a signal, and no data was transferred.
[EINVAL]
The STREAM or multiplexer referenced by fildes is linked (directly or indirectly) downstream from a multiplexer.
[EIO]
A physical I/O error has occurred.
[EIO]
The process is a member of a background process attempting to read from its controlling terminal, the process is ignoring or blocking the SIGTTIN signal or the process group is orphaned. This error may also be generated for implementation-dependent reasons.
[EISDIR]
The fildes argument refers to a directory and the implementation does not allow the directory to be read using zkRead().
[EOVERFLOW]
The file is a regular file, nbyte is greater than 0, the starting position is before the end-of-file and the starting position is greater than or equal to the offset maximum established in the open file description associated with fildes.

The zkRead() function may fail if:

[ENXIO]
A request was made of a non-existent device, or the request was outside the capabilities of the device.

PORTABILITY

The zkRead() function may portably be used only with file descriptors representing regular files. Any attempt to use it on a socket, directory, FIFO, STREAMS file, terminal device file, character special file, or block special file is non-portable.