fgets

Gets a string of characters from a stream and stores them in an array.

Library:LibC
Classification:ANSI
Service:File and Directory I/O

Syntax

  #include <stdio.h> 
   
  char *fgets (
     char   *buf,   
     int     n,   
     FILE   *fp);

Parameters

buf

(OUT) Points to the array into which the characters are to be stored.

n

(IN) Specifies the number of characters to read.

fp

(IN) Points to the file to be read.

Return Values

If successful, returns buf. If the stream is at the end-of-file, returns a NULL pointer and sets the end-of-file indicator on the stream.

If a read error occurs, returns a NULL pointer, sets the end-of-file indicator on the stream, and sets errno to one of the following:

Decimal

Constant

Description

4

EBADF

The file descriptor is not valid for reading.

5

ENOMEM

Insufficient storage space is available.

24

EAGAIN

The O_NONBLOCK flag is set for the file descriptor, and the process cannot immediately perform the read operation.

25

ENXIO

A request was made of a nonexistent device, or the request was outside the capabilities of the device.

28

EIO

The process is orphaned and cannot write to the file.

63

EINTR

A signal interrupted the read operation.

81

EOVERFLOW

The file is a regular file and an attempt was made to read at or beyond the offset maximum associated with the corresponding stream.

Remarks

The fgets function gets a string of characters from the file designated by fp and stores them in the array pointed to by buf. The fgets function stops reading characters when end-of-file is reached, or when a newline character is read, or when n-1 characters have been read, whichever comes first. The newline character is not discarded. A null-terminating character is placed immediately after the last character read into the array.

The gets function is similar to fgets except that it operates with stdin; it has no size argument, and it replaces a newline character with the null-terminating character.

See Also