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

### 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_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_CloseEx, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_TruncateChannel, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw — 通信路を使用する緩衝域使用入出力便益 buffered I/O facilities using channels
  SYNOPSIS
    #include <tcl.h>
    Tcl_Channel
    Tcl_OpenFileChannel(interp, fileName, mode, permissions)
    Tcl_Channel
    Tcl_OpenCommandChannel(interp, argc, argv, flags)
    Tcl_Channel
    Tcl_MakeFileChannel(handle, readOrWrite)
    Tcl_Channel
    Tcl_GetChannel(interp, channelName, modePtr)
    int
    Tcl_GetChannelNames(interp)
    int
    Tcl_GetChannelNamesEx(interp, pattern)
    void
    Tcl_RegisterChannel(interp, channel)
    int
    Tcl_UnregisterChannel(interp, channel)
    int
    Tcl_DetachChannel(interp, channel)
    int
    Tcl_IsStandardChannel(channel)
    int
    Tcl_Close(interp, channel)
    int
    Tcl_CloseEx(interp, channel, closeFlags)
    int
    Tcl_ReadChars(channel, readObjPtr, charsToRead, appendFlag)
    int
    Tcl_Read(channel, readBuf, bytesToRead)
    int
    Tcl_GetsObj(channel, lineObjPtr)
    int
    Tcl_Gets(channel, lineRead)
    int
    Tcl_Ungets(channel, input, inputLen, addAtEnd)
    int
    Tcl_WriteObj(channel, writeObjPtr)
    int
    Tcl_WriteChars(channel, charBuf, bytesToWrite)
    int
    Tcl_Write(channel, byteBuf, bytesToWrite)
    int
    Tcl_ReadRaw(channel, readBuf, bytesToRead)
    int
    Tcl_WriteRaw(channel, byteBuf, bytesToWrite)
    int
    Tcl_Eof(channel)
    int
    Tcl_Flush(channel)
    int
    Tcl_InputBlocked(channel)
    int
    Tcl_InputBuffered(channel)
    int
    Tcl_OutputBuffered(channel)
    Tcl_WideInt
    Tcl_Seek(channel, offset, seekMode)
    Tcl_WideInt
    Tcl_Tell(channel)
    int
    Tcl_TruncateChannel(channel, length)
    int
    Tcl_GetChannelOption(interp, channel, optionName, optionValue)
    int
    Tcl_SetChannelOption(interp, channel, optionName, newValue)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    const char *fileName (入力in)
    const char *mode (入力in)
    int permissions (入力in)
    int argc (入力in)
    const char **argv (入力in)
    int flags (入力in)
    ClientData handle (入力in)
    int readOrWrite (入力in)
    const char *channelName (入力in)
    int *modePtr (出力out)
    const char *pattern (入力in)
    Tcl_Channel channel (入力in)
    Tcl_Obj *readObjPtr (入出力in/out)
    int charsToRead (入力in)
    int closeFlags (入力in)
    int appendFlag (入力in)
    char *readBuf (out)
    int bytesToRead (入力in)
    Tcl_Obj *lineObjPtr (入出力in/out)
    Tcl_DString *lineRead (入出力in/out)
    const char *input (入力in)
    int inputLen (入力in)
    int addAtEnd (入力in)
    Tcl_Obj *writeObjPtr (入力in)
    const char *charBuf (入力in)
    const char *byteBuf (入力in)
    int bytesToWrite (入力in)
    Tcl_WideInt offset (入力in)
    int seekMode (入力in)
    Tcl_WideInt length (入力in)
    const char *optionName (入力in)
    Tcl_DString *optionValue (入力in)
    const char *newValue (入力in)
  DESCRIPTION
  TCL_OPENFILECHANNEL
  TCL_OPENCOMMANDCHANNEL
  TCL_MAKEFILECHANNEL
  TCL_GETCHANNEL
  TCL_REGISTERCHANNEL
  TCL_UNREGISTERCHANNEL
  TCL_DETACHCHANNEL
  TCL_ISSTANDARDCHANNEL
  TCL_CLOSE AND TCL_CLOSEEX
  TCL_READCHARS AND TCL_READ
  TCL_GETSOBJ AND TCL_GETS
  TCL_UNGETS
  TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE
  TCL_FLUSH
  TCL_SEEK
  TCL_TELL
  TCL_TRUNCATECHANNEL
  TCL_GETCHANNELOPTION
  TCL_SETCHANNELOPTION
  TCL_EOF
  TCL_INPUTBLOCKED
  TCL_INPUTBUFFERED
  TCL_OUTPUTBUFFERED
  PLATFORM ISSUES
  SEE ALSO
  KEYWORDS

### NAME

Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_CloseEx, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_TruncateChannel, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw — 通信路を使用する緩衝域使用入出力便益 buffered I/O facilities using channels

### SYNOPSIS

#include <tcl.h>
Tcl_Channel
Tcl_OpenFileChannel(interp, fileName, mode, permissions)
Tcl_Channel
Tcl_OpenCommandChannel(interp, argc, argv, flags)
Tcl_Channel
Tcl_MakeFileChannel(handle, readOrWrite)
Tcl_Channel
Tcl_GetChannel(interp, channelName, modePtr)
int
Tcl_GetChannelNames(interp)
int
Tcl_GetChannelNamesEx(interp, pattern)
void
Tcl_RegisterChannel(interp, channel)
int
Tcl_UnregisterChannel(interp, channel)
int
Tcl_DetachChannel(interp, channel)
int
Tcl_IsStandardChannel(channel)
int
Tcl_Close(interp, channel)
int
Tcl_CloseEx(interp, channel, closeFlags)
int
Tcl_ReadChars(channel, readObjPtr, charsToRead, appendFlag)
int
Tcl_Read(channel, readBuf, bytesToRead)
int
Tcl_GetsObj(channel, lineObjPtr)
int
Tcl_Gets(channel, lineRead)
int
Tcl_Ungets(channel, input, inputLen, addAtEnd)
int
Tcl_WriteObj(channel, writeObjPtr)
int
Tcl_WriteChars(channel, charBuf, bytesToWrite)
int
Tcl_Write(channel, byteBuf, bytesToWrite)
int
Tcl_ReadRaw(channel, readBuf, bytesToRead)
int
Tcl_WriteRaw(channel, byteBuf, bytesToWrite)
int
Tcl_Eof(channel)
int
Tcl_Flush(channel)
int
Tcl_InputBlocked(channel)
int
Tcl_InputBuffered(channel)
int
Tcl_OutputBuffered(channel)
Tcl_WideInt
Tcl_Seek(channel, offset, seekMode)
Tcl_WideInt
Tcl_Tell(channel)
int
Tcl_TruncateChannel(channel, length)
int
Tcl_GetChannelOption(interp, channel, optionName, optionValue)
int
Tcl_SetChannelOption(interp, channel, optionName, newValue)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  不都合報告とその中に登録された通信路の捜索に使用される｡　 Used for error reporting and to look up a channel registered in it.

const char *fileName (入力in)
  装置内の､又は､電網上のファイルの名前　 The name of a local or network file.

