FGETS(3)                       Library Routines                       FGETS(3)

NAME

       fgets, gets - get a line from a stream

SYNOPSIS

       #include <stdio.h>

       char *fgets (char *str, size_t size, FILE *stream);
       char *gets (char *str);

DESCRIPTION

       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 error.  The newline, if any, is retained.   If  any  characters  are
       read  and  there  is  no  error,  a \0 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

       Upon  successful  completion,  fgets  and  gets return a pointer to the
       string.  If end-of-file occurs before any characters are read, they re‐
       turn  NULL  and  the buffer contents is unchanged.  If an error occurs,
       they return NULL and the buffer contents is indeterminate.   The  fgets
       and  gets  functions  do not distinguish between end-of-file and error,
       and callers must use feof(3) and ferror(3) to determine which occurred.

ERRORS

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

GNO NOTES

       If these routines are used on a stream which has been opened in  binary
       mode,  the results may not be as is expected; this stdio implementation
       has the assumption that the newline character  is  the  linefeed  (\n).
       Since  a file opened in binary mode will usually, on the IIgs, use car‐
       ridge returns as the newline characters, the fgets  and  gets  routines
       will return more characters than expected.  This makes use of gets par���
       ticularly dangerous under GNO (see the section on BUGS, below).

SEE ALSO

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

STANDARDS

       The functions fgets and gets conform to ANSI/C.

BUGS

       Since it is usually impossible to ensure that the next  input  line  is
       less than some arbitrary length, and because overflowing the input buf‐
       fer is almost invariably a security violation,  programs  should  NEVER
       use gets.  The gets function exists purely to conform to ANSI/C.



GNO                            15 September 1997                      FGETS(3)