Document hoe Tcl_ReadChars() behaves in "-profile strict" mode when an encoding error happens.

1 files changed, 7 insertions, 5 deletions

diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index 1c6f619..85100fc 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -406,8 +406,10 @@ to UTF-8 based on the channel's encoding and storing the produced data in
 \fIreadObjPtr\fR's string representation.  The return value of
 \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR,
 that were stored in \fIreadObjPtr\fR.  If an error occurs while reading, the
-return value is TCL_INDEX_NONE and \fBTcl_ReadChars\fR records a POSIX error code that
-can be retrieved with \fBTcl_GetErrno\fR.
+return value is TCL_INDEX_NONE and \fBTcl_ReadChars\fR records a POSIX error
+code that can be retrieved with \fBTcl_GetErrno\fR. If an encoding error happens
+while the channel is in blocking mode with -profile strict, the characters
+retrieved until the encoding error happened will be stored in \fIreadObjPtr\fR.
 .PP
 Setting \fIcharsToRead\fR to TCL_INDEX_NONE will cause the command to read
 all characters currently available (non-blocking) or everything until
@@ -416,9 +418,9 @@ eof (blocking mode).
 The return value may be smaller than the value to read, indicating that less
 data than requested was available.  This is called a \fIshort read\fR.  In
 blocking mode, this can only happen on an end-of-file.  In nonblocking mode,
-a short read can also occur if there is not enough input currently
-available:  \fBTcl_ReadChars\fR returns a short count rather than waiting
-for more data.
+a short read can also occur if an encoding error is encountered (with -profile
+strict) or if there is not enough input currently available:
+\fBTcl_ReadChars\fR returns a short count rather than waiting for more data.
 .PP
 If the channel is in blocking mode, a return value of zero indicates an
 end-of-file condition.  If the channel is in nonblocking mode, a return