read, readx
Purpose
Reads from file.
Syntax
int read (fildes, buf, nbyte) int readx (fildes, buf, nbyte, ext)
int fildes; int fildes, ext;
char *buf; char *buf;
unsigned int nbyte; unsigned int nbyte;
Description
The read system call reads a set number of bytes into a
buffer. The read system call reads the number of bytes
set by the nbyte parameter from the file associated with
the fildes parameter and places those bytes into the
buffer pointed to by the buf parameter. If Distributed
Services is installed on your system, this file can
reside on another node.
The fildes parameter is a file descriptor obtained from a
creat, open, dup, fcntl, or pipe system call.
On devices capable of seeking, the read starts at a posi-
tion in the file given by the file pointer associated
with the fildes parameter. Upon return from the read
system call, the file pointer is incremented by the
number of bytes actually read.
Devices that are incapable of seeking always read from
the current position. The value of a file pointer asso-
ciated with such a file is undefined.
When attempting to read from an empty pipe (or FIFO):
o If O_NDELAY is set, the read returns 0.
o If O_NDELAY is clear, the read blocks 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 terminal
that has no data currently available:
o If O_NDELAY is set, the read returns 0.
o If O_NDELAY is clear, the read blocks until data
becomes available.
When attempting to read a regular file that supports
enforcement mode record locks, and all or part of the
region to be read is currently locked by another process:
o If O_NDELAY is set, then the read returns -1 and sets
errno to EAGAIN.
o If O_NDELAY is clear, then the read blocks the
calling process until the lock is released.
For more information about record locks, see "lockf."
If the file has been mapped, the read system call reads
from a mapped file segment. If the fildes file
descriptor was used to map the file copy-on-write, then
the copy-on-write segment is used. Otherwise, the read
system call reads from the read-write mapped segment for
the file. See "shmat" for information about mapping
files.
The readx system call performs the same function as read,
except that it provides communication with character
device drivers that require more information or return
more status than read can handle.
For files, directories, or special files with drivers
that do not handle extended operations, the readx system
call does exactly what the read system call does, and the
ext parameter is ignored.
Each driver interprets the ext parameter in a device-
dependent way, either as a value or as a pointer to a
communication area. The nonextended read system call is
equivalent to the extended readx system call with an ext
parameter value of 0. Drivers must apply reasonable
defaults when the ext parameter value is 0.
Return Value
Upon successful completion, the read and readx system
calls return the number of bytes actually read and placed
in the buffer; this number may be less than the value of
the nbyte parameter if the file is associated with a com-
munication line, or if the number of bytes left in the
file is less than the value of the nbyte parameter. A
value of 0 is returned when an end-of-file has been
reached. (For information about communication files, see
"ioctl" and "termio.") If read or readx fails, a value of
-1 is returned and errno is set to indicate the error.
Diagnostics
The read and readx system calls fail if one or more of
the following are true:
EBADF fildes is not a valid file descriptor open for
reading.
EAGAIN An enforcement mode record lock is outstanding
in the portion of the file that is to be read.
EFAULT buf &pointsout..
EDEADLK A deadlock would occur if the calling process
were to sleep until the region to be read was
unlocked.
EINTR A signal was caught during the read system
call.
If Distributed Services is installed on your system, read
or readx can also fail if one or more of the following
are true:
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EAGAIN The server is too busy to accept the
request.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Related Information
In this book: "creat," "dup," "fcntl," "ioctl,"
"lockf," "open," "pipe," and "termio."
Device Driver Development Guide.