Tcl Source Code

Check-in [3c244a994e]
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Docs
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | tip-312-new
Files: files | file ages | folders
SHA3-256: 3c244a994e2fb07ecb9bd1d27f57955c8a30f66157950a4143ddc233b6a6e0ef
User & Date: dkf 2019-04-03 12:22:07
Context
2019-04-04
08:52
Split up tests to get better focus on what is being tested check-in: 84706f16ce user: dkf tags: tip-312-new
2019-04-03
12:22
Docs check-in: 3c244a994e user: dkf tags: tip-312-new
09:36
refactor; mark broken tests as broken check-in: b3ffd86e9b user: dkf tags: tip-312-new
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to doc/LinkVar.3.

     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\"
     8      8   .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
     9      9   .so man.macros
    10     10   .BS
    11     11   .SH NAME
    12         -Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
           12  +Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
    13     13   .SH SYNOPSIS
    14     14   .nf
    15     15   \fB#include <tcl.h>\fR
    16     16   .sp
    17     17   int
    18     18   \fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR)
           19  +.sp
           20  +.VS "TIP 312"
           21  +int
           22  +\fBTcl_LinkArray\fR(\fIinterp, varName, addr, type, size\fR)
           23  +.VE "TIP 312"
    19     24   .sp
    20     25   \fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
    21     26   .sp
    22     27   \fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
    23     28   .SH ARGUMENTS
    24         -.AS Tcl_Interp writable
           29  +.AS Tcl_Interp varName in
    25     30   .AP Tcl_Interp *interp in
    26     31   Interpreter that contains \fIvarName\fR.
    27     32   Also used by \fBTcl_LinkVar\fR to return error messages.
    28     33   .AP "const char" *varName in
    29     34   Name of global variable.
    30         -.AP char *addr in
           35  +.AP void *addr in
    31     36   Address of C variable that is to be linked to \fIvarName\fR.
    32     37   .AP int type in
    33         -Type of C variable.  Must be one of \fBTCL_LINK_INT\fR,
           38  +Type of C variable for \fBTcl_LinkVar\fR or type of array element for
           39  +\fBTcl_LinkArray\fR.  Must be one of \fBTCL_LINK_INT\fR,
    34     40   \fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR,
    35     41   \fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR,
    36     42   \fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR,
    37         -\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR,
    38         -\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or
    39         -\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR
    40         -to make Tcl variable read-only.
           43  +\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, \fBTCL_LINK_DOUBLE\fR,
           44  +\fBTCL_LINK_BOOLEAN\fR, or one of the extra ones listed below.
           45  +.sp
           46  +In \fBTcl_LinkVar\fR, the additional linked type \fBTCL_LINK_STRING\fR may be
           47  +used.
           48  +.sp
           49  +.VS "TIP 312"
           50  +In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and
           51  +\fBTCL_LINK_BYTES\fR may be used.  \fBTCL_LINK_ALLOC\fR may also be OR'ed in
           52  +to tell Tcl to manage the storage for the array in the variable (that is, the
           53  +C variable is technically a pointer to an array, not the array itself).
           54  +.VE "TIP 312"
           55  +.sp
           56  +All the above for both functions may be
           57  +optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR to make the Tcl
           58  +variable read-only.
           59  +.AP int size in
           60  +.VS "TIP 312"
           61  +The number of elements in the C array. Must be greater than zero.
           62  +.VE "TIP 312"
    41     63   .BE
    42     64   .SH DESCRIPTION
    43     65   .PP
    44     66   \fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable
    45     67   named by \fIvarName\fR in sync with the C variable at the address
    46     68   given by \fIaddr\fR.
    47     69   Whenever the Tcl variable is read the value of the C variable will
    48     70   be returned, and whenever the Tcl variable is written the C
    49     71   variable will be updated to have the same value.
    50     72   \fBTcl_LinkVar\fR normally returns \fBTCL_OK\fR;  if an error occurs
    51     73   while setting up the link (e.g. because \fIvarName\fR is the
    52     74   name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result
    53     75   contains an error message.
           76  +.PP
           77  +.VS "TIP 312"
           78  +\fBTcl_LinkArray\fR is similar, but for arrays of fixed size (given by
           79  +the \fIsize\fR argument). When asked to allocate the backing C array
           80  +storage (via the \fBTCL_LINK_ALLOC\fR bit), it writes the address that
           81  +it allocated to the Tcl interpreter result in addition to storing the
           82  +location of the array in the C variable pointed to by \fIaddr\fR.
           83  +.VE "TIP 312"
    54     84   .PP
    55     85   The \fItype\fR argument specifies the type of the C variable,
           86  +or the type of the elements of the C array,
    56     87   and must have one of the following values, optionally OR'ed with
    57     88   \fBTCL_LINK_READ_ONLY\fR:
    58     89   .TP
    59     90   \fBTCL_LINK_INT\fR
    60         -The C variable is of type \fBint\fR.
           91  +.
           92  +The C variable, or each element of the C array, is of type \fBint\fR.
    61     93   Any value written into the Tcl variable must have a proper integer
    62     94   form acceptable to \fBTcl_GetIntFromObj\fR;  attempts to write
    63     95   non-integer values into \fIvarName\fR will be rejected with
    64     96   Tcl errors. Incomplete integer representations (like the empty
    65     97   string, '+', '-' or the hex/octal/binary prefix) are accepted
    66     98   as if they are valid too.
    67     99   .TP
    68    100   \fBTCL_LINK_UINT\fR
    69         -The C variable is of type \fBunsigned int\fR.
          101  +.
          102  +The C variable, or each element of the C array, is of type \fBunsigned int\fR.
    70    103   Any value written into the Tcl variable must have a proper unsigned
    71    104   integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
    72    105   platform's defined range for the \fBunsigned int\fR type; attempts to
    73    106   write non-integer values (or values outside the range) into
    74    107   \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
    75    108   representations (like the empty string, '+', '-' or the hex/octal/binary
    76    109   prefix) are accepted as if they are valid too.
    77    110   .TP
    78    111   \fBTCL_LINK_CHAR\fR
    79         -The C variable is of type \fBchar\fR.
          112  +.
          113  +The C variable, or each element of the C array, is of type \fBchar\fR.
    80    114   Any value written into the Tcl variable must have a proper integer
    81    115   form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
    82    116   \fBchar\fR datatype; attempts to write non-integer or out-of-range
    83    117   values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
    84    118   integer representations (like the empty string, '+', '-' or the
    85    119   hex/octal/binary prefix) are accepted as if they are valid too.
          120  +.RS
          121  +.PP
          122  +.VS "TIP 312"
          123  +If using an array of these, consider using \fBTCL_LINK_CHARS\fR instead.
          124  +.VE "TIP 312"
          125  +.RE
          126  +.TP
          127  +\fBTCL_LINK_CHARS\fR
          128  +.VS "TIP 312"
          129  +The C array is of type \fBchar *\fR and is mapped into Tcl as a string.
          130  +Any value written into the Tcl variable must have the same length as
          131  +the underlying storage. Only supported with \fBTcl_LinkArray\fR.
          132  +.VE "TIP 312"
    86    133   .TP
    87    134   \fBTCL_LINK_UCHAR\fR
    88         -The C variable is of type \fBunsigned char\fR.
          135  +.
          136  +The C variable, or each element of the C array, is of type \fBunsigned char\fR.
    89    137   Any value written into the Tcl variable must have a proper unsigned
    90    138   integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
    91    139   platform's defined range for the \fBunsigned char\fR type; attempts to
    92    140   write non-integer values (or values outside the range) into
    93    141   \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
    94    142   representations (like the empty string, '+', '-' or the hex/octal/binary
    95    143   prefix) are accepted as if they are valid too.
          144  +.RS
          145  +.PP
          146  +.VS "TIP 312"
          147  +If using an array of these, consider using \fBTCL_LINK_BYTES\fR instead.
          148  +.VE "TIP 312"
          149  +.RE
          150  +.TP
          151  +\fBTCL_LINK_BYTES\fR
          152  +.VS "TIP 312"
          153  +The C array is of type \fBunsigned char *\fR and is mapped into Tcl
          154  +as a bytearray.
          155  +Any value written into the Tcl variable must have the same length as
          156  +the underlying storage. Only supported with \fBTcl_LinkArray\fR.
          157  +.VE "TIP 312"
    96    158   .TP
    97    159   \fBTCL_LINK_SHORT\fR
    98         -The C variable is of type \fBshort\fR.
          160  +.
          161  +The C variable, or each element of the C array, is of type \fBshort\fR.
    99    162   Any value written into the Tcl variable must have a proper integer
   100    163   form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
   101    164   \fBshort\fR datatype; attempts to write non-integer or out-of-range
   102    165   values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
   103    166   integer representations (like the empty string, '+', '-' or the
   104    167   hex/octal/binary prefix) are accepted as if they are valid too.
   105    168   .TP
   106    169   \fBTCL_LINK_USHORT\fR
   107         -The C variable is of type \fBunsigned short\fR.
          170  +.
          171  +The C variable, or each element of the C array, is of type \fBunsigned short\fR.
   108    172   Any value written into the Tcl variable must have a proper unsigned
   109    173   integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
   110    174   platform's defined range for the \fBunsigned short\fR type; attempts to
   111    175   write non-integer values (or values outside the range) into
   112    176   \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
   113    177   representations (like the empty string, '+', '-' or the hex/octal/binary
   114    178   prefix) are accepted as if they are valid too.
   115    179   .TP
   116    180   \fBTCL_LINK_LONG\fR
   117         -The C variable is of type \fBlong\fR.
          181  +.
          182  +The C variable, or each element of the C array, is of type \fBlong\fR.
   118    183   Any value written into the Tcl variable must have a proper integer
   119    184   form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write
   120    185   non-integer or out-of-range
   121    186   values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
   122    187   integer representations (like the empty string, '+', '-' or the
   123    188   hex/octal/binary prefix) are accepted as if they are valid too.
   124    189   .TP
   125    190   \fBTCL_LINK_ULONG\fR
   126         -The C variable is of type \fBunsigned long\fR.
          191  +.
          192  +The C variable, or each element of the C array, is of type \fBunsigned long\fR.
   127    193   Any value written into the Tcl variable must have a proper unsigned
   128    194   integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
   129    195   platform's defined range for the \fBunsigned long\fR type; attempts to
   130    196   write non-integer values (or values outside the range) into
   131    197   \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
   132    198   representations (like the empty string, '+', '-' or the hex/octal/binary
   133    199   prefix) are accepted as if they are valid too.
   134    200   .TP
   135    201   \fBTCL_LINK_DOUBLE\fR
   136         -The C variable is of type \fBdouble\fR.
          202  +.
          203  +The C variable, or each element of the C array, is of type \fBdouble\fR.
   137    204   Any value written into the Tcl variable must have a proper real
   138    205   form acceptable to \fBTcl_GetDoubleFromObj\fR;  attempts to write
   139    206   non-real values into \fIvarName\fR will be rejected with
   140    207   Tcl errors. Incomplete integer or real representations (like the
   141    208   empty string, '.', '+', '-' or the hex/octal/binary prefix) are
   142    209   accepted as if they are valid too.
   143    210   .TP
   144    211   \fBTCL_LINK_FLOAT\fR
   145         -The C variable is of type \fBfloat\fR.
          212  +.
          213  +The C variable, or each element of the C array, is of type \fBfloat\fR.
   146    214   Any value written into the Tcl variable must have a proper real
   147    215   form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the
   148    216   range acceptable for a \fBfloat\fR; attempts to
   149    217   write non-real values (or values outside the range) into
   150    218   \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
   151    219   or real representations (like the empty string, '.', '+', '-' or
   152    220   the hex/octal/binary prefix) are accepted as if they are valid too.
   153    221   .TP
   154    222   \fBTCL_LINK_WIDE_INT\fR
   155         -The C variable is of type \fBTcl_WideInt\fR (which is an integer type
          223  +.
          224  +The C variable, or each element of the C array, is of type \fBTcl_WideInt\fR
          225  +(which is an integer type
   156    226   at least 64-bits wide on all platforms that can support it.)
   157    227   Any value written into the Tcl variable must have a proper integer
   158    228   form acceptable to \fBTcl_GetWideIntFromObj\fR;  attempts to write
   159    229   non-integer values into \fIvarName\fR will be rejected with
   160    230   Tcl errors. Incomplete integer representations (like the empty
   161    231   string, '+', '-' or the hex/octal/binary prefix) are accepted
   162    232   as if they are valid too.
   163    233   .TP
   164    234   \fBTCL_LINK_WIDE_UINT\fR
   165         -The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned
   166         -integer type at least 64-bits wide on all platforms that can support
   167         -it.)
          235  +.
          236  +The C variable, or each element of the C array, is of type \fBTcl_WideUInt\fR
          237  +(which is an unsigned integer type at least 64-bits wide on all platforms that
          238  +can support it.)
   168    239   Any value written into the Tcl variable must have a proper unsigned
   169    240   integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be
   170    241   cast to unsigned);
   171    242   .\" FIXME! Use bignums instead.
   172    243   attempts to write non-integer values into \fIvarName\fR will be
   173    244   rejected with Tcl errors. Incomplete integer representations (like
   174    245   the empty string, '+', '-' or the hex/octal/binary prefix) are accepted
   175    246   as if they are valid too.
   176    247   .TP
   177    248   \fBTCL_LINK_BOOLEAN\fR
   178         -The C variable is of type \fBint\fR.
          249  +.
          250  +The C variable, or each element of the C array, is of type \fBint\fR.
   179    251   If its value is zero then it will read from Tcl as
   180    252   .QW 0 ;
   181    253   otherwise it will read from Tcl as
   182    254   .QW 1 .
   183    255   Whenever \fIvarName\fR is
   184    256   modified, the C variable will be set to a 0 or 1 value.
   185    257   Any value written into the Tcl variable must have a proper boolean
   186    258   form acceptable to \fBTcl_GetBooleanFromObj\fR;  attempts to write
   187    259   non-boolean values into \fIvarName\fR will be rejected with
   188    260   Tcl errors.
   189    261   .TP
   190    262   \fBTCL_LINK_STRING\fR
          263  +.
   191    264   The C variable is of type \fBchar *\fR.
   192    265   If its value is not NULL then it must be a pointer to a string
   193    266   allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
   194    267   Whenever the Tcl variable is modified the current C string will be
   195    268   freed and new memory will be allocated to hold a copy of the variable's
   196    269   new value.
   197    270   If the C variable contains a NULL pointer then the Tcl variable
   198    271   will read as
   199    272   .QW NULL .
          273  +This is only supported by \fBTcl_LinkVar\fR.
   200    274   .PP
   201    275   If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the
   202    276   variable will be read-only from Tcl, so that its value can only be
   203    277   changed by modifying the C variable.
   204    278   Attempts to write the variable from Tcl will be rejected with errors.
   205    279   .PP
   206    280   \fBTcl_UnlinkVar\fR removes the link previously set up for the

