read — Read from a channel
read ?-nonewline? channelId
read channelId numChars
In the first form, the read command reads all of the data
from channelId up to the end of the file. If the
-nonewline switch is specified then the last character of
the file is discarded if it is a newline. In the second form, the
extra argument specifies how many characters to read. Exactly that
many characters will be read and returned, unless there are fewer
than numChars left in the file; in this case all the
remaining characters are returned. If the channel is configured to
use a multi-byte encoding, then the number of characters read may
not be the same as the number of bytes read.
ChannelId must be an identifier for an open channel such
as the Tcl standard input channel (stdin), the return value from an
invocation of open or
socket, or the result of
a channel creation command provided by a Tcl extension. The channel
must have been opened for input.
If channelId is in nonblocking mode, the command may not
read as many characters as requested: once all available input has
been read, the command will return the data that is available
rather than blocking for more input. If the channel is configured
to use a multi-byte encoding, then there may actually be some bytes
remaining in the internal buffers that do not form a complete
character. These bytes will not be returned until a complete
character is available or end-of-file is reached. The
-nonewline switch is ignored if the command returns before
reaching the end of the file.
Read translates end-of-line sequences in the input into
newline characters according to the -translation option for
the channel. See the fconfigure manual entry for a
discussion on ways in which fconfigure will alter input.
For most applications a channel connected to a serial port should
be configured to be nonblocking: fconfigure channelId
-blocking 0. Then read behaves much like
described above. Care must be taken when using read on
blocking serial ports:
- read channelId
numChars
- In this form read blocks until numChars have been
received from the serial port.
- read channelId
- In this form read blocks until the reception of the
end-of-file character, see fconfigure -eofchar. If
there no end-of-file character has been configured for the channel,
then read will block forever.
This example code reads a file all at once, and splits it into a
list, with each line in the file corresponding to an element in the
list:
set fl [open /proc/meminfo]
set data [read $fl]
close $fl
set lines [split $data \n]
file, eof, fblocked, fconfigure, Tcl_StandardChannels
blocking, channel, end of line, end of file, nonblocking, read, translation, encoding
Copyright © 1993 The Regents of the University of
California.
Copyright © 1994-1996 Sun Microsystems, Inc.