NAME
fgets,
gets —
get a
line from a stream
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdio.h>
char *
fgets(
char *
restrict str,
int
size,
FILE * restrict
stream);
char *
gets(
char
*str);
DESCRIPTION
The
fgets() function reads at most one less than the number of
characters specified by
size from the given
stream and stores them in the string
str. Reading stops when a newline character is found, at
end-of-file or error. The newline, if any, is retained, and a
‘
\0
’ character is appended to end the
string.
The
gets() function is equivalent to
fgets()
with an infinite
size and a
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 or an
error occurs before any characters are read, they return
NULL
. 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
-
-
- [
EBADF
]
- The given 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).
SEE ALSO
feof(3),
ferror(3),
fgetln(3)
STANDARDS
The functions
fgets() and
gets() conform to
ANSI X3.159-1989 (“ANSI C89”) and
IEEE Std 1003.1-2001 (“POSIX.1”). The
IEEE Std 1003.1-2008 (“POSIX.1”) revision
marked
gets() as obsolescent.
CAVEATS
The following bit of code illustrates a case where the programmer assumes a
string is too long if it does not contain a newline:
char buf[1024], *p;
while (fgets(buf, sizeof(buf), fp) != NULL) {
if ((p = strchr(buf, '\n')) == NULL) {
fprintf(stderr, "input line too long.\n");
exit(1);
}
*p = '\0';
printf("%s\n", buf);
}
While the error would be true if a line longer than 1023 characters were read,
it would be false in two other cases:
- If the last line in a file does not contain a newline, the
string returned by fgets() will not contain a newline
either. Thus strchr() will return
NULL
and the program will terminate, even if the
line was valid.
- All C string functions, including
strchr(), correctly assume the end of the string is
represented by a null (‘\0’) character. If the first character
of a line returned by fgets() were null,
strchr() would immediately return without considering
the rest of the returned text which may indeed include a newline.
Consider using
fgetln(3) instead
when dealing with untrusted input.
SECURITY CONSIDERATIONS
Since it is usually impossible to ensure that the next input line is less than
some arbitrary length, and because overflowing the input buffer is almost
invariably a security violation, programs should
NEVER use
gets(). The
gets() function exists purely
to conform to
ANSI X3.159-1989
(“ANSI C89”).