const char *mode (入力in)
  ファイルがどのように利用されるかを指定する｡ Tcl の open 命令への様式引数のどの値も許容させ得る｡　 Specifies how the file is to be accessed. May have any of the values allowed for the mode argument to the Tcl open command.

int permissions (入力in)
  POSIX-様式の利用権限､譬えば 0644｡もし新しいファイルが生成された場合､これらの利用権限はその生成されたファイルに設定される｡ POSIX-style permission flags such as 0644. If a new file is created, these permissions will be set on the created file.

int argc (入力in)
  argv 内の要素の個数｡　 The number of elements in argv.

const char **argv (入力in)
  命令パイプライン構築の為の引数｡これらの値は､Tcl の exec 命令への非切替え引数と同じ意味を有する｡　 Arguments for constructing a command pipeline. These values have the same meaning as the non-switch arguments to the Tcl exec command.

int flags (入力in)
  パイプライン内の標準入出力取っ手の性質を指定する: TCL_STDIN と TCL_STDOUT と TCL_STDERR と TCL_ENFORCE_MODE の論理和組合わせ｡もし TCL_STDIN が設定されていると､パイプライン中の最初の仔供の為の標準入出力がパイプの通信路である､そうでない場合､起動手順の標準入力と同じである; TCL_STDOUT と TCL_STDERR の為と似ている｡もし TCL_ENFORCE_MODE が設定されていないと､パイプは標準入出力取っ手から､そこに TCL_STDIN と TCL_STDOUT と TCL_STDERR が設定されていた標準入出力取っ手を上書きする為に､向け先変更できる｡設定されている場合は､そのような向け先変更は不都合を惹き起こす｡　 Specifies the disposition of the stdio handles in pipeline: OR-ed combination of TCL_STDIN, TCL_STDOUT, TCL_STDERR, and TCL_ENFORCE_MODE. If TCL_STDIN is set, stdin for the first child in the pipe is the pipe channel, otherwise it is the same as the standard input of the invoking process; likewise for TCL_STDOUT and TCL_STDERR. If TCL_ENFORCE_MODE is not set, then the pipe can redirect stdio handles to override the stdio handles for which TCL_STDIN, TCL_STDOUT and TCL_STDERR have been set. If it is set, then such redirections cause an error.

ClientData handle (入力in)
  ファイルへのOS固有の入出力取っ手｡ Unix では､これはファイル記述子､Windows では HANDLE である｡ Operating system specific handle for I/O to a file. For Unix this is a file descriptor, for Windows it is a HANDLE.

int readOrWrite (入力in)
  操作子上でどの操作が適正かを示すための TCL_READABLE と TCL_WRITABLE の論理和組合わせ｡　 OR-ed combination of TCL_READABLE and TCL_WRITABLE to indicate what operations are valid on handle.

const char *channelName (入力in)
  通信路の名前｡　 The name of the channel.

int *modePtr (出力out)
  通信路が読出しか書込みで開かれたかを表す TCL_READABLE と TCL_WRITABLE の論理和組合わせを受取る整数の変数を指す｡　 Points at an integer variable that will receive an OR-ed combination of TCL_READABLE and TCL_WRITABLE denoting whether the channel is open for reading and writing.

const char *pattern (入力in)
  合致すべき文様､ Tcl_StringMatch に渡される､若しくは NULL｡ The pattern to match on, passed to Tcl_StringMatch, or NULL.

Tcl_Channel channel (入力in)
  入力或いは出力の為の Tcl 通信路｡Tcl_OpenFileChannel 等の手続函数からの返り値でなければならい｡ A Tcl channel for input or output. Must have been the return value from a procedure such as Tcl_OpenFileChannel.

Tcl_Obj *readObjPtr (入出力in/out)
  通信路から読み出される文字を保存すべき Tcl 値への指示子｡ A pointer to a Tcl value in which to store the characters read from the channel.

int charsToRead (入力in)
  通信路から読み出される文字の個数｡もし通信路の符号化が２進である場合､これは通信路から読み出すべきバイトの個数に等しい｡　 The number of characters to read from the channel. If the channel's encoding is binary, this is equivalent to the number of bytes to read from the channel.

int closeFlags (入力in)
  もし0であると､その通信路は双方向に閉じられる｡もし､TCL_CLOSE_READであると､その通信路は読込みのみが閉じられる｡もしTCL_CLOSE_WRITEであると､その通信路は書込みのみ閉じられる｡これらの旗印は組合わせてはならない｡ If 0, the channel is closed in both directions. If TCL_CLOSE_READ, the channel is only closed for reading. If TCL_CLOSE_WRITE, the channel is only closed for writing. These flags must not be combined.

int appendFlag (入力in)
  もし非零の場合､値に追記されるべき通信から読み出されるデータ｡それ以外の場合､データは値の既存の内容を置換わる｡　 If non-zero, data read from the channel will be appended to the value. Otherwise, the data will replace the existing contents of the value.

char *readBuf (out)
  通信路から読み出されるバイトをその中に保存する緩衝域｡　 A buffer in which to store the bytes read from the channel.

int bytesToRead (入力in)
  通信路から読み出されるべきバイトの個数｡緩衝域 readBuf はこの多くのバイトを保有するに足る大きさでなければならない｡　 The number of bytes to read from the channel. The buffer readBuf must be large enough to hold this many bytes.

Tcl_Obj *lineObjPtr (入出力in/out)
  通信路から読み出される行を保存すべき Tcl 値への指示子｡読出された行は現在の値の値に追記される｡　 A pointer to a Tcl value in which to store the line read from the channel. The line read will be appended to the current value of the value.

Tcl_DString *lineRead (入出力in/out)
  通信路から読出される行を保存すべき Tcl 動的文字列への指示子｡呼出し者によって事前に初期化されていなければならない｡読まれる行は既に動的文字列内にあるどのデータにも追記されることになる｡　 A pointer to a Tcl dynamic string in which to store the line read from the channel. Must have been initialized by the caller. The line read will be appended to any data already in the dynamic string.

const char *input (入力in)
  通信路緩衝域に追加されるべき入力｡　　 The input to add to a channel buffer.

int inputLen (入力in)
  入力の長さ　 Length of the input

int addAtEnd (入力in)
  入力が通信路緩衝域の末尾または先頭のどちらに加えられるべきかを示す旗印｡　 Flag indicating whether the input should be added to the end or beginning of the channel buffer.

Tcl_Obj *writeObjPtr (入力in)
  その内容が通信路に出力されることになる Tcl 値への指示子｡　 A pointer to a Tcl value whose contents will be output to the channel.

const char *charBuf (入力in)
  通信路に出力すべき文字を含む緩衝域｡　 A buffer containing the characters to output to the channel.

const char *byteBuf (入力in)
  通信路に出力すべきバイトを含む緩衝域｡　 A buffer containing the bytes to output to the channel.

int bytesToWrite (入力in)
  charBuf か byteBuf から消費して通信路に出力すべきバイトの個数｡　 The number of bytes to consume from charBuf or byteBuf and output to the channel.

