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 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

Normally, when no input is immediately available, 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. 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. See section Primitives Interrupted by Signals. 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 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 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.) You can use the O_FSYNC open mode to make write always store the data to disk before returning; see section I/O 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 (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. 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 necessary cause write to return EINTR; it may instead result in a successful write which writes fewer bytes than requested. See section Primitives Interrupted by Signals.

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 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 first, previous, next, last section, table of contents.