text: .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 .
  