Open System Services System Calls Reference Manual (G06.29+, H06.08+, J06.03+)

spt_readz(2) OSS System Calls Reference Manual
NAME
spt_readz - Reads from a file (thread-aware version)
LIBRARY
H-series and J series OSS processes: /G/system/zdllnnn/zsptdll
SYNOPSIS
#include <sys/types.h> /* optional except for POSIX.1 */
#include <unistd.h>
#include <spthread.h>
ssize_t spt_readz(
int filedes,
void *buffer,
size_t nbytes);
PARAMETERS
filedes Specifies an open file descriptor obtained from a successful call to the
spt_acceptx(), creat(), creat64(), dup(), spt_dup2x(), spt_fcntlz(), open(),
open64(), pipe(), socket(),orsocketpair() function.
buffer Points to the buffer to receive data read.
nbytes Specifies the number of bytes to read from the file associated with the filedes
parameter.
If the value of nbytes is 0 (zero), the spt_readz() function returns 0 (zero).
There are no other results.
If the value of nbytes is greater than SSIZE_MAX, the spt_readz() function
returns -1 and sets errno to [EINVAL].
DESCRIPTION
The spt_readz() function is a thread-aware version of the read() function for regular files and
for special files.
The spt_readz() function attempts to read nbytes bytes of data from the file associated with the
filedes parameter into the buffer pointed to by the buffer parameter.
On regular files and devices capable of seeking, the spt_readz() function starts at a position in
the file given by the file pointer associated with the filedes parameter. Upon return from the
spt_readz() function, the file pointer is incremented by the number of bytes actually read.
Devices that are incapable of seeking always read from the current position. For such devices,
the value of the file pointer after a call to the spt_readz() function is always 0 (zero).
Upon successful completion, the spt_readz() function returns the number of bytes actually read
and placed in the buffer. This number is never greater than the value of the nbytes parameter.
The value returned can be less than nbytes if the number of bytes left in the file is less than
nbytes, if the spt_readz() request was interrupted by a signal, or if the file is a pipe, FIFO file,
socket, or special file and has fewer than nbytes bytes immediately available for reading. For
example, a spt_readz() from a file associated with a terminal might return one typed line of data.
No data transfer occurs past the current end-of-file (EOF). If the starting position is at or after the
end-of-file, 0 (zero) is returned.
If an spt_writez() or spt_writevz() call contains so much data that the file system needs to
resize a pipe or FIFO buffer, a read from that pipe or FIFO file can return up to 52 kilobytes of
data, regardless of the size of PIPE_BUF. If the buffer cannot be resized for the write operation,
a read from the pipe or FIFO file does not return more than 8192 bytes per call, regardless of the
setting of O_NONBLOCK.
7−358 Hewlett-Packard Company 527186-023