## Tcl9.0.3/Tk9.0.3 Documentation > Tcl C API > LinkVar

### 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_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar — Tcl 変数から C 言語変数への連結 link Tcl variable to C variable
  SYNOPSIS
    #include <tcl.h>
    int
    Tcl_LinkVar(interp, varName, addr, type)
    int
    Tcl_LinkArray(interp, varName, addr, type, size)
    Tcl_UnlinkVar(interp, varName)
    Tcl_UpdateLinkedVar(interp, varName)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    const char *varName (入力in)
    void *addr (入力in)
    int type (入力in)
    Tcl_Size size (入力in)
  明 DESCRIPTION
    TCL_LINK_INT
    TCL_LINK_UINT
    TCL_LINK_CHAR
    TCL_LINK_CHARS
    TCL_LINK_UCHAR
    TCL_LINK_BINARY
    TCL_LINK_SHORT
    TCL_LINK_USHORT
    TCL_LINK_LONG
    TCL_LINK_ULONG
    TCL_LINK_DOUBLE
    TCL_LINK_FLOAT
    TCL_LINK_WIDE_INT
    TCL_LINK_WIDE_UINT
    TCL_LINK_BOOLEAN
    TCL_LINK_STRING
  SEE ALSO
  KEYWORDS

### NAME

Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar — Tcl 変数から C 言語変数への連結 link Tcl variable to C variable

### SYNOPSIS

#include <tcl.h>
int
Tcl_LinkVar(interp, varName, addr, type)
int
Tcl_LinkArray(interp, varName, addr, type, size)
Tcl_UnlinkVar(interp, varName)
Tcl_UpdateLinkedVar(interp, varName)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  varName を含む解釈実行機能｡又､不都合伝言文を返す為に Tcl_LinkVar によって使われる｡ 　　 Interpreter that contains varName. Also used by Tcl_LinkVar to return error messages.

const char *varName (入力in)
  大局変数の名前｡　 Name of global variable.

void *addr (入力in)
  varName に連結されることになる C 言語変数の番地｡ Address of C variable that is to be linked to varName.

  Tcl_LinkArray 内では､変数内に配列の為の貯蔵域を創生することを Tcl に告げる為に NULL になるかもしれない｡ In Tcl_LinkArray, may be NULL to tell Tcl to create the storage for the array in the variable.

int type (入力in)
  Tcl_LinkVar に関する C 言語変数の型､又はTcl_LinkArray の配列要素の型｡TCL_LINK_INT か TCL_LINK_UINT か TCL_LINK_CHAR か TCL_LINK_UCHAR か TCL_LINK_SHORT か TCL_LINK_USHORT か TCL_LINK_LONG か TCL_LINK_ULONG か TCL_LINK_WIDE_INT か TCL_LINK_WIDE_UINT か TCL_LINK_FLOAT か TCL_LINK_DOUBLE か TCL_LINK_BOOLEAN か 下に列挙した追加の内の一つでなければならない｡ Type of C variable for Tcl_LinkVar or type of array element for Tcl_LinkArray. Must be one of TCL_LINK_INT, TCL_LINK_UINT, TCL_LINK_CHAR, TCL_LINK_UCHAR, TCL_LINK_SHORT, TCL_LINK_USHORT, TCL_LINK_LONG, TCL_LINK_ULONG, TCL_LINK_WIDE_INT, TCL_LINK_WIDE_UINT, TCL_LINK_FLOAT, TCL_LINK_DOUBLE, TCL_LINK_BOOLEAN, or one of the extra ones listed below.

  Tcl_LinkVar 内では､追加の連鎖型 TCL_LINK_STRING も使われ得る｡ In Tcl_LinkVar, the additional linked type TCL_LINK_STRING may be used.

  Tcl_LinkArray 内では､追加の連鎖型 TCL_LINK_CHARS と TCL_LINK_BINARY も使われ得る｡ In Tcl_LinkArray, the additional linked types TCL_LINK_CHARS and TCL_LINK_BINARY may be used.

  全ての上述の両方の函数の為のものは､TCL_LINK_READ_ONLY と論理和を行い Tcl 変数の読出し専用になすことが可能である｡ All the above for both functions may be optionally OR'ed with TCL_LINK_READ_ONLY to make the Tcl variable read-only.

