Node:fgets, Previous:gets, Up:Deprecated string input functions

fgets

The fgets ("file get string") function is similar to the gets function. This function is deprecated -- that means it is obsolete and it is strongly suggested you do not use it -- because it is dangerous. It is dangerous because if the input data contains a null character, you can't tell. Don't use fgets unless you know the data cannot contain a null. Don't use it to read files edited by the user because, if the user inserts a null character, you should either handle it properly or print a clear error message. Always use getline or getdelim instead of fgets if you can.

Rather than reading a string from standard input, as gets does, fgets reads it from a specified stream, up to and including a newline character. It stores the string in the string variable passed to it, adding a null character to terminate the string. This function takes three parameters: the first is the string into which to read data, the second is the maximum number of characters to read. (You must supply at least this many characters of space in the string, or your program will probably crash, but at least the fgets function protects against overflowing the string and creating a security hazard, unlike gets.) The third parameter is the stream from which to read. The number of characters that fgets reads is actually one less than than number specified; it stores the null character in the extra character space.

If there is no error, fgets returns the string read as a return value, which may be discarded. Otherwise, for example if the stream is already at end of file, it returns a null pointer.

Unfortunately, like the gets function, fgets is deprecated, in this case because when fgets cannot tell whether a null character is included in the string it reads. If a null character is read by fgets, it will be stored in the string along with the rest of the characters read. Since a null character terminates a string in C, C will then consider your string to end prematurely, right before the first null character. Only use fgets if you are certain the data read cannot contain a null; otherwise, use getline.

Here is a code example that uses fgets. It will create a text file containing the string Hidee ho! plus a newline, read it back with fgets, and print it on standard output. Notice that although 100 characters are allocated for the string my_string, and requested to be read in the fgets call, there are not that many characters in the file. The fgets function only reads the string up to the newline character; the important thing is to allocate enough space in the string variable to contain the string to be read.

#include <stdio.h>

int main()
{
  int input_character;
  FILE *my_stream;
  char my_filename[] = "snazzyjazz.txt";
  char my_string[100];

  my_stream = fopen (my_filename, "w");
  fprintf (my_stream, "Hidee ho!\n");

  /* Close stream; skip error-checking for brevity of example */
  fclose (my_stream);

  my_stream = fopen (my_filename, "r");
  fgets (my_string, 100, my_stream);

  /* Close stream; skip error-checking for brevity of example */
  fclose (my_stream);

  printf ("%s", my_string);

  return 0;
}