read(3tcl)						       Tcl Built-In Commands							read(3tcl)

__________________________________________________________________________________________________________________________________________________

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  charac-
	      ter 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 
]

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

Tcl									8.1								read(3tcl)