read(2)
_________________________________________________________________
read System Call
Read from an object.
_________________________________________________________________
SYNTAX
int read (fildes, buffer, nbyte)
int fildes;
char buffer[];
unsigned nbyte;
PARAMETERS
fildes An active, valid file descriptor.
buffer User data buffer.
nbyte Size (in bytes) of the user data buffer.
DESCRIPTION
Read transfers <nbyte> bytes of data from the object associated
with <fildes> into the buffer pointed to by <buffer>.
If <fildes> refers to an object pointer having a current position
attribute, the read starts at a position in the object given by
that attribute. If the current position refers to a part of a
file that has never been written (i.e., a part of a file that was
created by seeking past the end of the file) then the value of
the data is all zeros.
If the object pointer has no position attribute, then the
starting read position depends on the type of object being read.
The behavior of the read call is affected by the object attribute
flag O_NDELAY (see open(2)) associated with <fildes>.
If the O_NDELAY flag is set and <fildes> refers to a file that
has mandatory record locking enabled and is currently write
locked, the call returns -1 and errno is set to EAGAIN. If
O_NDELAY is clear, the call blocks until the appropriate lock is
removed or the call is interrupted by a signal.
When attempting to read from an empty pipe (or fifo) the
following will occur: If no process has the pipe open for
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
read(2)
writing, 0 is returned to indicate end-of-file. If some process
has the pipe open for writing, and O_NDELAY is set, -1 is
returned and errno is set to [EAGAIN]. If some process has the
pipe open for writing, and O_NDELAY is clear, the call will block
until some data is written or the pipe is closed by all processes
that had opened the pipe for writing.
When attempting to read a file associated with a character
special file that has no data currently available the following
will occur: If O_NDELAY is set, -1 is returned and errno is set
to [EAGAIN]. If O_NDELAY is clear, the call will block until
some data becomes available.
When read completes, the position attribute, if it exists, is
incremented by the number of bytes actually read. The access
time for the file is updated to reflect the time the read
occurred, unless the file resides on a read-only file system.
If an error occurs, the contents of <buffer> and any changes to
the object associated with <fildes> are defined by the object's
type. The default situation is that <buffer> and the object
associated with <fildes> are unchanged. This may not be the case
for some errors on some types of objects.
ACCESS CONTROL
<Fildes> must be open for reading.
RETURN VALUE
0..<nbyte> Completed successfully. The number of bytes
actually read is returned. The value 0 indicates
the `end-of-file' condition.
-1 An error occurred. Errno is set to indicate the
error.
EXCEPTIONS
Errno may be set to one of the following error codes:
EBADF <Fildes> is not a valid file descriptor open for
reading.
EFAULT <Buffer> points outside the allocated address
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
read(2)
space.
EINTR A signal was caught during the system call.
EDEADLK <fildes> refers to a file that has mandatory
record locking enabled and the read would produce
a deadlock condition. See lockf(2) for a
discussion of deadlock conditions.
SEE ALSO
The related manual sections: creat(2), dup(2), dup2(2),
fcntl(2), ioctl(2), open(2), pipe(2), readv(2), select(2),
socket(2), socketpair(2),
termio(7).
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)