fgets() — Read a string from a stream

Standards

Standards / Extensions C or C++ Dependencies
ISO C
POSIX.1
XPG4
XPG4.2
C99
Single UNIX Specification, Version 3 Language Environment®
both  

Format

#include <stdio.h>

char *fgets(char * __restrict__string, int n, FILE * __restrict__stream);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>

char *fgets_unlocked(char * __restrict__string, int n, FILE * __restrict__stream);

General description

Reads bytes from a stream pointed to by stream into an array pointed to by string, starting at the position indicated by the file position indicator. Reading continues until the number of characters read is equal to n-1, or until a newline character (\n), or until the end of the stream, whichever comes first. The fgets() function stores the result in string and adds a NULL character (\0) to the end of the string. The string includes the newline character, if read.

The fgets() function is not supported for files opened with type=record or type=blocked.

fgets() has the same restriction as any read operation for a read immediately following a write or a write immediately following a read. Between a write and a subsequent read, there must be an intervening flush or reposition. Between a read and a subsequent write, there must also be an intervening flush or reposition unless an EOF has been reached.

fgets_unlocked() is functionally equivalent to fgets() with the exception that it is not thread-safe. This function can safely be used in a multithreaded application if and only if it is called while the invoking thread owns the (FILE*) object, as is the case after a successful call to either the flockfile() or ftrylockfile() function.

Returned value

If successful, fgets() returns a pointer to the string buffer.

If unsuccessful, fgets() returns NULL to indicate failure.
Note: When the O_NONBLOCK flag is set for the file descriptor’s underlying stream and the thread would be delayed in the fgets() operation, then fgets() will set errno to EAGAIN. In the case of a FIFO stream, if some data has been read into the string buffer, fgets() will return a pointer to the string buffer to indicate the partial read.

If n is less than or equal to 0, it indicates a domain error; errno is set to EDOM to indicate the cause of the failure.

When n equals 1, it indicates a valid result. It means that the string buffer has only room for the NULL terminator; nothing is physically read from the file. (Such an operation is still considered a read operation, so it cannot immediately follow a write operation unless there is an intervening flush or reposition operation first.)

If n is greater than 1, fgets() will only fail if an I/O error occurs or if EOF is reached, and no data is read from the file.

The ferror() and feof() functions are used to distinguish between a read error and an EOF. Note that EOF is only reached when an attempt is made to read “past” the last byte of data. Reading up to and including the last byte of data does not turn on the EOF indicator.

If EOF is reached after data has already been read into the string buffer, fgets() returns a pointer to the string buffer to indicate success. A subsequent call would result in NULL being returned since EOF would be reached without any data being read.

Example

CELEBF18
/* CELEBF18                                      

   This example gets a line of input from a data stream.                        
   It reads no more than MAX_LEN - 1 characters, or up                          
   to a new-line character, from the stream.                                    
                                                                                
 */                                                                             
#include <stdio.h>                                                              
#define  MAX_LEN  100                                                           
                                                                                
int main(void)                                                                  
{                                                                               
   FILE *stream;                                                                
   char line[MAX_LEN], *result;                                                 
                                                                                
   stream = fopen("myfile.dat","r");                                            
                                                                                
   if ((result = fgets(line,MAX_LEN,stream)) != NULL)                           
       printf("The string is %s\n", result);                                    
                                                                                
   if (fclose(stream))                                                          
       printf("fclose error\n");                                                
}                                                                               

Related information