Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
read(3tcl)		     Tcl Built-In Commands		    read(3tcl)


       read - Read from	a channel

       read ?-nonewline? channelId

       read channelId numChars

       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 re-
       turned until a  complete	 character  is	available  or  end-of-file  is
       reached.	  The  -nonewline switch is ignored if the command returns be-
       fore 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.

       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.

       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]

       file(3tcl),  eof(3tcl), fblocked(3tcl), fconfigure(3tcl), Tcl_Standard-

       blocking, channel, end of line, end of file, nonblocking, read,	trans-
       lation, encoding

Tcl				      8.1			    read(3tcl)


Want to link to this manual page? Use this URL:

home | help