Tcl Built-In Commands                                   fcopy(1T)





NAME
     fcopy - Copy data from one channel to another.

SYNOPSIS
     fcopy inchan outchan ?-size size? ?-command callback?



DESCRIPTION
     The fcopy command copies data from one I/O  channel,  inchan
     to  another  I/O channel, outchan.  The fcopy command lever-
     ages 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 fcopy command transfers data from inchan  until  end  of
     file  or size bytes have been transferred. If no -size argu-
     ment is given, then the copy goes until end  of  file.   All
     the data read from inchan is copied to outchan.  Without the
     -command option, fcopy blocks until the copy is complete and
     returns the number of bytes written to outchan.

     The -command argument makes fcopy work  in  the  background.
     In  this  case  it  returns  immediately and the callback is
     invoked later when the  copy  completes.   The  callback  is
     called  with  one or two additional arguments that indicates
     how many  bytes  were  written  to  outchan.   If  an  error
     occurred  during the background copy, the second argument is
     the error string associated with the error.   With  a  back-
     ground  copy,  it  is not necessary to put inchan or outchan
     into non-blocking mode; the fcopy command takes care of that
     automatically.   However, it is necessary to enter the event
     loop by using the vwait command or by using Tk.

     You are not allowed to do other I/O operations  with  inchan
     or  outchan  during a background fcopy.  If either inchan or
     outchan get closed  while  the  copy  is  in  progress,  the
     current  copy  is  stopped  and  the command callback is not
     made.  If inchan is closed, then all data already queued for
     outchan is written out.

     Note that inchan can become  readable  during  a  background
     copy.   You  should turn off any fileevent handlers during a
     background copy so those handlers do not interfere with  the
     copy.   Any  I/O attempted by a fileevent handler will get a
     "channel busy" error.

     Fcopy translates end-of-line sequences in inchan and outchan
     according  to  the  -translation  option for these channels.



Tcl                     Last change: 8.0                        1






Tcl Built-In Commands                                   fcopy(1T)



     See the manual entry  for  fconfigure  for  details  on  the
     -translation  option.  The translations mean that the number
     of bytes read from inchan can be different than  the  number
     of bytes written to outchan.  Only the number of bytes writ-
     ten to outchan is reported, either as the return value of  a
     synchronous  fcopy or as the argument to the callback for an
     asynchronous fcopy.

     Fcopy obeys the encodings configured for the channels.  This
     means  that the incoming characters are converted internally
     first UTF-8 and then into the encoding of the channel  fcopy
     writes  to.  See the manual entry for fconfigure for details
     on the -encoding option. No conversion is done if both chan-
     nels  are set to encoding "binary". If only the output chan-
     nel is set to encoding "binary" the system  will  write  the
     internal UTF-8 representation of the incoming characters. If
     only the input channel is set to encoding "binary" the  sys-
     tem  will  assume  that  the  incoming bytes are valid UTF-8
     characters and convert them according to the  output  encod-
     ing.  The  behaviour  of  the system for bytes which are not
     valid UTF-8 characters is undefined in this case.


EXAMPLE
     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]} {



Tcl                     Last change: 8.0                        2






Tcl Built-In Commands                                   fcopy(1T)



               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




SEE ALSO
     eof(1T), fblocked(1T), fconfigure(1T)


KEYWORDS
     blocking, channel, end of line, end  of  file,  nonblocking,
     read, translation

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     
       ATRIBUTE TYPE     ATRIBUTE VALUE
    
     Availability         SUNWTcl        
    
     Interface Stability  Uncommitted    
    

NOTES
     Source for Tcl is available on http:/opensolaris.org.















Tcl                     Last change: 8.0                        3