Author:         Rene Zaumseil <r.zaumseil@freenet.de>
Author:         Larry W. Virden <lvirden@yahoo.com>
State:          Draft
Type:           Project
Vote:           Pending
Created:        26-Jan-2008
Post-History:   
Keywords:       variable,trace
Tcl-Version:    8.7

Abstract

This TIP proposes adding a command, Tcl_LinkArray, to allow linking of C variables to Tcl lists. It also adds more types of linked variable.

Rationale

The current C-API allows one to only link single variables. The proposed Tcl_LinkArray function allows the linking of C-arrays to Tcl list variables. If the given size value is 1 then it works like the existing Tcl_LinkVar function. The automatic creation of needed space when no address value is provided could be used for testing scenarios.

The new link types also allow one to link from strings and binary arrays to fixed memory locations.

The use of arrays with a given size > 1 allows a safe and simple C-Tcl connection. Array overwrites create errors.

Specification

This document proposes the following changes to the Tcl core:

New C API

Add a new public Tcl_LinkArray function to provide links of single variable and array variables. The new function would have the same parameters as the Tcl_LinkVar function, plus an additional int size. If the given size is 1, then we have the same functionality as before. With size > 1, the linked Tcl variable is a list variable. If the given address is NULL then the function allocates the necessary space on the C side itself.

int Tcl_LinkArray(Tcl_Interp *interp, const char *varName, char *addr, int type, int size)

The following link types will be supported:

TCL_LINK_INT, TCL_LINK_DOUBLE, TCL_LINK_BOOLEAN, TCL_LINK_STRING, TCL_LINK_WIDE_INT, TCL_LINK_CHAR, TCL_LINK_UCHAR, TCL_LINK_SHORT, TCL_LINK_USHORT, TCL_LINK_UINT, TCL_LINK_LONG, TCL_LINK_ULONG, TCL_LINK_FLOAT, TCL_LINK_WIDE_UINT, TCL_LINK_CHARS, TCL_LINK_BINARY

Of these, TCL_LINK_CHARS and TCL_LINK_BINARY are new, and are as defined below:

TCL_LINK_CHARS: The address of the C variable is used as a char *. The address remains always the same (different to TCL_LINK_STRING) and contains a \0 terminated string. The \0 counts towards the given size. The Tcl variable is used as a string and can contain up to size -1 characters.

TCL_LINK_BINARY: The address of the C variable is used as a unsigned char *. The address remains always the same. Read and write operations must always contain the full sized binary string.

Reference Implementation

See https://sourceforge.net/support/tracker.php?aid=1992824 .

Notes

The original TIP proposed a link command to allow these things to be done from the script level; this has been removed in the test suite support because of concerns about safety and security.

Copyright

This document has been placed in the public domain.