lgets fileId ?varName?
Reads the next Tcl list from the file given by
fileId and discards the terminating newline charac-
ter. This command differs from the gets command,
in that it reads Tcl lists rather than lines. If
the list contains a newline, then that newline will
be returned as part of the result. Only a newline
not quoted as part of the list indicates the end of
the list. There is no corresponding command for
outputting lists, as puts will do this correctly.
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 includ-
ing 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 specified and an error occurs, what ever
data was read will be returned in the variable,
however the resulting string may not be a valid
list.
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 charac-
ters except the newline, so eof may have to be used
to determine what really happened.
If lgets is used on a non-blocking file, blocking
will be temporarily enabled for the duration of the
lgets command. This is required by the current
implementation of the underlying Tcl I/O system.
In most cases, this will not cause any problems, as
the process writing the file should be writing
entire lists in one write operation. The only
difficulty that might arise is if non-blocking I/O
was being used to keep two processes from deadlock-
ing while exchanging large amounts of data.
This command is provided by Extended Tcl.