'\"
'\" 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.2 2003/11/24 05:09:59 bbbush Exp $
'\" 
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: fcopy.n,v 1.2 2003/11/24 05:09:59 bbbush Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH fcopy 3tcl 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
fcopy \- 從一個通道向另一個複製資料
.SH "總覽 SYNOPSIS"
\fBfcopy \fIinchan\fR \fIoutchan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR?
.BE

.SH "描述 DESCRIPTION"
.PP
\fBfcopy\fR  命令從一個 I/O 通道 \fIinchan\fR  向另一個 I/O 通道 \fIoutchan\fR  
複製資料。\fBfcopy\fR  命令在 Tcl I/O 系統中起到緩衝的槓桿作用(leverage)，它避免額外的複製，並且在向慢速目標如網路套介面複製大檔案的時候避免在主存中緩衝過多的資料。
.PP
 \fBfcopy\fR 命令從 \fIinchan\fR  傳輸資料直到檔案結束或傳輸完 \fIsize\fR位元組。如果沒有給出 \fB-size\fR 引數，則複製持續到檔案結束。從 \fIinchan\fR讀的所有資料都複製到 \fIoutchan\fR。如果沒有 \fB-command\fR選項，在複製完成並返回寫到 \fIoutchan \fR的位元組數之前 \fBfcopy\fR  將阻塞。
.PP
\fB-command\fR 引數使 \fBfcopy\fR在後臺工作。在這種情況下它立即返回，並在複製完成時呼叫  \fIcallback\fR。呼叫 \fIcallback\fR 加上一個或兩個額外的引數來指示有多少位元組被寫到了 \fIoutchan\fR。在後臺複製期間如果發生了一個錯誤，第二個引數是與錯誤相關聯的錯誤字串。使用後臺複製不需要把 \fIinchan\fR 或 \fIoutchan\fR 轉換成非阻塞模式；\fBfcopy\fR 命令將自動關照這些。但是，需要使用 \fBvwait\fR 命令或使用 Tk 進入事件迴圈。
.PP
在後臺複製期間不允許對 \fIinchan\fR 或 \fIoutchan \fR做其他 I/O 操作。如果在複製進行期間 \fIinchan\fR 或 \fIoutchan\fR  中被關閉，停止當前的複製並且不做命令回撥。如果 \fIinchan\fR被關閉，則寫出為 \fIoutchan\fR  而排隊(queue)的所有資料。
.PP
注意在一個命令複製期間 \fIinchan\fR 可以變成可讀的。在一個後臺複製期間你應該關閉任何 \fBfileevent\fR控制代碼，這樣這些控制代碼不與複製相觸及(interfere)。透過一個 \fBfileevent\fR控制代碼的任何 I/O 嘗試將得到一個 "channel busy"  錯誤。
.PP
.PP
\fBFcopy\fR  依據 \fIinchan\fR 和 \fIoutchan \fR的 \fB-translation\fR選項來轉換它們中的檔案行結束序列。參見\fBfconfigure\fR的手冊條目來得到 \fB-translation\fR  選項的詳情。轉換意味著從 \fIinchan\fR 讀到的位元組數與寫到 \fIoutchan\fR.的位元組數可能不同。只報告寫到 \fIoutchan\fR中的位元組數。要麼作為同步的 \fBfcopy\fR 的返回值，要麼作為給非同步的 \fBfcopy \fR的回撥的引數。  

.SH "範例 EXAMPLE"
.PP
第一個例子展示了回撥如何得到傳遞給它的傳輸了的位元組數。它還使用 vwait  來使應用進入事件迴圈。當然，不使用回撥也能做出這個簡化了的例子。
.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
第二個例子按塊(chunk)複製並在命令回撥中測試檔案結束。  
.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

.SH "[中文版維護人]"
.B 寒蟬退士
.SH "[中文版最新更新]"
.B 2001/08/02
.SH "《中國 Linux 論壇 man 手冊頁翻譯計劃》:"
.BI http://cmpp.linuxforum.net
.SH "跋"
.br
本頁面中文版由中文 man 手冊頁計劃提供。
.br
中文 man 手冊頁計劃：\fBhttps://github.com/man-pages-zh/manpages-zh\fR