diff options
Diffstat (limited to 'doc/read.n')
| -rw-r--r-- | doc/read.n | 96 |
1 files changed, 10 insertions, 86 deletions
@@ -4,7 +4,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH read n 8.1 Tcl "Tcl Built-In Commands" .so man.macros .BS @@ -16,6 +16,7 @@ read \- Read from a channel .sp \fBread \fIchannelId numChars\fR .BE + .SH DESCRIPTION .PP In the first form, the \fBread\fR command reads all of the data from @@ -50,113 +51,36 @@ 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 +configured to be nonblocking: \fBfconfigure \fIchannelId \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 -. +\fBread \fIchannelId numChars\fR In this form \fBread\fR blocks until \fInumChars\fR have been received from the serial port. .TP -\fBread \fIchannelId\fR -. +\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, see \fBfconfigure -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 + .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 -'\"Local Variables: -'\"mode: nroff -'\"End: |