FGETS

  .  Summary

  fgets(str <buffer>, int <n>, int <fh>);

  .  Description

  The fgets function reads characters from the open file indicated by
  the file handle <fh> into the string variable <buffer>. Reading
  stops when a newline (Line Feed) character is read, and end-of-file
  is encountered, a read error occurs, or <n> characters have been
  read. The Line Feed character (and the Carriage Return that usually
  precedes it on MS-DOS systems) is not kept as part of the string.

  Important: The SALT implementation of the fgets() function differs
  from the C language function of the same name. While both implemen-
  tations read until the Line Feed character, C keeps that character
  as part of the input string, while SALT doesn't. This change was
  made because in almost every case, the Line Feed is not needed, and
  would otherwise have to be manually stripped by the script after ev-
  ery read.

  Fgets does not pay attention to control-z in the file.

  .  Return Value

  A value of -1 is returned if there is a read error, or if there is
  an end-of-file before any characters can be read.

  .  Example

  int f;
  str s[100];
  f = fopen("test.dat", "r");
  while (!feof(f))         // print out contents of text file
   {
    fgets(s, 100, f);
    printsc(s);
   }