Changes to generic/tcl.decls.

   663    663   }
   664    664   # Obsolete, use Tcl_FSJoinPath
   665    665   declare 186 {
   666    666       char *Tcl_JoinPath(int argc, const char *const *argv,
   667    667   	    Tcl_DString *resultPtr)
   668    668   }
   669    669   declare 187 {
   670         -    int Tcl_LinkVar(Tcl_Interp *interp, const char *varName, char *addr,
          670  +    int Tcl_LinkVar(Tcl_Interp *interp, const char *varName, void *addr,
   671    671   	    int type)
   672    672   }
   673    673   
   674    674   # This slot is reserved for use by the plus patch:
   675    675   #  declare 188 {
   676    676   #	Tcl_MainLoop
   677    677   #  }

Changes to generic/tclDecls.h.

   593    593   /* 185 */
   594    594   EXTERN int		Tcl_IsSafe(Tcl_Interp *interp);
   595    595   /* 186 */
   596    596   EXTERN char *		Tcl_JoinPath(int argc, const char *const *argv,
   597    597   				Tcl_DString *resultPtr);
   598    598   /* 187 */
   599    599   EXTERN int		Tcl_LinkVar(Tcl_Interp *interp, const char *varName,
   600         -				char *addr, int type);
          600  +				void *addr, int type);
   601    601   /* Slot 188 is reserved */
   602    602   /* 189 */
   603    603   EXTERN Tcl_Channel	Tcl_MakeFileChannel(ClientData handle, int mode);
   604    604   /* 190 */
   605    605   EXTERN int		Tcl_MakeSafe(Tcl_Interp *interp);
   606    606   /* 191 */
   607    607   EXTERN Tcl_Channel	Tcl_MakeTcpClientChannel(ClientData tcpSocket);