Tcl_Size size (入力in)
  C 言語配列内の要素の数｡零より大きいことを要す｡ The number of elements in the C array. Must be greater than zero.

### 明 DESCRIPTION

Tcl_LinkVar は varName と名付けられた Tcl 変数を addr によって与えられた番地にある C 変数と同期して保有する為に種々の追跡を使う｡何時であれ Tcl 変数が読出された時は C 変数の値が返される､何時であれ Tcl 変数が書込まれると C 変数が同じ値を有するよう更新される｡ Tcl_LinkVar は通常 TCL_OK を返す; もし連結を設定している間に不都合が生じると(譬えば､ varName が配列名の理由で) TCL_ERROR が返され､解釈実行機能の結果に不都合伝言文が含まれる｡ Tcl_LinkVar uses variable traces to keep the Tcl variable named by varName in sync with the C variable at the address given by addr. Whenever the Tcl variable is read the value of the C variable will be returned, and whenever the Tcl variable is written the C variable will be updated to have the same value. Tcl_LinkVar normally returns TCL_OK; if an error occurs while setting up the link (e.g. because varName is the name of array) then TCL_ERROR is returned and the interpreter's result contains an error message.

Tcl_LinkArray は似ているが､固定寸法の配列用である(寸法引数によって与えられる)｡ C 配列貯蔵の戻り域を割り当てる為に供給された時( addr 引数経由で NULL である)､それは､Tcl 解釈実行機能に割当てる住所を結果に書く｡ Tcl_LinkArray is similar, but for arrays of fixed size (given by the size argument). When asked to allocate the backing C array storage (via the addr argument being NULL), it writes the address that it allocated to the Tcl interpreter result.

type 引数は C 変数の型､又は C 言語配列の要素の型を指定し､次の値の内の一つを有さなければならない､追加指定として､ TCL_LINK_READ_ONLY との論理的和の結合ができる: 　 The type argument specifies the type of the C variable, or the type of the elements of the C array, and must have one of the following values, optionally OR'ed with TCL_LINK_READ_ONLY:

TCL_LINK_INT
  C 変数､又は､C配列のそれぞれの要素は int 型である｡Tcl 変数に書かれた如何なる値も Tcl_GetIntFromObj に受入れられる適切な整数形式でなければならない; 非整数を varName に書込む試みは拒絶され Tcl 不都合を伴う｡不完全な整数表現（空文字列や､ '+'や '-'や十六進/八進/十進/二進 の前置辞､の様な）も妥当として受入れられ得る｡[訳註:十進数の前置辞は無い筈??ver9でも?] 　 The C variable, or each element of the C array, is of type int. Any value written into the Tcl variable must have a proper integer form acceptable to Tcl_GetIntFromObj; attempts to write non-integer values into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

TCL_LINK_UINT
  C 変数､又は､C配列のそれぞれの要素は unsigned int型である｡ Tcl 変数に書かれた如何なる値も Tcl_GetWideIntFromObj に受入れられる適切な符号なし整数形式でなければならず､且つOSによって unsigned int 型について定義された範囲内でなければならない; 非整数値(又は範囲外の値)を varName に書込む試みは拒絶され Tcl 不都合を伴う｡不完全な整数表現（空文字列､ '+'や '-'や十六進/八進/十進/二進 の前置辞､の様な）も妥当として受入れられ得る｡ 　 The C variable, or each element of the C array, is of type unsigned int. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to Tcl_GetWideIntFromObj and in the platform's defined range for the unsigned int type; attempts to write non-integer values (or values outside the range) into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

TCL_LINK_CHAR
  C 変数､又は､C配列のそれぞれの要素は char 型である｡ Tcl 変数に書かれた如何なる値も Tcl_GetIntFromObj に受入れられる適切な整数形式でなければならず､且つ char データ型の範囲内でなければならない; 非整数又は範囲外の値を varName に書込む試みは拒絶され Tcl 不都合を伴う｡不完全な整数表現（空文字列､ '+'や '-'や十六進/八進/十進/二進 の前置辞､の様な）も妥当として受入れられ得る｡ 　　 The C variable, or each element of the C array, is of type char. Any value written into the Tcl variable must have a proper integer form acceptable to Tcl_GetIntFromObj and be in the range of the char datatype; attempts to write non-integer or out-of-range values into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

  これらの配列を使う場合は､代りに TCL_LINK_CHARS の使用を考慮されたい｡ If using an array of these, consider using TCL_LINK_CHARS instead.

