## Tcl8.6.17/Tk8.6.17 Documentation > Tcl C API > CrtChannel

### 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
    Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered — 通信路の生成と操作の為の手続き函数　 procedures for creating and manipulating channels
  SYNOPSIS
    #include <tcl.h>
    Tcl_Channel
    Tcl_CreateChannel(typePtr, channelName, instanceData, mask)
    ClientData
    Tcl_GetChannelInstanceData(channel)
    const Tcl_ChannelType *
    Tcl_GetChannelType(channel)
    const char *
    Tcl_GetChannelName(channel)
    int
    Tcl_GetChannelHandle(channel, direction, handlePtr)
    Tcl_ThreadId
    Tcl_GetChannelThread(channel)
    int
    Tcl_GetChannelMode(channel)
    int
    Tcl_GetChannelBufferSize(channel)
    Tcl_SetChannelBufferSize(channel, size)
    Tcl_NotifyChannel(channel, mask)
    int
    Tcl_BadChannelOption(interp, optionName, optionList)
    int
    Tcl_IsChannelShared(channel)
    int
    Tcl_IsChannelRegistered(interp, channel)
    int
    Tcl_IsChannelExisting(channelName)
    void
    Tcl_CutChannel(channel)
    void
    Tcl_SpliceChannel(channel)
    void
    Tcl_ClearChannelHandlers(channel)
    int
    Tcl_ChannelBuffered(channel)
    const char *
    Tcl_ChannelName(typePtr)
    Tcl_ChannelTypeVersion
    Tcl_ChannelVersion(typePtr)
    Tcl_DriverBlockModeProc *
    Tcl_ChannelBlockModeProc(typePtr)
    Tcl_DriverCloseProc *
    Tcl_ChannelCloseProc(typePtr)
    Tcl_DriverClose2Proc *
    Tcl_ChannelClose2Proc(typePtr)
    Tcl_DriverInputProc *
    Tcl_ChannelInputProc(typePtr)
    Tcl_DriverOutputProc *
    Tcl_ChannelOutputProc(typePtr)
    Tcl_DriverSeekProc *
    Tcl_ChannelSeekProc(typePtr)
    Tcl_DriverWideSeekProc *
    Tcl_ChannelWideSeekProc(typePtr)
    Tcl_DriverThreadActionProc *
    Tcl_ChannelThreadActionProc(typePtr)
    Tcl_DriverTruncateProc *
    Tcl_ChannelTruncateProc(typePtr)
    Tcl_DriverSetOptionProc *
    Tcl_ChannelSetOptionProc(typePtr)
    Tcl_DriverGetOptionProc *
    Tcl_ChannelGetOptionProc(typePtr)
    Tcl_DriverWatchProc *
    Tcl_ChannelWatchProc(typePtr)
    Tcl_DriverGetHandleProc *
    Tcl_ChannelGetHandleProc(typePtr)
    Tcl_DriverFlushProc *
    Tcl_ChannelFlushProc(typePtr)
    Tcl_DriverHandlerProc *
    Tcl_ChannelHandlerProc(typePtr)
  引数 ARGUMENTS
    const Tcl_ChannelType *typePtr (入力in)
    const char *channelName (in)
    ClientData instanceData (入力in)
    int mask (入力in)
    Tcl_Channel channel (入力in)
    int direction (入力in)
    ClientData *handlePtr (出力out)
    int size (入力in)
    int mask (入力in)
    Tcl_Interp *interp (入力in)
    const char *optionName (入力in)
    const char *optionList (入力in)
  説明 DESCRIPTION
  TCL_の通信路型 TCL_CHANNELTYPE
  型名 TYPENAME
  版 VERSION
  BLOCKMODEPROC
  CLOSEPROC AND CLOSE2PROC
  INPUTPROC
  OUTPUTPROC
  SEEKPROC AND WIDESEEKPROC
  SETOPTIONPROC
  GETOPTIONPROC
  WATCHPROC
  GETHANDLEPROC
  FLUSHPROC
  HANDLERPROC
  THREADACTIONPROC
  TRUNCATEPROC
  TCL_BADCHANNELOPTION
  OLD CHANNEL TYPES
  SEE ALSO
  KEYWORDS

### NAME

Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered — 通信路の生成と操作の為の手続き函数　 procedures for creating and manipulating channels

### SYNOPSIS

#include <tcl.h>
Tcl_Channel
Tcl_CreateChannel(typePtr, channelName, instanceData, mask)
ClientData
Tcl_GetChannelInstanceData(channel)
const Tcl_ChannelType *
Tcl_GetChannelType(channel)
const char *
Tcl_GetChannelName(channel)
int
Tcl_GetChannelHandle(channel, direction, handlePtr)
Tcl_ThreadId
Tcl_GetChannelThread(channel)
int
Tcl_GetChannelMode(channel)
int
Tcl_GetChannelBufferSize(channel)
Tcl_SetChannelBufferSize(channel, size)
Tcl_NotifyChannel(channel, mask)
int
Tcl_BadChannelOption(interp, optionName, optionList)
int
Tcl_IsChannelShared(channel)
int
Tcl_IsChannelRegistered(interp, channel)
int
Tcl_IsChannelExisting(channelName)
void
Tcl_CutChannel(channel)
void
Tcl_SpliceChannel(channel)
void
Tcl_ClearChannelHandlers(channel)
int
Tcl_ChannelBuffered(channel)
const char *
Tcl_ChannelName(typePtr)
Tcl_ChannelTypeVersion
Tcl_ChannelVersion(typePtr)
Tcl_DriverBlockModeProc *
Tcl_ChannelBlockModeProc(typePtr)
Tcl_DriverCloseProc *
Tcl_ChannelCloseProc(typePtr)
Tcl_DriverClose2Proc *
Tcl_ChannelClose2Proc(typePtr)
Tcl_DriverInputProc *
Tcl_ChannelInputProc(typePtr)
Tcl_DriverOutputProc *
Tcl_ChannelOutputProc(typePtr)
Tcl_DriverSeekProc *
Tcl_ChannelSeekProc(typePtr)
Tcl_DriverWideSeekProc *
Tcl_ChannelWideSeekProc(typePtr)
Tcl_DriverThreadActionProc *
Tcl_ChannelThreadActionProc(typePtr)
Tcl_DriverTruncateProc *
Tcl_ChannelTruncateProc(typePtr)
Tcl_DriverSetOptionProc *
Tcl_ChannelSetOptionProc(typePtr)
Tcl_DriverGetOptionProc *
Tcl_ChannelGetOptionProc(typePtr)
Tcl_DriverWatchProc *
Tcl_ChannelWatchProc(typePtr)
Tcl_DriverGetHandleProc *
Tcl_ChannelGetHandleProc(typePtr)
Tcl_DriverFlushProc *
Tcl_ChannelFlushProc(typePtr)
Tcl_DriverHandlerProc *
Tcl_ChannelHandlerProc(typePtr)

### 引数 ARGUMENTS

const Tcl_ChannelType *typePtr (入力in)
  通信路上の入出力と他の機能の遂行の為に呼出されるかもしれない手続函数の番地を含む構造を指す｡ 　 Points to a structure containing the addresses of procedures that can be called to perform I/O and other functions on the channel.

const char *channelName (in)
  通信路の名前､譬えば file3 は他の通信路による使用中であってはならない｡NULL であってもよい､その場合通信路は名前なしで作成される｡作成された通信路は標準通信路(stdin か stdout か stderr)の一つが代入される場合､代入された通信路名前は標準通信路の名前になる｡ 　 The name of this channel, such as file3; must not be in use by any other channel. Can be NULL, in which case the channel is created without a name. If the created channel is assigned to one of the standard channels (stdin, stdout or stderr), the assigned channel name will be the name of the standard channel.

ClientData instanceData (入力in)
  この通信路に結合されるべき任意の１語｡この値はそれが起動された時に typePtr 内の手続函数に渡される｡ 　　 Arbitrary one-word value to be associated with this channel. This value is passed to procedures in typePtr when they are invoked.