................................................................................
  2119   2119       int (*tcl_Init) (Tcl_Interp *interp); /* 180 */
  2120   2120       void (*tcl_InitHashTable) (Tcl_HashTable *tablePtr, int keyType); /* 181 */
  2121   2121       int (*tcl_InputBlocked) (Tcl_Channel chan); /* 182 */
  2122   2122       int (*tcl_InputBuffered) (Tcl_Channel chan); /* 183 */
  2123   2123       int (*tcl_InterpDeleted) (Tcl_Interp *interp); /* 184 */
  2124   2124       int (*tcl_IsSafe) (Tcl_Interp *interp); /* 185 */
  2125   2125       char * (*tcl_JoinPath) (int argc, const char *const *argv, Tcl_DString *resultPtr); /* 186 */
  2126         -    int (*tcl_LinkVar) (Tcl_Interp *interp, const char *varName, char *addr, int type); /* 187 */
         2126  +    int (*tcl_LinkVar) (Tcl_Interp *interp, const char *varName, void *addr, int type); /* 187 */
  2127   2127       void (*reserved188)(void);
  2128   2128       Tcl_Channel (*tcl_MakeFileChannel) (ClientData handle, int mode); /* 189 */
  2129   2129       int (*tcl_MakeSafe) (Tcl_Interp *interp); /* 190 */
  2130   2130       Tcl_Channel (*tcl_MakeTcpClientChannel) (ClientData tcpSocket); /* 191 */
  2131   2131       char * (*tcl_Merge) (int argc, const char *const *argv); /* 192 */
  2132   2132       Tcl_HashEntry * (*tcl_NextHashEntry) (Tcl_HashSearch *searchPtr); /* 193 */
  2133   2133       void (*tcl_NotifyChannel) (Tcl_Channel channel, int mask); /* 194 */

