.Dd April 21, 2004
.Dt FGETLINE 3
.Os
.Sh NAME
.Nm fgetline
.Nd get a line from a stream
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In stdio.h
.Ft char *
.Fn fgetline "FILE * restrict stream"
.Sh DESCRIPTION
The
.Fn fgetline
function
returns a pointer to the next line from the stream referenced by
.Fa stream .
This line
.Em is
a C string as it ends with a terminating
.Dv NUL
character.
Trailing NL and CR characters at the end of the line are stripped
before the line is returned.
.Sh RETURN VALUES
Upon successful completion a pointer is returned;
this pointer becomes invalid after the next
.Tn I/O
operation on
.Fa stream
(whether successful or not)
or as soon as the stream is closed.
Otherwise,
.Dv NULL
is returned.
The
.Fn fgetline
function
does not distinguish between end-of-file and error; the routines
.Xr feof 3
and
.Xr ferror 3
must be used
to determine which occurred.
If an error occurs, the global variable
.Va errno
is set to indicate the error.
The end-of-file condition is remembered, even on a terminal, and all
subsequent attempts to read will return
.Dv NULL
until the condition is
cleared with
.Xr clearerr 3 .
.Pp
The text to which the returned pointer points may be modified,
provided that no changes are made beyond the trailing
.Dv NULL
.
These changes are lost as soon as the pointer becomes invalid.
.Sh ERRORS
.Bl -tag -width [EBADF]
.It Bq Er EBADF
The argument
.Fa stream
is not a stream open for reading.
.El
.Pp
The
.Fn fgetline
function
may also fail and set
.Va errno
for any of the errors specified for the routines
.Xr fflush 3 ,
.Xr malloc 3 ,
.Xr read 2 ,
.Xr stat 2 ,
or
.Xr realloc 3 .
.Sh SEE ALSO
.Xr ferror 3 ,
.Xr fgets 3 ,
.Xr fopen 3 ,
.Xr putc 3
.Sh HISTORY
The
.Fn fgetline
function first appeared in
BitKeeper-4.1.1 .
