1read(n) Tcl Built-In Commands read(n)
2______________________________________________________________________________
6
8 read - Read from a channel
9
11 read ?-nonewline? channelId
12 read channelId numChars
14______________________________________________________________________________
15
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 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 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 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
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 read channelId numChars
54 In this form read blocks until numChars have been received from
55 the serial port.
56 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
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 set fl [open /proc/meminfo]
68 set data [read $fl]
69 close $fl
70 set lines [split $data \n]
71
73 file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)
74
76 blocking, channel, end of line, end of file, nonblocking, read, trans‐
77 lation, encoding
78Tcl 8.1 read(n)