| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C |
both |
#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);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.
If successful, fgets() returns a pointer to the string buffer.
If unsuccessful, fgets() returns NULL to indicate failure.
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.
⁄* 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");
}