Changes to generic/tclLink.c.

    25     25   
    26     26   typedef struct Link {
    27     27       Tcl_Interp *interp;		/* Interpreter containing Tcl variable. */
    28     28       Tcl_Obj *varName;		/* Name of variable (must be global). This is
    29     29   				 * needed during trace callbacks, since the
    30     30   				 * actual variable may be aliased at that time
    31     31   				 * via upvar. */
    32         -    char *addr;			/* Location of C variable. */
           32  +    void *addr;			/* Location of C variable. */
    33     33       int bytes;			/* Size of C variable array. This is 0 when
    34     34   				 * single variables, and >0 used for array
    35     35   				 * variables. */
    36     36       int numElems;		/* Number of elements in C variable array.
    37     37   				 * Zero for single variables. */
    38     38       int type;			/* Type of link (TCL_LINK_INT, etc.). */
    39     39       union {
................................................................................
   133    133    *----------------------------------------------------------------------
   134    134    */
   135    135   
   136    136   int
   137    137   Tcl_LinkVar(
   138    138       Tcl_Interp *interp,		/* Interpreter in which varName exists. */
   139    139       const char *varName,	/* Name of a global variable in interp. */
   140         -    char *addr,			/* Address of a C variable to be linked to
          140  +    void *addr,			/* Address of a C variable to be linked to
   141    141   				 * varName. */
   142    142       int type)			/* Type of C variable: TCL_LINK_INT, etc. Also
   143    143   				 * may have TCL_LINK_READ_ONLY OR'ed in. */
   144    144   {
   145    145       Tcl_Obj *objPtr;
   146    146       Link *linkPtr;
   147    147       int code;