Tcl_WideInt offset (入力in)
  通信路内の､次の入力か出力操作が適用されることになる利用点に､seekMode によって与えられた位置から､どれだけ遠く迄､移動する必要があると､バイト単位で測定されたか｡正数でも負数でもあり得る｡　 How far to move the access point in the channel at which the next input or output operation will be applied, measured in bytes from the position given by seekMode. May be either positive or negative.

int seekMode (入力in)
  走査すべき位置への関連性; 通信路に関する新しい利用位置へ計算すべき変移が使用される｡適正な値は､ SEEK_SET と SEEK_CUR と SEEK_END｡　 Relative to which point to seek; used with offset to calculate the new access point for the channel. Legal values are SEEK_SET, SEEK_CUR, and SEEK_END.

Tcl_WideInt length (入力in)
  通信路を通信路に約めるべき長さ(非負数)｡　 The (non-negative) length to truncate the channel the channel to.

const char *optionName (入力in)
  この通信路に適用可能な指定項目の名前､譬えば -blocking の如し｡fconfigure 命令によってどの値でも受容れさせ得る｡　 The name of an option applicable to this channel, such as -blocking. May have any of the values accepted by the fconfigure command.

Tcl_DString *optionValue (入力in)
  指定項目､又は全ての指定項目のリストとその値の値を保存すべき場所｡呼出し者によって事前に初期化されていなければならない｡　 Where to store the value of an option or a list of all options and their values. Must have been initialized by the caller.

const char *newValue (入力in)
  optionName によって与えられた指定項目の為の新しい値｡　 New value for the option given by optionName.

### DESCRIPTION

Tcl 通信路仕組みは装置に依存しない､OSに依存しない種々のファイル､受け口､装置型上の緩衝された入力と出力の操作仕組みを提供する｡通信路の仕組みは新しい型の低水準の通信路駆動譜によって新しい通信路型に拡張できる; 通信路駆動譜相互作用機能は取扱説明書の Tcl_CreateChannel の見出し内に記述されている｡通信路の仕組みは Unix 標準入出力を准えた緩衝仕組みを提供し､通信路上の非同期入出力を許容する｡ The Tcl channel mechanism provides a device-independent and platform-independent mechanism for performing buffered input and output operations on a variety of file, socket, and device types. The channel mechanism is extensible to new channel types, by providing a low-level channel driver for the new type; the channel driver interface is described in the manual entry for Tcl_CreateChannel. The channel mechanism provides a buffering scheme modeled after Unix's standard I/O, and it also allows for nonblocking I/O on channels.

この手続函数は通信路構築様式の一般層の C APIs から構成される取扱説明書の見出しの中に記述されている｡通信路駆動譜構築様式の記述と通信路の新しい型に就いての通信路駆動譜を如何に実装するかについては取扱説明書の Tcl_CreateChannel を参照されたい｡ The procedures described in this manual entry comprise the C APIs of the generic layer of the channel architecture. For a description of the channel driver architecture and how to implement channel drivers for new types of channels, see the manual entry for Tcl_CreateChannel.

### TCL_OPENFILECHANNEL

Tcl_OpenFileChannel は fileName によって指定されたファイルを開き､そのファイルの入出力を遂行する為に使える通信路処理子を返す｡この API は Unix 標準入出力外部函数を准えたものである｡引数の構文と意味はファイルを開ける時の Tcl open 命令に与えられたものに似ている｡もし通信路を開ける間に不都合が生じると Tcl_OpenFileChannel は NULL を返し､ POSIX 不都合符号を記録する､それは Tcl_GetErrno により取出せる｡更にもし interp が 非-NULL の場合 Tcl_OpenFileChannel は､不都合伝言文を解釈実行機能の結果に残す｡ Tcl 8.4 の様に可能な場合は API Tcl_FSOpenFileChannel の基本値は Tcl_OpenFileChannel に優先する｡ Tcl_OpenFileChannel opens a file specified by fileName and returns a channel handle that can be used to perform input and output on the file. This API is modeled after the fopen procedure of the Unix standard I/O library. The syntax and meaning of all arguments is similar to those given in the Tcl open command when opening a file. If an error occurs while opening the channel, Tcl_OpenFileChannel returns NULL and records a POSIX error code that can be retrieved with Tcl_GetErrno. In addition, if interp is non-NULL, Tcl_OpenFileChannel leaves an error message in interp's result after any error. As of Tcl 8.4, the value-based API Tcl_FSOpenFileChannel should be used in preference to Tcl_OpenFileChannel wherever possible.

新しく作成された通信路は提供された解釈実行機能内に登録されない; それを登録する為には下で述べる Tcl_RegisterChannel を使われたい｡もし標準通信路の内の一つ stdin stdout or stderr が以前に閉じられている場合､新しい通信路の作成の活動は又標準通信路に関する置換えを指示する｡ The newly created channel is not registered in the supplied interpreter; to register it, use Tcl_RegisterChannel, described below. If one of the standard channels, stdin, stdout or stderr was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel.

### TCL_OPENCOMMANDCHANNEL

Tcl_OpenCommandChannel は exec と open 命令の機能への C-水準の相互作用機能である｡それは argv と argc によって指定される副手順の並びを作成し､その副手順と通信する為に使える通信路を返す｡ flags 引数はどの種類の通信がその命令パイプラインに実在するかを指し示す｡ Tcl_OpenCommandChannel provides a C-level interface to the functions of the exec and open commands. It creates a sequence of subprocesses specified by the argv and argc arguments and returns a channel that can be used to communicate with these subprocesses. The flags argument indicates what sort of communication will exist with the command pipeline.

もし TCL_STDIN 旗印が設定されている場合､最初の副手順への標準入力は通信路に結びつけられている: 通信路への書込みは副手順への入力をもたらす｡もし TCL_STDIN 旗印が設定されていない場合､最初の副手順への標準入力はこの応用譜の標準入力と同じになる｡もし TCL_STDOUT 旗印が設定されている場合､最後の副手順からの標準出力は通信路から読むことができる; それ以外の場合は応用譜の標準出力に流れる｡もし TCL_STDERR 旗印が設定されている場合､全ての副手順への標準不都合出力は通信路に返され､通信路が閉じた時は不都合になる; それ以外は応用譜の標準不都合出力に行く｡もし TCL_ENFORCE_MODE 旗印が設定されていない場合､ argc と argv は TCL_STDIN, TCL_STDOUT and TCL_STDERR を上書きする為に標準入出力処理機能の向け先を変更できる; 設定されている場合､ argc and argv について標準通信路を上書きする為に TCL_STDIN, TCL_STDOUT, and TCL_STDERR が設定されることは不都合である｡ If the TCL_STDIN flag is set then the standard input for the first subprocess will be tied to the channel: writing to the channel will provide input to the subprocess. If TCL_STDIN is not set, then standard input for the first subprocess will be the same as this application's standard input. If TCL_STDOUT is set then standard output from the last subprocess can be read from the channel; otherwise it goes to this application's standard output. If TCL_STDERR is set, standard error output for all subprocesses is returned to the channel and results in an error when the channel is closed; otherwise it goes to this application's standard error. If TCL_ENFORCE_MODE is not set, then argc and argv can redirect the stdio handles to override TCL_STDIN, TCL_STDOUT, and TCL_STDERR; if it is set, then it is an error for argc and argv to override stdio channels for which TCL_STDIN, TCL_STDOUT, and TCL_STDERR have been set.

