gets(n)                      Tcl ( )                      gets(n)



     _________________________________________________________________

     NAME
          gets - Read a line from a file

     SYNOPSIS
          gets fileId ?varName?
     _________________________________________________________________


     DESCRIPTION
          This command reads the next line  from  the  file  given  by
          fileId  and  discards the terminating newline character.  If
          varName is specified then the line is placed in the variable
          by  that  name and the return value is a count of the number
          of characters read (not including the newline).  If the  end
          of the file is reached before reading any characters then -1
          is returned and varName is  set  to  an  empty  string.   If
          varName  is  not specified then the return value will be the
          line (minus the newline character) or an empty string if the
          end  of  the  file is reached before reading any characters.
          An empty string will also be returned if a line contains  no
          characters except the newline, so eof may have to be used to
          determine what really happened.  If the  last  character  in
          the  file is not a newline character then gets behaves as if
          there were an additional newline character at the end of the
          file.   FileId  must  be  stdin  or  the return value from a
          previous call to open; it must refer  to  a  file  that  was
          opened  for  reading.   Any  existing  end-of-file  or error  |
          condition on the file is cleared at  the  beginning  of  the  |
          gets command.


     KEYWORDS
          file, line, read




















     Page 1                                         (printed 11/11/93)