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(3tcl), eof(3tcl), fblocked(3tcl), fconfigure(3tcl), Tcl_StandardChannels(3tcl)

KEYWORDS

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