int mask (入力in)
  通信路が読出し可能か書込み可能かを示す､TCL_READABLE と TCL_WRITABLE の､論理和､の組合せ｡ 　　 OR-ed combination of TCL_READABLE and TCL_WRITABLE to indicate whether a channel is readable and writable.

Tcl_Channel channel (入力in)
  操作を施すべき通信路｡ The channel to operate on.

int direction (入力in)
  TCL_READABLE の意味は入力処理が望まれている; TCL_WRITABLE の意味は出力処理が望まれている｡ TCL_READABLE means the input handle is wanted; TCL_WRITABLE means the output handle is wanted.

ClientData *handlePtr (出力out)
  望ましいOS固有の処理機能が保存されている箇所を指す｡ Points to the location where the desired OS-specific handle should be stored.

int size (入力in)
  この通信路内に割付られた緩衝域のバイト単位の寸法｡ The size, in bytes, of buffers to allocate in this channel.

int mask (入力in)
  この通信路上に起った行事を指し示す TCL_READABLE と TCL_WRITABLE と TCL_EXCEPTION の論理和の組み合わせ｡ An OR-ed combination of TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION that indicates events that have occurred on this channel.

Tcl_Interp *interp (入力in)
  現在の解釈実行機能(NULL でもよい)｡ Current interpreter. (can be NULL)

const char *optionName (入力in)
  不適切な指示項目の名前｡ Name of the invalid option.

const char *optionList (入力in)
  標準的一般選択肢リストに追加する為の固有の選択肢リスト( “-” 以外の空白で区切った語並び)｡ 一般選択肢不都合伝言文だけはNULL でもよい｡ Specific options list (space separated words, without “-”) to append to the standard generic options list. Can be NULL for generic options error message only.

### 説明 DESCRIPTION

Tcl は２層の通信路構造を使う｡それは､色々のファイル､装置､授受口､その他の為に同じ API を使い､入力と出力を遂行する為のC と Tcl 算譜を可能にする一般の上部層を提供する｡一般の C APIs は Tcl_OpenFileChannel に関する取扱説明書の項に記載されている｡ 　　　 Tcl uses a two-layered channel architecture. It provides a generic upper layer to enable C and Tcl programs to perform input and output using the same APIs for a variety of files, devices, sockets etc. The generic C APIs are described in the manual entry for Tcl_OpenFileChannel.

下の層はそれぞれのＯＳに運営されているそれぞれの型の装置の為の型固有の通信路駆動譜を提供する｡この取扱説明書の項目では一般層と型固有の装置駆動譜の間の通信に使われる C APIs が記述される｡更に如何に通信路の新しい型が新しい通信路駆動譜の提供によって与えられるかを記述している｡ 　　 The lower layer provides type-specific channel drivers for each type of device supported on each platform. This manual entry describes the C APIs used to communicate between the generic layer and the type-specific channel drivers. It also explains how new types of channels can be added by providing new channel drivers.

通信路駆動譜は幾つもの構成部品により構成されている: 第1､それぞれの通信路装置駆動譜は､通信路駆動譜と通信する為の一般層により使われる種々の操作を実装する函数へのポインタを含む Tcl_ChannelType 構造を提供する｡Tcl_ChannelType 構造とそれに参照される函数は下の TCL_CHANNELTYPE の節内に記述されている｡ 　　 Channel drivers consist of a number of components: First, each channel driver provides a Tcl_ChannelType structure containing pointers to functions implementing the various operations used by the generic layer to communicate with the channel driver. The Tcl_ChannelType structure and the functions referenced by it are described in the section TCL_CHANNELTYPE, below.

第２､通信路駆動譜は通常通信路の型の実存機能を作る為のTcl 命令を提供する｡譬えば､ Tcl open 命令はファイルと装置駆動命令に使われる命令を生成する､又､ Tcl socket 命令は電網通信の為の TCP 授受口を使う通信路を生成する｡ 　　 Second, channel drivers usually provide a Tcl command to create instances of that type of channel. For example, the Tcl open command creates channels that use the file and command channel drivers, and the Tcl socket command creates channels that use TCP sockets for network communication.

第３､通信路駆動譜は指示があればその型の通信路実在機能を開くための C 函数を提供する｡譬えば､ Tcl_OpenFileChannel はファイル通信路駆動譜を使う通信路を開く､又 Tcl_OpenTcpClient は TCP 電網通信規定を使う通信路を開く｡これ等の生成手続函数は典型的には通信路を開く為に､内部で Tcl_CreateChannel を使っている｡ 　　　 Third, a channel driver optionally provides a C function to open channel instances of that type. For example, Tcl_OpenFileChannel opens a channel that uses the file channel driver, and Tcl_OpenTcpClient opens a channel that uses the TCP network protocol. These creation functions typically use Tcl_CreateChannel internally to open the channel.

通信路に新しい型を追加する為には､Tcl_CreateChannelを起動することにより通信路を開く様な C API か Tcl 命令を実装しなければならない｡それにより､使用者が記述した駆動譜が Tcl_CreateChannel を呼ぶ時に､駆動譜の入出力手続函数を記述している構造が Tcl_ChannelType 内に渡される｡一般層は通信路上の操作を遂行する為にその構造内で参照されている手続函数を起動する｡ 　　　 To add a new type of channel you must implement a C API or a Tcl command that opens a channel by invoking Tcl_CreateChannel. When your driver calls Tcl_CreateChannel it passes in a Tcl_ChannelType structure describing the driver's I/O procedures. The generic layer will then invoke the functions referenced in that structure to perform operations on the channel.

Tcl_CreateChannel は新しい通信路を開き､それに与えられた typePtr と instanceData を結合する｡その通信路は mask によって指し示される様式で開かれる｡通信路駆動譜とその操作と Tcl_ChannelType 構造の論議については､下の TCL_CHANNELTYPE の節を参照されたい｡ Tcl_CreateChannel opens a new channel and associates the supplied typePtr and instanceData with it. The channel is opened in the mode indicated by mask. For a discussion of channel drivers, their operations and the Tcl_ChannelType structure, see the section TCL_CHANNELTYPE, below.

Tcl_CreateChannel は標準通信路を制御する命令譜と相互作用する｡標準通信路が､ Tcl_GetStdChannel の呼出しか Tcl_SetStdChannel の呼出しのどちらかを通して一度初期化されることによって､この通信路の閉鎖は次の Tcl_CreateChannel への呼出しが新しい通信路を新しい標準通信路にさせることを引起す｡標準通信路とそれを考慮した Tcl 外部函数の振舞いに就いての一般議論については Tcl_StandardChannels を参照されたい｡ Tcl_CreateChannel interacts with the code managing the standard channels. Once a standard channel was initialized either through a call to Tcl_GetStdChannel or a call to Tcl_SetStdChannel closing this standard channel will cause the next call to Tcl_CreateChannel to make the new channel the new standard channel too. See Tcl_StandardChannels for a general treatise about standard channels and the behavior of the Tcl library with regard to them.

Tcl_GetChannelInstanceData は channel 内の通信路に結合された実存機能データを返す｡これはこの通信路によって生成された Tcl_CreateChannel への呼出し内の instanceData 引数と同じである｡ Tcl_GetChannelInstanceData returns the instance data associated with the channel in channel. This is the same as the instanceData argument in the call to Tcl_CreateChannel that created this channel.

Tcl_GetChannelType は channel 引数内の通信路によって使われる Tcl_ChannelType 構造へのポインターを返す｡これはこの通信路によって生成された Tcl_CreateChannel への呼出し内の typePtr 引数と同じである｡ Tcl_GetChannelType returns a pointer to the Tcl_ChannelType structure used by the channel in the channel argument. This is the same as the typePtr argument in the call to Tcl_CreateChannel that created this channel.

Tcl_GetChannelName は通信路と結合している名前を含む文字列を返す､但し､ Tcl_CreateChannel への channelName 引数が NULL の場合は NULL を返す｡ Tcl_GetChannelName returns a string containing the name associated with the channel, or NULL if the channelName argument to Tcl_CreateChannel was NULL.

