1mNAME0m
       fcopy - Copy data from one channel to another.

1mSYNOPSIS0m
       1mfcopy 4m22minchan24m 4moutchan24m ?1m-size 4m22msize24m? ?1m-command 4m22mcallback24m?


1mDESCRIPTION0m
       The  1mfcopy  22mcommand copies data from one I/O channel, 4minchan24m to another
       I/O channel, 4moutchan24m.  The 1mfcopy 22mcommand 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.

       The  1mfcopy 22mcommand transfers data from 4minchan24m until end of file or 4msize0m
       bytes have been transferred. If no 1m-size 22margument is  given,  then  the
       copy  goes  until end of file.  All the data read from 4minchan24m is copied
       to 4moutchan24m.  Without the 1m-command 22moption, 1mfcopy 22mblocks until  the  copy
       is complete and returns the number of bytes written to 4moutchan24m.

       The 1m-command 22margument makes 1mfcopy 22mwork in the background.  In this case
       it returns immediately and the 4mcallback24m is invoked later when the  copy
       completes.  The 4mcallback24m is called with one or two additional arguments
       that indicates how many bytes were written to  4moutchan24m.   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  4minchan24m or 4moutchan24m into non-blocking mode; the 1mfcopy0m
       command takes care of that automatically.  However, it is necessary  to
       enter the event loop by using the 1mvwait 22mcommand or by using Tk.

       You  are  not allowed to do other I/O operations with 4minchan24m or 4moutchan0m
       during a background fcopy.  If either  4minchan24m  or  4moutchan24m  get  closed
       while the copy is in progress, the current copy is stopped and the com-
       mand callback is 4mnot24m made.  If 4minchan24m is closed, then all data  already
       queued for 4moutchan24m is written out.

       Note  that  4minchan24m  can  become readable during a background copy.  You
       should turn off any 1mfileevent 22mhandlers  during  a  background  copy  so
       those  handlers do not interfere with the copy.  Any I/O attempted by a
       1mfileevent 22mhandler will get a "channel busy" error.

       1mFcopy 22mtranslates end-of-line sequences in 4minchan24m and 4moutchan24m  according
       to  the  1m-translation  22moption for these channels.  See the manual entry
       for 1mfconfigure 22mfor details on the 1m-translation  22moption.   The  transla-
       tions  mean  that the number of bytes read from 4minchan24m can be different
       than the number of bytes written to 4moutchan24m.  Only the number of  bytes
       written  to  4moutchan24m  is reported, either as the return value of a syn-
       chronous 1mfcopy 22mor as the argument to the callback for  an  asynchronous
       1mfcopy22m.


1mEXAMPLE0m
       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.

              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



       The second example copies in chunks and tests for end of  file  in  the
       command callback

              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




1mSEE ALSO0m
       eof(n), fblocked(n), fconfigure(n)


1mKEYWORDS0m
       blocking,  channel, end of line, end of file, nonblocking, read, trans-
