diff options
| -rw-r--r-- | ChangeLog | 7 | ||||
| -rw-r--r-- | doc/fcopy.n | 37 |
2 files changed, 29 insertions, 15 deletions
@@ -1,8 +1,11 @@ 2005-04-13 Donal K. Fellows <donal.k.fellows@manchester.ac.uk> + * doc/fcopy.n: Improved documentation on copying binary files, + added an example and mentioned the use of [file copy]. * doc/fconfigure.n: Improved documentation of -encoding binary - option following comments from Steve Manning <steve@manning.net> - that the current documentation was not clear. + option. + This is all following comments from Steve Manning <steve@manning.net> + on comp.lang.tcl that the current documentation was not clear. 2005-04-13 Miguel Sofer <msofer@users.sf.net> diff --git a/doc/fcopy.n b/doc/fcopy.n index a90cc7b..a97950b 100644 --- a/doc/fcopy.n +++ b/doc/fcopy.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: fcopy.n,v 1.4 2004/09/06 09:44:56 dkf Exp $ +'\" RCS: @(#) $Id: fcopy.n,v 1.5 2005/04/13 11:06:27 dkf Exp $ '\" .so man.macros .TH fcopy n 8.0 Tcl "Tcl Built-In Commands" @@ -72,12 +72,15 @@ Only the number of bytes written to \fIoutchan\fR is reported, either as the return value of a synchronous \fBfcopy\fP or as the argument to the callback for an asynchronous \fBfcopy\fP. .PP -\fBFcopy\fR obeys the encodings configured for the channels. This +\fBFcopy\fR obeys the encodings 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 option. No conversion is done if both channels are -set to encoding "binary". If only the output channel is set to +\fB\-encoding\fR and \fB\-translation\fR options. No conversion is +done if both channels are +set to encoding "binary" and have matching translations. If only the +output channel is set to encoding "binary" the system will write the internal UTF-8 representation of the incoming characters. If only the input channel is set to encoding "binary" the system will assume that the incoming @@ -85,9 +88,19 @@ 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. -.SH EXAMPLE +.SH EXAMPLES .PP -This first example shows how the callback gets +The first example transfers the contents of one channel exactly to +another. Note that when copying one file to another, it is better to +use \fBfile copy\fR which also copies file metadata (e.g. the file +access permissions) where possible. +.DS +fconfigure $in -translation binary +fconfigure $out -translation binary +\fBfcopy\fR $in $out +.DE +.PP +This second example shows how the callback gets passed the number of bytes transferred. It also uses vwait to put the application into the event loop. Of course, this simplified example could be done without the command @@ -104,12 +117,11 @@ proc Cleanup {in out bytes {error {}}} { } set in [open $file1] set out [socket $server $port] -fcopy $in $out -command [list Cleanup $in $out] +\fBfcopy\fR $in $out -command [list Cleanup $in $out] vwait total - .DE .PP -The second example copies in chunks and tests for end of file +The third example copies in chunks and tests for end of file in the command callback .DS proc CopyMore {in out chunk bytes {error {}}} { @@ -120,7 +132,7 @@ proc CopyMore {in out chunk bytes {error {}}} { close $in close $out } else { - fcopy $in $out -command [list CopyMore $in $out $chunk] \\ + \fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] \\ -size $chunk } } @@ -128,13 +140,12 @@ set in [open $file1] set out [socket $server $port] set chunk 1024 set total 0 -fcopy $in $out -command [list CopyMore $in $out $chunk] -size $chunk +\fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] -size $chunk vwait done - .DE .SH "SEE ALSO" -eof(n), fblocked(n), fconfigure(n) +eof(n), fblocked(n), fconfigure(n), file(n) .SH KEYWORDS blocking, channel, end of line, end of file, nonblocking, read, translation |