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 |
---|