GNU Info
(libc.info)I/O Primitives
Input and Output Primitives
===========================
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'.
- Data Type: ssize_t
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 no terminating null
character is 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'
Normally, when no input is immediately available, `read'
waits for some input. But if the `O_NONBLOCK' flag is set
for the file (Note: 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. This problem never happens in the
GNU system.
Any condition that could result in `EAGAIN' can instead
result in a successful `read' which returns fewer bytes than
requested. Calling `read' again immediately would result in
`EAGAIN'.
`EBADF'
The FILEDES argument is not a valid file descriptor, or is
not open for reading.
`EINTR'
`read' was interrupted by a signal while it was waiting for
input. Note: Interrupted Primitives. A signal will not
necessary cause `read' to return `EINTR'; it may instead
result in a successful `read' which returns fewer bytes than
requested.
`EIO'
For many devices, and for disk files, this error code
indicates a hardware error.
`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 the signal is being blocked or
ignored, or because the process group is orphaned. Note: Job
Control, for more information about job control, and Note:
Signal Handling, for information about signals.
Please note that there is no function named `read64'. This is not
necessary since this function does not directly modify or handle
the possibly wide file offset. Since the kernel handles this state
internally, the `read' function can be used for all cases.
This function is a cancellation point in multi-threaded programs.
This is a problem if the thread allocates some resources (like
memory, file descriptors, semaphores or whatever) at the time
`read' is called. If the thread gets canceled these resources
stay allocated until the program ends. To avoid this, calls to
`read' should be protected using cancellation handlers.
The `read' function is the underlying primitive for all of the
functions that read from streams, such as `fgetc'.
- Function: ssize_t pread (int FILEDES, void *BUFFER, size_t SIZE,
off_t OFFSET)
The `pread' function is similar to the `read' function. The first
three arguments are identical, and the return values and error
codes also correspond.
The difference is the fourth argument and its handling. The data
block is not read from the current position of the file descriptor
`filedes'. Instead the data is read from the file starting at
position OFFSET. The position of the file descriptor itself is
not affected by the operation. The value is the same as before
the call.
When the source file is compiled with `_FILE_OFFSET_BITS == 64' the
`pread' function is in fact `pread64' and the type `off_t' has 64
bits, which makes it possible to handle files up to 2^63 bytes in
length.
The return value of `pread' describes the number of bytes read.
In the error case it returns -1 like `read' does and the error
codes are also the same, with these additions:
`EINVAL'
The value given for OFFSET is negative and therefore illegal.
`ESPIPE'
The file descriptor FILEDES is associate with a pipe or a
FIFO and this device does not allow positioning of the file
pointer.
The function is an extension defined in the Unix Single
Specification version 2.
- Function: ssize_t pread64 (int FILEDES, void *BUFFER, size_t SIZE,
off64_t OFFSET)
This function is similar to the `pread' function. The difference
is that the OFFSET parameter is of type `off64_t' instead of
`off_t' which makes it possible on 32 bit machines to address
files larger than 2^31 bytes and up to 2^63 bytes. The file
descriptor `filedes' must be opened using `open64' since otherwise
the large offsets possible with `off64_t' will lead to errors with
a descriptor in small file mode.
When the source file is compiled with `_FILE_OFFSET_BITS == 64' on
a 32 bit machine this function is actually available under the name
`pread' and so transparently replaces the 32 bit interface.
- 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 is output like
any other character.
The return value is the number of bytes actually written. This
may be SIZE, but can always be smaller. Your program should
always call `write' in a loop, iterating until all the data is
written.
Once `write' returns, the data is enqueued to be written and can be
read back right away, but it is not necessarily written out to
permanent storage immediately. You can use `fsync' when you need
to be sure your data has been permanently stored before
continuing. (It is more efficient for the system to batch up
consecutive writes and do them all at once when convenient.
Normally they will always be written to disk within a minute or
less.) Modern systems provide another function `fdatasync' which
guarantees integrity only for the file data and is therefore
faster. You can use the `O_FSYNC' open mode to make `write' always
store the data to disk before returning; Note: Operating Modes.
In the case of an error, `write' returns -1. The following
`errno' error conditions are defined for this function:
`EAGAIN'
Normally, `write' blocks until the write operation is
complete. But if the `O_NONBLOCK' flag is set for the file
(Note: Control Operations), 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. This problem does not arise in the
GNU system.
`EBADF'
The FILEDES argument is not a valid file descriptor, or is
not open for writing.
`EFBIG'
The size of the file would become larger than the
implementation can support.
`EINTR'
The `write' operation was interrupted by a signal while it was
blocked waiting for completion. A signal will not
necessarily cause `write' to return `EINTR'; it may instead
result in a successful `write' which writes fewer bytes than
requested. Note: Interrupted Primitives.
`EIO'
For many devices, and for disk files, this error code
indicates a hardware error.
`ENOSPC'
The device containing the file is full.
`EPIPE'
This error is returned when you try to write to a pipe or
FIFO that isn't open for reading by any process. When this
happens, a `SIGPIPE' signal is also sent to the process; see
Note: 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. Note: Interrupted
Primitives. The easy way to do this is with the macro
`TEMP_FAILURE_RETRY', as follows:
nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
Please note that there is no function named `write64'. This is not
necessary since this function does not directly modify or handle
the possibly wide file offset. Since the kernel handles this state
internally the `write' function can be used for all cases.
This function is a cancellation point in multi-threaded programs.
This is a problem if the thread allocates some resources (like
memory, file descriptors, semaphores or whatever) at the time
`write' is called. If the thread gets canceled these resources
stay allocated until the program ends. To avoid this, calls to
`write' should be protected using cancellation handlers.
The `write' function is the underlying primitive for all of the
functions that write to streams, such as `fputc'.
- Function: ssize_t pwrite (int FILEDES, const void *BUFFER, size_t
SIZE, off_t OFFSET)
The `pwrite' function is similar to the `write' function. The
first three arguments are identical, and the return values and
error codes also correspond.
The difference is the fourth argument and its handling. The data
block is not written to the current position of the file descriptor
`filedes'. Instead the data is written to the file starting at
position OFFSET. The position of the file descriptor itself is
not affected by the operation. The value is the same as before
the call.
When the source file is compiled with `_FILE_OFFSET_BITS == 64' the
`pwrite' function is in fact `pwrite64' and the type `off_t' has
64 bits, which makes it possible to handle files up to 2^63 bytes
in length.
The return value of `pwrite' describes the number of written bytes.
In the error case it returns -1 like `write' does and the error
codes are also the same, with these additions:
`EINVAL'
The value given for OFFSET is negative and therefore illegal.
`ESPIPE'
The file descriptor FILEDES is associated with a pipe or a
FIFO and this device does not allow positioning of the file
pointer.
The function is an extension defined in the Unix Single
Specification version 2.
- Function: ssize_t pwrite64 (int FILEDES, const void *BUFFER, size_t
SIZE, off64_t OFFSET)
This function is similar to the `pwrite' function. The difference
is that the OFFSET parameter is of type `off64_t' instead of
`off_t' which makes it possible on 32 bit machines to address
files larger than 2^31 bytes and up to 2^63 bytes. The file
descriptor `filedes' must be opened using `open64' since otherwise
the large offsets possible with `off64_t' will lead to errors with
a descriptor in small file mode.
When the source file is compiled using `_FILE_OFFSET_BITS == 64'
on a 32 bit machine this function is actually available under the
name `pwrite' and so transparently replaces the 32 bit interface.
automatically generated by info2www version 1.2.2.9