NAME    [Toc]    [Back]

     fgets, gets - get a line from a stream

SYNOPSIS    [Toc]    [Back]

     #include <stdio.h>

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

     char *
     gets(char *str);

DESCRIPTION    [Toc]    [Back]

     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
     on error.  The newline, if any, is retained.  In any case, a
` ' 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    [Toc]    [Back]

     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 functions gets() do
not distinguish
  between  end-of-file  and error, and callers must use
feof(3) and
     ferror(3) to determine which occurred.  Whether fgets()  can
possibly fail
     with  a  size argument of 1 is implementation-dependent.  On
OpenBSD,
     fgets() will never return NULL when size is 1.

ERRORS    [Toc]    [Back]

     [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    [Toc]    [Back]

     feof(3), ferror(3), fgetln(3)

STANDARDS    [Toc]    [Back]

     The functions fgets() and gets() conform to ANSI X3.159-1989
(``ANSI
     C'').

CAVEATS    [Toc]    [Back]

     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, '0)) == NULL) {
                             fprintf(stderr,   "input   line  too
long.0);
                             exit(1);
                     }
                     *p = ' ';
                     printf("%s0, buf);
             }

     While the error would be true if a line  >  1023  characters
were read, it
     would be false in two other cases:

           1.    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.

           2.   All C string functions, including strchr(),  correctly assume
                the  end  of  the string is represented by a null
(` ') 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.

BUGS    [Toc]    [Back]

     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
     C'').

OpenBSD      3.6                           June      4,      1993