通信路を開く間に不都合が生じると､ Tcl_OpenCommandChannel は NULL を返し､ POSIX 不都合符号を記録する､それは Tcl_GetErrno により取出せる｡更に､ Tcl_OpenCommandChannel は､もし解釈実行機能が NULL でなければ､不都合伝言文を解釈実行機能の結果に残す｡ If an error occurs while opening the channel, Tcl_OpenCommandChannel returns NULL and records a POSIX error code that can be retrieved with Tcl_GetErrno. In addition, Tcl_OpenCommandChannel leaves an error message in the interpreter's result. interp cannot be NULL.

新しく作成された通信路は提供された解釈実行機能内に登録されない; それを登録する為には下で述べる Tcl_RegisterChannel を使われたい｡もし標準通信路の内の一つ stdin, stdout or stderr が以前に閉じられている場合､新しい通信路の作成の活動は又標準通信路に関する置換えを指示する｡ The newly created channel is not registered in the supplied interpreter; to register it, use Tcl_RegisterChannel, described below. If one of the standard channels, stdin, stdout or stderr was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel.

### TCL_MAKEFILECHANNEL

Tcl_MakeFileChannel は既存の､OS固有のファイル処理機能から Tcl_Channel を作る｡新しく作成された通信路は提供された解釈実行機能内に登録されない; それを登録する為には下で述べる Tcl_RegisterChannel を使われたい｡もし標準通信路の内の一つ stdin, stdout or stderr が以前に閉じられている場合､新しい通信路の作成の活動は又標準通信路に関する置換えを指示する｡ Tcl_MakeFileChannel makes a Tcl_Channel from an existing, platform-specific, file handle. The newly created channel is not registered in the supplied interpreter; to register it, use Tcl_RegisterChannel, described below. If one of the standard channels, stdin, stdout or stderr was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel.

### TCL_GETCHANNEL

Tcl_GetChannel は Tcl_CreateChannel によって作る時に使った channelName と interp 内の Tcl 解釈実行機能へのポインターを与えられ通信路を返す｡もしその通信路がその解釈実行機能内にその名前で登録されていない場合､手続函数は NULL を返す｡もし modePtr 引数が NULL でない場合､それは整数変数を指し､それは通信路が読みと書きの為に開かれたかを記述する TCL_READABLE と TCL_WRITABLE の､論理的或は､の組合せを受取る｡ Tcl_GetChannel returns a channel given the channelName used to create it with Tcl_CreateChannel and a pointer to a Tcl interpreter in interp. If a channel by that name is not registered in that interpreter, the procedure returns NULL. If the modePtr argument is not NULL, it points at an integer variable that will receive an OR-ed combination of TCL_READABLE and TCL_WRITABLE describing whether the channel is open for reading and writing.

Tcl_GetChannelNames and Tcl_GetChannelNamesEx は登録された通信路の名前を解釈実行機能の結果にリスト値として書く｡ Tcl_GetChannelNamesEx はこの名前を紋様に従って篩う｡もし紋様が NULL の場合､何も篩われない｡もし結果の書込みに不都合が生じない場合は返り値は TCL_OK であり､それ以外は TCL_ERROR であり､不都合伝言文が解釈実行機能の結果に残される｡ Tcl_GetChannelNames and Tcl_GetChannelNamesEx write the names of the registered channels to the interpreter's result as a list value. Tcl_GetChannelNamesEx will filter these names according to the pattern. If pattern is NULL, then it will not do any filtering. The return value is TCL_OK if no errors occurred writing to the result, otherwise it is TCL_ERROR, and the error message is left in the interpreter's result.

### TCL_REGISTERCHANNEL

Tcl_RegisterChannel は解釈実行機能内の利用可能な通信路の揃いに通信路を加える｡この呼出しの後､ Tcl 算譜はその解釈実行機能内で Tcl_CreateChannel への呼出し内で与えられた名前を使って入力や出力操作にその通信路を参照できる｡この呼出しの後､通信路は解釈実行機能の特性になり､呼出し側は通信路に Tcl_Close を呼ぶべきではない; 通信路は登録除外の時に解釈実行機能により自動的に閉じられる｡ Tcl_RegisterChannel adds a channel to the set of channels accessible in interp. After this call, Tcl programs executing in that interpreter can refer to the channel in input or output operations using the name given in the call to Tcl_CreateChannel. After this call, the channel becomes the property of the interpreter, and the caller should not call Tcl_Close for the channel; the channel will be closed automatically when it is unregistered from the interpreter.

Tcl にその通信路の参照を有すること望むことを指し示す為に､どの Tcl 解釈実行機能の外にある符号も解釈実行機能を NULL として Tcl_RegisterChannel を呼ぶことができる｡引き続き､ Tcl 解釈実行機能内に通信路は登録することができ､それは Tcl_UnregisterChannel への呼び出しの合致番号が作成されたときのみ閉じられる｡これによりどの解釈実行機能の外部の符号命令が安全に Tcl 解釈実行機能内に登録された通信路を参照することを許容する｡ Code executing outside of any Tcl interpreter can call Tcl_RegisterChannel with interp as NULL, to indicate that it wishes to hold a reference to this channel. Subsequently, the channel can be registered in a Tcl interpreter and it will only be closed when the matching number of calls to Tcl_UnregisterChannel have been made. This allows code executing outside of any interpreter to safely hold a reference to a channel that is also registered in a Tcl interpreter.

この手続函数は標準通信路を管理する符号命令と相互に作用する｡もし標準通信路が Tcl_RegisterChannel への初めての呼出しより前に初期化されてない場合､その呼び出しで初期化される｡標準通信路と､それに関する Tcl 外部函数の振舞いに就いては Tcl_StandardChannels を参照されたい｡ This procedure interacts with the code managing the standard channels. If no standard channels were initialized before the first call to Tcl_RegisterChannel, they will get initialized by that call. See Tcl_StandardChannels for a general treatise about standard channels and the behavior of the Tcl library with regard to them.

### TCL_UNREGISTERCHANNEL

Tcl_UnregisterChannel は解釈実行機能内の利用可能な通信路の揃いから通信路を取外す｡之を呼んだ後､ Tcl 算譜は最早その解釈実行機能内の通信路を参照する通信路の名前を使うことはできない｡この操作が解釈実行機能内の最後の通信の登録を取外すと､通信路は閉じられ破壊される｡ Tcl_UnregisterChannel removes a channel from the set of channels accessible in interp. After this call, Tcl programs will no longer be able to use the channel's name to refer to the channel in that interpreter. If this operation removed the last registration of the channel in any interpreter, the channel is also closed and destroyed.

Tcl に最早その通信路の参照を有さないことを指し示す為に､ Tcl 解釈実行機能に結合しない符号は解釈実行機能を NULL として Tcl_UnregisterChannel を呼ぶことができる｡もし之が通信路への最後の参照であると､それは閉じられる｡Tcl_UnregisterChannel は Tcl_DetachChannel に非常によく似ているが､違いはそれは実在しているものへの更なる参照がない時に常に閉じられることである｡ Code not associated with a Tcl interpreter can call Tcl_UnregisterChannel with interp as NULL, to indicate to Tcl that it no longer holds a reference to that channel. If this is the last reference to the channel, it will now be closed. Tcl_UnregisterChannel is very similar to Tcl_DetachChannel except that it will also close the channel if no further references to it exist.

