read(n) Tcl Built-In Commands read(n)
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 buf-
fers that do not form a complete character. These bytes will not be returned until a com-
plete 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.
USE WITH SERIAL PORTS
For most applications a channel connected to a serial port should be configured to be non-
blocking: 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.
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.
file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)
blocking, channel, end of line, end of file, nonblocking, read, translation, encoding
Tcl 8.1 read(n)