## Tcl8.6.17/Tk8.6.17 Documentation > Tcl Commands > fcopy

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

### NAME

fcopy — データをどこかの通信路からどこかへ複写する Copy data from one channel to another

### 構文 SYNOPSIS

fcopy inchan outchan ?-size size? ?-command callback?

### 説明 DESCRIPTION

この fcopy 命令はデータを一つの入出力通信路 inchan から､他の入出力通信路 outchan に複写する｡この fcopy 命令は余分な複写を避ける為､及び､電網入出力装置の様な遅い仕向け先に大きなファイルを複写する時の主記憶装置への過剰なデータの緩衝貯蔵を避ける為､Tcl 入出力系中の緩衝作用を適正化する｡ 　　　 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.

この fcopy 命令は､ inchan から､ファイルの末尾迄､又は size のバイトか文字が移送されてしまう迄､データを移送する; もし二つの通信路が同じ符号系を使用している場合は size はバイト単位､そうでない場合は文字単位である｡もし､ -size 引数が与えられないと､ファイル末尾迄複写を行う｡ inchan から読んだ全てのデータが outchan に複写される｡ -command 指定なしの場合､ fcopy は複写が完了するまで制御を抑制し､ outchan に書込まれたバイトまたは文字の個数を返す( -size 指定と同じ規則を使う)｡ 　　　 The fcopy command transfers data from inchan until end of file or size bytes or characters have been transferred; size is in bytes if the two channels are using the same encoding, and is in characters otherwise. 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 or characters (using the same rules as for the -size option) written to outchan.

この -command 引数は fcopy に処理を背景で行わせる｡この場合､制御はすぐさま戻って来て､後に､複写が完了した時に､ callback が起動される｡その callback は､一つか二つの追加的な引数を伴って呼出され､その引数は outchan にどれだけのバイト数書かれたかを指し示す｡もし､背景処理の複写中に不都合が生じると､第二引数が不都合に関連する不都合文字列である｡背景処理の複写では､ inchan 又は outchan を 非同期 にする必要はない; この fcopy 命令は､注意深くその様に自動で処理する｡しかしながら､行事待機へは vwait 命令かTk を使って入る必要がある｡ 　　 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.

背景処理の fcopy の間､inchan での他の入力操作や outchan での他の出力操作は許容されない｡下の双方向ファイル複写実施例に例示する様に､その逆は完全に合法である｡ 　 You are not allowed to do other input operations with inchan, or output operations with outchan, during a background fcopy. The converse is entirely legitimate, as exhibited by the bidirectional fcopy example below.

もし､複写が進行している間に inchan か outchan が閉じられると､進行中の複写は停止し､命令の回収は生じない｡もしinchan が閉じると既に outchan 用に出力待ちになったデータは全て書き出される｡ 　　 If either inchan or outchan get closed while the copy is in progress, the current copy is stopped and the command callback is not made. If inchan is closed, then all data already queued for outchan is written out.

註意すべきは､ inchan は背景処理の複写の間に読込み可になり得る事である｡背景処理の間は､どの fileevent 処理機能も切断して､その処理機能が複写に干渉しないようにするのが好ましい｡(fileevent 処理機能やその他による)どの様な､誤った側への入出力の試みも､ “channel busy (通信路は使用中)” の不都合が返って来る｡ 　　　　 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 wrong-sided I/O attempted (by a fileevent handler or otherwise) will get a “channel busy” error.

fcopy は inchan と outchan の中の行末の記号を -translation 指示項目に従って変換する｡ 詳細は取り扱い説明書の fconfigure の項の -translation 指示項目を参照されたい｡この変換の意味は､ inchan から読んだバイトの個数は outchan に書いたバイトの個数と違うかもしれないことである｡同期している fcopy の返り値でも､非同期の fcopy の呼戻しの引数としての返り値でも､ outchan に書いたバイトの個数のみが報告される｡ 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 translations 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 synchronous fcopy or as the argument to the callback for an asynchronous fcopy.

fcopy では 符号系と文字の変換は通信路の構成設定に従う｡これは､入力文字が内部的に最初に UTF-8に変換され次に､ fcopy が書込む通信路の符号系に変換されることを意味する｡詳細は取扱い説明書の fconfigure の項の -encoding と -translation 指示項目を参照されたい｡もし両方の通信路が “binary(２進数)” に設定され､変換が適合していると変換は行われない｡もし､出力のみが “２進数” に設定されていると､システムは､入力した文字は内部のUTF-8 表現で書く｡もし､入力のみが “２進数” に設定されていると､システムは､入力した文字は内部のUTF-8 文字に適合していると仮定し､それを出力符号化に従って変換する｡この場合､UTF-8 文字に適合しないバイトに関するシステムの振舞いは､定義されていない｡ Fcopy obeys the encodings and character translations configured for the channels. This means that the incoming characters are converted internally 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 channels 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

第１の例では､一つの通信路からもう一つへ内容を正確に転送する｡注意すべきは､一つのファイルから他のファイルへ複写するときに､file copy を使う方が好ましい､そちらは､可能であれば､ファイルの汎データ(譬えば､ファイル使用の許可権限)も複写する｡

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

第２の例は､如何にして､手渡した転送したバイトの個数を､回収が受取るかを示す｡応用譜を行事待ち巡回に入れるために vwait を使っている｡勿論､この簡略化した例は回収命令なしでも動く｡ 　　　 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

第４の例では､二つの通信受け口の間で双方向の fcopy を非同期に開始する｡これ等は二つのパイプ [open "|hal 9000" r+] でも可能である(但し､四つのファイル行事接続点は全て塞がっているので､通話は記述譜には秘密のまま残る)｡ 　　　 The fourth example starts an asynchronous, bidirectional fcopy between two sockets. Those could also be pipes from two [open "|hal 9000" r+] (though their conversation would remain secret to the script, since all four fileevent slots are busy).

    set flows 2
    proc Done {dir args} {
         global flows done
         puts "$dir is over."
         incr flows -1
         if {$flows<=0} {set done 1}
    }
    fcopy $sok1 $sok2 -command [list Done UP]
    fcopy $sok2 $sok1 -command [list Done DOWN]
    vwait done

### SEE ALSO

eof, fblocked, fconfigure, file

### KEYWORDS

blocking, channel, end of line, end of file, nonblocking, read, translation
Copyright © 1993 The Regents of the University of California.
Copyright © 1994-1997 Sun Microsystems, Inc.