.\" Copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)read.2	4.1 (Berkeley) 05/09/85
.\"
.TH READ 2 
.UC 4
.SH NAME
read \- read from file
.SH SYNOPSIS
.nf
.B read(fildes, buffer, nbytes)
.B char *buffer;
.fi
.SH DESCRIPTION
A file descriptor is a word
returned from a successful
.I "open, creat, dup,"
or
.I pipe
call.
.I Buffer
is the location of
.I nbytes
contiguous
bytes into which the input will be placed.
It is not guaranteed
that all
.I 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.
.PP
If the returned value is 0, then
end-of-file has been reached.
.PP
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.
.PP
.SH "SEE ALSO"
open(2), creat(2), dup(2), pipe(2), vread(2)
.SH 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
.I nbytes,
file descriptor not that of
an input file.
.SH "ASSEMBLER (PDP-11)"
(read = 3.)
.br
(file descriptor in r0)
.br
.B sys read; buffer; nbytes
.br
(byte count in r0)
.SH BUGS
It should be possible to call
.I 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
.IR tty (4)).
.PP
Processes which have been orphaned by their parents
and have been inherited by
.IR init (8)
never receive SIGTTIN signals.
Instead
.I read
returns with an end-of-file indication.