distrib/share/tcl/help/tcl/files/fcopy

   1 NAME
   2        fcopy - Copy data from one channel to another.
   3
   4 SYNOPSIS
   5        fcopy inchan outchan ?-size size? ?-command callback?
   6
   7
   8 DESCRIPTION
   9        The  fcopy  command copies data from one I/O channel, inchan to another
  10        I/O channel, outchan.  The fcopy command leverages the buffering in the
  11        Tcl  I/O  system  to avoid extra copies and to avoid buffering too much
  12        data in main memory when copying large files to slow destinations  like
  13        network sockets.
  14
  15        The  fcopy command transfers data from inchan until end of file or size
  16        bytes have been transferred. If no -size argument is  given,  then  the
  17        copy  goes  until end of file.  All the data read from inchan is copied
  18        to outchan.  Without the -command option, fcopy blocks until  the  copy
  19        is complete and returns the number of bytes written to outchan.
  20
  21        The -command argument makes fcopy work in the background.  In this case
  22        it returns immediately and the callback is invoked later when the  copy
  23        completes.  The callback is called with one or two additional arguments
  24        that indicates how many bytes were written to  outchan.   If  an  error
  25        occurred  during  the background copy, the second argument is the error
  26        string associated with the error.  With a background copy,  it  is  not
  27        necessary  to  put  inchan or outchan into non-blocking mode; the fcopy
  28        command takes care of that automatically.  However, it is necessary  to
  29        enter the event loop by using the vwait command or by using Tk.
  30
  31        You  are  not allowed to do other I/O operations with inchan or outchan
  32        during a background fcopy.  If either  inchan  or  outchan  get  closed
  33        while the copy is in progress, the current copy is stopped and the com-
  34        mand callback is not made.  If inchan is closed, then all data  already
  35        queued for outchan is written out.
  36
  37        Note  that  inchan  can  become readable during a background copy.  You
  38        should turn off any fileevent handlers  during  a  background  copy  so
  39        those  handlers do not interfere with the copy.  Any I/O attempted by a
  40        fileevent handler will get a "channel busy" error.
  41
  42        Fcopy translates end-of-line sequences in inchan and outchan  according
  43        to  the  -translation  option for these channels.  See the manual entry
  44        for fconfigure for details on the -translation  option.   The  transla-
  45        tions  mean  that the number of bytes read from inchan can be different
  46        than the number of bytes written to outchan.  Only the number of  bytes
  47        written  to  outchan  is reported, either as the return value of a syn-
  48        chronous fcopy or as the argument to the callback for  an  asynchronous
  49        fcopy.
  50
  51        Fcopy  obeys the encodings configured for the channels. This means that
  52        the incoming characters are converted internally first UTF-8  and  then
  53        into  the encoding of the channel fcopy writes to. See the manual entry
  54        for fconfigure for details on the -encoding option.  No  conversion  is
  55        done  if both channels are set to encoding "binary". If only the output
  56        channel is set to encoding "binary" the system will write the  internal
  57        UTF-8  representation  of  the  incoming  characters. If only the input
  58        channel is set to encoding "binary" the system  will  assume  that  the
  59        incoming bytes are valid UTF-8 characters and convert them according to
  60        the output encoding. The behaviour of the system for  bytes  which  are
  61        not valid UTF-8 characters is undefined in this case.
  62
  63
  64 EXAMPLE
  65        This  first  example  shows  how the callback gets passed the number of
  66        bytes transferred.  It also uses vwait to put the application into  the
  67        event  loop.   Of course, this simplified example could be done without
  68        the command callback.
  69
  70               proc Cleanup {in out bytes {error {}}} {
  71                   global total
  72                   set total $bytes
  73                   close $in
  74                   close $out
  75                   if {[string length $error] != 0} {
  76                    # error occurred during the copy
  77                   }
  78               }
  79               set in [open $file1]
  80               set out [socket $server $port]
  81               fcopy $in $out -command [list Cleanup $in $out]
  82               vwait total
  83
  84
  85
  86        The second example copies in chunks and tests for end of  file  in  the
  87        command callback
  88
  89               proc CopyMore {in out chunk bytes {error {}}} {
  90                   global total done
  91                   incr total $bytes
  92                   if {([string length $error] != 0) || [eof $in]} {
  93                    set done $total
  94                    close $in
  95                    close $out
  96                   } else {
  97                    fcopy $in $out -command [list CopyMore $in $out $chunk] \
  98                        -size $chunk
  99                   }
 100               }
 101               set in [open $file1]
 102               set out [socket $server $port]
 103               set chunk 1024
 104               set total 0
 105               fcopy $in $out -command [list CopyMore $in $out $chunk] -size $chunk
 106               vwait done
 107
 108
 109
 110
 111 SEE ALSO
 112        eof(n), fblocked(n), fconfigure(n)
 113
 114
 115 KEYWORDS
 116        blocking,  channel, end of line, end of file, nonblocking, read, trans-