# fgets

From cppreference.com
< c‎ | io

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

### See also

scanf fscanf sscanf scanf_s fscanf_s sscanf_s (C11)(C11)(C11) | reads formatted input from stdin, a file stream or a buffer (function)
gets gets_s (until C11)(since C11) | reads a character string from `stdin` (function)
fputs | writes a character string to a file stream (function)
getline getwline getdelim getwdelim (dynamic memory TR) | read from a stream into a automatically resized buffer until delimiter/end of line (function)
C++ documentation for fgets

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=c/io/fgets&oldid=85689"