通讯编程

开发平台：
Visual C++

fcopy.n：源码内容
							'"
'" Copyright (c) 1993 The Regents of the University of California.
'" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'"
'" See the file "license.terms" for information on usage and redistribution
'" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'" 
'" RCS: @(#) $Id: fcopy.n,v 1.3.14.1 2007/01/29 16:50:35 dgp Exp $
'" 
.so man.macros
.TH fcopy n 8.0 Tcl "Tcl Built-In Commands"
.BS
'" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
fcopy - Copy data from one channel to another.
.SH SYNOPSIS
fBfcopy fIinchanfR fIoutchanfR ?fB-size fIsizefR? ?fB-command fIcallbackfR?
.BE
.SH DESCRIPTION
.PP
The fBfcopyfP command copies data from one I/O channel, fIinchanfR to another I/O channel, fIoutchanfR.
The fBfcopyfP 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.
.PP
The fBfcopyfP 
command transfers data from fIinchanfR until end of file
or fIsizefP bytes have been 
transferred. If no fB-sizefP argument is given,
then the copy goes until end of file.
All the data read from fIinchanfR is copied to fIoutchanfR.
Without the fB-commandfP option, fBfcopyfP blocks until the copy is complete
and returns the number of bytes written to fIoutchanfR.
.PP
The fB-commandfP argument makes fBfcopyfP work in the background.
In this case it returns immediately and the fIcallbackfP is invoked
later when the copy completes.
The fIcallbackfP is called with
one or two additional 
arguments that indicates how many bytes were written to fIoutchanfR.
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 fIinchanfR or fIoutchanfR into
non-blocking mode; the fBfcopyfP command takes care of that automatically.
However, it is necessary to enter the event loop by using
the fBvwaitfP command or by using Tk.
.PP
You are not allowed to do other I/O operations with
fIinchanfR or fIoutchanfR during a background fcopy.
If either fIinchanfR or fIoutchanfR get closed
while the copy is in progress, the current copy is stopped
and the command callback is fInotfP made.
If fIinchanfR is closed,
then all data already queued for fIoutchanfR is written out.
.PP
Note that fIinchanfR can become readable during a background copy.
You should turn off any fBfileeventfP handlers during a background
copy so those handlers do not interfere with the copy.
Any I/O attempted by a fBfileeventfP handler will get a "channel busy" error.
.PP
fBFcopyfR translates end-of-line sequences in fIinchanfR and fIoutchanfR
according to the fB-translationfR option
for these channels.
See the manual entry for fBfconfigurefR for details on the
fB-translationfR option.
The translations mean that the number of bytes read from fIinchanfR
can be different than the number of bytes written to fIoutchanfR.
Only the number of bytes written to fIoutchanfR is reported,
either as the return value of a synchronous fBfcopyfP or
as the argument to the callback for an asynchronous fBfcopyfP.
.PP
fBFcopyfR 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 fBfcopyfR writes
to. See the manual entry for fBfconfigurefR for details on the
fB-encodingfR option. No conversion is done if both channels are
set to encoding "binary". 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.
.SH EXAMPLE
.PP
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.
.DS
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
.DE
.PP
The second example copies in chunks and tests for end of file
in the command callback
.DS
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 -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
.DE
.SH "SEE ALSO"
eof(n), fblocked(n), fconfigure(n)
.SH KEYWORDS
blocking, channel, end of line, end of file, nonblocking, read, translation

						