Go to the previous, next section.
This section describes the functions for performing primitive input and
output operations on file descriptors: read, write, and
lseek. These functions are declared in the header file
`unistd.h'.
This data type is used to represent the sizes of blocks that can be
read or written in a single operation. It is similar to size_t,
but must be a signed type.
Function: ssize_t read (int filedes, void *buffer, size_t size)
The read function reads up to size bytes from the file
with descriptor filedes, storing the results in the buffer.
(This is not necessarily a character string and there is no terminating
null character added.)
The return value is the number of bytes actually read. This might be less than size; for example, if there aren't that many bytes left in the file or if there aren't that many bytes immediately available. The exact behavior depends on what kind of file it is. Note that reading less than size bytes is not an error.
A value of zero indicates end-of-file (except if the value of the
size argument is also zero). This is not considered an error.
If you keep calling read while at end-of-file, it will keep
returning zero and doing nothing else.
If read returns at least one character, there is no way you can
tell whether end-of-file was reached. But if you did reach the end, the
next read will return zero.
In case of an error, read returns -1. The following
errno error conditions are defined for this function:
EAGAIN
read waits for
some input. But if the O_NONBLOCK flag is set for the file
(see section File Status Flags), read returns immediately without
reading any data, and reports this error.
Compatibility Note: Most versions of BSD Unix use a different
error code for this: EWOULDBLOCK. In the GNU library,
EWOULDBLOCK is an alias for EAGAIN, so it doesn't matter
which name you use.
On some systems, reading a large amount of data from a character special
file can also fail with EAGAIN if the kernel cannot find enough
physical memory to lock down the user's pages. This is limited to
devices that transfer with direct memory access into the user's memory,
which means it does not include terminals, since they always use
separate buffers inside the kernel.
EBADF
EINTR
read was interrupted by a signal while it was waiting for input.
See section Primitives Interrupted by Signals.
EIO
EIO also occurs when a background process tries to read from the
controlling terminal, and the normal action of stopping the process by
sending it a SIGTTIN signal isn't working. This might happen if
signal is being blocked or ignored, or because the process group is
orphaned. See section Job Control, for more information about job control,
and section Signal Handling, for information about signals.
The read function is the underlying primitive for all of the
functions that read from streams, such as fgetc.
Function: ssize_t write (int filedes, const void *buffer, size_t size)
The write function writes up to size bytes from
buffer to the file with descriptor filedes. The data in
buffer is not necessarily a character string and a null character
output like any other character.
The return value is the number of bytes actually written. This is normally the same as size, but might be less (for example, if the physical media being written to fills up).
In the case of an error, write returns -1. The following
errno error conditions are defined for this function:
EAGAIN
write blocks until the write operation is complete.
But if the O_NONBLOCK flag is set for the file (see section Control Operations on Files), it returns immediately without writing any data, and
reports this error. An example of a situation that might cause the
process to block on output is writing to a terminal device that supports
flow control, where output has been suspended by receipt of a STOP
character.
Compatibility Note: Most versions of BSD Unix use a different
error code for this: EWOULDBLOCK. In the GNU library,
EWOULDBLOCK is an alias for EAGAIN, so it doesn't matter
which name you use.
On some systems, writing a large amount of data from a character special
file can also fail with EAGAIN if the kernel cannot find enough
physical memory to lock down the user's pages. This is limited to
devices that transfer with direct memory access into the user's memory,
which means it does not include terminals, since they always use
separate buffers inside the kernel.
EBADF
EFBIG
EINTR
write operation was interrupted by a signal while it was
blocked waiting for completion. See section Primitives Interrupted by Signals.
EIO
EIO also occurs when a background process tries to write to the
controlling terminal, and the normal action of stopping the process by
sending it a SIGTTOU signal isn't working. This might happen if
the signal is being blocked or ignored. See section Job Control, for more
information about job control, and section Signal Handling, for
information about signals.
ENOSPC
EPIPE
SIGPIPE
signal is also sent to the process; see section Signal Handling.
Unless you have arranged to prevent EINTR failures, you should
check errno after each failing call to write, and if the
error was EINTR, you should simply repeat the call.
See section Primitives Interrupted by Signals. The easy way to do this is with the
macro TEMP_FAILURE_RETRY, as follows:
nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
The write function is the underlying primitive for all of the
functions that write to streams, such as fputc.
Go to the previous, next section.