HP 3000 Manuals HP 3000 Manuals
read
Reads data from a file.
Syntax
#include <unistd.h>
ssize_t read (int fildes, void *buffer, size_t nbyte);
Parameters
fildes An open file descriptor.
buffer A pointer to a buffer where data is returned. The size of the
buffer must be greater than nbyte.
nbyte The maximum number of bytes to read.
Return Values
>=0 Success. An integer value indicating the number of bytes
actually read is returned.
-1 An error occurred. The content of the buffer is indeterminate
and errno is set to indicate the error condition.
Description
The read() function attempts to read nbyte bytes from the open file
associated with the open file descriptor fildes into the buffer pointed
to by buffer.
On a file capable of seeking, read() starts from the current file offset
position. Before successful return, the file offset is incremented by
the number of bytes actually read.
On a file not capable of seeking, read() starts from the current
position. (The file offset for such a file is undefined.)
Upon successful completion, the read() function returns the actual number
of bytes copied to the buffer and, if nbyte is greater than 0, marks for
update the st_atime time field of the file.
The value returned by read() is never greater than nbyte. The value
returned may be less than nbyte if either the number of bytes left in the
file is less than nbyte or the file is a special file (STDIN_FILENO) and
fewer than nbytes are available.
If nbytes is zero, the read() function returns zero bytes of data. In
this case, the file offset position is not changed, and no time fields
are marked for update.
No data transfer occurs past the current end-of-file (EOF). Zero is
returned if the file offset position is at or after the EOF. For any
portion of the file prior to the EOF that is not written to, read()
returns bytes with a value of zero.
Implementation Considerations
Refer to the EFAULT, EIMPL, and ESYSERR error descriptions below.
Signals generated for the calling process during execution of read() are
deferred from delivery until completion of this function.
Errors
If an error occurs, errno is set to one of the following values:
EBADF CAUSE The fildes parameter is not a valid file descriptor
open for reading.
ACTION Check the value of the fildes, check permission bits
of file or check the access mode used in opening the
file.
EFAULT CAUSE The system detected a NULL or bad address in
attempting to use the buffer parameter.
ACTION Make sure that the pointer is correctly initialized.
EIMPL CAUSE The value specified in nbyte is greater than
{SSIZE_MAX}.
ACTION Reduce the value specified in nbyte.
ESYSERR CAUSE An operating system error has occurred that does not
map directly to any of the above errors.
ACTION Examine the MPE/iX error stack for the type of system
error.
See Also
creat(), dup(), execl(), execv(), fork(), open(), unlink(), POSIX.1
(Section 6.4.1)