fgets

Defined in header `<stdio.h>`
char fgets( char str, int count, FILE *stream );		(until C99)
char fgets( char restrict str, int count, FILE *restrict stream );		(since C99)

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 end-of-file occurs or a newline character is found, in which case str will contain that newline character. If no errors occur, writes a null character at the position immediately after the last character written to str.

The behavior is undefined if count is less than 1.

Parameters

str	-	pointer to an element of a char array
count	-	maximum number of characters to write (typically the length of `str`)
stream	-	file stream to read the data from

Return value

str on success, null pointer on failure.

If the failure has been caused by end-of-file condition, additionally sets the eof indicator (see feof()) on stream. The contents of the array pointed to by str are not altered in this case.

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 ambiguous in the case where count==1, common implementations read no characters, store zero in str[0], and report success (return str)

Example

Run this code

#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");
}

Output:

"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

Language
Headers
Type support
Program utilities
Variadic function support
Error handling
Dynamic memory management
Date and time utilities
Strings library
Algorithms
Numerics
Input/output support
Localization support
Atomic operations (C11)
Thread support (C11)
Technical Specifications

scanffscanfsscanfscanf_sfscanf_ssscanf_s (C11)(C11)(C11)	reads formatted input from stdin, a file stream or a buffer (function)
getsgets_s (removed in C11)(since C11)	reads a character string from `stdin` (function)
fputs	writes a character string to a file stream (function)
getlinegetwlinegetdelimgetwdelim (dynamic memory TR)	read from a stream into a automatically resized buffer until delimiter/end of line (function)