### TCL_DETACHCHANNEL

Tcl_DetachChannel は解釈実行機能内の利用可能な通信路の揃いから通信路を取外す｡之を呼んだ後､ Tcl 算譜は最早その解釈実行機能内の通信路を参照する通信路の名前を使うことはできない｡その後は､この命令は更なる効果を有さない｡標準通信路(stdout stderr stdin)には使うことができない､又､このうちの一つを渡すと TCL_ERROR が返される｡ Tcl_DetachChannel removes a channel from the set of channels accessible in interp. After this call, Tcl programs will no longer be able to use the channel's name to refer to the channel in that interpreter. Beyond that, this command has no further effect. It cannot be used on the standard channels (stdout, stderr, stdin), and will return TCL_ERROR if passed one of those channels.

Tcl に最早その通信路の参照を有さないことを指し示す為に､ Tcl 解釈実行機能に結合しない符号は解釈実行機能を NULL,として Tcl_DetachChannel を呼ぶことができる｡ Tcl_UnregisterChannel とは異なり､もし之が通信路への最後の参照であると､それは閉じられる｡ Code not associated with a Tcl interpreter can call Tcl_DetachChannel with interp as NULL, to indicate to Tcl that it no longer holds a reference to that channel. If this is the last reference to the channel, unlike Tcl_UnregisterChannel, it will not be closed.

### TCL_ISSTANDARDCHANNEL

Tcl_IsStandardChannel は通信路が三つの標準通信路 stdin, stdout or stderr の内の一つか否かを試験する｡もしそうなら1,をそれ以外は 0 を返す｡ Tcl_IsStandardChannel tests whether a channel is one of the three standard channels, stdin, stdout or stderr. If so, it returns 1, otherwise 0.

与えられた通信路か標準通信路が初期化されたか､有効であるかを検査することはない｡ No attempt is made to check whether the given channel or the standard channels are initialized or otherwise valid.

### TCL_CLOSE AND TCL_CLOSEEX

Tcl_Close は通信路 channel を遺棄する､それは現在開かれている通信路を指し示す｡ Tcl_Close が呼出された時､通信路はどの解釈実行機能にも登録されない｡緩衝域の出力は通信路の破壊の前に通信路の出力装置に吐出され､どの緩衝域入力も遺棄される｡もし之が同期通通信路の場合､呼出しは全ての緩衝域データが成功裏に通信路の出力装置に送られるまで制御は返らない｡もし之が非同期通信路で且つ抑制なしに書き出しできない緩衝域出力がある場合､呼出しは直ぐに制御を返す; 出力は背景で追出され､通信路は全ての緩衝データが出力され一度閉じられる｡この場合追出し中の不都合は報告されない｡ Tcl_Close destroys the channel channel, which must denote a currently open channel. The channel should not be registered in any interpreter when Tcl_Close is called. Buffered output is flushed to the channel's output device prior to destroying the channel, and any buffered input is discarded. If this is a blocking channel, the call does not return until all buffered data is successfully sent to the channel's output device. If this is a nonblocking channel and there is buffered output that cannot be written without blocking, the call returns immediately; output is flushed in the background and the channel will be closed once all of the buffered data has been output. In this case errors during flushing are not reported.

Tcl_CloseExは､そのcloseFlags假引数に従って通信路の全閉と半閉の両方を許容する｡上記假引数の説明を参照されたい｡通信路の､開かれてない方向に関して閉鎖の試みは不都合である｡通信路は､読出しと書込みの両方が閉じられる時のみ破壊される｡ソケットと命令パイプのみ半閉じに対応する｡ Tcl_CloseEx allows for both full closing and half-closing of channels depending on its closeFlags parameter. See the description of the parameter above. It is an error to attempt to close the channel for a direction for which it is not open. The channel is destroyed only when it has been closed for both reading and writing. Only socket and command pipe channels support half-closing.

もし､通信路が成功裡に閉じられると､Tcl_CloseとTcl_CloseExはTCL_OKを返す｡もし､不都合が生じると､これ等は､TCL_ERRORを返し､ Tcl_GetErrnoで取り出せるPOSIX不都合符号を記録する｡もし､通信路が同期的に閉じられ､且つ､通信路閉鎖の間に不都合が生じ､且つ､interpがヌルでない場合､不都合伝達文が解釈実行機能の結果に残される｡ If the channel was closed successfully, Tcl_Close and Tcl_CloseEx return TCL_OK. If an error occurs, they return TCL_ERROR and record a POSIX error code that can be retrieved with Tcl_GetErrno. If the channel is being closed synchronously and an error occurs during closing of the channel and interp is not NULL, an error message is left in the interpreter's result.

註意: Tcl_RegisterChannel を使って登録された通信路について通信路閉鎖函数を呼出すことは安全ではない; 詳細は上記Tcl_RegisterChannelに関する説明を参照されたい｡ もし通信路が Tcl_RegisterChannel 呼出しへの chan 引数として与えられた場合､代りに Tcl_UnregisterChannel を使うべきであり､それは､全ての Tcl_RegisterChannel 呼出しが対応する Tcl_UnregisterChannel 呼出しに合致したときに内部的に Tcl_Close を呼ぶ｡ Note: it is not safe to call the channel closing functions on a channel that has been registered using Tcl_RegisterChannel; see the documentation for Tcl_RegisterChannel, above, for details. If the channel has ever been given as the chan argument in a call to Tcl_RegisterChannel, you should instead use Tcl_UnregisterChannel, which will internally call Tcl_Close when all calls to Tcl_RegisterChannel have been matched by corresponding calls to Tcl_UnregisterChannel.

### TCL_READCHARS AND TCL_READ

Tcl_ReadChars は通信路からのバイトを消費し､バイトから通信路の符号系に基いた UTF-8 に変換し出来上がったデータを readObjPtr の 文字列内の表現に保存する｡ Tcl_ReadChars の返り値は文字の個数であり､ charsToRead 迄で readObjPtr に保存される｡読む時に不都合が生じると返り値は -1 であり､ Tcl_ReadChars は POSIX 不都合符号を記録する､それは Tcl_GetErrno により取出せる｡ Tcl_ReadChars consumes bytes from channel, converting the bytes to UTF-8 based on the channel's encoding and storing the produced data in readObjPtr's string representation. The return value of Tcl_ReadChars is the number of characters, up to charsToRead, that were stored in readObjPtr. If an error occurs while reading, the return value is -1 and Tcl_ReadChars records a POSIX error code that can be retrieved with Tcl_GetErrno.

charsToRead を -1 に設定すると命令に現在利用できる全ての文字(非同期)又はファイル末尾まで全部(同期様式)を読むことを惹き起こす｡ Setting charsToRead to -1 will cause the command to read all characters currently available (non-blocking) or everything until eof (blocking mode).

