fcopy man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin logo
[printable version]

fcopy(n)		     Tcl Built-In Commands		      fcopy(n)

______________________________________________________________________________

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 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  fcopy command transfers data from inchan until end of file or size
       bytes have been transferred. If no -size argument 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 background 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 com‐
       mand 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.  See the manual entry
       for fconfigure for details on the -translation  option.	 The  transla‐
       tions  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
       written	to  outchan  is reported, either as the return value of a syn‐
       chronous fcopy or as the argument to the callback for  an  asynchronous
       fcopy.

       Fcopy obeys the encodings and character translations configured for the
       channels. This means that the incoming characters are converted	inter‐
       nally  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 and -translation options. No conversion is done if both chan‐
       nels are set to encoding “binary” and have  matching  translations.  If
       only  the  output  channel  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 system will
       assume that the incoming bytes are valid UTF-8 characters  and  convert
       them  according to the output encoding. The behaviour of the system for
       bytes which are not valid UTF-8 characters is undefined in this case.

EXAMPLES
       The first example transfers the contents	 of  one  channel  exactly  to
       another.	 Note  that  when copying one file to another, it is better to
       use file copy which also copies file metadata  (e.g.  the  file	access
       permissions) where possible.

	      fconfigure $in -translation binary
	      fconfigure $out -translation binary
	      fcopy $in $out

       This  second  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 third 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 -size $chunk \
			      -command [list CopyMore $in $out $chunk]
		  }
	      }
	      set in [open $file1]
	      set out [socket $server $port]
	      set chunk 1024
	      set total 0
	      fcopy $in $out -size $chunk \
		      -command [list CopyMore $in $out $chunk]
	      vwait done

SEE ALSO
       eof(n), fblocked(n), fconfigure(n), file(n)

KEYWORDS
       blocking,  channel, end of line, end of file, nonblocking, read, trans‐
       lation

Tcl				      8.0			      fcopy(n)
[top]

List of man pages available for Darwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net