TCL_LINK_CHARS
  C 配列は char * 型であり､且つ､文字列として Tcl の中に対応付けされている｡ Tcl 変数の中に書かれたどの値も､基礎になっている貯蔵域と同じ長さを持たねばならない｡ Tcl_LinkArray についてのみ運営されている｡ The C array is of type char * and is mapped into Tcl as a string. Any value written into the Tcl variable must have the same length as the underlying storage. Only supported with Tcl_LinkArray.

TCL_LINK_UCHAR
  C 変数､又は､C配列のそれぞれの要素は unsigned char 型である｡ Tcl 変数に書かれた如何なる値も Tcl_GetIntFromObj に受入れられる適切な符号なし整数形式でなければならず､且つOSによって unsigned char 型について定義された範囲内でなければならない; 非整数値(又は範囲外の値)を varName に書込む試みは拒絶され Tcl 不都合を伴う｡不完全な整数表現（空文字列､ '+'や '-'や十六進/八進/十進/二進 の前置辞､の様な）も妥当として受入れられ得る｡ 　　 The C variable, or each element of the C array, is of type unsigned char. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to Tcl_GetIntFromObj and in the platform's defined range for the unsigned char type; attempts to write non-integer values (or values outside the range) into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

  If using an array of these, consider using TCL_LINK_BINARY instead.

TCL_LINK_BINARY
  C 配列は unsigned char * 型であり､且つ､文字列として Tcl の中に対応付けされている｡ Tcl 変数の中に書かれたどの値も､基礎になっている貯蔵域と同じ長さを持たねばならない｡ Tcl_LinkArray についてのみ運営されている｡ The C array is of type unsigned char * and is mapped into Tcl as a bytearray. Any value written into the Tcl variable must have the same length as the underlying storage. Only supported with Tcl_LinkArray.

TCL_LINK_SHORT
  C 変数､又は､C配列のそれぞれの要素は short 型である｡ Tcl 変数に書かれた如何なる値も Tcl_GetIntFromObj に受入れられる適切な整数形式でなければならず､且つ short データ型の範囲内でなければならない; 非整数又は範囲外の値を varName に書込む試みは拒絶され Tcl 不都合を伴う｡不完全な整数表現（空文字列､ '+'や '-'や十六進/八進/十進/二進 の前置辞､の様な）も妥当として受入れられ得る｡ 　　 The C variable, or each element of the C array, is of type short. Any value written into the Tcl variable must have a proper integer form acceptable to Tcl_GetIntFromObj and be in the range of the short datatype; attempts to write non-integer or out-of-range values into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

TCL_LINK_USHORT
  C 変数､又は､C配列のそれぞれの要素は unsigned short 型である｡ Tcl 変数に書かれた如何なる値も Tcl_GetIntFromObj に受入れられる適切な符号なし整数形式でなければならず､且つOSによって unsigned short 型について定義された範囲内でなければならない; 非整数値(又は範囲外の値)を varName に書込む試みは拒絶され Tcl 不都合を伴う｡不完全な整数表現（空文字列､ '+'や '-'や十六進/八進/十進/二進 の前置辞､の様な）も妥当として受入れられ得る｡ 　　 The C variable, or each element of the C array, is of type unsigned short. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to Tcl_GetIntFromObj and in the platform's defined range for the unsigned short type; attempts to write non-integer values (or values outside the range) into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

TCL_LINK_LONG
  C 変数､又は､C配列のそれぞれの要素は long 型である｡ Tcl 変数に書かれた如何なる値も Tcl_GetLongFromObj に受入れられる適切な整数形式でなければならない; 非整数又は範囲外の値を varName に書込む試みは拒絶され Tcl 不都合を伴う｡不完全な整数表現（空文字列､ '+'や '-'や十六進/八進/十進/二進 の前置辞､の様な）も妥当として受入れられ得る｡ 　　 The C variable, or each element of the C array, is of type long. Any value written into the Tcl variable must have a proper integer form acceptable to Tcl_GetLongFromObj; attempts to write non-integer or out-of-range values into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

