1read(n)                      Tcl Built-In Commands                     read(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       read - Read from a channel
9

SYNOPSIS

11       read ?-nonewline? channelId
12
13       read channelId numChars
14______________________________________________________________________________
15

DESCRIPTION

17       In  the  first  form, the read command reads all of the data from chan‐
18       nelId up to the end of the file.  If the -nonewline switch is specified
19       then  the  last  character of the file is discarded if it is a newline.
20       In the second form, the extra argument specifies how many characters to
21       read.   Exactly  that many characters will be read and returned, unless
22       there are fewer than numChars left in the file; in this  case  all  the
23       remaining characters are returned.  If the channel is configured to use
24       a multi-byte encoding, then the number of characters read  may  not  be
25       the same as the number of bytes read.
26
27       ChannelId  must  be  an  identifier for an open channel such as the Tcl
28       standard input channel (stdin), the return value from an invocation  of
29       open or socket, or the result of a channel creation command provided by
30       a Tcl extension. The channel must have been opened for input.
31
32       If channelId is in nonblocking mode, the command may not read  as  many
33       characters  as  requested:  once all available input has been read, the
34       command will return the data that is available rather than blocking for
35       more input.  If the channel is configured to use a multi-byte encoding,
36       then there may actually be some bytes remaining in the internal buffers
37       that  do  not  form  a  complete  character.   These  bytes will not be
38       returned until a complete character  is  available  or  end-of-file  is
39       reached.   The  -nonewline  switch  is  ignored  if the command returns
40       before reaching the end of the file.
41
42       Read translates end-of-line sequences in the input into newline charac‐
43       ters  according  to  the  -translation option for the channel.  See the
44       fconfigure manual entry for a discussion on ways  in  which  fconfigure
45       will alter input.
46

USE WITH SERIAL PORTS

48       For  most  applications  a channel connected to a serial port should be
49       configured to be nonblocking: fconfigure channelId -blocking  0.   Then
50       read  behaves much like described above.  Care must be taken when using
51       read on blocking serial ports:
52
53       read channelId numChars
54              In this form read blocks until numChars have been received  from
55              the serial port.
56
57       read channelId
58              In  this form read blocks until the reception of the end-of-file
59              character, see fconfigure  -eofchar.  If  there  no  end-of-file
60              character  has  been  configured for the channel, then read will
61              block forever.
62

EXAMPLE

64       This example code reads a file all at once, and splits it into a  list,
65       with each line in the file corresponding to an element in the list:
66
67              set fl [open /proc/meminfo]
68              set data [read $fl]
69              close $fl
70              set lines [split $data \n]
71

SEE ALSO

73       file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)
74

KEYWORDS

76       blocking,  channel, end of line, end of file, nonblocking, read, trans‐
77       lation, encoding
78
79
80
81Tcl                                   8.1                              read(n)
Impressum