The
fgets ();
function
reads at most one less than the number of characters specified by
Fa size
from the given
Fa stream
and stores them in the string
Fa str .
Reading stops when a newline character is found,
at end-of-file or error.
The newline, if any, is retained.
If any characters are read and there is no error, a
`\0'
character is appended to end the string.
The
gets ();
function
is equivalent to
fgets ();
with an infinite
Fa size
and a
Fa stream
of
stdin
except that the newline character (if any) is not stored in the string.
It is the caller's responsibility to ensure that the input line,
if any, is sufficiently short to fit in the string.
RETURN VALUES
Upon successful completion,
fgets ();
and
gets ();
return
a pointer to the string.
If end-of-file occurs before any characters are read,
they return
NULL
and the buffer contents remain unchanged.
If an error occurs,
they return
NULL
and the buffer contents are indeterminate.
The
fgets ();
and
gets ();
functions
do not distinguish between end-of-file and error, and callers must use
feof(3)
and
ferror(3)
to determine which occurred.
ERRORS
Bq Er EBADF
The given
Fa stream
is not a readable stream.
The function
fgets ();
may also fail and set
errno
for any of the errors specified for the routines
fflush(3),
fstat(2),
read(2),
or
malloc(3).
The function
gets ();
may also fail and set
errno
for any of the errors specified for the routine
getchar(3).
SECURITY CONSIDERATIONS
The
gets ();
function cannot be used securely.
Because of its lack of bounds checking,
and the inability for the calling program
to reliably determine the length of the next incoming line,
the use of this function enables malicious users
to arbitrarily change a running program's functionality through
a buffer overflow attack.
It is strongly suggested that the
fgets ();
function be used in all cases.
(See
the FSA.)
