summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--ChangeLog7
-rw-r--r--doc/fcopy.n37
2 files changed, 29 insertions, 15 deletions
diff --git a/ChangeLog b/ChangeLog
index 2296924..c592c22 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -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