OpenCores
URL https://opencores.org/ocsvn/or1k_old/or1k_old/trunk

Subversion Repositories or1k_old

[/] [or1k_old/] [trunk/] [insight/] [tcl/] [doc/] [fcopy.n] - Blame information for rev 1782

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
'\"
2
'\" Copyright (c) 1993 The Regents of the University of California.
3
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
4
'\"
5
'\" See the file "license.terms" for information on usage and redistribution
6
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7
'\"
8
'\" RCS: @(#) $Id: fcopy.n,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $
9
'\"
10
.so man.macros
11
.TH fcopy n 8.0 Tcl "Tcl Built-In Commands"
12
.BS
13
'\" Note:  do not modify the .SH NAME line immediately below!
14
.SH NAME
15
fcopy \- Copy data from one channel to another.
16
.SH SYNOPSIS
17
\fBfcopy \fIinchan\fR \fIoutchan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR?
18
.BE
19
 
20
.SH DESCRIPTION
21
.PP
22
The \fBfcopy\fP command copies data from one I/O channel, \fIinchan\fR to another I/O channel, \fIoutchan\fR.
23
The \fBfcopy\fP command leverages the buffering in the Tcl I/O system to
24
avoid extra copies and to avoid buffering too much data in
25
main memory when copying large files to slow destinations like
26
network sockets.
27
.PP
28
The \fBfcopy\fP
29
command transfers data from \fIinchan\fR until end of file
30
or \fIsize\fP bytes have been
31
transferred. If no \fB\-size\fP argument is given,
32
then the copy goes until end of file.
33
All the data read from \fIinchan\fR is copied to \fIoutchan\fR.
34
Without the \fB\-command\fP option, \fBfcopy\fP blocks until the copy is complete
35
and returns the number of bytes written to \fIoutchan\fR.
36
.PP
37
The \fB\-command\fP argument makes \fBfcopy\fP work in the background.
38
In this case it returns immediately and the \fIcallback\fP is invoked
39
later when the copy completes.
40
The \fIcallback\fP is called with
41
one or two additional
42
arguments that indicates how many bytes were written to \fIoutchan\fR.
43
If an error occurred during the background copy, the second argument is the
44
error string associated with the error.
45
With a background copy,
46
it is not necessary to put \fIinchan\fR or \fIoutchan\fR into
47
non-blocking mode; the \fBfcopy\fP command takes care of that automatically.
48
However, it is necessary to enter the event loop by using
49
the \fBvwait\fP command or by using Tk.
50
.PP
51
You are not allowed to do other I/O operations with
52
\fIinchan\fR or \fIoutchan\fR during a background fcopy.
53
If either \fIinchan\fR or \fIoutchan\fR get closed
54
while the copy is in progress, the current copy is stopped
55
and the command callback is \fInot\fP made.
56
If \fIinchan\fR is closed,
57
then all data already queued for \fIoutchan\fR is written out.
58
.PP
59
Note that \fIinchan\fR can become readable during a background copy.
60
You should turn off any \fBfileevent\fP handlers during a background
61
copy so those handlers do not interfere with the copy.
62
Any I/O attempted by a \fBfileevent\fP handler will get a "channel busy" error.
63
.PP
64
\fBFcopy\fR translates end-of-line sequences in \fIinchan\fR and \fIoutchan\fR
65
according to the \fB\-translation\fR option
66
for these channels.
67
See the manual entry for \fBfconfigure\fR for details on the
68
\fB\-translation\fR option.
69
The translations mean that the number of bytes read from \fIinchan\fR
70
can be different than the number of bytes written to \fIoutchan\fR.
71
Only the number of bytes written to \fIoutchan\fR is reported,
72
either as the return value of a synchronous \fBfcopy\fP or
73
as the argument to the callback for an asynchronous \fBfcopy\fP.
74
 
75
.SH EXAMPLE
76
.PP
77
This first example shows how the callback gets
78
passed the number of bytes transferred.
79
It also uses vwait to put the application into the event loop.
80
Of course, this simplified example could be done without the command
81
callback.
82
.DS
83
proc Cleanup {in out bytes {error {}}} {
84
    global total
85
    set total $bytes
86
    close $in
87
    close $out
88
    if {[string length $error] != 0} {
89
        # error occurred during the copy
90
    }
91
}
92
set in [open $file1]
93
set out [socket $server $port]
94
fcopy $in $out -command [list Cleanup $in $out]
95
vwait total
96
 
97
.DE
98
.PP
99
The second example copies in chunks and tests for end of file
100
in the command callback
101
.DS
102
proc CopyMore {in out chunk bytes {error {}}} {
103
    global total done
104
    incr total $bytes
105
    if {([string length $error] != 0) || [eof $in] {
106
        set done $total
107
        close $in
108
        close $out
109
    } else {
110
        fcopy $in $out -command [list CopyMore $in $out $chunk] \\
111
            -size $chunk
112
    }
113
}
114
set in [open $file1]
115
set out [socket $server $port]
116
set chunk 1024
117
set total 0
118
fcopy $in $out -command [list CopyMore $in $out $chunk] -size $chunk
119
vwait done
120
 
121
.DE
122
 
123
.SH "SEE ALSO"
124
eof(n), fblocked(n), fconfigure(n)
125
 
126
.SH KEYWORDS
127
blocking, channel, end of line, end of file, nonblocking, read, translation

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.