Tcl_GetChannelHandle は与えられた direction の為の channel に結合したOS-固有の装置処理子を handlePtr によって指定された位置内に置き､TCL_OK を返す｡もし通信路が指定した方向の装置処理子を有さない場合は代りに TCL_ERROR が返される｡異なる通信路駆動譜は処理子の異なる型を返す｡どの型の処理子が返されるかの決定に就いては､それぞれの駆動譜に関する取扱説明書の項目を参照されたい｡ Tcl_GetChannelHandle places the OS-specific device handle associated with channel for the given direction in the location specified by handlePtr and returns TCL_OK. If the channel does not have a device handle for the specified direction, then TCL_ERROR is returned instead. Different channel drivers will return different types of handle. Refer to the manual entries for each driver to determine what type of handle is returned.

Tcl_GetChannelThread は指定された channel を現在管理している時分割の識別子を返す｡これによりファイル行事を多重時分割核に就いての正しい行事待ち行列に送る事を通信路駆動譜に許容する｡ Tcl_GetChannelThread returns the id of the thread currently managing the specified channel. This allows channel drivers to send their file events to the correct event queue even for a multi-threaded core.

Tcl_GetChannelMode は通信路が入力用､或は出力用のいずれかに開かれるかを指し示す TCL_READABLE と TCL_WRITABLE の､倫理和､の組合せを返す｡ Tcl_GetChannelMode returns an OR-ed combination of TCL_READABLE and TCL_WRITABLE, indicating whether the channel is open for input and output.

Tcl_GetChannelBufferSize は channel 内に入力又は出力を保有する為に割付けられた緩衝域のバイト単位の寸法を返す｡下に記述した Tcl_SetChannelBufferSize の以前の呼出しによって値が設定されていない場合は無為設定値の 4096 が返される｡ Tcl_GetChannelBufferSize returns the size, in bytes, of buffers allocated to store input or output in channel. If the value was not set by a previous call to Tcl_SetChannelBufferSize, described below, then the default value of 4096 is returned.

Tcl_SetChannelBufferSize は入力又は出力通信路上で引続く操作内で割当てられた緩衝域のバイト単位の寸法を設定する｡ size 引数は十と百万の間であるべきで､それにより十から百万バイトの緩衝域を許容する｡もし size がこの範囲の外側であると､Tcl_SetChannelBufferSize は緩衝域寸法を 4096 に設定する｡ Tcl_SetChannelBufferSize sets the size, in bytes, of buffers that will be allocated in subsequent operations on the channel to store input or output. The size argument should be between one and one million, allowing buffers of one byte to one million bytes. If size is outside this range, Tcl_SetChannelBufferSize sets the buffer size to 4096.

Tcl_NotifyChannel は mask により指定され通信路上に生じた行事である一般層を指し示す為に通信路駆動譜に呼ばれる｡通信路駆動譜は､何時であれ通信路のために通信路処理子が呼ばれる (若しくは､緩衝域払出し記入の様な中断されている担当譜が遂行される)必要がある時に､この函数を起動する任務を担っている｡更なる詳細については下の WATCHPROC を参照されたい｡ Tcl_NotifyChannel is called by a channel driver to indicate to the generic layer that the events specified by mask have occurred on the channel. Channel drivers are responsible for invoking this function whenever the channel handlers need to be called for the channel (or other pending tasks like a write flush should be performed). See WATCHPROC below for more details.

Tcl_BadChannelOption は完全な不都合伝言文を生成する為に通信路駆動譜固有の setOptionProc か getOptionProc から呼ばれる｡ Tcl_BadChannelOption is called from driver specific setOptionProc or getOptionProc to generate a complete error message.

Tcl_ChannelBuffered は通信路自身の内部緩衝域内(押込み領域)に現在入力緩衝されたバイトの数を返す｡供給された通信路がその一部になっている通信路の棚の為の全体の緩衝域内のデータに関しては報告しない｡ Tcl_ChannelBuffered returns the number of bytes of input currently buffered in the internal buffer (push back area) of the channel itself. It does not report about the data in the overall buffers for the stack of channels the supplied channel is part of.

Tcl_IsChannelShared は指定された channel の参照数を確認し､ channel が複数の解釈実行機能の間で共有されている(結果== 1)か否(結果== 0)かを返す｡ Tcl_IsChannelShared checks the refcount of the specified channel and returns whether the channel was shared among multiple interpreters (result == 1) or not (result == 0).

Tcl_IsChannelRegistered は指定された channel が与えられた解釈実行機能内に登録されている(結果== 1)か否(結果== 0)かを確認する｡ Tcl_IsChannelRegistered checks whether the specified channel is registered in the given interpreter (result == 1) or not (result == 0).

Tcl_IsChannelExisting は指定された名前の通信路が全ての通信路の(時分割)-大域リスト内に登録されている(結果== 1)か否(結果== 0)かを確認する｡ Tcl_IsChannelExisting checks whether a channel with the specified name is registered in the (thread)-global list of all channels (result == 1) or not (result == 0).

Tcl_CutChannel は全ての(現在の時分割の)通信路の(時分割)大域リストから指定した channel を取去る｡幾つかの解釈実行機能内に登録された通信路への応用譜は許容されない｡又､もし Tcl_ChannelType の版が TCL_CHANNEL_VERSION_4 (又はそれ以上)で且つ､ Tcl_DriverThreadActionProc がその為に定義されている場合は､駆動譜に通知する｡ Tcl_CutChannel removes the specified channel from the (thread)global list of all channels (of the current thread). Application to a channel still registered in some interpreter is not allowed. Also notifies the driver if the Tcl_ChannelType version is TCL_CHANNEL_VERSION_4 (or higher), and Tcl_DriverThreadActionProc is defined for it.

Tcl_SpliceChannel は全ての(現在の時分割の)通信路の(時分割)大域リストに指定された channel を追加する｡どれかの解釈実行機能内に登録された通信路への応用譜は許容されない｡又､もし Tcl_ChannelType の版が TCL_CHANNEL_VERSION_4 (又はそれ以上)で且つ､ Tcl_DriverThreadActionProc がその為に定義されている場合は､駆動譜に通知する｡ Tcl_SpliceChannel adds the specified channel to the (thread)global list of all channels (of the current thread). Application to a channel registered in some interpreter is not allowed. Also notifies the driver if the Tcl_ChannelType version is TCL_CHANNEL_VERSION_4 (or higher), and Tcl_DriverThreadActionProc is defined for it.

Tcl_ClearChannelHandlers は全ての通信路処理子と､指定された channel に結合した行事記述譜とを取去る､そして､この通信路に関する全ての行事処理課程を遮断する｡ Tcl_ClearChannelHandlers removes all channel handlers and event scripts associated with the specified channel, thus shutting down all event processing for this channel.

### TCL_の通信路型 TCL_CHANNELTYPE

通信路駆動譜は通信路上の種々の操作を実装する函数へのポインターを含む Tcl_ChannelType 構造を提供する; これらの操作は共通の層による必要性により起動される｡その構造は棚に詰まれた通信路駆動譜による不具合を修繕する為に Tcl 8.3.2/8.4 内で開始する版番号を附けられた｡古い構造についての詳細については下の OLD CHANNEL TYPES を参照されたい｡ 　　　　 A channel driver provides a Tcl_ChannelType structure that contains pointers to functions that implement the various operations on a channel; these operations are invoked as needed by the generic layer. The structure was versioned starting in Tcl 8.3.2/8.4 to correct a problem with stacked channel drivers. See the OLD CHANNEL TYPES section below for details about the old structure.

Tcl_ChannelType 構造は次の欄を含む: 　　　 The Tcl_ChannelType structure contains the following fields:

    typedef struct Tcl_ChannelType {
            const char *typeName;
            Tcl_ChannelTypeVersion version;
            Tcl_DriverCloseProc *closeProc;
            Tcl_DriverInputProc *inputProc;
            Tcl_DriverOutputProc *outputProc;
            Tcl_DriverSeekProc *seekProc;
            Tcl_DriverSetOptionProc *setOptionProc;
            Tcl_DriverGetOptionProc *getOptionProc;
            Tcl_DriverWatchProc *watchProc;
            Tcl_DriverGetHandleProc *getHandleProc;
            Tcl_DriverClose2Proc *close2Proc;
            Tcl_DriverBlockModeProc *blockModeProc;
            Tcl_DriverFlushProc *flushProc;
            Tcl_DriverHandlerProc *handlerProc;
            Tcl_DriverWideSeekProc *wideSeekProc;
            Tcl_DriverThreadActionProc *threadActionProc;
            Tcl_DriverTruncateProc *truncateProc;
    } Tcl_ChannelType;

全ての通信路操作の為の実装を提供する必要があるわけではない｡NULL に設定される必要の無いものは構造内の: blockModeProc, seekProc, setOptionProc, getOptionProc, getHandleProc と close2Proc 更に加えて flushProc, handlerProc, threadActionProc と truncateProc である｡意味があるようには実装できない他の函数は､呼ばれた時に相当する操作が利用できないことを指し示す EINVAL を返すべきである｡又､註意すべきは､もし seekProc が存在する時は wideSeekProc は NULL であるかもしれない｡ 　　　　 It is not necessary to provide implementations for all channel operations. Those which are not necessary may be set to NULL in the struct: blockModeProc, seekProc, setOptionProc, getOptionProc, getHandleProc, and close2Proc, in addition to flushProc, handlerProc, threadActionProc, and truncateProc. Other functions that cannot be implemented in a meaningful way should return EINVAL when called, to indicate that the operations they represent are not available. Also note that wideSeekProc can be NULL if seekProc is.

Tcl_ChannelType の具体化の為にのみ上記構造を使うべきである｡Tcl_ChannelType 構造内の欄を参照する時は､値を得る為に次の函数を使うべきである: 　　　　 The user should only use the above structure for Tcl_ChannelType instantiation. When referencing fields in a Tcl_ChannelType structure, the following functions should be used to obtain the values: Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelThreadActionProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, or Tcl_ChannelHandlerProc.

構造への変更は標準通信路型が２進数と両立するような方法でなされた｡しかし､積上げた棚を使う通信路の型(即ち､TLS, Trf )は､積上げ棚の為の従来の命令譜は不都合を生じるので､上記変更に相当する新しい版を有する｡ 　　　　 The change to the structures was made in such a way that standard channel types are binary compatible. However, channel types that use stacked channels (i.e. TLS, Trf) have new versions to correspond to the above change since the previous code for stacked channels had problems.

#### 型名 TYPENAME

typeName の欄は駆動譜により実装された装置の型を識別する零終端文字列を含む､譬えば file や socket｡ 　　 The typeName field contains a null-terminated string that identifies the type of the device implemented by this driver, e.g. file or socket.

この値は文字列へのポインタを返す Tcl_ChannelName により取戻される｡ 　　　 This value can be retrieved with Tcl_ChannelName, which returns a pointer to the string.

#### 版 VERSION

version の欄には使用者が要求した構造の版が設定されるべきである｡TCL_CHANNEL_VERSION_2 が最低限に推奨される｡ TCL_CHANNEL_VERSION_3 では wideSeekProc の構成員を指定する必要がある｡TCL_CHANNEL_VERSION_4 では threadActionProc の構成員を指定する必要がある(wideSeekProc を含む)｡TCL_CHANNEL_VERSION_5 では truncateProc の構成員を指定する必要がある( wideSeekProc と threadActionProc を含む)｡これらのどれも設定されていない場合は､この Tcl_ChannelType は元の構造を有すると仮定される｡更なる詳細は OLD CHANNEL TYPES を参照されたい｡ Tcl とそれぞれの構造をもつ函数が認識されるとき､棚積みされた通信路は正しく機能する為には､少なくとも TCL_CHANNEL_VERSION_2 でなければならない｡ The version field should be set to the version of the structure that you require. TCL_CHANNEL_VERSION_2 is the minimum recommended. TCL_CHANNEL_VERSION_3 must be set to specify the wideSeekProc member. TCL_CHANNEL_VERSION_4 must be set to specify the threadActionProc member (includes wideSeekProc). TCL_CHANNEL_VERSION_5 must be set to specify the truncateProc members (includes wideSeekProc and threadActionProc). If it is not set to any of these, then this Tcl_ChannelType is assumed to have the original structure. See OLD CHANNEL TYPES for more details. While Tcl will recognize and function with either structures, stacked channels must be of at least TCL_CHANNEL_VERSION_2 to function correctly.

この値は Tcl_ChannelVersion によって取戻され､その値はTCL_CHANNEL_VERSION_5 か TCL_CHANNEL_VERSION_4 か TCL_CHANNEL_VERSION_3 か TCL_CHANNEL_VERSION_2 か TCL_CHANNEL_VERSION_1 の内のどれか一つである｡ 　　　 This value can be retrieved with Tcl_ChannelVersion, which returns one of TCL_CHANNEL_VERSION_5, TCL_CHANNEL_VERSION_4, TCL_CHANNEL_VERSION_3, TCL_CHANNEL_VERSION_2 or TCL_CHANNEL_VERSION_1.

#### BLOCKMODEPROC

The blockModeProc の欄は装置上に同期様式か非同期様式を設定する為に一般層に呼ばれた函数の番地を含む｡lockModeProc は次の原型と合致すべきである: 　　 The blockModeProc field contains the address of a function called by the generic layer to set blocking and nonblocking mode on the device. BlockModeProc should match the following prototype:

    typedef int Tcl_DriverBlockModeProc(
            ClientData instanceData,
            int mode);

instanceData はこの通信路が作成された時に Tcl_CreateChannel に渡された値と同じである｡装置を同期或は非同期様式に設定する為の mode 引数は TCL_MODE_BLOCKING か TCL_MODE_NONBLOCKING である｡その函数は操作が成功すると零を返し､操作が失敗すると非零の POSIX 不都合符号を返す｡ 　　　 The instanceData is the same as the value passed to Tcl_CreateChannel when this channel was created. The mode argument is either TCL_MODE_BLOCKING or TCL_MODE_NONBLOCKING to set the device into blocking or nonblocking mode. The function should return zero if the operation was successful, or a nonzero POSIX error code if the operation failed.

もし操作が成功すると､その函数はその通信路が同期様式又は非同期様式に入った事を記録し､同期又は非同期の挙動を実装する為に与えられた instanceData を修正することができる｡幾つかの装置の型の為に､同期又は非同期挙動は基礎のOS系により実装され得る; 他の装置型の為に挙動は通信路駆動譜内で模倣されなければならない｡ 　　　 If the operation is successful, the function can modify the supplied instanceData to record that the channel entered blocking or nonblocking mode and to implement the blocking or nonblocking behavior. For some device types, the blocking and nonblocking behavior can be implemented by the underlying operating system; for other device types, the behavior must be emulated in the channel driver.

この値は Tcl_ChannelBlockModeProc で取戻すことができ､それは函数にポインターを返す｡ 　　　 This value can be retrieved with Tcl_ChannelBlockModeProc, which returns a pointer to the function.

blockModeProc を供給しない通信路駆動譜は非常に非常に註意する必要がある｡それは一般層に､それは同期様式が受入れ可能であると､厳密に伝える必要があり､それは又､使用者にも説明して通信路の同期様式が受入れ不能の値に変化しないようにするべきである｡ここでの何かの混乱は解釈実行機能を(間違った､見つけ難い)暗礁に導くことになる｡ 　　　 A channel driver not supplying a blockModeProc has to be very, very careful. It has to tell the generic layer exactly which blocking mode is acceptable to it, and should this also document for the user so that the blocking mode of the channel is not changed to an unacceptable value. Any confusion here may lead the interpreter into a (spurious and difficult to find) deadlock.

#### CLOSEPROC AND CLOSE2PROC

closeProc 欄は通信路が閉じる時に､装置関連情報を消去する為に､一般層に呼ばれる函数の番地を含む｡ closeProc は次の原型に合致しなければならない: 　　 The closeProc field contains the address of a function called by the generic layer to clean up driver-related information when the channel is closed. CloseProc must match the following prototype:

    typedef int Tcl_DriverCloseProc(
            ClientData instanceData,
            Tcl_Interp *interp);

instanceData 引数は通信路が作成された時に Tcl_CreateChannel に提供すると同じ値である｡この函数はこの通信路の為に通信路駆動譜によって維持されているどの貯蔵も解放し､この通信路によってひと括りにされた入力と出力装置を閉じる｡全ての待ち行列の出力はこの函数が呼ばれる前に装置に払い出され､ closeProc を呼出した後のこの依頼による更なる装置の操作は起動されない｡閉鎖操作が成功した場合は､その手続函数は零を返し､それ以外の場合は非零 POSIX 不都合符号を返すことになる｡更に､もし不都合が生じ且つ､ interp が NULL ではない場合､手続函数は不都合伝言文を解釈実行機能の結果内に保存する｡ 　　　 The instanceData argument is the same as the value provided to Tcl_CreateChannel when the channel was created. The function should release any storage maintained by the channel driver for this channel, and close the input and output devices encapsulated by this channel. All queued output will have been flushed to the device before this function is called, and no further driver operations will be invoked on this instance after calling the closeProc. If the close operation is successful, the procedure should return zero; otherwise it should return a nonzero POSIX error code. In addition, if an error occurs and interp is not NULL, the procedure should store an error message in the interpreter's result.

別法として､独立に読みと書き側の閉鎖を運営する通信路は closeProc を TCL_CLOSE2PROC に設定しても好い､又､次の原型に合致する函数の番地に close2Proc を設定する: 　　　 Alternatively, channels that support closing the read and write sides independently may set closeProc to TCL_CLOSE2PROC and set close2Proc to the address of a function that matches the following prototype:

    typedef int Tcl_DriverClose2Proc(
            ClientData instanceData,
            Tcl_Interp *interp,
            int flags);

close2Proc は駆動譜が読み 又は/及び 書き側の通信路を閉じることを指し示す為に､ TCL_CLOSE_READ や TCL_CLOSE_WRITE の論理和の組合せの flags の組合せを伴って呼ばれる｡通信路駆動譜は一つ或は両方の通信路を閉じる為に close2Proc が呼ばれた後に通信路に追加的な操作を遂行するために起動されるかもしれない｡もし flags が 0 (零)であると､その駆動譜は上記の closeProc の為に記述された方法により通信路が閉じられる｡全ての旗印が解消を伴う close2Proc の呼出しの後はこの依頼による更なる操作は起動されない｡全ての場合に､この close2Proc 函数は閉鎖操作が成功する場合には零を返し; そうでない場合は非零 POSIX 不都合符号を返すことになる｡更に､もし不都合が生じ､且つ interp が NULL でない場合､手続函数は不都合伝言文を解釈実行機能の結果内に保存する｡ 　　　 The close2Proc will be called with flags set to an OR'ed combination of TCL_CLOSE_READ or TCL_CLOSE_WRITE to indicate that the driver should close the read and/or write side of the channel. The channel driver may be invoked to perform additional operations on the channel after close2Proc is called to close one or both sides of the channel. If flags is 0 (zero), the driver should close the channel in the manner described above for closeProc. No further operations will be invoked on this instance after close2Proc is called with all flags cleared. In all cases, the close2Proc function should return zero if the close operation was successful; otherwise it should return a nonzero POSIX error code. In addition, if an error occurs and interp is not NULL, the procedure should store an error message in the interpreter's result.

closeProc と close2Proc の値は Tcl_ChannelCloseProc や Tcl_ChannelClose2Proc で取戻す事ができ､それはそれぞれの函数にポインターを返す｡ 　　　 The closeProc and close2Proc values can be retrieved with Tcl_ChannelCloseProc or Tcl_ChannelClose2Proc, which return a pointer to the respective function.

#### INPUTPROC

inputProc 欄は､ファイルや装置からデータを読んで内部緩衝域に保存する為に一般層から呼ばれる函数の番地を含む｡inputProc は次の原型と合致しなければならない: 　　　 The inputProc field contains the address of a function called by the generic layer to read data from the file or device and store it in an internal buffer. InputProc must match the following prototype:

    typedef int Tcl_DriverInputProc(
            ClientData instanceData,
            char *buf,
            int bufSize,
            int *errorCodePtr);

instanceData は､通信路が作成された時に､ Tcl_CreateChannel に渡された値と同じである｡その buf 引数は装置からの入力を保存するバイトの配列を指し､その bufSize 引数は buf の箇所で如何に多くのバイトが利用できるかを指し示す｡ InstanceData is the same as the value passed to Tcl_CreateChannel when the channel was created. The buf argument points to an array of bytes in which to store input from the device, and the bufSize argument indicates how many bytes are available at buf.

errorCodePtr は一般層によって提供された整数変数を指している｡もし不都合が生じるとその函数は変数に生じた不都合を識別する POSIX 不都合符号を設定する｡ 　　　 The errorCodePtr argument points to an integer variable provided by the generic layer. If an error occurs, the function should set the variable to a POSIX error code that identifies the error that occurred.

その函数は通信路によってひと括りにされた装置からデータを読み buf に保存する｡成功すると､函数は入力装置から何バイト読み buf の箇所に保存するかを指し示す非負整数を返す筈である｡不都合であると､函数は-1.を返すであろう｡装置から幾らかのデータを読んだ後に不都合が生じると､そのデータは喪失される｡ 　　　 The function should read data from the input device encapsulated by the channel and store it at buf. On success, the function should return a nonnegative integer indicating how many bytes were read from the input device and stored at buf. On error, the function should return -1. If an error occurs after some data has been read from the device, that data is lost.

もし inputProc が入力装置は幾らかのデータが利用できるが bufSize 引数にる要求よりも少ないことが確定する場合､函数は利用できる限りのデータのみを読込み同期せずに戻ることを試みる｡もし入力装置が利用可能なデータを有さず､通信路が非同期様式である場合､函数は EAGAIN 不都合を返す｡もし入力装置が利用可能なデータを有さず､通信路が同期様式である場合､函数は少なくとも装置から１バイトのデータが読み得る迄同期する; 次に､同期なしに可能な限り多くのデータを返すことになる｡ 　　　 If inputProc can determine that the input device has some data available but less than requested by the bufSize argument, the function should only attempt to read as much data as is available and return without blocking. If the input device has no data available whatsoever and the channel is in nonblocking mode, the function should return an EAGAIN error. If the input device has no data available whatsoever and the channel is in blocking mode, the function should block for the shortest possible time until at least one byte of data can be read from the device; then, it should return as much data as it can read without blocking.

この値はポインターを函数に返す Tcl_ChannelInputProc によって取戻し得る｡ 　　　 This value can be retrieved with Tcl_ChannelInputProc, which returns a pointer to the function.

#### OUTPUTPROC

outputProc 欄はデータを内部緩衝域から出力装置に移動する為に一般層から呼ばれる函数の番地を含む｡outputProc は次の原型と合致する必要がある: 　　　 The outputProc field contains the address of a function called by the generic layer to transfer data from an internal buffer to the output device. OutputProc must match the following prototype:

    typedef int Tcl_DriverOutputProc(
            ClientData instanceData,
            const char *buf,
            int toWrite,
            int *errorCodePtr);

instanceData は､通信路が作成された時に､ Tcl_CreateChannel に渡された値と同じである｡buf 引数は装置に書かれるバイトの配列を含み､toWrite 引数は buf 引数から何バイト書かれるかを指し示す｡ InstanceData is the same as the value passed to Tcl_CreateChannel when the channel was created. The buf argument contains an array of bytes to be written to the device, and the toWrite argument indicates how many bytes are to be written from the buf argument.

errorCodePtr は一般層によって提供された整数変数を指している｡もし不都合が生じるとその函数は変数に生じた不都合を識別する POSIX 不都合符号を設定する｡ 　　　 The errorCodePtr argument points to an integer variable provided by the generic layer. If an error occurs, the function should set this variable to a POSIX error code that identifies the error.

その函数は通信路によってひと括りにされた出力装置に buf の箇所のデータを書込むであろう｡成功すると､その函数はその出力装置に何バイト書かれたかを指し示す非負整数を返すであろう｡返り値は通常 toWrite と同じであるが､譬えば出力操作が信号により中断したような場合はそれより少ないかもしれない｡もし不都合が生じると函数は -1を返すであろう｡不都合が生じた場合､幾らかのデータが装置に書込まれたかもしれない｡ 　　　 The function should write the data at buf to the output device encapsulated by the channel. On success, the function should return a nonnegative integer indicating how many bytes were written to the output device. The return value is normally the same as toWrite, but may be less in some cases such as if the output operation is interrupted by a signal. If an error occurs the function should return -1. In case of error, some data may have been written to the device.

もし通信路が非同期であって出力装置が全く何のデータも吸収できない場合､函数は何のデータを書込むことなく EAGAIN 不都合と共に -1 を返すであろう｡ 　　 If the channel is nonblocking and the output device is unable to absorb any data whatsoever, the function should return -1 with an EAGAIN error without writing any data.

この値はポインターを函数に返す Tcl_ChannelOutputProc によって取戻し得る｡ This value can be retrieved with Tcl_ChannelOutputProc, which returns a pointer to the function.

#### SEEKPROC AND WIDESEEKPROC

seekProc 欄はその位置に引続く入力や出力操作が適用される箇所に利用位置を移す為に一般層から呼ばれる函数の番地を含む｡SeekProc は次の原型と合致する必要がある: 　　　 The seekProc field contains the address of a function called by the generic layer to move the access point at which subsequent input or output operations will be applied. SeekProc must match the following prototype:

    typedef int Tcl_DriverSeekProc(
            ClientData instanceData,
            long offset,
            int seekMode,
            int *errorCodePtr);

instanceData 引数は通信路が作成された時にに与えられた Tcl_CreateChannel 値と同じである｡ offset と seekMode は Tcl_Seek 手続函数の為のものと同じ意味を有する｡( Tcl_OpenFileChannel に関する取扱説明書内に記載されている) 　　　　 The instanceData argument is the same as the value given to Tcl_CreateChannel when this channel was created. Offset and seekMode have the same meaning as for the Tcl_Seek procedure (described in the manual entry for Tcl_OpenFileChannel).

errorCodePtr は函数から返される errno 値の為に一般層によって提供された整数変数を指している｡函数は不都合が生じた場合この変数を POSIX 不都合符号に設定するであろう｡もし通信路の型が捜索を実装していない場合函数は EINVAL 不都合符号を保存するであろう｡ 　　　 The errorCodePtr argument points to an integer variable provided by the generic layer for returning errno values from the function. The function should set this variable to a POSIX error code if an error occurs. The function should store an EINVAL error code if the channel type does not implement seeking.

返り値は新しい利用位置である､但し不都合の場合は -1 である｡もし不都合が生じると､その函数は利用位置を移動しないであろう｡ 　　　 The return value is the new access point or -1 in case of error. If an error occurred, the function should not move the access point.

もし非-NULL seekProc 欄が存在する場合､ wideSeekProc 欄は2GB.より大きいファイルの捜索を許容する為に広幅の位置(即ち32-bit を超える)を扱う代用函数の番地を含むかもしれない｡ wideSeekProc は seekProc に優先して呼ばれるが､ wideSeekProc が定義されている場合は両方が定義されなければならない｡wideSeekProc は次の原型に合致しなければならない: 　　　　 If there is a non-NULL seekProc field, the wideSeekProc field may contain the address of an alternative function to use which handles wide (i.e. larger than 32-bit) offsets, so allowing seeks within files larger than 2GB. The wideSeekProc will be called in preference to the seekProc, but both must be defined if the wideSeekProc is defined. WideSeekProc must match the following prototype:

    typedef Tcl_WideInt Tcl_DriverWideSeekProc(
            ClientData instanceData,
            Tcl_WideInt offset,
            int seekMode,
            int *errorCodePtr);

型の偏寄位置と返り型が異なっている場合を除いて､引数と結果の値は､上記の seekProc と同じことを意味する｡ 　　　 The arguments and return values mean the same thing as with seekProc above, except that the type of offsets and the return type are different.

seekProc 値はポインターを函数に返し､ Tcl_ChannelSeekProc によって取戻し得る､同時に wideSeekProc は Tcl_ChannelWideSeekProc によって取戻し得る｡ 　　　 The seekProc value can be retrieved with Tcl_ChannelSeekProc, which returns a pointer to the function, and similarly the wideSeekProc can be retrieved with Tcl_ChannelWideSeekProc.

#### SETOPTIONPROC

setOptionProc 欄は通信路上に通信路型固有の選択肢を設定する為に一般層から呼ばれる函数の番地を含む｡setOptionProc は次の原型と合致する必要がある: 　　　 The setOptionProc field contains the address of a function called by the generic layer to set a channel type specific option on a channel. setOptionProc must match the following prototype:

    typedef int Tcl_DriverSetOptionProc(
            ClientData instanceData,
            Tcl_Interp *interp,
            const char *optionName,
            const char *newValue);

optionName は設定すべき選択肢の名前であり､newValue は文字列としてのその選択肢の為の新しい値である｡instanceData は通信路が作成された時にに与えられた Tcl_CreateChannel 値と同じである｡函数は､何であれ､選択肢の新しい値を実装することが要求されている通信路型固有の活動を行う｡ optionName is the name of an option to set, and newValue is the new value for that option, as a string. The instanceData is the same as the value given to Tcl_CreateChannel when this channel was created. The function should do whatever channel type specific action is required to implement the new value of the option.

ある選択肢は一般命令譜によって処理され､この函数は譬えば -blockmode の様に､それを設定する為に呼ばれるのではない｡他の選択肢はそれぞれの通信路の型に固有であり､通信路駆動譜の setOptionProc 手続函数はそれらを実装する為に呼出される｡ setOptionProc 欄は NULL であるかも知れず､その場合､この通信路型は型固有の選択肢を運営していないことを指し示す｡ 　　　 Some options are handled by the generic code and this function is never called to set them, e.g. -blockmode. Other options are specific to each channel type and the setOptionProc procedure of the channel driver will get called to implement them. The setOptionProc field can be NULL, which indicates that this channel type supports no type specific options.

もし選択肢の値が成功裡に新しい値に修正された場合､その函数は TCL_OK を返す｡それは､ Tcl_BadChannelOption を呼んでもよく､それは optionName が認識できない場合､それ自身が TCL_ERROR を返す｡もし newValue が運用されていない選択肢の為の値を指定した場合､または体系呼出し不都合が生じた場合､この函数は､ interp が NULL でない時には不都合伝言文を interp の結果の中に残す｡この函数は又適切な POSIX 不都合符号を保存する為に Tcl_SetErrno を呼んでもよい｡ 　 If the option value is successfully modified to the new value, the function returns TCL_OK. It should call Tcl_BadChannelOption which itself returns TCL_ERROR if the optionName is unrecognized. If newValue specifies a value for the option that is not supported or if a system call error occurs, the function should leave an error message in the result of interp if interp is not NULL. The function should also call Tcl_SetErrno to store an appropriate POSIX error code.

この値はポインターを函数に返す Tcl_ChannelSetOptionProc によって取戻し得る｡ 　　　 This value can be retrieved with Tcl_ChannelSetOptionProc, which returns a pointer to the function.

#### GETOPTIONPROC

getOptionProc 欄は通信路上の通信路型固有の値を得る為に一般層から呼ばれる函数の番地を含む｡getOptionProc は次の原型と合致する必要がある: 　　　 The getOptionProc field contains the address of a function called by the generic layer to get the value of a channel type specific option on a channel. getOptionProc must match the following prototype:

    typedef int Tcl_DriverGetOptionProc(
            ClientData instanceData,
            Tcl_Interp *interp,
            const char *optionName,
            Tcl_DString *optionValue);

optionName はこの通信路の型に運営されている選択肢の名前である｡もし､選択肢の名前が NULL でない場合､この函数は､ Tcl 動的文字列 optionValue 内に文字列として現在の値を保存する｡もし optionName が NULL の場合､この函数は optionValue 内に代わりに運営している選択肢のリストとその現在値を保存する｡成功すると､この函数は TCL_OK を返す｡ Tcl_BadChannelOption を呼んでもよく､それは optionName が認識できない場合自身に TCL_ERROR を返す｡もし､系呼び出し不都合が生じると､この函数は､ interp が NULL.でない時には不都合伝言文を interp の結果欄に残す｡この函数は又適切な POSIX 不都合符号を保存する為に Tcl_SetErrno を呼ぶかもしれない｡ OptionName is the name of an option supported by this type of channel. If the option name is not NULL, the function stores its current value, as a string, in the Tcl dynamic string optionValue. If optionName is NULL, the function stores in optionValue an alternating list of all supported options and their current values. On success, the function returns TCL_OK. It should call Tcl_BadChannelOption which itself returns TCL_ERROR if the optionName is unrecognized. If a system call error occurs, the function should leave an error message in the result of interp if interp is not NULL. The function should also call Tcl_SetErrno to store an appropriate POSIX error code.

幾つかの指示項目は一般命令譜によって処理され､この函数は譬えば -blockmode の様に､それを設定する為に呼ばれるのではない｡他の指示項目はそれぞれの通信路の型に固有であり､通信路駆動譜の getOptionProc 手続函数はそれらを実装する為に呼出される｡ getOptionProc 欄は NULL であるかも知れず､その場合､この通信路型は型固有の指示項目を運営していないことを指し示す｡ 　　　 Some options are handled by the generic code and this function is never called to retrieve their value, e.g. -blockmode. Other options are specific to each channel type and the getOptionProc procedure of the channel driver will get called to implement them. The getOptionProc field can be NULL, which indicates that this channel type supports no type specific options.

この値はポインターを函数に返す Tcl_ChannelGetOptionProc によって取戻し得る｡ 　　　 This value can be retrieved with Tcl_ChannelGetOptionProc, which returns a pointer to the function.

#### WATCHPROC

watchProc 欄はこの通信路上に注目される行事を通知する為の行事通知仕組みを初期化する為に一般層に呼ばれる函数の番地を含む｡watchProc は次の原型に合致しなければならない: 　　　 The watchProc field contains the address of a function called by the generic layer to initialize the event notification mechanism to notice events of interest on this channel. WatchProc should match the following prototype:

    typedef void Tcl_DriverWatchProc(
            ClientData instanceData,
            int mask);

この instanceData はこの通信路が作成された時 Tcl_CreateChannel に渡された値と同じである｡ mask 引数は､TCL_READABLE と TCL_WRITABLE と TCL_EXCEPTION の論理和の結合である; この通信路上で､呼出し者が伝達することを注目している行事を指し示す｡ 　　　 The instanceData is the same as the value passed to Tcl_CreateChannel when this channel was created. The mask argument is an OR-ed combination of TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION; it indicates events the caller is interested in noticing on this channel.

この函数は通信路上に注目している行事が存在する時に通知する為の装置型固有の仕組みを初期化するであろう｡通信路上に一つ或はそれ以上の指定された行事が起った時､その通信路駆動譜は一般通信路部分機能に通知する為に Tcl_NotifyChannel を呼び出すことを担当する｡その駆動譜は Tcl_NotifyChannel を過度に頻繁に起動することにより他の通信路駆動譜や回収の原資に欠乏を感じさせない様註意しなくてはならない｡通信路行事が他の行事の順番に組込まれることを許容する為に Tcl 行事待ち行列を使用することにより公正さを保障できる｡行事を待ち行列に如何に組み入れるかの詳細は Tcl_QueueEvent の記述を参照されたい｡ 　　　 The function should initialize device type specific mechanisms to notice when an event of interest is present on the channel. When one or more of the designated events occurs on the channel, the channel driver is responsible for calling Tcl_NotifyChannel to inform the generic channel module. The driver should take care not to starve other channel drivers or sources of callbacks by invoking Tcl_NotifyChannel too frequently. Fairness can be insured by using the Tcl event queue to allow the channel event to be scheduled in sequence with other events. See the description of Tcl_QueueEvent for details on how to queue an event.

この値はポインターをその函数に返す Tcl_ChannelWatchProc によって取戻し得る｡ 　　　 This value can be retrieved with Tcl_ChannelWatchProc, which returns a pointer to the function.

#### GETHANDLEPROC

getHandleProc 欄はこの通信路から装置固有の処理機能を取戻す為に一般層に呼ばれる函数の番地を含む｡getHandleProc は次の原型に合致しなければならない: 　　　 The getHandleProc field contains the address of a function called by the generic layer to retrieve a device-specific handle from the channel. GetHandleProc should match the following prototype:

    typedef int Tcl_DriverGetHandleProc(
            ClientData instanceData,
            int direction,
            ClientData *handlePtr);

InstanceData はこの通信路が作成された時 Tcl_CreateChannel に渡された値と同じである｡その direction 引数はその入力に使われる処理機能を取戻す為の TCL_READABLE 或は､その出力に使われる処理機能を取戻す為の TCL_WRITABLE のいずれである｡ InstanceData is the same as the value passed to Tcl_CreateChannel when this channel was created. The direction argument is either TCL_READABLE to retrieve the handle used for input, or TCL_WRITABLE to retrieve the handle used for output.

もし､通信路実装が装置固有の処理機能を有する場合､この函数は direction 引数に従って､通信路に結合した適切な処理機能を取戻すべきである｡その処理機能は handlePtr によって参照される位置に保存されるであろう､又 TCL_OK が返されるであろう｡もし､通信路が指定された方向に開かれていない場合､又はもし通信路実装が装置処理機能を使わない場合この函数は TCL_ERROR を返すことになる｡ 　　　 If the channel implementation has device-specific handles, the function should retrieve the appropriate handle associated with the channel, according the direction argument. The handle should be stored in the location referred to by handlePtr, and TCL_OK should be returned. If the channel is not open for the specified direction, or if the channel implementation does not use device handles, the function should return TCL_ERROR.

この値はポインターをその函数に返す Tcl_ChannelGetHandleProc によって取戻し得る｡ This value can be retrieved with Tcl_ChannelGetHandleProc, which returns a pointer to the function.

#### FLUSHPROC

この flushProc 欄は現在は将来の使用の為に予約されている｡これは NULL を設定すべきである｡ flushProc は次の原型に合致しなければならない: 　　　 The flushProc field is currently reserved for future use. It should be set to NULL. FlushProc should match the following prototype:

    typedef int Tcl_DriverFlushProc(
            ClientData instanceData);

この値はポインターをその函数に返す Tcl_ChannelFlushProc によって取戻し得る｡ 　　　 This value can be retrieved with Tcl_ChannelFlushProc, which returns a pointer to the function.

#### HANDLERPROC

この handlerProc 欄は行事が生じた通信路を通知する為に一般層に呼ばれる函数の番地を含む｡基礎の(棚積みされた)通信路上に生じる行事の通知を希望する棚積みされた通信路駆動譜の為に､定義されるべきである｡handlerProc は次の原型に合致しなければならない: 　　　　 The handlerProc field contains the address of a function called by the generic layer to notify the channel that an event occurred. It should be defined for stacked channel drivers that wish to be notified of events that occur on the underlying (stacked) channel. HandlerProc should match the following prototype:

    typedef int Tcl_DriverHandlerProc(
            ClientData instanceData,
            int interestMask);

InstanceData はこの通信路が作成された時 Tcl_CreateChannel に渡された値と同じである｡その interestMask は､TCL_READABLE と TCL_WRITABLE の論理的和､の結合である; この通信路上で､どの型の行事が生じるかを指し示す｡ InstanceData is the same as the value passed to Tcl_CreateChannel when this channel was created. The interestMask is an OR-ed combination of TCL_READABLE or TCL_WRITABLE; it indicates what type of event occurred on this channel.

この値はポインターをその函数に返す Tcl_ChannelHandlerProc によって取戻し得る｡ 　　　 This value can be retrieved with Tcl_ChannelHandlerProc, which returns a pointer to the function.

#### THREADACTIONPROC

この threadActionProc 欄は通信路が生成､閉鎖､異なる時分割への移動が生じたとき､即ち､何時であれ､時分割固有の駆動譜状態が初期化又は更新された時に､一般層に呼ばれる函数の番地を含む｡それは NULL であってもよい｡ TCL_CHANNEL_THREAD_REMOVE の活動は､通信路の為に維持されているであろう時分割固有のどのようなデータであれ更新か除去をすべきことを駆動譜に通知する為に使われる｡ 　　　　 The threadActionProc field contains the address of the function called by the generic layer when a channel is created, closed, or going to move to a different thread, i.e. whenever thread-specific driver state might have to initialized or updated. It can be NULL. The action TCL_CHANNEL_THREAD_REMOVE is used to notify the driver that it should update or remove any thread-specific data it might be maintaining for the channel.

TCL_CHANNEL_THREAD_INSERT の活動は､相棒として時分割の呼出しに使う為に維持されているであろう時分割固有のどのようなデータであれ更新か初期化をすべきことを駆動譜に通知する為に使われる｡更なる詳細は Tcl_CutChannel と Tcl_SpliceChannel を参照されたい｡ 　　　 The action TCL_CHANNEL_THREAD_INSERT is used to notify the driver that it should update or initialize any thread-specific data it might be maintaining using the calling thread as the associate. See Tcl_CutChannel and Tcl_SpliceChannel for more detail.

    typedef void Tcl_DriverThreadActionProc(
            ClientData instanceData,
            int action);

InstanceData はこの通信路が作成された時 Tcl_CreateChannel に渡された値と同じである｡ InstanceData is the same as the value passed to Tcl_CreateChannel when this channel was created.

この値はポインターをその函数に返す Tcl_ChannelThreadActionProc によって取戻し得る｡ 　　　 These values can be retrieved with Tcl_ChannelThreadActionProc, which returns a pointer to the function.

#### TRUNCATEPROC

truncateProc 欄は､通信路がある長さに切詰められる時､一般的な層によって呼出される函数の番地を含む｡ NULL でも構わない｡ 　　　 The truncateProc field contains the address of the function called by the generic layer when a channel is truncated to some length. It can be NULL.

    typedef int Tcl_DriverTruncateProc(
            ClientData instanceData,
            Tcl_WideInt length);

InstanceData は､通信路が作成された時､ Tcl_CreateChannel に渡された値と同じであり､ length は基礎になるファイルの新しい長さである､それは非負である｡成功した時の結果は 0 ､失敗の時は不都合符号番号である( Tcl_SetErrno と一緒の使用に適す)｡ InstanceData is the same as the value passed to Tcl_CreateChannel when this channel was created, and length is the new length of the underlying file, which should not be negative. The result should be 0 on success or an errno code (suitable for use with Tcl_SetErrno) on failure.

この値はポインターをその函数に返す Tcl_ChannelTruncateProc によって取戻し得る｡ 　　　 These values can be retrieved with Tcl_ChannelTruncateProc, which returns a pointer to the function.

### TCL_BADCHANNELOPTION

この手続函数は不都合伝言文 ““bad”option[不適な追加指定]” を(指示項目の)解釈実行機能内に作成する｡ それは､不適切な 設定/取得 指示項目が要求された時に通信路駆動譜によって使われる｡ その目的は一般指示項目リストを固有なものに追加連結し､一般指示項目不都合文字列を要素分解することである｡ 　　　 This procedure generates a “bad option” error message in an (optional) interpreter. It is used by channel drivers when an invalid Set/Get option is requested. Its purpose is to concatenate the generic options list to the specific ones and factorize the generic options error message string.

それは常に TCL_ERROR を返す 　　　 It always returns TCL_ERROR

不都合伝言文は､命令が不都合な追加指定により起動されていることを指し示す為に interp の結果の値内に作成される｡伝言文は次の形式を有する 　　　 An error message is generated in interp's result value to indicate that a command was invoked with a bad option. The message has the form

    bad option "blah": should be one of
        <...generic options...>+<...specific options...>

そこで得られのは､譬えば: 　　 so you get for instance:

    bad option "-blah": should be one of -blocking,
        -buffering, -buffersize, -eofchar, -translation,
        -peername, or -sockname

““peername”sockname” に等価な optionList と共に呼ばれた時には　　　　 when called with optionList equal to “peername sockname”

“blah” は optionName 引数であり ““<固有の指定項目>”” は固有の追加指定語が空白で区切られたリストである｡ この函数はそれぞれの指定項目の前への負の符号と､後へのコンマと､最後の指定項目の前への “or” の､挿入には充分に註意を払っている｡ “blah” is the optionName argument and “<specific options>” is a space separated list of specific option words. The function takes good care of inserting minus signs before each option, commas after, and an “or” before the last option.

### OLD CHANNEL TYPES

元の(8.3.1版以前) Tcl_ChannelType 構造は次の欄を含む: 　　　 The original (8.3.1 and below) Tcl_ChannelType structure contains the following fields:

    typedef struct Tcl_ChannelType {
        const char *typeName;
        Tcl_DriverBlockModeProc *blockModeProc;
        Tcl_DriverCloseProc *closeProc;
        Tcl_DriverInputProc *inputProc;
        Tcl_DriverOutputProc *outputProc;
        Tcl_DriverSeekProc *seekProc;
        Tcl_DriverSetOptionProc *setOptionProc;
        Tcl_DriverGetOptionProc *getOptionProc;
        Tcl_DriverWatchProc *watchProc;
        Tcl_DriverGetHandleProc *getHandleProc;
        Tcl_DriverClose2Proc *close2Proc;
    } Tcl_ChannelType;

依然として上記構造で通信路を作成する事はありうる｡その内部通信路符号は版を決定する｡もしも棚に詰込む通信路駆動譜を作ろうとしているなら､初期の棚に詰込む通信路の実装の不都合( 8.2.0 から 8.3.1 版内)の故に､新しい Tcl_ChannelType を使うことが強制される｡ 　　　 It is still possible to create channel with the above structure. The internal channel code will determine the version. It is imperative to use the new Tcl_ChannelType structure if you are creating a stacked channel driver, due to problems with the earlier stacked channel implementation (in 8.2.0 to 8.3.1).

8.4.0 より以前の(即ち 後期の8.3 版と初期の 8.4 版開発時期) Tcl_ChannelType 構造は次の欄を含む:　 　　 Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part of the 8.4 development cycle) the Tcl_ChannelType structure contained the following fields:

    typedef struct Tcl_ChannelType {
        const char *typeName;
        Tcl_ChannelTypeVersion version;
        Tcl_DriverCloseProc *closeProc;
        Tcl_DriverInputProc *inputProc;
        Tcl_DriverOutputProc *outputProc;
        Tcl_DriverSeekProc *seekProc;
        Tcl_DriverSetOptionProc *setOptionProc;
        Tcl_DriverGetOptionProc *getOptionProc;
        Tcl_DriverWatchProc *watchProc;
        Tcl_DriverGetHandleProc *getHandleProc;
        Tcl_DriverClose2Proc *close2Proc;
        Tcl_DriverBlockModeProc *blockModeProc;
        Tcl_DriverFlushProc *flushProc;
        Tcl_DriverHandlerProc *handlerProc;
        Tcl_DriverTruncateProc *truncateProc;
    } Tcl_ChannelType;

上記構造が通信路型として登録されるとき､ version 欄は常に TCL_CHANNEL_VERSION_2 であるべきである｡ When the above structure is registered as a channel type, the version field should always be TCL_CHANNEL_VERSION_2.

### SEE ALSO

Tcl_Close, Tcl_OpenFileChannel, Tcl_SetErrno, Tcl_QueueEvent, Tcl_StackChannel, Tcl_GetStdChannel

### KEYWORDS

blocking, channel driver, channel registration, channel type, nonblocking
Copyright © 1996-1997 Sun Microsystems, Inc.
Copyright © 1997-2000 Ajuba Solutions.