diff options
| -rw-r--r-- | doc/gets.n | 33 | ||||
| -rw-r--r-- | doc/puts.n | 2 | ||||
| -rw-r--r-- | doc/read.n | 29 |
3 files changed, 60 insertions, 4 deletions
@@ -50,9 +50,38 @@ these three cases. .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 which accepts the data. An encoding error is reported by the POSIX error code \fBEILSEQ\fR. -The file pointer is unchanged in the error case and an eventual returned -character count is \fB-1\fR. +The file pointer is unchanged in the error case. +.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 example +.CS +% set f [open test_A_195_B.txt wb]; puts -nonewline $f A\xC3B; close $f +.CE +Encoding error example +.CS +% set f [open test_A_195_B.txt r] +file384b6a8 +% fconfigure $f -encoding utf-8 -profile strict +% catch {gets $f} e d +1 +% set d +-data A -code 1 -level 0 +-errorstack {INNER {invokeStk1 gets file384b6a8}} +-errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}} +-errorinfo {...} -errorline 1 +% tell $f +0 +% fconfigure $f -encoding binary -profile strict +% gets $f +AÃB +.CE +ToDo: -data is TIP 653 and may be removed here or explained. .SH "EXAMPLE" This example reads a file one line at a time and prints it out with the current line number attached to the start of each line. @@ -66,7 +66,7 @@ via a file event that the channel is ready for more output data). .PP Encoding errors may exist, if the encoding profile \fBstrict\fR is used. \fBputs\fR writes out data until an encoding error occurs and fails with -POSIX error code \fBEILSEQ\fR on a non encodable data. +POSIX error code \fBEILSEQ\fR. .SH EXAMPLES .PP @@ -71,10 +71,18 @@ In the next call, no data is returned and the \fBEILSEQ\fR error state is set. 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 +% fconfigure $f -encoding utf-8 -profile strict -blocking 1 % catch {read $f} e d 1 % set d @@ -87,6 +95,25 @@ file35a65a0 % fconfigure $f -encoding binary -profile strict % read $f ÃB +% close $f +.CE +Non blocking example +. +.CS +% set f [open test_A_195_B.txt r] +file35a65a0 +% fconfigure $f -encoding utf-8 -profile strict -blocking 1 +% read $f +A +% tell $f +1 +% catch {read $f} e d +1 +% set d +-data {} -code 1 -level 0 +-errorstack {INNER {invokeStk1 read file384b228}} +-errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}} +-errorinfo {...} -errorline 1 .CE ToDo: -data is TIP 653 and may be removed here or explained. .SH "USE WITH SERIAL PORTS" |