返り値は読むべき値より小さいかもしれない､それは要求されたデータは利用できるものより小さい事を指し示す｡これは読み不足と呼ばれる｡同期様式ではこれはファイル末尾が生じた時のみ可能である｡非同期様式では不足読みは現在利用できる入力は充分ではない場合にも可能である: Tcl_ReadChars は更なるデータを待つより不足数を返す｡ The return value may be smaller than the value to read, indicating that less data than requested was available. This is called a short read. In blocking mode, this can only happen on an end-of-file. In nonblocking mode, a short read can also occur if there is not enough input currently available: Tcl_ReadChars returns a short count rather than waiting for more data.

もし通信路が同期様式の場合､零の返り値はファイル末条件であることを指し示す｡もし通信路が非同期様式の場合､返り値の零は､現在利用できるデータがないか､ファイル末尾条件かのどちらかであることを指し示す｡どちらの条件が実際に生じたかは Tcl_Eof and Tcl_InputBlocked を使う｡ If the channel is in blocking mode, a return value of zero indicates an end-of-file condition. If the channel is in nonblocking mode, a return value of zero indicates either that no input is currently available or an end-of-file condition. Use Tcl_Eof and Tcl_InputBlocked to tell which of these conditions actually occurred.

Tcl_ReadChars は種々の行末表現を､現在の行末認識様式に従って､正規の \n 内部表現に変換する｡行末認識と種々のOS固有様式は取扱い説明書の Tcl fconfigure 命令の見出しに記述されている｡ Tcl_ReadChars translates the various end-of-line representations into the canonical \n internal representation according to the current end-of-line recognition mode. End-of-line recognition and the various platform-specific modes are described in the manual entry for the Tcl fconfigure command.

出来栄えの最適化の為に､通信路から符号系２進数により読む時､バイトは読みに従って UTF-8 には変換されない｡代りに､ readObjPtr 内にバイト配列値として内部表現を保存する｡この値の文字列表現は必要な場合のみ構成される(譬えば､ Tcl_GetStringFromObj による呼出し)｡この様にバイト志向のデータが通信路から読込でき､ Tcl_GetByteArrayFromObj とその関連函数の呼出により操作され､ UTF-8 との変換の負担なしに通信路に書込まれる｡ As a performance optimization, when reading from a channel with the encoding binary, the bytes are not converted to UTF-8 as they are read. Instead, they are stored in readObjPtr's internal representation as a byte-array value. The string representation of this value will only be constructed if it is needed (e.g., because of a call to Tcl_GetStringFromObj). In this way, byte-oriented data can be read from a channel, manipulated by calling Tcl_GetByteArrayFromObj and related functions, and then written to a channel without the expense of ever converting to or from UTF-8.

Tcl_Read は Tcl_ReadChars に似ている､違いは通信路の符号系を考慮せず､符号変換をしないことである｡それは批判され又､非国際的 Tcl 拡張への互換性の為に存在する｡通信路からバイトを受取り readBuf 内に保存し行末変換を途中で遂行する｡ Tcl_Read の返り値は bytesToRead,迄の readBuf に書かれたバイトの個数である｡ Tcl_Read により作成された緩衝域は零終端ではない｡その内容は零番の位置から帰り値により指し示される位置まで含まれる｡ Tcl_Read is similar to Tcl_ReadChars, except that it does not do encoding conversions, regardless of the channel's encoding. It is deprecated and exists for backwards compatibility with non-internationalized Tcl extensions. It consumes bytes from channel and stores them in readBuf, performing end-of-line translations on the way. The return value of Tcl_Read is the number of bytes, up to bytesToRead, written in readBuf. The buffer produced by Tcl_Read is not null-terminated. Its contents are valid from the zeroth position up to and excluding the position indicated by the return value.

Tcl_ReadRaw は Tcl_Read と同じであるが､棚積みを保障しない｡ Tcl_Read (及び API内の他の函数も)は常に供給された通信路の一部の棚の最上段の通信路からデータを得るが､ Tcl_ReadRaw はそうではない｡そこでこの函数は変換の通信路駆動譜についてのみ使用できる､即ち､通信路の他なの中央に使用された駆動譜が通信路からのデータを下の変形に移動する｡ Tcl_ReadRaw is the same as Tcl_Read but does not compensate for stacking. While Tcl_Read (and the other functions in the API) always get their data from the topmost channel in the stack the supplied channel is part of, Tcl_ReadRaw does not. Thus this function is only usable for transformational channel drivers, i.e. drivers used in the middle of a stack of channels, to move data from the channel below into the transformation.

### TCL_GETSOBJ AND TCL_GETS

Tcl_GetsObj 命令は通信路の符号系に基き､バイトを UTF-8 に変換しながら､入力の全部の行が見えるまで､通信路からのバイトを使い尽す｡もし通信路の符号系が２進数の場合､夫々の通信路から読んだバイトは個別のユニコード文字として取扱われる｡終りの行末文字を除く行の全ての文字が文字列表現に追記される｡行末文字は読まれて遺棄される｡ Tcl_GetsObj consumes bytes from channel, converting the bytes to UTF-8 based on the channel's encoding, until a full line of input has been seen. If the channel's encoding is binary, each byte read from the channel is treated as an individual Unicode character. All of the characters of the line except for the terminating end-of-line character(s) are appended to lineObjPtr's string representation. The end-of-line character(s) are read and discarded.

もし行が成功裏に読まれると､返る値は零かそれ以上でバイトを指し示す数は lineObjPtr.に保存される｡不都合が生じると､ Tcl_GetsObj は -1 を返し POSIX 不都合符号を記録する､それは Tcl_GetErrno により取出せる｡ Tcl_GetsObj もファイル末尾に到達した場合は -1 を返す; Tcl_Eof 手続函数はファイル末尾状態から不都合を区別することに使うことができる｡ If a line was successfully read, the return value is greater than or equal to zero and indicates the number of bytes stored in lineObjPtr. If an error occurs, Tcl_GetsObj returns -1 and records a POSIX error code that can be retrieved with Tcl_GetErrno. Tcl_GetsObj also returns -1 if the end of the file is reached; the Tcl_Eof procedure can be used to distinguish an error from an end-of-file condition.

もし通信路が非同期様式の場合､利用できるデータがないか､利用できるデータが行末文字を含まない場合も返り値は -1 になりうる｡ -1 が返された時､通信路にとって入力が利用できない為か否かを定める為に Tcl_InputBlocked 手続函数が起動され得る｡ If the channel is in nonblocking mode, the return value can also be -1 if no data was available or the data that was available did not contain an end-of-line character. When -1 is returned, the Tcl_InputBlocked procedure may be invoked to determine if the channel is blocked because of input unavailability.

Tcl_Gets は Tcl_GetsObj と同じであるが､違いはTcl 値ではなく､結果の文字が lineRead によって動的に与えられた文字列に追記される｡ Tcl_Gets is the same as Tcl_GetsObj except the resulting characters are appended to the dynamic string given by lineRead rather than a Tcl value.

### TCL_UNGETS

