[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
| 3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
---|
| 4 | '\" |
---|
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 7 | '\" |
---|
| 8 | '\" RCS: @(#) $Id: fcopy.n,v 1.17 2007/12/13 15:22:32 dgp Exp $ |
---|
| 9 | '\" |
---|
| 10 | .so man.macros |
---|
| 11 | .TH fcopy n 8.0 Tcl "Tcl Built-In Commands" |
---|
| 12 | .BS |
---|
| 13 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
| 14 | .SH NAME |
---|
| 15 | fcopy \- Copy data from one channel to another |
---|
| 16 | .SH SYNOPSIS |
---|
| 17 | \fBfcopy \fIinchan\fR \fIoutchan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? |
---|
| 18 | .BE |
---|
| 19 | |
---|
| 20 | .SH DESCRIPTION |
---|
| 21 | .PP |
---|
| 22 | The \fBfcopy\fR command copies data from one I/O channel, \fIinchan\fR to another I/O channel, \fIoutchan\fR. |
---|
| 23 | The \fBfcopy\fR command leverages the buffering in the Tcl I/O system to |
---|
| 24 | avoid extra copies and to avoid buffering too much data in |
---|
| 25 | main memory when copying large files to slow destinations like |
---|
| 26 | network sockets. |
---|
| 27 | .PP |
---|
| 28 | The \fBfcopy\fR |
---|
| 29 | command transfers data from \fIinchan\fR until end of file |
---|
| 30 | or \fIsize\fR bytes have been |
---|
| 31 | transferred. If no \fB\-size\fR argument is given, |
---|
| 32 | then the copy goes until end of file. |
---|
| 33 | All the data read from \fIinchan\fR is copied to \fIoutchan\fR. |
---|
| 34 | Without the \fB\-command\fR option, \fBfcopy\fR blocks until the copy is complete |
---|
| 35 | and returns the number of bytes written to \fIoutchan\fR. |
---|
| 36 | .PP |
---|
| 37 | The \fB\-command\fR argument makes \fBfcopy\fR work in the background. |
---|
| 38 | In this case it returns immediately and the \fIcallback\fR is invoked |
---|
| 39 | later when the copy completes. |
---|
| 40 | The \fIcallback\fR is called with |
---|
| 41 | one or two additional |
---|
| 42 | arguments that indicates how many bytes were written to \fIoutchan\fR. |
---|
| 43 | If an error occurred during the background copy, the second argument is the |
---|
| 44 | error string associated with the error. |
---|
| 45 | With a background copy, |
---|
| 46 | it is not necessary to put \fIinchan\fR or \fIoutchan\fR into |
---|
| 47 | non-blocking mode; the \fBfcopy\fR command takes care of that automatically. |
---|
| 48 | However, it is necessary to enter the event loop by using |
---|
| 49 | the \fBvwait\fR command or by using Tk. |
---|
| 50 | .PP |
---|
| 51 | You are not allowed to do other I/O operations with |
---|
| 52 | \fIinchan\fR or \fIoutchan\fR during a background \fBfcopy\fR. |
---|
| 53 | If either \fIinchan\fR or \fIoutchan\fR get closed |
---|
| 54 | while the copy is in progress, the current copy is stopped |
---|
| 55 | and the command callback is \fInot\fR made. |
---|
| 56 | If \fIinchan\fR is closed, |
---|
| 57 | then all data already queued for \fIoutchan\fR is written out. |
---|
| 58 | .PP |
---|
| 59 | Note that \fIinchan\fR can become readable during a background copy. |
---|
| 60 | You should turn off any \fBfileevent\fR handlers during a background |
---|
| 61 | copy so those handlers do not interfere with the copy. |
---|
| 62 | Any I/O attempted by a \fBfileevent\fR handler will get a |
---|
| 63 | .QW "channel busy" |
---|
| 64 | error. |
---|
| 65 | .PP |
---|
| 66 | \fBFcopy\fR translates end-of-line sequences in \fIinchan\fR and \fIoutchan\fR |
---|
| 67 | according to the \fB\-translation\fR option |
---|
| 68 | for these channels. |
---|
| 69 | See the manual entry for \fBfconfigure\fR for details on the |
---|
| 70 | \fB\-translation\fR option. |
---|
| 71 | The translations mean that the number of bytes read from \fIinchan\fR |
---|
| 72 | can be different than the number of bytes written to \fIoutchan\fR. |
---|
| 73 | Only the number of bytes written to \fIoutchan\fR is reported, |
---|
| 74 | either as the return value of a synchronous \fBfcopy\fR or |
---|
| 75 | as the argument to the callback for an asynchronous \fBfcopy\fR. |
---|
| 76 | .PP |
---|
| 77 | \fBFcopy\fR obeys the encodings and character translations configured |
---|
| 78 | for the channels. This |
---|
| 79 | means that the incoming characters are converted internally first |
---|
| 80 | UTF-8 and then into the encoding of the channel \fBfcopy\fR writes |
---|
| 81 | to. See the manual entry for \fBfconfigure\fR for details on the |
---|
| 82 | \fB\-encoding\fR and \fB\-translation\fR options. No conversion is |
---|
| 83 | done if both channels are |
---|
| 84 | set to encoding |
---|
| 85 | .QW binary |
---|
| 86 | and have matching translations. If only the output channel is set to encoding |
---|
| 87 | .QW binary |
---|
| 88 | the system will write the internal UTF-8 representation of the incoming |
---|
| 89 | characters. If only the input channel is set to encoding |
---|
| 90 | .QW binary |
---|
| 91 | the system will assume that the incoming |
---|
| 92 | bytes are valid UTF-8 characters and convert them according to the |
---|
| 93 | output encoding. The behaviour of the system for bytes which are not |
---|
| 94 | valid UTF-8 characters is undefined in this case. |
---|
| 95 | |
---|
| 96 | .SH EXAMPLES |
---|
| 97 | .PP |
---|
| 98 | The first example transfers the contents of one channel exactly to |
---|
| 99 | another. Note that when copying one file to another, it is better to |
---|
| 100 | use \fBfile copy\fR which also copies file metadata (e.g. the file |
---|
| 101 | access permissions) where possible. |
---|
| 102 | .CS |
---|
| 103 | fconfigure $in -translation binary |
---|
| 104 | fconfigure $out -translation binary |
---|
| 105 | \fBfcopy\fR $in $out |
---|
| 106 | .CE |
---|
| 107 | .PP |
---|
| 108 | This second example shows how the callback gets |
---|
| 109 | passed the number of bytes transferred. |
---|
| 110 | It also uses vwait to put the application into the event loop. |
---|
| 111 | Of course, this simplified example could be done without the command |
---|
| 112 | callback. |
---|
| 113 | .CS |
---|
| 114 | proc Cleanup {in out bytes {error {}}} { |
---|
| 115 | global total |
---|
| 116 | set total $bytes |
---|
| 117 | close $in |
---|
| 118 | close $out |
---|
| 119 | if {[string length $error] != 0} { |
---|
| 120 | # error occurred during the copy |
---|
| 121 | } |
---|
| 122 | } |
---|
| 123 | set in [open $file1] |
---|
| 124 | set out [socket $server $port] |
---|
| 125 | \fBfcopy\fR $in $out -command [list Cleanup $in $out] |
---|
| 126 | vwait total |
---|
| 127 | .CE |
---|
| 128 | .PP |
---|
| 129 | The third example copies in chunks and tests for end of file |
---|
| 130 | in the command callback |
---|
| 131 | .CS |
---|
| 132 | proc CopyMore {in out chunk bytes {error {}}} { |
---|
| 133 | global total done |
---|
| 134 | incr total $bytes |
---|
| 135 | if {([string length $error] != 0) || [eof $in]} { |
---|
| 136 | set done $total |
---|
| 137 | close $in |
---|
| 138 | close $out |
---|
| 139 | } else { |
---|
| 140 | \fBfcopy\fR $in $out -size $chunk \e |
---|
| 141 | -command [list CopyMore $in $out $chunk] |
---|
| 142 | } |
---|
| 143 | } |
---|
| 144 | set in [open $file1] |
---|
| 145 | set out [socket $server $port] |
---|
| 146 | set chunk 1024 |
---|
| 147 | set total 0 |
---|
| 148 | \fBfcopy\fR $in $out -size $chunk \e |
---|
| 149 | -command [list CopyMore $in $out $chunk] |
---|
| 150 | vwait done |
---|
| 151 | .CE |
---|
| 152 | |
---|
| 153 | .SH "SEE ALSO" |
---|
| 154 | eof(n), fblocked(n), fconfigure(n), file(n) |
---|
| 155 | |
---|
| 156 | .SH KEYWORDS |
---|
| 157 | blocking, channel, end of line, end of file, nonblocking, read, translation |
---|