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 chan-
       nelId 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 charac-
       ters  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, trans-
       lation, encoding

Tcl                                   8.1                              read(n)