.TH FGETMFS 3 local
.DA 23 May 1989
.SH NAME
fgetmfs \- read an arbitrarily long, possibly continued line
.SH SYNOPSIS
.B "#include <stdio.h>
.br
.B "#include <fgetmfs.h>
.PP
.B "char *fgetmfs(stream, limit, cont)"
.br
.B "FILE *stream;"
.br
.B "int limit, cont;"
.PP
.B "char *fgetms(stream)
.br
.B "FILE *stream;"
.PP
.B "char *cfgetms(stream)
.br
.B "FILE *stream;"
.SH DESCRIPTION
.I Fgetmfs
reads an arbitrarily long line from
.IR stream ,
allocating memory via
.IR malloc (3)
as needed.
If
.I limit
is non-negative,
.I fgetmfs
will read no more than
.I limit
bytes from
.IR stream .
For efficiency,
if
.I cont
is not
.IR CONT_NO ,
such as
.I CONT_NOSPC
or
.IR CONT_SPC ,
occurrences of a backslash and a newline together
and in that order
will be deleted from the input stream;
if
.I cont
is
.IR CONT_NOSPC ,
any whitespace after the newline
in the input stream will also be deleted from it.
.PP
The macros
.I fgetms
(to read without continuations)
and
.I cfgetms
(to read with continuations and remove leading whitespace)
should be used instead when the
.I limit
is not needed.
.PP
.I Fgetmfs
is intended to provide a reliable mechanism for reading
input containing lines of arbitrary length,
rather than trusting that no line with be longer than some
arbitrary tolerance.
.PP
The memory returned by
.I fgetmfs
should be returned when no longer needed via
.IR free (3).
.\" .SH FILES
.SH SEE ALSO
.IR malloc (3),
.IR fgets (3)
.SH DIAGNOSTICS
Returns NULL (0) if memory cannot be allocated or upon reading end-of-file;
use
.I feof(stream)
to distinguish.
.SH HISTORY
Written by Geoff Collyer
at the University of Toronto
as part of the C news project.
.SH BUGS
It's too slow.
.br
The meaning of the
.I cont
flag is ugly,
but layering this form of continuation on top is even slower.