Man Linux: Main Page and Category List

NAME

       fgets - get a string from a stream

SYNOPSIS

       #include <stdio.h>

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

DESCRIPTION

       The  fgets()  function  shall  read  bytes  from  stream into the array
       pointed to by s, until n-1 bytes are read, or a <newline> is  read  and
       transferred  to  s,  or  an  end-of-file  condition is encountered. The
       string is then terminated with a null byte.

       The fgets() function may mark the st_atime field of the file associated
       with  stream  for update. The st_atime field shall be marked for update
       by the  first  successful  execution  of  fgetc(),  fgets(),  fgetwc(),
       fgetws(),  fread(),  fscanf(),  getc(),  getchar(),  gets(), or scanf()
       using stream that returns data not supplied by a prior call to ungetc()
       or ungetwc().

RETURN VALUE

       Upon successful completion, fgets() shall return s. If the stream is at
       end-of-file, the end-of-file indicator for the stream shall be set  and
       fgets() shall return a null pointer.  If a read error occurs, the error
       indicator for the stream shall be set,  fgets()  shall  return  a  null
       pointer,    and shall set errno to indicate the error.

ERRORS

       Refer to fgetc() .

       The following sections are informative.

EXAMPLES

   Reading Input
       The  following  example  uses  fgets()  to  read  each  line  of input.
       {LINE_MAX}, which defines the  maximum  size  of  the  input  line,  is
       defined in the <limits.h> header.

              #include <stdio.h>
              ...
              char line[LINE_MAX];
              ...
              while (fgets(line, LINE_MAX, fp) != NULL) {
              ...
              }
              ...

APPLICATION USAGE

       None.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       fopen()   ,   fread()  ,  gets()  ,  the  Base  Definitions  volume  of
       IEEE Std 1003.1-2001, <stdio.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .