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

### 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
    chan — 通信路の読み､書き､取扱操作 Read, write and manipulate channels
  SYNOPSIS
  説明 DESCRIPTION
    chan blocked channelId
    chan close channelId ?direction?
    chan configure channelId ?optionName? ?value? ?optionName value?...
    -blocking boolean
    -buffering newValue
    -buffersize newSize
    -encoding name
    -eofchar char
    -eofchar {inChar outChar}
    -translation translation
    -translation {inTranslation outTranslation}
      auto
      binary
      cr
      crlf
      lf
    chan copy inputChan outputChan ?-size size? ?-command callback?
    chan create mode cmdPrefix
    chan eof channelId
    chan event channelId event ?script?
    chan flush channelId
    chan gets channelId ?varName?
    chan names ?pattern?
    chan pending mode channelId
    chan pipe
    chan pop channelId
    chan postevent channelId eventSpec
    chan push channelId cmdPrefix
    chan puts ?-nonewline? ?channelId? string
    chan read channelId ?numChars?
    chan read ?-nonewline? channelId
      chan read channelId numChars
      chan read channelId
    chan seek channelId offset ?origin?
      start
      current
      end
    chan tell channelId
    chan truncate channelId ?length?
  EXAMPLES
  単純な開伝達経路例 SIMPLE CHANNEL OPERATION EXAMPLES
  SEE ALSO
  KEYWORDS

### NAME

chan — 通信路の読み､書き､取扱操作 Read, write and manipulate channels

### SYNOPSIS

chan option ?arg arg ...?

### 説明 DESCRIPTION

