From eb121d13b5b652da7400bbe6b5b58d06c992709e Mon Sep 17 00:00:00 2001 From: oehhar Date: Sun, 5 Nov 2023 17:56:27 +0000 Subject: Worked on examples for read and gets --- doc/gets.n | 33 +++++++++++++++++++++++++++++++-- doc/puts.n | 2 +- doc/read.n | 29 ++++++++++++++++++++++++++++- 3 files changed, 60 insertions(+), 4 deletions(-) diff --git a/doc/gets.n b/doc/gets.n index 0e4239f..59e00c7 100644 --- a/doc/gets.n +++ b/doc/gets.n @@ -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. diff --git a/doc/puts.n b/doc/puts.n index e8df581..0943f87 100644 --- a/doc/puts.n +++ b/doc/puts.n @@ -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 diff --git a/doc/read.n b/doc/read.n index 66e6c30..4e93d58 100644 --- a/doc/read.n +++ b/doc/read.n @@ -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" -- cgit v0.12