diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/fcopy.n | 131 |
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 |