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

### 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

fileevent — 通信路が読出し可か書込み可になった時に記述譜を実行する Execute a script when a channel becomes readable or writable

### 構文 SYNOPSIS

fileevent channelId readable ?script?

fileevent channelId writable ?script?

### 説明 DESCRIPTION

この命令はファイル行事処理操作子を作る為に使われる｡ファイル行事処理操作子は､何時であれ､通信路が読出し可か書込み可になった時に､記述譜が評価される様に､通信路と記述譜を結縛している｡ファイル行事処理操作子は､行事駆動方式で､他の処理手続からデータを受取ることを許容することによく使用され､それにより､データ到来を待つ間に受取り手が､使用者と対話を続けられる｡もし､利用できるデータが無いときに､応用譜が同期通信路の gets か read を起動すると､入力データが届く迄､処理が抑制される; 他の行事には従事できないので､使用者に向けては “凍結” が生じる｡ fileevent を使うと､処理手続はデータが何時届いたかを見分けられ､抑制が起らない時にのみ gets か read を起動することができる｡ 　　　 This command is used to create file event handlers. 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 while waiting for the data to arrive. If an application invokes gets or 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 fileevent, the process can tell when data is present and only invoke gets or read when they will not block.

fileevent の引数 channelId は､Tcl 標準通信路(stdin か stdout か stderr)､若しくは､ open や socket の起動からの返り値､若しくは､Tcl拡張によってもたらされた通信路作成命令の結果の値の様な､開いた通信路を参照する｡ 　　　 The channelId argument to fileevent refers to an open channel such as a Tcl standard channel (stdin, stdout, or stderr), the return value from an invocation of open or socket, or the result of a channel creation command provided by a Tcl extension.

script 引数が指定された場合､ fileevent は新しい行事処理操作子を作成する: script は通信路が(fileevent の第二引数に従って)読出し可か書込み可になった時にはいつでも記述譜が評価されることになる｡この場合 fileevent は空文字列を返す｡ファイルの readable と writable 行事処理機操作子は独立していて､その生成消滅も別々になり得る｡しかし､殆どは､与えられた解釈実行機能中の特定の時には､ファイルに一つの読出し用と一つの書込み用の処理操作子があるだけである｡もし fileevent が呼ばれると､起動された解釈実行機能の中に既に指定された処理操作子が実在する時は､新しい記述譜が古いものに置き換わる｡ 　　 If the script argument is specified, then fileevent creates a new event handler: script will be evaluated whenever the channel becomes readable or writable (depending on the second argument to fileevent). In this case fileevent returns an empty string. The readable and writable event handlers for a file are independent, and may be created and deleted separately. However, there may be at most one readable and one writable handler for a file at a given time in a given interpreter. If fileevent is called when the specified handler already exists in the invoking interpreter, the new script replaces the old one.

script 引数が指定されていない場合､fileevent は channelId の為の現在の記述譜を､なければ空文字列を､返す｡ script として空文字列が指定される場合は､行事処理操作子が削除され､どの様な記述譜も起動されなくなる｡その通信路が閉じられるか解釈実行機能が消去されると何時でもファイル行事処理操作子は自動的に消去される｡ If the script argument is not specified, fileevent returns the current script for channelId, or an empty string if there is none. If the script argument is specified as an empty string then the event handler is deleted, so that no script will be invoked. A file event handler is also deleted automatically whenever its channel is closed or its interpreter is deleted.

基礎端末装置に利用可能な未読データがあると通信路は読出し可能と看做される｡もし､入力緩衝域に未読のデータがあると､最も最近に通信路を読む試みが､ 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 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 nonblocking 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.

行事駆動式入出力が､通信路に良く動作するのは､ fconfigure 命令で非同期方法に置かれたときである｡同期方法の中では､基礎ファイル又は端末装置が受入れ可能より多くのデータを与えると puts 命令は抑制が生じるかもしれない､又､準備できる以上のデータを読もうとすると､ gets や read 命令は抑制が生じるかもしれない; 読出し可能な基礎ファイルや端末装置は抑制が成功する事を保障しないかもしれない(反証例は､多バイト符号変換や､圧縮や､暗号変換)｡この様な全ての場合に､命令が抑制されている間､行事は全く処理されない｡ 　　　 Event-driven I/O works best for channels that have been placed into nonblocking mode with the fconfigure command. In blocking mode, a puts command may block if you give it more data than the underlying file or device can accept, and a gets or read command will block if you attempt to read more data than is ready; a readable underlying file or device may not even guarantee that a blocking [read 1] will succeed (counter-examples being multi-byte encodings, compression or encryption transforms ). In all such cases, no events will be processed while the commands block.

非同期様式では､ puts と read と gets は同期することはない｡これ等が如何に同期や非同期通信路を処理するかの情報については個別の命令の説明を参照されたい｡ 　　　 In nonblocking mode puts, read, and gets never block. See the documentation for the individual commands for information on how they handle blocking and nonblocking channels.

ファイルの終末状態の試験は何か通信路を読む試みの後でなされるべきである｡ファイル終末旗印が一たび設定されるとデータの末尾を読む試みが生じ､この読出しの前の検査は追加的な行事が発生することが要求される｡ 　　　 Testing for the end of file condition should be done after any attempts read the channel data. The eof flag is set once an attempt to read the end of data has occurred and testing before this read will require an additional event to be fired.

ファイル行事の為の記述譜は､ fileevent 命令が起動された解釈実行機能の中の､(どの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 fileevent 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.

### 実施例 EXAMPLE

この中では､何時であれ $chan が読出し可能になったら､引数としての通信路を伴って GetData が呼び出される様に設定する｡ read 呼出しは､現在､どの様な２進データであれ同期なしに利用できれば読むことになる｡ここでは､ファイル終末が生じた時に､継続的な呼出しを回避する為に､通信路がファイル行事を除去させる(上述参照)｡その代わりに通信路はその状態で閉じられても好い｡ 　　　 In this setup GetData will be called with the channel as an argument whenever $chan becomes readable. The read call will read whatever binary data is currently available without blocking. Here the channel has the fileevent removed when an end of file occurs to avoid being continually called (see above). Alternatively the channel may be closed on this condition.

    proc GetData {chan} {
        set data [read $chan]
        puts "[string length $data] $data"
        if {[eof $chan]} {
            fileevent $chan readable {}
        }
    }

    fconfigure $chan -blocking 0 -translation binary
    fileevent $chan readable [list GetData $chan]

次の例は行志向のデータを読む為の gets の使用を実証する｡ 　 The next example demonstrates use of gets to read line-oriented data.

    proc GetData {chan} {
        if {[gets $chan line] >= 0} {
            puts $line
        }
        if {[eof $chan]} {
            close $chan
        }
    }

    fconfigure $chan -blocking 0 -buffering line -translation crlf
    fileevent $chan readable [list GetData $chan]

### 著作権表示 CREDITS

fileevent は､ Mark Diekhans によって創られた addinput 命令に基いている｡ fileevent is based on the addinput command created by Mark Diekhans.

### SEE ALSO

fconfigure, gets, interp, puts, read, Tcl_StandardChannels

### KEYWORDS

asynchronous I/O, blocking, channel, event handler, nonblocking, readable, script, writable.
Copyright © 1994 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.
Copyright © 2008 Pat Thoyts