1mNAME0m
       read - Read from a channel

1mSYNOPSIS0m
       1mread 22m?1m-nonewline22m? 4mchannelId0m

       1mread 4m22mchannelId24m 4mnumChars0m


1mDESCRIPTION0m
       In  the  first  form, the 1mread 22mcommand reads all of the data from 4mchan-0m
       4mnelId24m up to the end of the file.  If the 1m-nonewline 22mswitch 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 4mnumChars24m 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.

       4mChannelId24m  must  be  an  identifier for an open channel such as the Tcl
       standard input channel (1mstdin22m), the return value from an invocation  of
       1mopen 22mor 1msocket22m, or the result of a channel creation command provided by
       a Tcl extension. The channel must have been opened for input.

       If 4mchannelId24m 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  1m-nonewline  22mswitch  is  ignored  if the command returns
       before reaching the end of the file.

       1mRead 22mtranslates end-of-line sequences in the input into newline charac-
       ters  according  to  the  1m-translation 22moption for the channel.  See the
       1mfconfigure 22mmanual entry for a discussion on ways  in  which  1mfconfigure0m
       will alter input.


1mUSE WITH SERIAL PORTS0m
       For  most  applications  a channel connected to a serial port should be
       configured to be nonblocking: 1mfconfigure 4m22mchannelId24m 1m-blocking  4m22m024m.   Then
       1mread  22mbehaves much like described above.  Care must be taken when using
       1mread 22mon blocking serial ports:

       1mread 4m22mchannelId24m 4mnumChars0m
              In this form 1mread 22mblocks until 4mnumChars24m have been received  from
              the serial port.

       1mread 4m22mchannelId0m
              In  this form 1mread 22mblocks until the reception of the end-of-file
              character, see 1mfconfigure  -eofchar22m.  If  there  no  end-of-file
              character  has  been  configured for the channel, then 1mread 22mwill
              block forever.

1mEXAMPLE0m
       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 [1mread 22m$fl]
              close $fl
              set lines [split $data \n]


1mSEE ALSO0m
       file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)


1mKEYWORDS0m
       blocking,  channel, end of line, end of file, nonblocking, read, trans-
