diff options
Diffstat (limited to 'doc/read.n')
| -rw-r--r-- | doc/read.n | 142 |
1 files changed, 3 insertions, 139 deletions
@@ -18,146 +18,10 @@ read \- Read from a channel .BE .SH DESCRIPTION .PP -In the first form, the \fBread\fR command reads all of the data from -\fIchannelId\fR up to the end of the file. If the \fB\-nonewline\fR -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 \fInumChars\fR 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. -.PP -\fIChannelId\fR must be an identifier for an open channel such as the -Tcl standard input channel (\fBstdin\fR), the return value from an -invocation of \fBopen\fR or \fBsocket\fR, or the result of a channel -creation command provided by a Tcl extension. The channel must have -been opened for input. -.PP -If \fIchannelId\fR 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 returned until a complete character is available or -end-of-file is reached. The \fB\-nonewline\fR switch is ignored if -the command returns before reaching the end of the file. -.PP -\fBRead\fR translates end-of-line sequences in the input into -newline characters according to the \fB\-translation\fR option -for the channel. -See the \fBfconfigure\fR manual entry for a discussion on ways in -which \fBfconfigure\fR will alter input. -.SH "ENCODING ERRORS" -.PP -Encoding errors may exist, if the encoding profile \fBstrict\fR is used. -Encoding errors are special, as an eventual introspection or recovery is -possible by changing to an encoding (or encoding profile), which accepts -the data. -An encoding error is reported by the POSIX error code \fBEILSEQ\fR. -.PP -In blocking mode, the error is directly thrown, even, if there is a -leading decodable data portion. -The file pointer is advanced just before the encoding error. -An eventual well decoded data chunk before the encoding error is returned -in the error option dictionary key \fB\-data\fR. -The value of the key contains the empty string, if the error arises at the -first data position. -.PP -In non blocking mode, first, any data without encoding error is returned -(without error state). -In the next call, no data is returned and the \fBEILSEQ\fR error state is set. -The key \fB\-data\fR is not present. -.PP -Here is an example with an encoding error in UTF-8 encoding, which is then -introspected by a switch to the binary encoding. The test file contains a not -continued multi-byte sequence at position 1 (\fBA \\xC3 B\fR): -.PP -File creation for examples -. -.CS -% set f [open test_A_195_B.txt wb]; puts -nonewline $f A\\xC3B; close $f -.CE -Blocking example -. -.CS -% set f [open test_A_195_B.txt r] -file35a65a0 -% fconfigure $f -encoding utf-8 -profile strict -blocking 1 -% catch {read $f} e d -1 -% set d --data A -code 1 -level 0 --errorstack {INNER {invokeStk1 read file35a65a0}} --errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}} --errorinfo {...} -errorline 1 -% tell $f -1 -% fconfigure $f -encoding binary -profile strict -% read $f -ÃB -% close $f -.CE -The already decoded data "A" is returned in the error options dictionary key -\fB\-data\fR. -The file position is advanced on the encoding error position 1. -The data at the error position is thus recovered by the next \fBread\fR command. -.PP -Non blocking example -. -.CS -% set f [open test_A_195_B.txt r] -file35a65a0 -% fconfigure $f -encoding utf-8 -profile strict -blocking 0 -% read $f -A -% tell $f -1 -% catch {read $f} e d -1 -% set d --code 1 -level 0 --errorstack {INNER {invokeStk1 read file384b228}} --errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}} --errorinfo {...} -errorline 1 -.CE -.SH "USE WITH SERIAL PORTS" -'\" Note: this advice actually applies to many versions of Tcl -.PP -For most applications a channel connected to a serial port should be -configured to be nonblocking: \fBfconfigure\fI channelId \fB\-blocking -\fI0\fR. Then \fBread\fR behaves much like described above. Care -must be taken when using \fBread\fR on blocking serial ports: -.TP -\fBread \fIchannelId numChars\fR -. -In this form \fBread\fR blocks until \fInumChars\fR have been received -from the serial port. -.TP -\fBread \fIchannelId\fR -. -In this form \fBread\fR blocks until the reception of the end-of-file -character, see \fBfconfigure\fR \fB\-eofchar\fR. If there no end-of-file -character has been configured for the channel, then \fBread\fR will -block forever. -.SH "EXAMPLE" -.PP -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: -.PP -.CS -set fl [open /proc/meminfo] -set data [\fBread\fR $fl] -close $fl -set lines [split $data \en] -.CE +The \fBread\fR command has been superceded by the \fBchan read\fR +command which supports the same syntax and options. .SH "SEE ALSO" -file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3) -.SH KEYWORDS -blocking, channel, end of line, end of file, nonblocking, read, translation, -encoding +chan(n) '\"Local Variables: '\"mode: nroff '\"End: |