TCL_LINK_ULONG
  C 変数､又は､C配列のそれぞれの要素は unsigned long 型である｡ Tcl 変数に書かれた如何なる値も Tcl_GetWideIntFromObj に受入れられる適切な符号なし整数形式でなければならず､且つOSによって unsigned long 型について定義された範囲内でなければならない; 非整数値(又は範囲外の値)を varName に書込む試みは拒絶され Tcl 不都合を伴う｡不完全な整数表現（空文字列､ '+'や '-'や十六進/八進/十進/二進 の前置辞､の様な）も妥当として受入れられ得る｡ 　　 The C variable, or each element of the C array, is of type unsigned long. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to Tcl_GetWideIntFromObj and in the platform's defined range for the unsigned long type; attempts to write non-integer values (or values outside the range) into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

TCL_LINK_DOUBLE
  C 変数､又は､C配列のそれぞれの要素は double 型である｡ Tcl 変数に書かれた如何なる値も Tcl_GetDoubleFromObj に受入れられる適切な実数形式でなければならない; 非実数値を varName に書込む試みは拒絶され Tcl 不都合を伴う｡不完全な整数又は実数表現（空文字列､ '+'や '-'や十六進/八進/十進/二進 の前置辞､の様な）も妥当として受入れられ得る｡ The C variable, or each element of the C array, is of type double. Any value written into the Tcl variable must have a proper real form acceptable to Tcl_GetDoubleFromObj; attempts to write non-real values into varName will be rejected with Tcl errors. Incomplete integer or real representations (like the empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

TCL_LINK_FLOAT
  C 変数､又は､C配列のそれぞれの要素は float 型である｡ Tcl 変数に書かれた如何なる値も Tcl_GetDoubleFromObj に受入れられる適切な実数形式形式でなければならず､且つ float 型について受入れられる範囲内でなければならない; 非実数値(又は範囲外の値)を varName に書込む試みは拒絶され Tcl 不都合を伴う｡不完全な整数又は実数表現（空文字列､ '+'や '-'や十六進/八進/十進/二進 の前置辞､の様な）も妥当として受入れられ得る｡ 　 The C variable, or each element of the C array, is of type float. Any value written into the Tcl variable must have a proper real form acceptable to Tcl_GetDoubleFromObj and must be within the range acceptable for a float; attempts to write non-real values (or values outside the range) into varName will be rejected with Tcl errors. Incomplete integer or real representations (like the empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

TCL_LINK_WIDE_INT
  C 変数､又は､C配列のそれぞれの要素は Tcl_WideInt 型である(それは整数型で全てのOS上で少なくとも 64-ビット巾で運営可能なもの)｡ Tcl 変数に書かれた如何なる値も Tcl_GetWideIntFromObj に受入れられる適切な整数形式でなければならない; 非整数値を varName に書込む試みは拒絶され Tcl 不都合を伴う｡不完全な整数表現（空文字列､ '+'や '-'や十六進/八進/十進/二進 の前置辞､の様な）も妥当として受入れられ得る｡ 　 The C variable, or each element of the C array, is of type Tcl_WideInt (which is an integer type at least 64-bits wide on all platforms that can support it.) Any value written into the Tcl variable must have a proper integer form acceptable to Tcl_GetWideIntFromObj; attempts to write non-integer values into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

TCL_LINK_WIDE_UINT
  C 変数､又は､C配列のそれぞれの要素は Tcl_WideUInt 型(それは符号なし整数型で､運営可能な全てのOS上で､少なくとも 64-ビット巾のもの)である｡ Tcl 変数に書かれた如何なる値も Tcl_GetWideUIntFromObj に受入れられる適切な符号なし長精度整数形式を持たねばならない; varNameへの非-整数の書込みの試みはTcl不都合を伴い拒絶される｡ 不完全な整数表現（空文字列や､'+'や '-'や十六進/八進/十進/二進 前置辞 の様な）も妥当として受入れられ得る｡ 　 The C variable, or each element of the C array, is of type Tcl_WideUInt (which is an unsigned integer type at least 64-bits wide on all platforms that can support it.) Any value written into the Tcl variable must have a proper unsigned wideinteger form acceptable to Tcl_GetWideUIntFromObj; attempts to write non-integer values into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

TCL_LINK_BOOLEAN
  C 変数､又は､C配列のそれぞれの要素は int 型である｡もしその値が零であれば Tcl から “0” として読み; それ以外は Tcl から “1” として読む｡何時であれ､ varName が修正される時は､ C 変数は 0 か 1 に設定される｡ Tcl に書かれた如何なる値も Tcl_GetBooleanFromObj に受入れられる適切な論理値形式でなければならない; 非論理値を varName に書込む試みは拒絶され Tcl 不都合を伴う｡ 　　 The C variable, or each element of the C array, is of type int. If its value is zero then it will read from Tcl as “0”; otherwise it will read from Tcl as “1”. Whenever varName is modified, the C variable will be set to a 0 or 1 value. Any value written into the Tcl variable must have a proper boolean form acceptable to Tcl_GetBooleanFromObj; attempts to write non-boolean values into varName will be rejected with Tcl errors.

TCL_LINK_STRING
  C 変数は char * 型である｡もしその値が NULL でなければ Tcl_Alloc によって割当られた文字列へのポインターでなければならない｡何時であれ､Tcl 変数が修正された時は現在の C 文字列は解放され新しい変数の値の複写を保有する為に新しい記憶域が割付られる｡もし C 変数が NULL ポインターを保有していた場合､ Tcl 変数は “NULL” として読む｡これは Tcl_LinkVar によってのみ運営されている｡ The C variable is of type char *. If its value is not NULL then it must be a pointer to a string allocated with Tcl_Alloc. Whenever the Tcl variable is modified the current C string will be freed and new memory will be allocated to hold a copy of the variable's new value. If the C variable contains a NULL pointer then the Tcl variable will read as “NULL”. This is only supported by Tcl_LinkVar.

もし TCL_LINK_READ_ONLY 旗印が type 内に存在すると変数は Tcl から読出し専用になるので､その値は C 変数の修正によってのみ変更される｡ Tcl からの変数変更の試みは拒絶され不都合を伴う｡ 　　　 If the TCL_LINK_READ_ONLY flag is present in type then the variable will be read-only from Tcl, so that its value can only be changed by modifying the C variable. Attempts to write the variable from Tcl will be rejected with errors.

Tcl_UnlinkVar は varName によって変数の為に以前に設定された連結を取り去る｡もし varName のための連結が実在しない場合この手続函数は効果を持たない｡ Tcl_UnlinkVar removes the link previously set up for the variable given by varName. If there does not exist a link for varName then the procedure has no effect.

Tcl_UpdateLinkedVar は C 変数が変更された後ですぐさま Tcl 変数を強制定期に更新する為に起動されるかもしれない｡多くの場合､この手続函数は必要ではない､理由はどの Tcl 変数を読む試みも最新の C 変数の値を返すから｡しかしもし Tcl 変数に追跡が設定されている場合(譬えば Tk 部品が変数の値を表示したい場合)追跡は C 変数が変更された時には発動されない｡ Tcl_UpdateLinkedVar may be invoked after the C variable has changed to force the Tcl variable to be updated immediately. In many cases this procedure is not needed, since any attempt to read the Tcl variable will return the latest value of the C variable. However, if a trace has been set on the Tcl variable (such as a Tk widget that wishes to display the value of the variable), the trace will not trigger when the C variable has changed. Tcl_UpdateLinkedVar ensures that any traces on the Tcl variable are invoked.

註意すべきはどの Tcl 解釈実行機能の呼出しも Tcl_UpdateLinkedVar は解釈実行機能によって作成された同じ時分割片から呼出されなければならない｡最も安全な仕組みは C 変数が解釈実行機能によって作成された同じ時分割片のみから更新されることである(可能なら Tcl_ThreadQueueEvent によって送られた行事に反応して)が､別の時分割片内で変数を更新する必要がある時､ Tcl_UpdateLinkedVar を実行する解釈実行機能を時分割割当てを指し示す為に Tcl_AsyncMark を使うことを推奨する｡ 　　　　　 Note that, as with any call to a Tcl interpreter, Tcl_UpdateLinkedVar must be called from the same thread that created the interpreter. The safest mechanism is to ensure that the C variable is only ever updated from the same thread that created the interpreter (possibly in response to an event posted with Tcl_ThreadQueueEvent), but when it is necessary to update the variable in a separate thread, it is advised that Tcl_AsyncMark be used to indicate to the thread hosting the interpreter that it is ready to run Tcl_UpdateLinkedVar.

### SEE ALSO

Tcl_TraceVar

### KEYWORDS

boolean, integer, link, read-only, real, string, trace, variable
Copyright © 1993 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.