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  -nonew-
       line  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 chan-
       nelId -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.



SEE ALSO
       file(n), eof(n), fblocked(n), fconfigure(n), Tcl_Standard-
       Channels(3)


KEYWORDS
       blocking,  channel, end of line, end of file, nonblocking,
