Ticket [a173f9229f]: fcopy man page: document encoding error behaviour. Depreciate tcl8 encoding profile and same encoding = binary mode

1 files changed, 100 insertions, 31 deletions

diff --git a/doc/fcopy.n b/doc/fcopy.n
index b043898..307f40f 100644
--- a/doc/fcopy.n
+++ b/doc/fcopy.n
@@ -17,39 +17,108 @@ fcopy \- Copy data from one channel to another
 
 .SH DESCRIPTION
 .PP
-Reads characters from \fIinputChan\fR and writes them to \fIoutputChan\fR until
-all characters are copied, blocking until the copy is complete and returning
-the number of characters copied.  Leverages internal buffers to avoid extra
-copies and to avoid buffering too much data in main memory when copying large
-files to slow destinations like network sockets.
-.PP
-\fB\-size\fR limits the number of characters copied.
-.PP
-\fB\-command\fR makes \fBfcopy\fR return immediately, work in the background,
-and call \fIcallback\fR when the copy completes, providing as an additional
-argument the number of characters written to \fIoutputChan\fR.  If an error
-occurres during the background copy, another argument provides the message for
-the error.  \fIinputChan\fR and \fIoutputChan\fR are automatically configured
-for non-blocking mode if needed.  Background copying only works correctly if
-events are being processed e.g. via \fBvwait\fR or Tk.
-.PP
-During a background copy no other read operation may be performed on
-\fIinputChan\fR, and no other write operation may be performed on
-\fIoutputChan\fR.  However, write operations may by performed on
-\fIinputChan\fR and read operations may be performed on \fIoutputChan\fR, as
-exhibited by the bidirectional copy example below.
-.PP
-If either \fIinputChan\fR or \fIoutputChan\fR is closed while the copy is in
-progress, copying ceases and \fBno\fR callback is made.  If \fIinputChan\fR is
-closed all data already queued is written to \fIoutputChan\fR.
-.PP
-There should be no event handler established for \fIinputChan\fR  because it
-may become readable during a background copy.  An attempt to read or write from
-within an event handler results result in the error,  "channel busy".  Any
-wrong-sided I/O attempted (by a \fBfileevent\fR handler or otherwise) results
-in a
+The \fBfcopy\fR command copies data from one I/O channel, \fIinchan\fR to another I/O channel, \fIoutchan\fR.
+The \fBfcopy\fR command leverages the buffering in the Tcl I/O system to
+avoid extra copies and to avoid buffering too much data in
+main memory when copying large files to destinations like
+network sockets.
+.
+.SS "DATA QUANTITY"
+All data until \fIEOF\fR is copied.
+In addition, the quantity of copied data may be specified by the option \fB-size\fR.
+The given size is in bytes, if the input channel is in binary mode.
+Otherwise, it is in characters.
+.PP
+Depreciated feature: the transfer is treated as a binary transfer, if the encoding
+profile is set to
+.QW tcl8
+and the input encoding matches the output encoding.
+In this case, eventual encoding errors are not handled.
+An eventually given size is in bytes in this case.
+This feature exists for TCL 8 compatibility.
+.PP
+.SS "BACKGROUND OPERATION MODE"
+Without the \fB\-command\fR option, \fBfcopy\fR blocks until the copy is complete
+and returns the number of bytes or characters (using the same rules as
+for the \fB\-size\fR option) written to \fIoutchan\fR.
+.PP
+The \fB\-command\fR argument makes \fBfcopy\fR work in the background.
+In this case it returns immediately and the \fIcallback\fR is invoked
+later when the copy completes.
+The \fIcallback\fR is called with
+one or two additional
+arguments that indicates how many bytes were written to \fIoutchan\fR.
+If an error occurred during the background copy, the second argument is the
+error string associated with the error.
+With a background copy,
+it is not necessary to put \fIinchan\fR or \fIoutchan\fR into
+non-blocking mode; the \fBfcopy\fR command takes care of that automatically.
+However, it is necessary to enter the event loop by using
+the \fBvwait\fR command or by using Tk.
+.PP
+You are not allowed to do other input operations with \fIinchan\fR, or
+output operations with \fIoutchan\fR, during a background
+\fBfcopy\fR. The converse is entirely legitimate, as exhibited by the
+bidirectional fcopy example below.
+.PP
+If either \fIinchan\fR or \fIoutchan\fR get closed
+while the copy is in progress, the current copy is stopped
+and the command callback is \fInot\fR made.
+If \fIinchan\fR is closed,
+then all data already queued for \fIoutchan\fR is written out.
+.PP
+Note that \fIinchan\fR can become readable during a background copy.
+You should turn off any \fBfileevent\fR handlers during a background
+copy so those handlers do not interfere with the copy.
+Any wrong-sided I/O attempted (by a \fBfileevent\fR handler or otherwise) will get a
 .QW "channel busy"
 error.
+.
+.SS "CHANNEL TRANSLATION OPTIONS"
+\fBFcopy\fR translates end-of-line sequences in \fIinchan\fR and \fIoutchan\fR
+according to the \fB\-translation\fR option
+for these channels.
+See the manual entry for \fBfconfigure\fR for details on the
+\fB\-translation\fR option.
+The translations mean that the number of bytes read from \fIinchan\fR
+can be different than the number of bytes written to \fIoutchan\fR.
+Only the number of bytes written to \fIoutchan\fR is reported,
+either as the return value of a synchronous \fBfcopy\fR or
+as the argument to the callback for an asynchronous \fBfcopy\fR.
+.SS "CHANNEL ENCODING OPTIONS"
+\fBFcopy\fR obeys the encodings, profiles and character translations configured
+for the channels. This
+means that the incoming characters are converted internally first
+UTF-8 and then into the encoding of the channel \fBfcopy\fR writes
+to. See the manual entry for \fBfconfigure\fR for details on the
+\fB\-encoding\fR and \fB\-profile\fR options. No conversion is
+done if both channels are
+set to encoding
+.QW binary
+and have matching translations. If only the output channel is set to encoding
+.QW binary
+the system will write the internal UTF-8 representation of the incoming
+characters. If only the input channel is set to encoding
+.QW binary
+the system will assume that the incoming
+bytes are valid UTF-8 characters and convert them according to the
+output encoding. The behaviour of the system for bytes which are not
+valid UTF-8 characters is undefined in this case.
+.PP
+\fBFcopy\fR may throw encoding errors (error code \fBEILSEQ\fR), if input or output
+channel is configured to the
+.QW strict
+encoding profile.
+.PP
+If an encoding error arises on the input channel, any data before the error byte is
+written to the output channel. The input file pointer is located just before the
+values causing the encoding error.
+Error inspection or recovery is possible by changing the encoding parameters and
+invoking a file command (\fBread\fR, \fBfcopy\fR).
+.PP
+If an encoding error arises on the output channel, the errorneous data is lost.
+To make the difference between the input error case and the output error case, only the
+error message may be inspected (read or write), as both throw the error code \fIEILSEQ\fR.
 .SH EXAMPLES
 .PP
 The first example transfers the contents of one channel exactly to