1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: read.n,v 1.15 2007/12/13 15:22:33 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH read n 8.1 Tcl "Tcl Built-In Commands" |
---|
12 | .BS |
---|
13 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
14 | .SH NAME |
---|
15 | read \- Read from a channel |
---|
16 | .SH SYNOPSIS |
---|
17 | \fBread \fR?\fB\-nonewline\fR? \fIchannelId\fR |
---|
18 | .sp |
---|
19 | \fBread \fIchannelId numChars\fR |
---|
20 | .BE |
---|
21 | |
---|
22 | .SH DESCRIPTION |
---|
23 | .PP |
---|
24 | In the first form, the \fBread\fR command reads all of the data from |
---|
25 | \fIchannelId\fR up to the end of the file. If the \fB\-nonewline\fR |
---|
26 | switch is specified then the last character of the file is discarded |
---|
27 | if it is a newline. In the second form, the extra argument specifies |
---|
28 | how many characters to read. Exactly that many characters will be |
---|
29 | read and returned, unless there are fewer than \fInumChars\fR left in |
---|
30 | the file; in this case all the remaining characters are returned. If |
---|
31 | the channel is configured to use a multi-byte encoding, then the |
---|
32 | number of characters read may not be the same as the number of bytes |
---|
33 | read. |
---|
34 | .PP |
---|
35 | \fIChannelId\fR must be an identifier for an open channel such as the |
---|
36 | Tcl standard input channel (\fBstdin\fR), the return value from an |
---|
37 | invocation of \fBopen\fR or \fBsocket\fR, or the result of a channel |
---|
38 | creation command provided by a Tcl extension. The channel must have |
---|
39 | been opened for input. |
---|
40 | .PP |
---|
41 | If \fIchannelId\fR is in nonblocking mode, the command may not read as |
---|
42 | many characters as requested: once all available input has been read, |
---|
43 | the command will return the data that is available rather than |
---|
44 | blocking for more input. If the channel is configured to use a |
---|
45 | multi-byte encoding, then there may actually be some bytes remaining |
---|
46 | in the internal buffers that do not form a complete character. These |
---|
47 | bytes will not be returned until a complete character is available or |
---|
48 | end-of-file is reached. The \fB\-nonewline\fR switch is ignored if |
---|
49 | the command returns before reaching the end of the file. |
---|
50 | .PP |
---|
51 | \fBRead\fR translates end-of-line sequences in the input into |
---|
52 | newline characters according to the \fB\-translation\fR option |
---|
53 | for the channel. |
---|
54 | See the \fBfconfigure\fR manual entry for a discussion on ways in |
---|
55 | which \fBfconfigure\fR will alter input. |
---|
56 | |
---|
57 | .SH "USE WITH SERIAL PORTS" |
---|
58 | '\" Note: this advice actually applies to many versions of Tcl |
---|
59 | |
---|
60 | For most applications a channel connected to a serial port should be |
---|
61 | configured to be nonblocking: \fBfconfigure \fIchannelId \fB\-blocking |
---|
62 | \fI0\fR. Then \fBread\fR behaves much like described above. Care |
---|
63 | must be taken when using \fBread\fR on blocking serial ports: |
---|
64 | .TP |
---|
65 | \fBread \fIchannelId numChars\fR |
---|
66 | In this form \fBread\fR blocks until \fInumChars\fR have been received |
---|
67 | from the serial port. |
---|
68 | .TP |
---|
69 | \fBread \fIchannelId\fR |
---|
70 | In this form \fBread\fR blocks until the reception of the end-of-file |
---|
71 | character, see \fBfconfigure -eofchar\fR. If there no end-of-file |
---|
72 | character has been configured for the channel, then \fBread\fR will |
---|
73 | block forever. |
---|
74 | .SH "EXAMPLE" |
---|
75 | This example code reads a file all at once, and splits it into a list, |
---|
76 | with each line in the file corresponding to an element in the list: |
---|
77 | .CS |
---|
78 | set fl [open /proc/meminfo] |
---|
79 | set data [\fBread\fR $fl] |
---|
80 | close $fl |
---|
81 | set lines [split $data \en] |
---|
82 | .CE |
---|
83 | |
---|
84 | .SH "SEE ALSO" |
---|
85 | file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3) |
---|
86 | |
---|
87 | .SH KEYWORDS |
---|
88 | blocking, channel, end of line, end of file, nonblocking, read, translation, encoding |
---|