fgets

char *fgets( char          *str, int count, FILE          *stream );

char *fgets( char *restrict str, int count, FILE *restrict stream );

Reads at most count - 1 characters from the given file stream and stores them in the character array pointed to by str. Parsing stops if a newline character is found, in which case str will contain that newline character, or if end-of-file occurs. If bytes are read and no errors occur, writes a null character at the position immediately after the last character written to str.

Parameters

Return value

str on success, null pointer on failure.

If the end-of-file condition is encountered, sets the eof indicator on stream (see feof()). This is only a failure if it causes no bytes to be read, in which case a null pointer is returned and the contents of the array pointed to by str are not altered (i.e. the first byte is not overwritten with a null character).

If the failure has been caused by some other error, sets the error indicator (see ferror()) on stream. The contents of the array pointed to by str are indeterminate (it may not even be null-terminated).

Notes

POSIX additionally requires that fgets sets errno if it encounters an failure other than the end-of-file condition.

Although the standard specification is unclear in the cases where count<=1, common implementations do.

• if count < 1, do nothing, report error
• if count == 1,
• some implementations do nothing, report error,
• others read nothing, store zero in str[0], report success

Example

#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
    FILE* tmpf = tmpfile();
    fputs("Alan Turing\n", tmpf);
    fputs("John von Neumann\n", tmpf);
    fputs("Alonzo Church\n", tmpf);
 
    rewind(tmpf);
 
    char buf[8];
    while (fgets(buf, sizeof buf, tmpf) != NULL)
          printf("\"%s\"\n", buf);
 
    if (feof(tmpf))
       puts("End of file reached");
}

"Alan Tu"
"ring
"
"John vo"
"n Neuma"
"nn
"
"Alonzo "
"Church
"
End of file reached

References

• C11 standard (ISO/IEC 9899:2011):
• 7.21.7.2 The fgets function (p: 331)
• C99 standard (ISO/IEC 9899:1999):
• 7.19.7.2 The fgets function (p: 296)
• C89/C90 standard (ISO/IEC 9899:1990):
• 4.9.7.2 The fgets function

See also