NAME

read − read from file

SYNOPSIS

read(fildes, buffer, nbytes)
char \(**buffer;

DESCRIPTION

A file descriptor is a word returned from a successful open, creat, dup, or pipe call.  Buffer is the location of nbytes contiguous bytes into which the input will be placed.  It is not guaranteed that all nbytes bytes will be read; for example if the file refers to a typewriter at most one line will be returned.  In any event the number of characters read is returned. 

If the returned value is 0, then end-of-file has been reached. 

Unless the reader is ignoring or holding SIGTTIN signals, reads from the control typewriter while not in its process group cause a SIGTTIN signal to be sent to the reader’s process group; in the former case an end-of-file is returned. 

SEE ALSO

open(2), creat(2), dup(2), pipe(2), vread(2)

DIAGNOSTICS

As mentioned, 0 is returned when the end of the file has been reached.  If the read was otherwise unsuccessful the return value is −1.  Many conditions can generate an error: physical I/O errors, bad buffer address, preposterous nbytes, file descriptor not that of an input file. 

ASSEMBLER (PDP-11)

(read = 3.) 
(file descriptor in r0)
sys read; buffer; nbytes
(byte count in r0)

BUGS

It should be possible to call read and have it return immediately without blocking if there is no input available.  As a single special case, this is currently done on control terminals when the reading process has requested SIGTINT signals when input arrives (see tty(4)).

Processes which have been orphaned by their parents and have been inherited by init(8) never receive SIGTTIN signals. Instead read returns with an end-of-file indication. 

4th Berkeley Distribution  —  %W%%Q%%Y%