read

read(n)                       Tcl Built-In Commands                      read(n)



________________________________________________________________________________

NAME
       read - Read from a channel

SYNOPSIS
       read ?-nonewline? channelId

       read channelId numChars
________________________________________________________________________________

DESCRIPTION
       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.

USE WITH SERIAL PORTS
       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.

EXAMPLE
       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]

SEE ALSO
       file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)

KEYWORDS
       blocking, channel, end of line, end of file, nonblocking, read,
       translation, encoding



Tcl                                    8.1                               read(n)