1mNAME0m
       gets - Read a line from a channel

1mSYNOPSIS0m
       1mgets 4m22mchannelId24m ?4mvarName24m?


1mDESCRIPTION0m
       This  command reads the next line from 4mchannelId24m, returns everything in
       the line up to (but not including) the  end-of-line  character(s),  and
       discards the end-of-line character(s).

       4mChannelId24m  must  be  an  identifier for an open channel such as the Tcl
       standard input channel (1mstdin22m), the return value from an invocation  of
       1mopen 22mor 1msocket22m, or the result of a channel creation command provided by
       a Tcl extension. The channel must have been opened for input.

       If 4mvarName24m is omitted the line is returned as the result  of  the  com-
       mand.   If 4mvarName24m is specified then the line is placed in the variable
       by that name and the return value is a count of the number  of  charac-
       ters returned.

       If  end  of  file occurs while scanning for an end of line, the command
       returns whatever input is available up to the end of  file.   If  4mchan-0m
       4mnelId24m  is  in  nonblocking  mode  and there is not a full line of input
       available, the command returns an empty string and does not consume any
       input.  If 4mvarName24m is specified and an empty string is returned in 4mvar-0m
       4mName24m because of end-of-file or because of  insufficient  data  in  non-
       blocking  mode,  then  the return count is -1.  Note that if 4mvarName24m is
       not specified then the end-of-file and no-full-line-available cases can
       produce the same results as if there were an input line consisting only
       of the end-of-line character(s).  The 1meof 22mand 1mfblocked 22mcommands can  be
       used to distinguish these three cases.

1mEXAMPLE0m
       This example reads a file one line at a time and prints it out with the
       current line number attached to the start of each line.

              set chan [open "some.file.txt"]
              set lineNumber 0
              while {[1mgets 22m$chan line] >= 0} {
                  puts "[incr lineNumber]: $line"
              }
              close $chan


1mSEE ALSO0m
       file(n), eof(n), fblocked(n), Tcl_StandardChannels(3)


1mKEYWORDS0m
