FGETS(3)                       Library Routines                       FGETS(3)


       fgets, gets - get a line from a stream


       #include <stdio.h>

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


       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

       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.


       Upon  successful  completion,  fgets  and  gets return a pointer to the
       string.  If end-of-file occurs before any  characters  are  read,  they
       return  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.


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


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


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


       The functions fgets and gets conform to ANSI/C.


       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/C.

GNO                            15 September 1997                      FGETS(3)

Man(1) output converted with man2html