[25] | 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 |
---|