# fgets

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           fgets — get a string from a stream
    


## SYNOPSIS



           #include <stdio.h>
    
           char *fgets(char *restrict _s_ , int _n_ , FILE *restrict _stream_);
    


## DESCRIPTION



           The functionality described on this reference page is aligned with
           the ISO C standard. Any conflict between the requirements
           described here and the ISO C standard is unintentional. This
           volume of POSIX.1‐2017 defers to the ISO C standard.
    
           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.
           A null byte shall be written immediately after the last byte read
           into the array.  If the end-of-file condition is encountered
           before any bytes are read, the contents of the array pointed to by
           _s_ shall not be changed.
    
           The _fgets_() function may mark the last data access timestamp of
           the file associated with _stream_ for update. The last data access
           timestamp shall be marked for update by the first successful
           execution of _fgetc_(), _fgets_(), _fread_(), _fscanf_(), _getc_(),
           _getchar_(), _getdelim_(), _getline_(), _gets_(), or _scanf_() using _stream_
           that returns data not supplied by a prior call to _ungetc_().
    


## 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(3p).
    
           _The following sections are informative._
    


## EXAMPLES



       **Reading Input**
           The following example uses _fgets_() to read lines of input. It
           assumes that the file it is reading is a text file and that lines
           in this text file are no longer than 16384 (or {LINE_MAX} if it is
           less than 16384 on the implementation where it is running) bytes
           long. (Note that the standard utilities have no line length limit
           if _sysconf_(_SC_LINE_MAX) returns -1 without setting _errno_.  This
           example assumes that _sysconf_(_SC_LINE_MAX) will not fail.)
    
               #include <limits.h>
               #include <stdio.h>
               #include <unistd.h>
               #define MYLIMIT 16384
    
               char *line;
               int line_max;
               if (LINE_MAX >= MYLIMIT) {
                   // Use maximum line size of MYLIMIT. If LINE_MAX is
                   // bigger than our limit, sysconf() cannot report a
                   // smaller limit.
                   line_max = MYLIMIT;
               } else {
                   long limit = sysconf(_SC_LINE_MAX);
                   line_max = (limit < 0 || limit > MYLIMIT) ? MYLIMIT : (int)limit;
               }
    
               // line_max + 1 leaves room for the null byte added by fgets().
               line = malloc(line_max + 1);
               if (line == NULL) {
                   // out of space
                   ...
                   return error;
               }
    
               while (fgets(line, line_max + 1, fp) != NULL) {
                   // Verify that a full line has been read ...
                   // If not, report an error or prepare to treat the
                   // next time through the loop as a read of a
                   // continuation of the current line.
                   ...
                   // Process line ...
                   ...
               }
               free(line);
               ...
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *