fgets

Purpose

Reads a line of text from a file, retaining the newline (if present).

Format

str = fgets(fh, maxsize)
Parameters:
  • fh (scalar) – file handle of a file opened with fopen().
  • maxsize (scalar) – maximum size of string to read in, including the terminating null byte.
Returns:

str (string) – Contains the text read from the file line specified by the file handle fh. The maximum size of the str, including the terminating null byte, is maxsize.

Examples

 // Specify file name with full path
 fname = getGAUSSHome() $+ "examples/housing.csv";

 // Open file handle for reading
 fh = fopen(fname, "r");

// Read the first line of the file
// (up to 100 characters)
s = fgets(fh, 100);

After the above code, s will equal:

"taxes","beds","baths","new","price","size"
// Read the second line of the file
// by running 'fgets' again with the
// same file handle.
s = fgets(fh, 100);

After running the line above, s will be equal to:

3104,4,2,0,279.9,2048

Remarks

The fgets() procedure reads text from a file into a string. It reads up to a newline, the end of the file, or \(maxsize-1\) characters. The result is placed in str, which is then terminated with a null byte. The newline, if present, is retained.

If the file is already at end-of-file when you call fgets(), your program will terminate with an error. Use eof() in conjunction with fgets() to avoid this.

If the file was opened for update (see fopen()) and you are switching from writing to reading, don’t forget to call fseek() or fflush() first, to flush the file’s buffer.

If you pass fgets() the handle of a file opened with open (i.e., a data set or matrix file), your program will terminate with a fatal error.

See also

Functions fgetst(), fgetsa(), fopen()