この命令は､開いている( open や socket 命令によって､既に作成された､或いは､処理手順中の標準入力､標準出力､不具合出力に相当する省略時設定の名前 stdin か stdout か stderr を付けられた)通信路に､其処から読出し､書き込み､他の取扱操作の､幾つかの操作を提供する｡option はこの通信路で何を行うかを指し示す; option については混同の恐れのないどの様な短縮形も可能でである｡有効なものは以下の通り: 　　　 This command provides several operations for reading from, writing to and otherwise manipulating open channels (such as have been created with the open and socket commands, or the default named channels stdin, stdout or stderr which correspond to the process's standard input, output and error streams respectively). Option indicates what to do with the channel; any unique abbreviation for option is acceptable. Valid options are:

chan blocked channelId
  これは､ channelId として呼ばれた通信路上の最後の入力操作の失敗が､抑制の手順以外によるものか否かを試験し､その理由であれば､1 を返す｡それ以外では 0 を返す｡註意すべきは､この命令は凡そ通信路が非同期 に構成設定されいてるときのみ1を返す; 全ての Tcl 通信路は初期設定では 同期は是になっている｡ 　 This tests whether the last input operation on the channel called channelId failed because it would have otherwise caused the process to block, and returns 1 if that was the case. It returns 0 otherwise. Note that this only ever returns 1 when the channel has been configured to be non-blocking; all Tcl channels have blocking turned on by default.

chan close channelId ?direction?
  channelId と呼ばれる通信路を閉じて壊す｡註意すべきは､その通信路に登録されている全ての実在するファイル行事は削除されることである｡もし direction 引数(それは read か write 又はそれらの混同の恐れのない短縮形でなければならない)が存在する時､その通信路は半閉じになるだけなので､読み書きからそれぞれ書込み専用か読出し専用になるだけかもしれない｡もし読出し専用通信路が読みを閉じると恰も通信路の全閉鎖と同じになる､そのことは書込み専用通信路についても同様である｡ direction 引数なしではその通信路は読書き両方を閉じる(このような方向が現在開いている場合のみ)｡読出し専用通信路を書込み閉鎖するか､または書込み専用通信路を読出し閉鎖すると不都合が生じる｡ 　　　 Close and destroy the channel called channelId. Note that this deletes all existing file-events registered on the channel. If the direction argument (which must be read or write or any unique abbreviation of them) is present, the channel will only be half-closed, so that it can go from being read-write to write-only or read-only respectively. If a read-only channel is closed for reading, it is the same as if the channel is fully closed, and respectively similar for write-only channels. Without the direction argument, the channel is closed for both reading and writing (but only if those directions are currently open). It is an error to close a read-only channel for writing, or a write-only channel for reading.

  通信路の閉鎖の動作の一部として､全ての緩衝域の出力は通信路の出力装置に追出される(通信路が書込み可能を止めようとしている場合のみ)､どのような入力緩衝域も遺棄される(読出し可能を止めようとしている場合のみ)､基礎になっているOSの原資が閉じられ､その後の channelId の使用は不能になる(通信路が完全に閉じられた場合のみ双方が)｡ 　　　 As part of closing the channel, all buffered output is flushed to the channel's output device (only if the channel is ceasing to be writable), any buffered input is discarded (only if the channel is ceasing to be readable), the underlying operating system resource is closed and channelId becomes unavailable for future use (both only if the channel is being completely closed).

  もし通信路が同期で通信路が書込み可能を中止しようとしている場合､命令は全ての出力が追出される迄返らない｡もし通信路が非同期で追出されてない出力があると､通信路は開いた状態で残され､命令は直ぐに制御を帰す; 出力は背景処理で追出され､通信路は追出しが完了した時に閉じられる｡ 　　 If the channel is blocking and the channel is ceasing to be writable, the command does not return until all output is flushed. If the channel is non-blocking and there is unflushed output, the channel remains open and the command returns immediately; output will be flushed in the background and the channel will be closed when all the flushing is complete.

  もし channelId が命令パイプラインについて同期通信路である場合､ chan close は子供の処理課程が完了するのを待つ｡ 　　　 If channelId is a blocking channel for a command pipeline then chan close waits for the child processes to complete.

  もし通信路が解釈実行機能の間で共有されていると､ chan close は channelId を起動している解釈実行機能で使えなくするが､全ての共有している解釈実行機能で閉じられる迄は､それ以上の影響はない｡その通信路を登録している最後の解釈実行機能がchan close (又は close)を起動すると､上述の消去動作が始まる｡半閉じについては､通信路の半閉じは現在の解釈実行機能の通信路の視野に､全ての通信路がその方向(又は両方向)を閉じられる迄にのみ適用する｡通信路の共有についての記述は interp 命令を参照されたい｡ 　　　 If the channel is shared between interpreters, then chan close makes channelId unavailable in the invoking interpreter but has no other effect until all of the sharing interpreters have closed the channel. When the last interpreter in which the channel is registered invokes chan close (or close), the cleanup actions described above occur. With half-closing, the half-close of the channel only applies to the current interpreter's view of the channel until all channels have closed it in that direction (or completely). See the interp command for a description of channel sharing.

  解釈実行機能が壊される時と､処理手順が終了する時は通信路は自動的に完全に閉じられる｡処理手順が終了する前に､全ての出力が正しく追出されることが確実に行われる様に､通信路は 同期の方法に切換る｡ 　　　 Channels are automatically fully closed when an interpreter is destroyed and when the process exits. Channels are switched to blocking mode, to ensure that all output is correctly flushed before the process exits.

  この命令は空文字列を戻す､又､出力を追出している間に不都合が生じると不都合状態を発生させる｡もし､命令パイプ中の命令が open を発生して不都合を戻すと､chan close は不都合を発生する( exec 命令に準拠する)｡ The command returns an empty string, and may generate an error if an error occurs while flushing output. If a command in a command pipeline created with open returns an error, chan close generates an error (similar to the exec command.)

  註意すべきは受け口や命令パイプラインの半閉じは深刻な副作用を有することがある､理由はそれらは基礎になっているOSの原資の shutdown() や close() になり得る､それは Tcl 算譜への他の処理課程や系の応答を変更するかも知れない｡ 　　　 Note that half-closes of sockets and command pipelines can have important side effects because they result in a shutdown() or close() of the underlying system resource, which can change how other processes or systems respond to the Tcl program.

chan configure channelId ?optionName? ?value? ?optionName value?...
  channelId の名称の通信路構成設定の選択を問合せる又は設定する｡ Query or set the configuration options of the channel named channelId.

  optionName 又は value 引数が一つも与えられない場合､この命令は通信路について､選択できる追加指定の名前と値のリストを返す｡ optionName が与えられ､ value が与えられない場合､この命令は与えられた追加指定の現在の値を返す｡ optionName と value の対が１つ或いはそれ以上与えられた場合､この命令は､それぞれの名前の指定項目に､対応する値を設定する; この場合戻る値は空文字列である｡ 　　　 If no optionName or value arguments are supplied, the command returns a list containing alternating option names and values for the channel. If optionName is supplied but no value then the command returns the current value of the given option. If one or more pairs of optionName and value are supplied, the command sets each of the named options to the corresponding value; in this case the return value is an empty string.

  次に述べる追加指定は全ての通信路について適用される｡更に､各通信路の型はそれだけに適用される追加指定を追加しても好い｡特定の型の通信路に適用される追加指定については､それぞれの型の通信路を生成する命令に関する取扱い説明書の項目を参照されたい｡譬えば､socket についての追加指定については socket 命令に関する取扱説明書の項目を､直列装置に関する追加指定については open 命令を参照されたい｡ 　 The options described below are supported for all channels. In addition, each channel type may add options that only it supports. See the manual entry for the command that creates each type of channel for the options supported by that specific type of channel. For example, see the manual entry for the socket command for additional options for sockets, and the open command for additional options for serial devices.

-blocking boolean
  この -blocking 追加指定は通信路上の入出力操作が､無期限に遮断する手順を惹き起しえるかを定める｡追加指定の値は適切な論理値であるこを要す｡通信路は通常は同期様式である; もし通信路が非同期様式に置かれると chan gets, chan read, chan The -blocking option determines whether I/O operations on the channel can cause the process to block indefinitely. The value of the option must be a proper boolean value. Channels are normally in blocking mode; if a channel is placed into non-blocking mode it will affect the operation of the chan gets, chan read, chan puts, chan flush, and chan close commands; see the documentation for those commands for details. For non-blocking mode to work correctly, the application must be using the Tcl event loop (e.g. by calling Tcl_DoOneEvent or invoking the vwait command).

-buffering newValue
  もし newValue が full であると､入出力システムは､内部緩衝域が満杯になる迄､又は､chan flush 命令が起動する迄､出力を緩衝域に貯める｡newValue が line であると､入出力システムは､改行文字が出力される時に何時も､自動的に通信路に出力を吐出す｡ newValue が none であると､入出力システムは､出力操作の後､そのつど､自動的に出力を吐出す｡ -buffering の省略時設定は､通信路が端末装置に接続されてない限り full に設定される; その様な通信路については初期設定は line である｡更に､stdin と stdout は初期には line に設定され､stderr は none に設定される｡ 　　　 If newValue is full then the I/O system will buffer output until its internal buffer is full or until the chan flush command is invoked. If newValue is line, then the I/O system will automatically flush output for the channel whenever a newline character is output. If newValue is none, the I/O system will flush automatically after every output operation. The default is for -buffering to be set to full except for channels that connect to terminal-like devices; for these channels the initial setting is line. Additionally, stdin and stdout are initially set to line, and stderr is set to none.

-buffersize newSize
  newSize は整数であることを要す; その値は､バイト数として､緩衝域の大きさの設定に使われ､その後に､通信路への､入力､又は出力を保存する為に､(記憶域が)再配列される｡ newSize は百万を越えない数であることを要し､バイト単位の寸法として百万迄の緩衝域を許容する｡ newSize must be an integer; its value is used to set the size of buffers, in bytes, subsequently allocated for this channel to store input or output. newSize must be a number of no more than one million, allowing buffers of up to one million bytes in size.

-encoding name
  この追加指定は通信路の文字符号系を encoding names に返され名前付けされた文字符号系のうちの一つ､又は特別の値 binary として指定し､それにより､データがTclの中で使われているユニコードから､或いは逆方向に変換できる様にする為に使われる｡譬えば､Tcl用に シフトJIS の日本語ファイルから文字を読み､適切に処置して内容を表示する為には､変換法が シフトJIS に設定される｡その後で､その通信路から読むときに､日本語ファイルのバイトは､読んだ通りにユニコードに変換される｡書き込みにも対応でき - それで､Tcl文字列が通信路に書込まれ､出力時に自動的に指定された文字符号系に変換される｡ 　 This option is used to specify the encoding of the channel as one of the named encodings returned by encoding names or the special value binary, so that the data can be converted to and from Unicode for use in Tcl. For instance, in order for Tcl to read characters from a Japanese file in shiftjis and properly process and display the contents, the encoding would be set to shiftjis. Thereafter, when reading from the channel, the bytes in the Japanese file would be converted to Unicode as they are read. Writing is also supported - as Tcl strings are written to the channel they will automatically be converted to the specified encoding on output.

  もしファイルが純二進数データを含んでいると(譬えば､JPEG 映像)､通路の為の文字符号は binary に構成設定するのがよい｡そうすると､Tcl はファイル中のデータに解釈実行機能を割当てず､単純に生のバイトを読書きするようになる｡ Tcl binary 命令はこのバイト志向のデータの取扱に使用できる｡二進データを移送したい時には､通常は -translation 追加指定を binary に設定する方法がより優れている､理由はこの方法はデータ流れのバイトの他の自動解釈実行機能も切断するためである｡ 　　　 If a file contains pure binary data (for instance, a JPEG image), the encoding for the channel should be configured to be binary. Tcl will then assign no interpretation to the data in the file and simply read or write raw bytes. The Tcl binary command can be used to manipulate this byte-oriented data. It is usually better to set the -translation option to binary when you want to transfer binary data, as this turns off the other automatic interpretations of the bytes in the stream as well.

  新しく開かれた通信路の省略時設定の符号変換は､ encoding system によって返された OSの為の相互対話に使用されるのと同じOS基盤依存､又､地域固有の系の符号系である｡　　　 The default encoding for newly opened channels is the same platform- and locale-dependent system encoding used for interfacing with the operating system, as returned by encoding system.

-eofchar char

-eofchar {inChar outChar}
  この追加指定は､ファイル終端にCtrl-z (\x1A) を使用する DOS ファイル系に対応する｡ char が空文字列でない場合は､入力中にこの文字に遭遇すると､この文字がファイル終末の合図である｡出力については､通信路が閉じるときに､ファイル終末記号が出力される｡ char が空文字の場合､ファイル終末を意味する特別な記号はない｡読み-書き通信路については､二要素リストがそれぞれ入力用と出力用のファイル末尾標識を指定する｡面倒なら､読み-書き通信路の終端記号の設定に一つだけの値を設定し､読出しと書き出しの両方に適用することも出来る｡読み-書き通信路への終端記号の問合せには､常に二要素のリストが戻って来る｡ -eofchar の省略時設定は Windows の下のファイル以外では､全て空文字列である｡Windows では､ -eofchar は､読出し用には Control-z (\x1A) ､書き込み用には空文字列である｡-eofchar 値として受入れられる範囲は \x01 ～ \x7f である; この範囲外に -eofchar を設定しょうとすると不都合が発生する｡ 　　　 This option supports DOS file systems that use Control-z (\x1A) as an end of file marker. If char is not an empty string, then this character signals end-of-file when it is encountered during input. For output, the end-of-file character is output when the channel is closed. If char is the empty string, then there is no special end of file character marker. For read-write channels, a two-element list specifies the end of file marker for input and output, respectively. As a convenience, when setting the end-of-file character for a read-write channel you can specify a single value that will apply to both reading and writing. When querying the end-of-file character of a read-write channel, a two-element list will always be returned. The default value for -eofchar is the empty string in all cases except for files under Windows. In that case the -eofchar is Control-z (\x1A) for reading and the empty string for writing. The acceptable range for -eofchar values is \x01 - \x7f; attempting to set -eofchar to a value outside of this range will generate an error.

-translation translation

-translation {inTranslation outTranslation}
  Tcl の記述譜では､行末は常に行替記号 (\n) の一文字で表現している｡しかしながら､実際のファイルや装置では行末は､OS毎に､或いは同じOS上でも装置毎に､様々に異なって表現される｡譬えば､Unixでは､ファイルには 行替記号が使われるが､電網接続には普通は 改行-行送 の組が使用される｡入力では(即ち､ chan gets と chan read を使って) Tcl入出力系は自動的に外部での行末表現を行替記号 に翻訳している｡出力では､ (即ち､ chan puts を使って)､入出力系は､行替記号を外部の行末表現に翻訳している｡省略時の翻訳方法は､auto であって､全ての普通の場合を処理しる､しかし､ -translation 指定によって行末翻訳を明示的に制御することができる｡ 　　 In Tcl scripts the end of a line is always represented using a single newline character (\n). However, in actual files and devices the end of a line may be represented differently on different platforms, or even for different devices on the same platform. For example, under UNIX newlines are used in files, whereas carriage-return-linefeed sequences are normally used in network connections. On input (i.e., with chan gets and chan read) the Tcl I/O system automatically translates the external end-of-line representation into newline characters. Upon output (i.e., with chan puts), the I/O system translates newlines to the external end-of-line representation. The default translation mode, auto, handles all the common cases automatically, but the -translation option provides explicit control over the end of line translations.

  -translation に結合された値は読出し専用と書込み専用の通信路のための一個の項目である｡入出力通信路のための､その値は二要素のリストである; 読み込み翻訳様式がリストの第一要素であり､書き込み翻訳様式が第二要素である｡めんどうなら､読み書き通信路の翻訳様式の設定のとき､読み込みと書き込みの両方に適用する単一の値を指定することも可能である｡読み書き通信路の翻訳様式の問合せの時には､常に二つの要素のリストが返ってくる｡現在､次の値が適用できる:　 　　 The value associated with -translation is a single item for read-only and write-only channels. The value is a two-element list for read-write channels; the read translation mode is the first element of the list, and the write translation mode is the second element. As a convenience, when setting the translation mode for a read-write channel you can specify a single value that will apply to both reading and writing. When querying the translation mode of a read-write channel, a two-element list will always be returned. The following values are currently supported:

  auto
    入力の翻訳様式として､auto は､ 行送り (lf), 先頭戻り (cr), 先頭戻りと 行送り (crlf) の何れも､行末の表現として取り扱う｡行-行 さえも､行末の表現として変更でき､これらは全ての場合が改行に翻訳される｡出力の翻訳様式では､ auto は OSに依存した表現を選択する; 接続端末 (socket )用には全てのOSでTclは crlf を選び､全てのUnix 系には､ lf を撰び､多くのWindows 系には､ crlf を撰ぶ｡ -translation の省略時設定は､入力､出力共に auto である｡ As the input translation mode, auto treats any of newline (lf), carriage return (cr), or carriage return followed by a newline (crlf) as the end of line representation. The end of line representation can even change from line-to-line, and all cases are translated to a newline. As the output translation mode, auto chooses a platform specific representation; for sockets on all platforms Tcl chooses crlf, for all Unix flavors, it chooses lf, and for the various flavors of Windows it chooses crlf. The default setting for -translation is auto for both input and output.

  binary
    lf 指定に似て行末の翻訳は実施されないが､但し､追加的に､空文字列には -eofchar を設定して不能にし､且つ､-encoding を iso8859-1 に設定する｡この命令の設定により､通信経路は完全に､二進の入力と出力に構成設定される: その通信経路から読まれるそれぞれのバイトは､バイトとして保持している同じ値を有するユニコード文字になり､その通信路に書込まれるそれぞれの文字は出力内の単一のバイトになる｡これにより､データ内のそれぞれの文字が 0 から 255 の範囲に残っている限り二進符号と継目なく利用する事ができるようになって､二進符号データと文字の間の区別が無くなる｡譬えば､ JPEG 影像はその様な通信路から読み取って､操作して､その通信路へ書き戻すことができる｡ Like lf, no end-of-line translation is performed, but in addition, sets -eofchar to the empty string to disable it, and sets -encoding to iso8859-1. With this one setting, a channel is fully configured for binary input and output: Each byte read from the channel becomes the Unicode character having the same value as that byte, and each character written to the channel becomes a single byte in the output. This makes it possible to work seamlessly with binary data as long as each character in the data remains in the range of 0 to 255 so that there is no distinction between binary data and text. For example, A JPEG image can be read from a such a channel, manipulated, and then written back to such a channel.

  cr
    基礎となるファイルまたは装置の行末は１文字の先頭戻り文字で表現される｡入力翻訳の様式としては､ cr では､先頭戻り を改行に変換する｡出力翻訳としての様式で､cr の様式では､改行を先頭戻り に変換する｡ 　　 The end of a line in the underlying file or device is represented by a single carriage return character. As the input translation mode, cr mode converts carriage returns to newline characters. As the output translation mode, cr mode translates newline characters to carriage returns.

  crlf
    基礎となるファイルまたは装置の行末は先頭戻りに続く行送り記号で表現される｡入力翻訳の様式としては､ crlf 様式では､先頭戻り行送りの組を改行に変換する｡出力翻訳としての様式で､crlf の様式では､改行を先頭戻り行送り に変換する｡この様式は 典型的に Windows と電網接続で使われている｡ 　　 The end of a line in the underlying file or device is represented by a carriage return character followed by a linefeed character. As the input translation mode, crlf mode converts carriage-return-linefeed sequences to newline characters. As the output translation mode, crlf mode translates newline characters to carriage-return-linefeed sequences. This mode is typically used on Windows platforms and for network connections.

  lf
    基礎となるファイルまたは端末装置の行末は一文字の改行(行送)文字で表現される｡この様式では､入力も､出力も翻訳は行われない｡この様式は 典型的に UNIXで使われている｡ 　　 The end of a line in the underlying file or device is represented by a single newline (linefeed) character. In this mode no translations occur during either input or output. This mode is typically used on UNIX platforms.

chan copy inputChan outputChan ?-size size? ?-command callback?
  通信路 inputChan からデータを複写し､通信路 outputChan へ複写する､前者は､入力用に開けておかねばならなず､後者は書き出し用に開けておかねばならない｡この chan copy 命令は､Tcl入出力系の緩衝に影響を及ぼし､電網受け口(sockets)の様な遅い出力先に大きなファイルを複写する時に主記憶装置に過度の複写や､緩衝が起ることを避けている｡ Copy data from the channel inputChan, which must have been opened for reading, to the channel outputChan, which must have been opened for writing. The chan copy 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.

  この chan copy 命令は､ inputChan から､ファイルの末尾迄､又は size のバイトか文字が移送されてしまう迄､データを移送する; もし二つの通信路が同じ符号系を使用している場合は size はバイト単位､そうでない場合は文字単位である｡もし､ -size 引数が与えられないと､ファイル末尾迄複写を行う｡ inputChan から読んだ全てのデータが outputChan に複写される｡ -command 指定なしの場合､ chan copy は複写が完了するまで制御を抑制し､ outputChan に書込まれたバイトまたは文字の個数を返す(-size 指定と同じ規則を使う)｡ 　　 The chan copy command transfers data from inputChan 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 inputChan is copied to outputChan. Without the -command option, chan copy 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 outputChan.

  この -command 引数は chan copy に処理を背景で行わせる｡この場合､制御はすぐさま戻って来て､後に､複写が完了した時に､ callback が起動される｡その callback は､一つか二つの追加的な引数を伴って呼出され､その引数は outputChan にどれだけのバイト数書くかを指し示す｡もし､背景処理の複写中に不都合が生じると､第二引数が不都合に関連する不都合文字列である｡背景処理の複写では､ inputChan や outputChan を非同期 で処理する必要はない; この chan copy 命令は､自動で処理してくれる｡しかしながら､行事待機へは vwait 命令かTk を使って入る必要がある｡ 　　　 The -command argument makes chan copy 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 outputChan. 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 inputChan or outputChan into non-blocking mode; the chan copy command takes care of that automatically. However, it is necessary to enter the event loop by using the vwait command or by using Tk.

  背景処理で chan copy を行っている間は､ inputChan と outputChan には他の入出力操作を行うことは許容されていない｡もし inputChan か outputChan の何れかが複写処理中に､閉じられると､実行中の複写は停止し命令の callback は行われない｡もし､ inputChan が閉じられると､既に outputChan 用に待ち行列をなしていた全データは書き出される｡ 　　　 You are not allowed to do other I/O operations with inputChan or outputChan during a background chan copy. If either inputChan or outputChan get closed while the copy is in progress, the current copy is stopped and the command callback is not made. If inputChan is closed, then all data already queued for outputChan is written out.

  註意すべきことに､ inputChan は背景処理の複写中に読出し可能になる｡背景処理の複写中に chan event か fileevent 処理のどれを切断しても､その処理機能は複写には影響を及ぼさない｡chan event や fileevent 処理機能によるどの様な入出力の試みも「通信路は使用中」の不都合を引起す｡ 　　 Note that inputChan can become readable during a background copy. You should turn off any chan event or fileevent handlers during a background copy so those handlers do not interfere with the copy. Any I/O attempted by a chan event or fileevent handler will get a “channel busy” error.

  chan copy は inputChan と outputChan 中の行末の箇所を､この通信路の -translation 追加指定に従って､移送する(上述の chan configure 参照)｡この移送は､ inputChan から読んだバイト数と､ outputChan に書いたバイト数が違うかもしれないことを意味する｡同期した chan copy の return 値としても､或いは､非同期の chan copy の為のcallbackの引数としても､どちらも､ outputChan に書いたバイト個数のみが報告される｡ Chan copy translates end-of-line sequences in inputChan and outputChan according to the -translation option for these channels (see chan configure above). The translations mean that the number of bytes read from inputChan can be different than the number of bytes written to outputChan. Only the number of bytes written to outputChan is reported, either as the return value of a synchronous chan copy or as the argument to the callback for an asynchronous chan copy.

  chan copy は通信路について､構成設定された文字番号番号体系と文字変換を得る｡これは､入ってくる記号は最初に内部でUTF-8に変換され､次に､ chan copy が書込む通信路の文字番号体系に変換することを意味する(-encoding と -translation 追加指定の詳細は､上述の chan configure 参照のこと)｡両方の通信路が符号体系 binary に設定され､移送に合致したときのみ変換なしになる｡もし､出力通信路だけが符号体系 binary に設定されると､システムは､入ってきた記号の内部のUTF-8表現に書く｡もし､入力通信路のみが符号体系 binary に設定されると､システムは､入ってくるバイトが UTF-8 の文字に適していると仮定し､それを出力の文字符号体系に変換する｡この設定で､UTF-8 文字に適していないバイトについての､システムの挙動は定義されていない｡ Chan copy 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 chan copy writes to (see chan configure above 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.

chan create mode cmdPrefix
  この副命令は､新しい記述譜水準通信路を､その処理子としての､命令前置辞を使って作成する｡この様な通信路は何れも影像通信路と呼ばれる｡指定した命令前置辞 cmdPrefix は空でないリストであることを要し､取扱説明書 refchan の頁で記述されたAPIを提供することが好ましい｡この新しい通信路の処理子は chan create 命令の結果として戻され､そして､通信路が開かれる｡通信路を除去するには close か chan close を使う｡ 　　　 This subcommand creates a new script level channel using the command prefix cmdPrefix as its handler. Any such channel is called a reflected channel. The specified command prefix, cmdPrefix, must be a non-empty list, and should provide the API described in the refchan manual page. The handle of the new channel is returned as the result of the chan create command, and the channel is open. Use either close or chan close to remove the channel.

  引数 mode は新しい通信路が､読出し､書き出し､両方､のどれであるかを指定する｡それには､文字列 “read” か “write” のどれかが入っているリストでなければならない｡そのリストは少なくとも１つの要素を有する必要があり､さもなくば､通信路として書き込みも読み出しもできずに､意味がなくなる｡新しい通信路の為の､この処理子命令は選択した方向の様式に対応している必要があり､さもなくば不都合が発生される｡ 　　　 The argument mode specifies if the new channel is opened for reading, writing, or both. It has to be a list containing any of the strings “read” or “write”, The list must have at least one element, as a channel you can neither write to nor read from makes no sense. The handler command for the new channel must support the chosen mode, or an error is thrown.

  命令前置辞は大域名前空間の中で､呼出し棚の頂上で､取扱説明書の refchan の頁で記述された通りに追記した引数を従えて実行される｡呼び出しが生じた時､命令の準備が生じる｡命令の名前変更しなければ､次の処理機能手段の呼出しが失敗するかもしれない､同様に処理機能を起動する通信路命令が失敗を起こすかもしれない｡起動される副命令によっては､不都合伝号分は先の失敗の理由を説明することができないかもしれない｡　 　　　 The command prefix is executed in the global namespace, at the top of call stack, following the appending of arguments as described in the refchan manual page. Command resolution happens at the time of the call. Renaming the command, or destroying it means that the next call of a handler method may fail, causing the channel command invoking the handler to fail as well. Depending on the subcommand being invoked, the error message may not be able to explain the reason for that failure.

  この副命令で生成した全ての通信路は､自身がどの解釈実行機能で作成されたかを知っており､たとえその通信路が共有され､そして/又は､それが異なる解釈実行機能に移っていても､その解釈実行機能の実行機能命令のみを実行する｡それぞれに呼応した通信路も自身がどの時分割処理単位(thread)で作成されたかを知っており､たとえその通信路が異なる時分割処理単位に移っていても､その時分割処理単位の実行機能命令のみを実行する｡これを終らせるには､元々の時分割片に向けて特別な行事を送りつけることにより､全ての処理機能の起動を進めることである｡このことは､最初の時分割処理単位(即ち､ chan create 命令を実行した時分割処理単位)が､活動的な行事待機を有し､即ち､それがそのような行事を処理しうることを意味する｡そうでなければ､その処理単位は無限抑止におくられる｡堂々巡りに陥るかもしれない｡ 　　　 Every channel created with this subcommand knows which interpreter it was created in, and only ever executes its handler command in that interpreter, even if the channel was shared with and/or was moved into a different interpreter. Each reflected channel also knows the thread it was created in, and executes its handler command only in that thread, even if the channel was moved into a different thread. To this end all invocations of the handler are forwarded to the original thread by posting special events to it. This means that the original thread (i.e. the thread that executed the chan create command) must have an active event loop, i.e. it must be able to process such events. Otherwise the thread sending them will block indefinitely. Deadlock may occur.

  註意すべきは､これは､二つの終端が二つの異なる時分割処理単位中で活動できる様な通信路の作成を許容し､そのような活動単位間を結ぶデータ流志向の橋をもたらす｡言い換えると､send 命令の代わりの､時分割処理単位間の正規の情報交換の方法を提供できる｡ 　 　 Note that this permits the creation of a channel whose two endpoints live in two different threads, providing a stream-oriented bridge between these threads. In other words, we can provide a way for regular stream communication between threads instead of having to send commands.

  時分割処理単位や解釈実行機能が除去された時､この副命令で作成され､そして､その基本的計算機能として､この処理単位/解釈実行機能を使っていた､全ての通信路は除去される､同様に､それを共有していた又はそれに持込んでいた全ての解釈実行機能内の､更にどのような時分割処理単位内であれ輸送していた通信路も除去される｡このことが､他の時分割処理単位 又は/共に 解釈実行機能 の支援を打ち切ることになっても､避けることはできない｡この様な通信路の使用を試みると未知の通信路処理に関わる通常の不都合発生を引起す｡ 　　　 When a thread or interpreter is deleted, all channels created with this subcommand and using this thread/interpreter as their computing base are deleted as well, in all interpreters they have been shared with or moved into, and in whatever thread they have been transferred to. While this pulls the rug out under the other thread(s) and/or interpreter(s), this cannot be avoided. Trying to use such a channel will cause the generation of a regular error about unknown channel handles.

  この副命令は安全であり､安全な解釈実行機能を利用可能にさせる｡任意のTcl命令系の実行の為に手配している間は､系も､その命令が常に安全な解釈実行機能の中で実行されることが確実になるようにする｡　 　　 This subcommand is safe and made accessible to safe interpreters. While it arranges for the execution of arbitrary Tcl code the system also makes sure that the code is always executed within the safe interpreter.

chan eof channelId
  channelId で呼ばれた通信路の最後の操作がデータ流れの末尾に到達していた為に失敗したのか否かを試験し､ファイル終端に達していれば1を､そうでなければ0を戻す｡ 　　 Test whether the last input operation on the channel called channelId failed because the end of the data stream was reached, returning 1 if end-of-file was reached, and 0 otherwise.

chan event channelId event ?script?
  channelId と呼ばれた通信路が､ event (読出し可か､書き込み可､でなければならない)で記述された状態に入る時は何時でも file event handler として呼出される様に実装される様 Tcl 記述譜 script の為に準備する; そのような機能子は､同時には､行事当り､通信路当り唯一個実装されえる｡もし script が空文字列であると､その時の実行機能は消去される(通信路が閉じられたり､解釈実行機能が除去されても､そうなる)｡もし script が省略されると､そのとき実装されている記述譜が(若しくは､その様な実行機能が実装されていないと空文字列が)返される｡行事待機が稼動中である時のみ 呼び戻し が遂行される(譬えば､ vwait や update 経由で)｡ 　　　 Arrange for the Tcl script script to be installed as a file event handler to be called whenever the channel called channelId enters the state described by event (which must be either readable or writable); only one such handler may be installed per event per channel at a time. If script is the empty string, the current handler is deleted (this also happens if the channel is closed or the interpreter deleted). If script is omitted, the currently installed script is returned (or an empty string if no such handler is installed). The callback is only performed if the event loop is being serviced (e.g. via vwait or update).

  ファイルの行事処理機能子は､通常は､外の行事駆動性の手続函数からデータを受けられることを許容することに使われて､それにより､受ける側は､データが到着するのを待っている間､使用者や､他の通信路と相互に交信を続けることができる｡もし応用譜が､利用できる入力データが無いときに､同期した通信路に chan gets か chan read を起動すると､その手続函数は抑制される；入力データが届く迄､それ以外の行事には答えられなくなり､使用者には｢凍結状態｣に思われる｡ chan event を使うと､手続函数はデータが存在する時に通信でき､しかも､抑制が生じない時に chan gets や chan read を起動するだけである｡ 　 　　 A file event handler is a binding between a channel and a script, such that the script is evaluated whenever the channel becomes readable or writable. File event handlers are most commonly used to allow data to be received from another process on an event-driven basis, so that the receiver can continue to interact with the user or with other channels while waiting for the data to arrive. If an application invokes chan gets or chan read on a blocking channel when there is no input data available, the process will block; until the input data arrives, it will not be able to service other events, so it will appear to the user to “freeze up” . With chan event, the process can tell when data is present and only invoke chan gets or chan read when they will not block.

  通信路は､基本的端末装置に未読の利用可能なデータがあれば､読出し可能と看做す｡通信路は入力緩衝域に未読のデータがある場合にも､最も最近の通信路を読む試みが chan gets 呼出しであって､その時に入力域に行末が見付けられない特別の場合を除いて､読出し可能と看做す｡この性質により､行事を使う非同期様式で､一度に行毎に読まれるファイルを許容している｡通信路は､基礎のファイルや端末装置にファイル終末や不都合状態が存在するときも､読出し可能と看做す｡記述譜 script にとって､この様な条件の確認と処理を適切に行うことは重要である; 譬えば､もしファイル終末の重要な確認を欠くと､ script が読出しデータなしで戻ってくると､すぐさま､読み込みが起動され無限繰返しに陥るかもしれない｡ 　　　 A channel is considered to be readable if there is unread data available on the underlying device. A channel is also considered to be readable if there is unread data in an input buffer, except in the special case where the most recent attempt to read from the channel was a chan gets call that could not find a complete line in the input buffer. This feature allows a file to be read a line at a time in non-blocking mode using events. A channel is also considered to be readable if an end of file or error condition is present on the underlying file or device. It is important for script to check for these conditions and handle them appropriately; for example, if there is no special check for end of file, an infinite loop may occur where script reads no data, returns, and is immediately invoked again.

  通信路は､基礎的ファイルか端末装置に､非同期で､少なくとも１つのバイトでも書き得るか､基礎的ファイルか端末装置上に不具合状態があると､書込み可能と看做す｡註意すべきは､委託側の受け口が非同時方法で開いていると､それが接続された時又は､接続が失敗した時に書込み可能になる｡ 　　　 A channel is considered to be writable if at least one byte of data can be written to the underlying file or device without blocking, or if an error condition is present on the underlying file or device. Note that client sockets opened in asynchronous mode become writable when they become connected or if the connection fails.

  行事-駆動 I/O は chan configure 命令により非同期方法に配置された通信路で最も効率よく動く｡非同期方法では､ chan puts 命令は基礎ファイル又は端末装置が受取れる異常のデータを与えると抑制するかもしれない､そして､chan gets や chan read 命令は､準備したものより多くのデータを読もうと試みると抑制がおこる；命令の抑制中は､行事は全く処理されない｡非同期方法では chan puts, chan read, chan gets は抑制を起こすことはない｡ 　　　 Event-driven I/O works best for channels that have been placed into non-blocking mode with the chan configure command. In blocking mode, a chan puts command may block if you give it more data than the underlying file or device can accept, and a chan gets or chan read command will block if you attempt to read more data than is ready; no events will be processed while the commands block. In non-blocking mode chan puts, chan read, and chan gets never block.

  ファイル行事の為の記述譜は､ chan event 命令が起動された解釈実行機能の中では､大域水準で遂行される(全てのTcl手順の文脈の外で)｡もし､記述譜実行中に､不都合が生じると､ interp bgerror に登録された命令が不具合をの報告に使用される｡更に､そのファイルの行事処理子は､不都合を戻すと取消される；これは､不具合のある処理機能による無限繰返しを防ぐ為に実施される｡ 　　 The script for a file event is executed at global level (outside the context of any Tcl procedure) in the interpreter in which the chan event command was invoked. If an error occurs while executing the script then the command registered with interp bgerror is used to report the error. In addition, the file event handler is deleted if it ever returns an error; this is done in order to prevent infinite loops due to buggy handlers.

chan flush channelId
  channelId から呼ばれた通信路用の全ての未処理出力が書込まれる｡ Ensures that all pending output for the channel called channelId is written.

  もし通信路が同期方法であると､全ての緩衝用出力が通信路に追出される迄､命令の制御が返らない｡もし通信路が非同期方法であると､全ての緩衝用出力が通信路に追出される前に､命令の制御は戻る; 残りは背景処理で基礎ファイル又は端末機器が取込み可能な限りできるだけ速く追出される｡ 　　　 If the channel is in blocking mode the command does not return until all the buffered output has been flushed to the channel. If the channel is in non-blocking mode, the command may return before all buffered output has been flushed; the remainder will be flushed in the background as fast as the underlying file or device is able to absorb it.

chan gets channelId ?varName?
  channelId として呼出した通信路から､次の行を読み出す｡もし varName が指定されていないと､この命令の結果はファイル終末迄､読み込んだ行(末尾の改行文字なしに)か､空文字列であるか､もし非同期方法では､利用可能なデータが尽きる迄､である｡ varName が指定されていると､読み出されるべき行が varName を呼ばれた変数に書かれる､そして､結果は､読込んだ文字の数であり､ファイル終末に達するか､非同期方法では､利用可能なデータが尽きると､ｰ1である｡ 　　　 Reads the next line from the channel called channelId. If varName is not specified, the result of the command will be the line that has been read (without a trailing newline character) or an empty string upon end-of-file or, in non-blocking mode, if the data available is exhausted. If varName is specified, the line that has been read will be written to the variable called varName and result will be the number of characters that have been read or -1 if end-of-file was reached or, in non-blocking mode, if the data available is exhausted.

  行の部分を読出し途中にファイル終末が起ると､部分行が返って来る(又は､ varName 中に書かれる)｡ varName が指定されていないと､ファイル終末条件は､ chan eof 命令の使用による空行により識別し得る､又､部分行-非同期の条件は chan blocked 命令により識別できる｡ 　　　 If an end-of-file occurs while part way through reading a line, the partial line will be returned (or written into varName). When varName is not specified, the end-of-file case can be distinguished from an empty line using the chan eof command, and the partial-line-but-non-blocking case can be distinguished with the chan blocked command.

chan names ?pattern?
  全ての通信路の名前のリストを生成する｡もし pattern が指定されていると､名前がそれに適合する(string match と同じ方法によって)様な通信路だけが返って来る｡ 　　　 Produces a list of all channel names. If pattern is specified, only those channel names that match it (according to the rules of string match) will be returned.

chan pending mode channelId
  様式 mode が入力inputか出力outputかによって､ channelId の為に現在緩衝にある入力又は出力の(対応する)バイト数が返る｡(特に有用なのは､読み込み可能な行事の回収が､適用可能な限度を行の長さを課して､敵性の使用者による､緩衝の為に利用できる記憶量を超過した極端に長い行を設えた､担当-拒否の攻撃を避けることです)｡もし､通信路が問題にされている様式で開かれていないと-1が返って来る｡ 　　　 Depending on whether mode is input or output, returns the number of bytes of input or output (respectively) currently buffered internally for channelId (especially useful in a readable event callback to impose application-specific limits on input line lengths to avoid a potential denial-of-service attack where a hostile user crafts an extremely long line that exceeds the available memory to buffer it). Returns -1 if the channel was not opened for the mode in question.

chan pipe
  独立のパイプを作成し､その読出し側及び､書込み側通信路が２要素リストとして返される､その第１要素が読出し側､第２要素が書込み側である｡譬えば副処理課程からの stderr と stdout を別々に出力先変更するには便利かもしれない｡こうする為には､ "2>@" や ">@" により､パイプの書込み側で出力先変更操作を産出し､次に､すぐさまその親の中でそれを閉じる｡これは子供が一度終了させた読出し側にファイル末尾信号を得る為に必要であり､そうでなければその出力を閉じさせる｡ 　　　 Creates a standalone pipe whose read- and write-side channels are returned as a 2-element list, the first element being the read side and the second the write side. Can be useful e.g. to redirect separately stderr and stdout from a subprocess. To do this, spawn with "2>@" or ">@" redirection operators onto the write side of a pipe, and then immediately close it in the parent. This is necessary to get an EOF on the read side once the child has exited or otherwise closed its output.

  注意すべきは､パイプの緩衝域手段はOS水準では本質的に多様な違いがあるかもしれない; パイプの出力側になされた書込み結果が即座に入力側に現れると仮定することは安全ではない｡それは基本的な相違であり､Tcl ではそれを抑え込めない｡全体の流れの意味論は互換であり､従って､読み書きの同期は殆ど差異が見られないが､いつ書かれたかについての得られた正確な事柄は互換ではない｡試験のためにパイプラインを使用するときに得てして露見しがちであるが; 潜在的な短絡読みが陥り易い袋小路に入ることがないよう注意すべきである｡ 　　　 Note that the pipe buffering semantics can vary at the operating system level substantially; it is not safe to assume that a write performed on the output side of the pipe will appear instantly to the input side. This is a fundamental difference and Tcl cannot conceal it. The overall stream semantics are compatible, so blocking reads and writes will not see most of the differences, but the details of what exactly gets written when are not. This is most likely to show up when using pipelines for testing; care should be taken to ensure that deadlocks do not occur and that potential short reads are allowed for.

chan pop channelId
  通信路 channelId から､変換があれば一番上のものを取り去る｡変換がない場合は channelId に加える､これはその通信路の chan close と等価である｡結果は通常空文字列であるが､ある状況では不都合になることもある(即ち､基礎の系の流れが閉じられる処では結果は不都合になる)｡ 　　　 Removes the topmost transformation from the channel channelId, if there is any. If there are no transformations added to channelId, this is equivalent to chan close of that channel. The result is normally the empty string, but can be an error in some situations (i.e. where the underlying system stream is closed and that results in an error).

chan postevent channelId eventSpec
  この副命令は､chan create により指定された命令の処理子に利用される｡ channelId 処理子によって表現されている通信路に､ eventSpec 中に列挙された行事が生じたことを通知する｡この引数は読み込み read と書込み write したどれかの文字列を含んでいるリストでなければならない｡そのリストは少なくとも１個の要素を含まなくてはならない､もし､通知すべき行事がない場合に､命令を起動する意味が無くなるためである｡ 　　　 This subcommand is used by command handlers specified with chan create. It notifies the channel represented by the handle channelId that the event(s) listed in the eventSpec have occurred. The argument has to be a list containing any of the strings read and write. The list must contain at least one element as it does not make sense to invoke the command if there are no events to post.

  註意すべきは､この副命令は chan create によって 作成/操作 されたかもしれない通信路の処理子にのみ使用されうる｡その他の通信路はこの副命令に不都合を報告させることになる｡ 　　　 Note that this subcommand can only be used with channel handles that were created/opened by chan create. All other channels will cause this subcommand to report an error.

  通信路のTcl 水準のみが､即ち､その命令の処理子が､その行事を､その通信路を作成した解釈実行機能に､この命令の使用が制限されていると通知するであろう｡言い換えると､影像の通信路に､その実現を含まない解釈実行機能から行事を通知することは許容されていない｡それ以外の全ての解釈実行機能からの通知の試みはこの副命令の不都合報告を引起す｡ 　　　 As only the Tcl level of a channel, i.e. its command handler, should post events to it we also restrict the usage of this command to the interpreter that created the channel. In other words, posting events to a reflected channel from an interpreter that does not contain it's implementation is not allowed. Attempting to post an event from any other interpreter will cause this subcommand to report an error.

  その他の制限は､入出力の核がそれへの関心を登録していない行事の通知はできないと言うことである｡それを試みると､手順から不都合が報告される｡ refchan に記載された watch の命令処理方法を参照されたい､その文書には影像通信路の為の命令のAPIが規定されている｡ Another restriction is that it is not possible to post events that the I/O core has not registered an interest in. Trying to do so will cause the method to throw an error. See the command handler method watch described in refchan, the document specifying the API of command handlers for reflected channels.

  この命令は安全であり､安全な解釈実行機能を利用可能にさせる｡縦え､実行中の解釈実行機能中でも､他の解釈実行機能や他の時分割片､はては､その行事が安全な解釈実行機能から通知され､そして信頼される解釈実行機能に監視されていても､それは､chan event 処理子の実行を起動することができる｡chan event 処理機能は常にそれを設定した解釈実行機能の中で遂行される｡ 　　　 This command is safe and made accessible to safe interpreters. It can trigger the execution of chan event handlers, whether in the current interpreter or in other interpreters or other threads, even where the event is posted from a safe interpreter and listened for by a trusted interpreter. Chan event handlers are always executed in the interpreter that set them up.

chan push channelId cmdPrefix
  通信路 channelId の頂上に新しい変換を加える｡ cmdPrefix 引数は変換を実装する為に使われることになる処理機能を表現する一つ或はそれ以上の語のリストを記述する｡命令前置辞は､ transchan 取扱説明書頁に記述された API を提供しなくてはならない｡この副命令の結果は変換の処理機能である｡註意すべきは､変換が､一緒に使用されるか､通信路を読出しも書込みもできなくすることができる通信路の様式に対応する能力があることを確かめる事が重要である｡ 　　　 Adds a new transformation on top of the channel channelId. The cmdPrefix argument describes a list of one or more words which represent a handler that will be used to implement the transformation. The command prefix must provide the API described in the transchan manual page. The result of this subcommand is a handle to the transformation. Note that it is important to make sure that the transformation is capable of supporting the channel mode that it is used with or this can make the channel neither readable nor writable.

chan puts ?-nonewline? ?channelId? string
  string の末尾に改行記号を付けて channelId の名称の通信路に書込む｡指定子の標しの -nonewline が与えられない限り､末尾に改行記号が記入される｡もし channelId が省略されると､その文字列は標準出力 stdout に記入される｡ 　　　 Writes string to the channel named channelId followed by a newline character. A trailing newline character is written unless the optional flag -nonewline is given. If channelId is omitted, the string is written to the standard output channel, stdout.

  出力中の改行記号は､その通信路の為の､ -translation 指定に､現在､構成設定されている値に従って､OS特有の 行末記号列に変換される(譬えば､PCの改行は通常､先頭戻り-行送り記号列に置換される; 詳細は上述の chan configure を参照されたい)｡ 　　　 Newline characters in the output are translated by chan puts to platform-specific end-of-line sequences according to the currently configured value of the -translation option for the channel (for example, on PCs newlines are normally replaced with carriage-return-linefeed sequences; see chan configure above for details).

  Tcl は 出力を内部で緩衝域保存するので､chan puts によって書かれた文字が直接出力ファイルや装置に現れないかもしれない; Tcl は通常緩衝域が一派にになるか､通信路が閉鎖されるまで出力を見合わせる｡使用者は chan flush 命令によってすぐさま出力の出現を強制することができる｡　　　 Tcl buffers output internally, so characters written with chan puts may not appear immediately on the output file or device; Tcl will normally delay output until the buffer is full or the channel is closed. You can force output to appear immediately with the chan flush command.

  出力緩衝域が一杯になると､この chan puts 命令は通常は､貯蔵された全てのデータがOSによって出力の為に受け入れられる迄､抑制する｡もし channelId が非同期様式ならば､ chan puts 命令は縦えOSがデータを受入れられなくても抑制しない｡その代わり､Tclは､そのデータを緩衝域に貯蔵しつづけ､背景処理で､基礎ファイルや端末装置が受入れられる限り速く記入する｡応用譜は非同期で出力を働かせるにはTclの行事繰返しを使わねばならない; さもないと､ Tcl は､更なる出力データに対する､ファイルや端末装置の受け入れ準備完了を知ることができない｡こうすることで､大量の記憶領域を消費するかもしれない非同期様式の通信路に任意の大きさのデータを緩衝貯蔵できるようになる｡記憶領域の消費を避けるには､非同期の入出力は､通常は､ chan event 命令による､行事-駆動の方式を使うことである｡(ファイルの行事経由で､最近に､通信路が更なるデータの出力の準備完了を通知される迄､ chan puts を起動してはならない)｡ 　　　 When the output buffer fills up, the chan puts command will normally block until all the buffered data has been accepted for output by the operating system. If channelId is in non-blocking mode then the chan puts command will not block even if the operating system cannot accept the data. Instead, Tcl continues to buffer the data and writes it in the background as fast as the underlying file or device can accept it. The application must use the Tcl event loop for non-blocking output to work; otherwise Tcl never finds out that the file or device is ready for more output data. It is possible for an arbitrarily large amount of data to be buffered for a channel in non-blocking mode, which could consume a large amount of memory. To avoid wasting memory, non-blocking I/O should normally be used in an event-driven fashion with the chan event command (do not invoke chan puts unless you have recently been notified via a file event that the channel is ready for more output data).

chan read channelId ?numChars?

chan read ?-nonewline? channelId
  最初の書式中では､結果は channelId と名付けられた通信路から読んだ､次の numChars 文字になる; もし numChars が省略されると､通信路が失敗(ファイル終末､抑制､又は他の不都合状態)を告げる点までの全ての文字が読込まれる｡第二の書式中では(即ち､ numChars が省略されている)､読込んだ文字列のどの末尾の改行も削除することを指示する -nonewline 標を与えてもよい｡ 　　　 In the first form, the result will be the next numChars characters read from the channel named channelId; if numChars is omitted, all characters up to the point when the channel would signal a failure (whether an end-of-file, blocked or other error condition) are read. In the second form (i.e. when numChars has been omitted) the flag -nonewline may be given to indicate that any trailing newline in the string that has been read should be trimmed.

  もし channelId が非同期方法であると､ chan read 要求されたと同じだけの文字を読まないかもしれない: 一度､全ての利用可能なデータが読み込まれると､この命令は､更なる入力の阻止をせず､利用可能なデータを戻す｡もし､通信路が多バイト文字列体系に構成設定されていると､内部緩衝域に完全な文字に至らない､少しのバイトが残ることが多い｡緩衝域中の､この様なバイトは､完全な文字を形成するか､ファイル終末が届くかしないと返らない｡ファイル終末が届く前に命令が戻る時は､この -nonewline 切替子は無視される｡ 　　　 If channelId is in non-blocking mode, chan read may not read as many characters as requested: once all available input has been read, the command will return the data that is available rather than blocking for more input. If the channel is configured to use a multi-byte encoding, then there may actually be some bytes remaining in the internal buffers that do not form a complete character. These bytes will not be returned until a complete character is available or end-of-file is reached. The -nonewline switch is ignored if the command returns before reaching the end of the file.

  chan read では入力中の行末文字並びを通信路用の -translation 選択子に従って､改行に翻訳する(方法の論議については､上述の chan configure の chan configure が入力を改める方法の箇所を参照されたい)｡ Chan read translates end-of-line sequences in the input into newline characters according to the -translation option for the channel (see chan configure above for a discussion on the ways in which chan configure will alter input).

  直列入力端子から読み込む時､大多数の応用譜は直列入力端子を非同期に構成設定する､この様に: 　　　 When reading from a serial port, most applications should configure the serial port channel to be non-blocking, like this:

      chan configure channelId -blocking 0.

  そこで､ chan read は上で色々述べたように振舞う｡註意すべきは､殆どの直列端子は比較的遅い; 其処から各文字を読込む毎に､読出し可の行事を得ることも全く可能である｡同期直列端子から chan read を使って読む時に次の事を註意せねばならぬ: 　　　 Then chan read behaves much like described above. Note that most serial ports are comparatively slow; it is entirely possible to get a readable event for each character read from them. Care must be taken when using chan read on blocking serial ports:

  chan read channelId numChars
    この形式の chan read は直列端子から numChars 個受取るまで抑止する｡ In this form chan read blocks until numChars have been received from the serial port.

  chan read channelId
    この形式の chan read はファイル終末記号を受取るまで抑制する､chan configure -eofchar を参照されたい｡もしこの通信路の為に終端記号が構成設定されなかったら､ chan read は何時までも抑制する｡ 　　　 In this form chan read blocks until the reception of the end-of-file character, see chan configure -eofchar. If there no end-of-file character has been configured for the channel, then chan read will block forever.

chan seek channelId offset ?origin?
  channelId と言う名前の通信路の為の基礎データ流れのなかの最新の利用位置を origin を基準にして offset バイトの位置に設定する｡ offset は整数でなくてはならず(負数でもよい)､ origin は次のどれか一つである: 　　　 Sets the current access position within the underlying data stream for the channel named channelId to be offset bytes relative to origin. Offset must be an integer (which may be negative) and origin must be one of the following:

  start
    基礎ファイル又は端末装置の新しい利用位置は､始点から offset バイトの位置である｡ The new access position will be offset bytes from the start of the underlying file or device.

  current
    基礎ファイル又は端末装置の新しい利用位置は､現在の位置から offset バイトの位置である; 負の値の offset は基礎ファイル又は端末装置の利用位置を後方に移動する｡ 　　　 The new access position will be offset bytes from the current access position; a negative offset moves the access position backwards in the underlying file or device.

  end
    基礎ファイル又は端末装置の新しい利用位置は､ファイル終点から offset バイトの位置である｡負の offset はファイル終りから手前の位置に利用位置を置き､正の offset はファイル終り以降にファイル利用位置を置く｡ 　　　 The new access position will be offset bytes from the end of the file or device. A negative offset places the access position before the end of file, and a positive offset places the access position after the end of file.

    引数 origin の省略時設定は start である｡ The origin argument defaults to start.

    chan seek は､縦え通信路が非同期方法であっても､命令が戻る前に通信路の為の出力用緩衝域を､全て追出す｡又､全ての緩衝域に貯蓄された､未読の入力を遺棄する｡この命令は空文字列を持帰る｡この命令を掃引に対応していないファイルや端末装置の通信路に適用すると不都合が生じる｡ Chan seek flushes all buffered output for the channel before the command returns, even if the channel is in non-blocking mode. It also discards any buffered and unread input. This command returns an empty string. An error occurs if this command is applied to channels whose underlying file or device does not support seeking.

    註意すべきは､ offset の値はバイトの補正値であり､文字単位の補正値ではない｡ chan seek とchan tell 操作はchan read と異なり､文字単位ではなくバイト単位で操作する｡ 　　　 Note that offset values are byte offsets, not character offsets. Both chan seek and chan tell operate in terms of bytes, not characters, unlike chan read.

chan tell channelId
  channelId と言う名前の通信路の為の基礎データ流れのなかの最新の利用位置を与える数を戻す｡この戻った値は､その通信路を特定の位置に設定する為に､chan seek に伝えることのできるバイト数の補正値である｡註意すべきは､この値は､バイトの補正値であり､chan read と異なる｡通信路の為に戻った値が-1であると､探求には対応していない｡ 　　　 Returns a number giving the current access position within the underlying data stream for the channel named channelId. This value returned is a byte offset that can be passed to chan seek in order to set the channel to a particular position. Note that this value is in terms of bytes, not characters like chan read. The value returned is -1 for channels that do not support seeking.

chan truncate channelId ?length?
  channelId と言う名前の通信路の為の基礎データ流れの長さを length に(又は､もし length が省略されると､基礎データ流れの中での現在のバイト偏倚に)､設定する｡その通信路は約められる前に追い払われる｡ 　　　 Sets the byte length of the underlying data stream for the channel named channelId to be length (or to the current byte offset within the underlying data stream if length is omitted). The channel is flushed before truncation.

### EXAMPLES

#### 単純な開伝達経路例 SIMPLE CHANNEL OPERATION EXAMPLES

端末向けか否かに拘らず､常に即座に stdout を送る事を Tcl に指導する｡ Instruct Tcl to always send output to stdout immediately, whether or not it is to a terminal:

    fconfigure stdout -buffering none

次の用例では､Windows では､文字列を捜索の為に､共通の符号番号 CP1252 を使ってファイルが開かれ､その部分を書換え､後に二行に切詰める｡ 　 In the following example a file is opened using the encoding CP1252, which is common on Windows, searches for a string, rewrites that part, and truncates the file two lines later.

    set f [open somefile.txt r+]
    chan configure $f -encoding cp1252
    set offset 0

    #  ファイルから文字列｢FOOBAR｣ を捜す
    # Search for string "FOOBAR" in the file
    while {[chan gets $f line] >= 0} {
        set idx [string first FOOBAR $line]
        if {$idx >= 0} {
            # 見つけた; 行を再記入
            # Found it; rewrite line

            chan seek $f [expr {$offset + $idx}]
            chan puts -nonewline $f BARFOO

            #  末尾迄行を飛越し､約める
            # Skip to end of following line, and truncate
            chan gets $f
            chan gets $f
            chan truncate $f

            # ここでファイル検索を停止する
            # Stop searching the file now
            break
        }

        # 後々の為､次の行の位置を保存する
        # Save offset of start of next line for later
        set offset [chan tell $f]
    }
    chan close $f

同時に入力する他への処置を妨げることなく､一行づつの入力に応答する電網中央集中処理装置｡ 　　　 A network server that echoes its input line-by-line without preventing servicing of other connections at the same time:

    # This is a very simple logger...
    proc log {message} {
        chan puts stdout $message
    }

    # 何時であれ､新しい依頼者が中央集中処理装置に接続したら呼ばれる
    # This is called whenever a new client connects to the server
    proc connect {chan host port} {
        set clientName [format <%s:%d> $host $port]
        log "connection from $clientName"
        chan configure $chan -blocking 0 -buffering line
        chan event $chan readable [list echoLine $chan $clientName]
    }

    # 何時であれ､最低１バイトの入力データが利用可能か
    # 通信路が依頼者に閉じられるかしたら呼ばれる
    # This is called whenever either at least one byte of input
    # data is available, or the channel was closed by the client.
    proc echoLine {chan clientName} {
        chan gets $chan line
        if {[chan eof $chan]} {
            log "finishing connection from $clientName"
            chan close $chan
        } elseif {![chan blocked $chan]} {
            # 行末を待つよう留めることはなかった
            # Didn't block waiting for end-of-line
            log "$clientName - $line"
            chan puts $chan $line
        }
    }

    # 接続の中央処理装置を生成し､接続の進入を待つ為の行事巡回に入る...
    # Create the server socket and enter the event-loop to wait
    # for incoming connections...
    socket -server connect 12345
    vwait forever

### SEE ALSO

close, eof, fblocked, fconfigure, fcopy, file, fileevent, flush, gets, open, puts, read, seek, socket, tell, refchan, transchan, Tcl_StandardChannels

### KEYWORDS

blocking, channel, end of file, events, input, non-blocking, offset, output, readable, seek, stdio, tell, writable
Copyright © 2005-2006 Donal K. Fellows