Tcl_Ungets は通信路の入力待ち行列の､先頭と末尾どちらにでも､データの追加に使われる｡ポインター input は加えられるデータを指す｡加えられる長さは inputLen で与えられる｡非零値の addAtEnd はデータが待ち行列の末尾に加えられることを指し示す; それ以外は待ち行列の先頭に加えられる｡もし通信路が “sticky[粘着性]” 末尾を設定させている場合､入力待ち行列にはデータは加えられない｡ Tcl_Ungets is used to add data to the input queue of a channel, at either the head or tail of the queue. The pointer input points to the data that is to be added. The length of the input to add is given by inputLen. A non-zero value of addAtEnd indicates that the data is to be added at the end of queue; otherwise it will be added at the head of the queue. If channel has a “sticky” EOF set, no data will be added to the input queue. Tcl_Ungets returns inputLen or -1 if an error occurs.

### TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE

Tcl_WriteChars は charBuf.の箇所の文字データを bytesToWrite だけ受付ける｡緩衝域の UTF-8 文字は通信路の符号に変換され channel への出力待ち行列に並ぶ｡もし bytesToWrite が負の場合､Tcl_WriteChars は charBuf が零終端であると予測し零が来る迄全部を出力する｡ Tcl_WriteChars accepts bytesToWrite bytes of character data at charBuf. The UTF-8 characters in the buffer are converted to the channel's encoding and queued for output to channel. If bytesToWrite is negative, Tcl_WriteChars expects charBuf to be null-terminated and it outputs everything up to the null.

出力用の待ち行列のデータは､内部緩衝の理由で､出力用装置にすぐさまには現れないかもしれない｡もしデータを直ぐに現すべき場合は､ Tcl_WriteChars,呼出しの後に Tcl_Flush を呼出すか､出力に関する -buffering 指示項目を none.に設定されたい｡もし出力用に､完全な行が受け取れらるや否や直ぐにデータが現れることを望む場合､通信路の -buffering 指示項目を line 様式に設定されたい｡ Data queued for output may not appear on the output device immediately, due to internal buffering. If the data should appear immediately, call Tcl_Flush after the call to Tcl_WriteChars, or set the -buffering option on the channel to none. If you wish the data to appear as soon as a complete line is accepted for output, set the -buffering option on the channel to line mode.

Tcl_WriteChars の返り値は通信路に出力用に何バイトが受入れられたかの数である｡これは成功を指し示す零より大きい値か不都合が生じたことを表す -1 かである｡もし不都合が生じると Tcl_WriteChars は､ POSIX 不都合符号を記録する､それは Tcl_GetErrno.により取出せる｡ The return value of Tcl_WriteChars is a count of how many bytes were accepted for output to the channel. This is either greater than zero to indicate success or -1 to indicate that an error occurred. If an error occurs, Tcl_WriteChars records a POSIX error code that may be retrieved with Tcl_GetErrno.

出力データ用の改行文字は通信路に関する -translation 追加指示項目に従ってOS固有の行末並びに変換される｡これは縦え通信路が符号系を有さない場合も実行される｡ Newline characters in the output data are translated to platform-specific end-of-line sequences according to the -translation option for the channel. This is done even if the channel has no encoding.

Tcl_WriteObj は Tcl_WriteChars と同じであるが､違いは前者はその内容が通信路への出力である Tcl 値を受付ける｡ writeObjPtr の 文字列表現内の UTF-8 文字は通信路の符号系に変換され､通信路への出力に関する待ち行列に追加する｡出来栄えの最適化のため､ binary 符号系を使って通信路に書込み時に､ UTF-8 文字はそれが書かれているようには変換されない｡その代わり､バイト配列値としての writeObjPtr の内部表現のバイトが通信路に書かれる｡値のバイト配列表現は必要であれば構築される｡この方法で､通信路から読むことが可能なバイト志向データは Tcl_GetByteArrayFromObj と関連する函数を呼出すことにより操つられ､それで UTF-8.との変換の負担なしに通信路へ書込む｡ Tcl_WriteObj is similar to Tcl_WriteChars except it accepts a Tcl value whose contents will be output to the channel. The UTF-8 characters in writeObjPtr's string representation are converted to the channel's encoding and queued for output to channel. As a performance optimization, when writing to a channel with the encoding binary, UTF-8 characters are not converted as they are written. Instead, the bytes in writeObjPtr's internal representation as a byte-array value are written to the channel. The byte-array representation of the value will be constructed if it is needed. In this way, byte-oriented data can be read from a channel, manipulated by calling Tcl_GetByteArrayFromObj and related functions, and then written to a channel without the expense of ever converting to or from UTF-8.

Tcl_Write は Tcl_WriteChars と同じであるが違いは､通信路の符号系を考慮することなく符号変換しないことである｡それは批判され又､非国際的 Tcl 拡張への互換性の為に存在する｡それはt byteBuf の箇所のデータの bytesToWrite バイトを受入れ通信路への出力に関する待ち行列に追記する｡もし bytesToWrite が負の場合Tcl_Write は byteBuf が零終端であると予測し零が来る迄全部を出力する｡ Tcl_Write is similar to Tcl_WriteChars except that it does not do encoding conversions, regardless of the channel's encoding. It is deprecated and exists for backwards compatibility with non-internationalized Tcl extensions. It accepts bytesToWrite bytes of data at byteBuf and queues them for output to channel. If bytesToWrite is negative, Tcl_Write expects byteBuf to be null-terminated and it outputs everything up to the null.

Tcl_WriteRaw は Tcl_Write と同じであるが､棚積みを保証しない｡ Tcl_Write (及び､ API内の他の函数)が常にその入力を棚内の最頂の通信路に注入している間､供給されている通信路はその部分であるが､Tcl_WriteRaw はそうではない｡従って､この函数は変換の通信路駆動譜の為にのみ使用できる､即ち､駆動譜は通信路の棚の中で使われデータを下の通信路の中に変換する為に使われる｡ Tcl_WriteRaw is the same as Tcl_Write but does not compensate for stacking. While Tcl_Write (and the other functions in the API) always feed their input to the topmost channel in the stack the supplied channel is part of, Tcl_WriteRaw does not. Thus this function is only usable for transformational channel drivers, i.e. drivers used in the middle of a stack of channels, to move data from the transformation into the channel below it.

### TCL_FLUSH

Tcl_Flush は基礎のファイルや装置に書込まれるべき全ての通信路の為の出力用緩衝域内データをできるだけ惹き起こす｡もし通信路が同期様式である場合､呼出しは全ての緩衝域データが通信路に送られて仕舞うか何かの不都合が生じるまで制御を返さない｡通信路が非同期であると呼出しは直ぐに戻る; それは背景処理追出しが始まりそれが通信路に緩衝域データを最後には書込む事になる､可能な限り速く通信路が中断できるように｡ Tcl_Flush causes all of the buffered output data for channel to be written to its underlying file or device as soon as possible. If the channel is in blocking mode, the call does not return until all the buffered data has been sent to the channel or some error occurred. The call returns immediately if the channel is nonblocking; it starts a background flush that will write the buffered data to the channel eventually, as fast as the channel is able to absorb it.

返り値は通常 TCL_OK である｡もし不都合が生じると Tcl_Flush は TCL_ERROR を返し､ POSIX 不都合符号を記録する､それは Tcl_GetErrno により取出せる｡ The return value is normally TCL_OK. If an error occurs, Tcl_Flush returns TCL_ERROR and records a POSIX error code that can be retrieved with Tcl_GetErrno.

