1fcopy(n)                     Tcl Built-In Commands                    fcopy(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       fcopy - Copy data from one channel to another
9

SYNOPSIS

11       fcopy inchan outchan ?-size size? ?-command callback?
12_________________________________________________________________
13
14

DESCRIPTION

16       The  fcopy  command copies data from one I/O channel, inchan to another
17       I/O channel, outchan.  The fcopy command leverages the buffering in the
18       Tcl  I/O  system  to avoid extra copies and to avoid buffering too much
19       data in main memory when copying large files to slow destinations  like
20       network sockets.
21
22       The  fcopy command transfers data from inchan until end of file or size
23       bytes have been transferred. If no -size argument is  given,  then  the
24       copy  goes  until end of file.  All the data read from inchan is copied
25       to outchan.  Without the -command option, fcopy blocks until  the  copy
26       is complete and returns the number of bytes written to outchan.
27
28       The -command argument makes fcopy work in the background.  In this case
29       it returns immediately and the callback is invoked later when the  copy
30       completes.  The callback is called with one or two additional arguments
31       that indicates how many bytes were written to  outchan.   If  an  error
32       occurred  during  the background copy, the second argument is the error
33       string associated with the error.  With a background copy,  it  is  not
34       necessary  to  put  inchan or outchan into non-blocking mode; the fcopy
35       command takes care of that automatically.  However, it is necessary  to
36       enter the event loop by using the vwait command or by using Tk.
37
38       You  are  not allowed to do other I/O operations with inchan or outchan
39       during a background fcopy.  If either  inchan  or  outchan  get  closed
40       while the copy is in progress, the current copy is stopped and the com‐
41       mand callback is not made.  If inchan is closed, then all data  already
42       queued for outchan is written out.
43
44       Note  that  inchan  can  become readable during a background copy.  You
45       should turn off any fileevent handlers  during  a  background  copy  so
46       those  handlers do not interfere with the copy.  Any I/O attempted by a
47       fileevent handler will get a “channel busy” error.
48
49       Fcopy translates end-of-line sequences in inchan and outchan  according
50       to  the  -translation  option for these channels.  See the manual entry
51       for fconfigure for details on the -translation  option.   The  transla‐
52       tions  mean  that the number of bytes read from inchan can be different
53       than the number of bytes written to outchan.  Only the number of  bytes
54       written  to  outchan  is reported, either as the return value of a syn‐
55       chronous fcopy or as the argument to the callback for  an  asynchronous
56       fcopy.
57
58       Fcopy obeys the encodings and character translations configured for the
59       channels. This means that the incoming characters are converted  inter‐
60       nally  first  UTF-8  and  then  into  the encoding of the channel fcopy
61       writes to. See the manual entry  for  fconfigure  for  details  on  the
62       -encoding and -translation options. No conversion is done if both chan‐
63       nels are set to encoding “binary” and have  matching  translations.  If
64       only  the  output  channel  is set to encoding “binary” the system will
65       write the internal UTF-8 representation of the incoming characters.  If
66       only  the  input  channel  is  set to encoding “binary” the system will
67       assume that the incoming bytes are valid UTF-8 characters  and  convert
68       them  according to the output encoding. The behaviour of the system for
69       bytes which are not valid UTF-8 characters is undefined in this case.
70
71

EXAMPLES

73       The first example transfers the contents  of  one  channel  exactly  to
74       another.  Note  that  when copying one file to another, it is better to
75       use file copy which also copies file metadata  (e.g.  the  file  access
76       permissions) where possible.
77              fconfigure $in -translation binary
78              fconfigure $out -translation binary
79              fcopy $in $out
80
81       This  second  example  shows how the callback gets passed the number of
82       bytes transferred.  It also uses vwait to put the application into  the
83       event  loop.   Of course, this simplified example could be done without
84       the command callback.
85              proc Cleanup {in out bytes {error {}}} {
86                  global total
87                  set total $bytes
88                  close $in
89                  close $out
90                  if {[string length $error] != 0} {
91                # error occurred during the copy
92                  }
93              }
94              set in [open $file1]
95              set out [socket $server $port]
96              fcopy $in $out -command [list Cleanup $in $out]
97              vwait total
98
99       The third example copies in chunks and tests for end  of  file  in  the
100       command callback
101              proc CopyMore {in out chunk bytes {error {}}} {
102                  global total done
103                  incr total $bytes
104                  if {([string length $error] != 0) || [eof $in]} {
105                set done $total
106                close $in
107                close $out
108                  } else {
109                fcopy $in $out -size $chunk \
110                              -command [list CopyMore $in $out $chunk]
111                  }
112              }
113              set in [open $file1]
114              set out [socket $server $port]
115              set chunk 1024
116              set total 0
117              fcopy $in $out -size $chunk \
118                      -command [list CopyMore $in $out $chunk]
119              vwait done
120
121

SEE ALSO

123       eof(n), fblocked(n), fconfigure(n), file(n)
124
125

KEYWORDS

127       blocking,  channel, end of line, end of file, nonblocking, read, trans‐
128       lation
129
130
131
132Tcl                                   8.0                             fcopy(n)
Impressum