gets(S)                        6 January 1993                        gets(S)


 Name

    gets, fgets - get a string from a stream

 Syntax


    cc  . . .  -lc


    #include  <stdio.h>

    char *gets (s)
    char *s;

    char *fgets (s, n, stream)
    char *s;
    int n;
    FILE *stream;


 Description

    The gets function reads characters from the standard input stream, stdin,
    into the array pointed to by s, until a new-line character is read or an
    end-of-file condition is encountered.  The new-line character is dis-
    carded and the string is terminated with a null character. See warning
    below on the use of gets.

    The fgets function reads characters from the stream into the array
    pointed to by s, until n-1 characters are read, or a new-line character
    is read and transferred to s, or an end-of-file condition is encountered.
    The string is then terminated with a null character.

 Warning

    The gets function is unsafe to use.  It does not limit the number of
    characters placed into the passed buffer, even though that buffer has
    some fixed size.  For this reason, the fgets function should be used
    instead.

    fgets is not, however, a direct substitute for gets. With fgets, as soon
    as the buffer is filled, the remainder of the line is left for the next
    fgets, while gets always reads the entire line even when it overflows the
    buffer.

 Diagnostics

    If end-of-file is encountered and no characters have been read, no char-
    acters are transferred to s and a NULL pointer is returned.  If a read
    error occurs, such as trying to use these functions on a file that has
    not been opened for reading, a NULL pointer is returned.  Otherwise s is
    returned.

 See also

    ferror(S), fopen(S), fread(S), getc(S), scanf(S), stdio(S)

 Standards conformance

    fgets and gets are conformant with:
    AT&T SVID Issue 2;
    X/Open Portability Guide, Issue 3, 1989;
    ANSI X3.159-1989 Programming Language -- C;
    Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2);
    IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C
    Language] (ISO/IEC 9945-1);
    and NIST FIPS 151-1.