109 lines
5.0 KiB
HTML
109 lines
5.0 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - fcopy manual page</TITLE></HEAD><BODY>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
fcopy - Copy data from one channel to another.
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>fcopy </B><I>inchan</I> <I>outchan</I> ?<B>-size </B><I>size</I>? ?<B>-command </B><I>callback</I>?<BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
The <B>fcopy</B> command copies data from one I/O channel, <I>inchan</I> to another I/O channel, <I>outchan</I>.
|
|
The <B>fcopy</B> 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 slow destinations like
|
|
network sockets.
|
|
<P>
|
|
The <B>fcopy</B>
|
|
command transfers data from <I>inchan</I> until end of file
|
|
or <I>size</I> bytes have been
|
|
transferred. If no <B>-size</B> argument is given,
|
|
then the copy goes until end of file.
|
|
All the data read from <I>inchan</I> is copied to <I>outchan</I>.
|
|
Without the <B>-command</B> option, <B>fcopy</B> blocks until the copy is complete
|
|
and returns the number of bytes written to <I>outchan</I>.
|
|
<P>
|
|
The <B>-command</B> argument makes <B>fcopy</B> work in the background.
|
|
In this case it returns immediately and the <I>callback</I> is invoked
|
|
later when the copy completes.
|
|
The <I>callback</I> is called with
|
|
one or two additional
|
|
arguments that indicates how many bytes were written to <I>outchan</I>.
|
|
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 <I>inchan</I> or <I>outchan</I> into
|
|
non-blocking mode; the <B>fcopy</B> command takes care of that automatically.
|
|
However, it is necessary to enter the event loop by using
|
|
the <B><A HREF="../TkCmd/vwait.htm">vwait</A></B> command or by using Tk.
|
|
<P>
|
|
You are not allowed to do other I/O operations with
|
|
<I>inchan</I> or <I>outchan</I> during a background fcopy.
|
|
If either <I>inchan</I> or <I>outchan</I> get closed
|
|
while the copy is in progress, the current copy is stopped
|
|
and the command callback is <I>not</I> made.
|
|
If <I>inchan</I> is closed,
|
|
then all data already queued for <I>outchan</I> is written out.
|
|
<P>
|
|
Note that <I>inchan</I> can become readable during a background copy.
|
|
You should turn off any <B><A HREF="../TkCmd/fileevent.htm">fileevent</A></B> handlers during a background
|
|
copy so those handlers do not interfere with the copy.
|
|
Any I/O attempted by a <B><A HREF="../TkCmd/fileevent.htm">fileevent</A></B> handler will get a "channel busy" error.
|
|
<P>
|
|
<B>Fcopy</B> translates end-of-line sequences in <I>inchan</I> and <I>outchan</I>
|
|
according to the <B>-translation</B> option
|
|
for these channels.
|
|
See the manual entry for <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> for details on the
|
|
<B>-translation</B> option.
|
|
The translations mean that the number of bytes read from <I>inchan</I>
|
|
can be different than the number of bytes written to <I>outchan</I>.
|
|
Only the number of bytes written to <I>outchan</I> is reported,
|
|
either as the return value of a synchronous <B>fcopy</B> or
|
|
as the argument to the callback for an asynchronous <B>fcopy</B>.
|
|
|
|
<H3><A NAME="M5">EXAMPLE</A></H3>
|
|
This first 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
|
|
callback.
|
|
<PRE>proc Cleanup {in out bytes {error {}}} {
|
|
global total
|
|
set total $bytes
|
|
close $in
|
|
close $out
|
|
if {[string length $error] != 0} {
|
|
# error occurred during the copy
|
|
}
|
|
}
|
|
set in [open $file1]
|
|
set out [socket $server $port]
|
|
fcopy $in $out -command [list Cleanup $in $out]
|
|
vwait total</PRE>
|
|
<P>
|
|
The second example copies in chunks and tests for end of file
|
|
in the command callback
|
|
<PRE>proc CopyMore {in out chunk bytes {error {}}} {
|
|
global total done
|
|
incr total $bytes
|
|
if {([string length $error] != 0) || [eof $in] {
|
|
set done $total
|
|
close $in
|
|
close $out
|
|
} else {
|
|
fcopy $in $out -command [list CopyMore $in $out $chunk] \
|
|
-size $chunk
|
|
}
|
|
}
|
|
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
|
|
vwait done</PRE>
|
|
<H3><A NAME="M6">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/eof.htm">eof</A></B>, <B><A HREF="../TkCmd/fblocked.htm">fblocked</A></B>, <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B>
|
|
<H3><A NAME="M7">KEYWORDS</A></H3>
|
|
<A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/E.htm#end of line">end of line</A>, <A href="../Keywords/E.htm#end of file">end of file</A>, <A href="../Keywords/N.htm#nonblocking">nonblocking</A>, <A href="../Keywords/R.htm#read">read</A>, <A href="../Keywords/T.htm#translation">translation</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|