### TCL_SEEK

Tcl_Seek は引続くデータが読み書きされる channel 内の利用位置を移動する｡移動操作に先立って､通信路用の出力用緩衝域は払出され､入力用干渉域は遺棄される｡ Tcl_Seek moves the access point in channel where subsequent data will be read or written. Buffered output is flushed to the channel and buffered input is discarded, prior to the seek operation.

Tcl_Seek は通常新しい利用位置を返す｡もし不都合が生じると､ Tcl_Seek は -1 を返し POSIX 不都合符号を記録する､それは Tcl_GetErrno. によって取出し可能である｡不都合の後､利用位置は移動されるかも移動されないかもしれない｡ Tcl_Seek normally returns the new access point. If an error occurs, Tcl_Seek returns -1 and records a POSIX error code that can be retrieved with Tcl_GetErrno. After an error, the access point may or may not have been moved.

### TCL_TELL

Tcl_Tell は通信路に対する現在の利用位置を返す｡もし､通信路が捜索を運営師弟愛場合､返される値は -1 である｡ Tcl_Tell returns the current access point for a channel. The returned value is -1 if the channel does not support seeking.

### TCL_TRUNCATECHANNEL

Tcl_TruncateChannel は基礎となる channel を与えられた length に切詰める｡操作が成功すると TCL_OK を返し､それ以外は TCL_ERROR を返す｡ Tcl_TruncateChannel truncates the file underlying channel to a given length of bytes. It returns TCL_OK if the operation succeeded, and TCL_ERROR otherwise.

### TCL_GETCHANNELOPTION

Tcl_GetChannelOption は､ optionValue 内に通信路に就いて現在有効な選択肢の内の一つの値か､又は全ての選択肢とその値のリストかを取戻す｡ channel 引数はそれに就いて選択肢を問合せるか全ての選択肢とその値を取戻す通信路を識別する｡もし optionName が NULL の場合､それは問合せる為の選択肢の名前である; 選択肢の値は optionValue によって指定される Tcl 動的文字列に複写される｡もし optionName が NULL の場合､函数は引続く Tcl_DStringAppendElement への呼出しを使って､選択肢の名前の代理の表と､ optionValue 内のその値とを保存する｡種々の以前に存在した選択肢とその可能な値は Tcl fconfigure 命令に就いての取扱説明書内の見出しを参照されたい｡他の選択肢は夫々の通信路か多によって追加可能である｡これ等の通信路型固有の型はその型の通信路を作成についての Tcl 命令についての取扱説明書内の見出し内に記述されている; 譬えば､追加的 TCP 基準の通信路についての選択肢は取扱説明書内の Tcl socket 命令の見出しに記述されている｡手続函数は通常 TCL_OK を返す｡もし不都合が生じると TCL_ERROR を返し､適切なる POSIX 不都合符号を保存する為に Tcl_SetErrno を呼出す｡ Tcl_GetChannelOption retrieves, in optionValue, the value of one of the options currently in effect for a channel, or a list of all options and their values. The channel argument identifies the channel for which to query an option or retrieve all options and their values. If optionName is not NULL, it is the name of the option to query; the option's value is copied to the Tcl dynamic string denoted by optionValue. If optionName is NULL, the function stores an alternating list of option names and their values in optionValue, using a series of calls to Tcl_DStringAppendElement. The various preexisting options and their possible values are described in the manual entry for the Tcl fconfigure command. Other options can be added by each channel type. These channel type specific options are described in the manual entry for the Tcl command that creates a channel of that type; for example, the additional options for TCP-based channels are described in the manual entry for the Tcl socket command. The procedure normally returns TCL_OK. If an error occurs, it returns TCL_ERROR and calls Tcl_SetErrno to store an appropriate POSIX error code.

### TCL_SETCHANNELOPTION

Tcl_SetChannelOption は新しい値 newValue を選択肢option の為に channel 上に設定する｡手続函数は通常 TCL_OK を返す｡もし不都合が生じると､ TCL_ERROR を返し､更に､ interp が非-NULL の場合 Tcl_SetChannelOption は不都合伝言文を解釈実行機能の結果内に残す｡ Tcl_SetChannelOption sets a new value newValue for an option optionName on channel. The procedure normally returns TCL_OK. If an error occurs, it returns TCL_ERROR; in addition, if interp is non-NULL, Tcl_SetChannelOption leaves an error message in the interpreter's result.

### TCL_EOF

Tcl_Eof は､もし通信路が最後の入力操作の間にファイル末尾に遭遇すると､非零を返す｡ Tcl_Eof returns a nonzero value if channel encountered an end of file during the last input operation.

### TCL_INPUTBLOCKED

もし channel が非同期様式であって且つ､利用できるデータが充分でない為に､最後の入力操作が返したデータが要求されたより少ない場合 Tcl_InputBlocked は零を返す｡もし通信路が同期様式の場合､呼出しは常に零を返す｡ Tcl_InputBlocked returns a nonzero value if channel is in nonblocking mode and the last input operation returned less data than requested because there was insufficient data available. The call always returns zero if the channel is in blocking mode.

### TCL_INPUTBUFFERED

Tcl_InputBuffered は通信路の為の内部緩衝域内の現在緩衝保存された入力のバイト数を返す｡もしこの通信路が読込の為に開かれていない場合､この函数は常に零を返す｡ Tcl_InputBuffered returns the number of bytes of input currently buffered in the internal buffers for a channel. If the channel is not open for reading, this function always returns zero.

### TCL_OUTPUTBUFFERED

Tcl_OutputBuffered は通信路の為の内部緩衝域内の現在緩衝保存された出力のバイト数を返す｡もしこの通信路が書込みの為に開かれていない場合､この函数は常に零を返す｡ Tcl_OutputBuffered returns the number of bytes of output currently buffered in the internal buffers for a channel. If the channel is not open for writing, this function always returns zero.

### PLATFORM ISSUES

Tcl_GetChannelHandle から返された処理機能はOSと通信路の型に依存する｡ Unix では､処理機能は常に Unix ファイル記述子として open 系呼出しから返される｡ Windows では､処理機能は通信路が Tcl_OpenFileChannel か Tcl_OpenCommandChannel か Tcl_MakeFileChannel によって作成された時のファイルの HANDLE である｡他の通信路の型は Windows で異なる型の処理機能を返すかもしれない｡ The handles returned from Tcl_GetChannelHandle depend on the platform and the channel type. On Unix platforms, the handle is always a Unix file descriptor as returned from the open system call. On Windows platforms, the handle is a file HANDLE when the channel was created with Tcl_OpenFileChannel, Tcl_OpenCommandChannel, or Tcl_MakeFileChannel. Other channel types may return a different type of handle on Windows platforms.

### SEE ALSO

DString, fconfigure, filename, fopen, Tcl_CreateChannel

### KEYWORDS

access point, blocking, buffered I/O, channel, channel driver, end of file, flush, input, nonblocking, output, read, seek, write
Copyright © 1996-1997 Sun Microsystems, Inc.