\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#312: Add More Link Types}
\date{January 26, 2008}
\author{Rene Zaumseil, Larry W. Virden}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#312}&\textbf{Add More Link Types}\\\hline
Author&

Rene Zaumseil \tipmail{r.zaumseil}{freenet.de}
\par
Larry W. Virden \tipmail{lvirden}{yahoo.com}
\\
Created&Saturday, \(\text{26}^{\text{th}}\) January 2008\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.9 $\\
Keywords&variable, trace\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes adding a command, \textbf{Tcl\_LinkArray}, to allow linking of C variables to Tcl lists. It also adds more types of linked variable.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The current C-API allows one to only link single variables. The proposed \textit{Tcl\_LinkArray} function allows the linking of C-arrays to Tcl list variables. If the given \textit{size} value is 1 then it works like the existing \textit{Tcl\_LinkVar} function. The automatic creation of needed space when no \textit{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 \textit{size \tiprangle{} 1} allows a safe and simple C-Tcl connection. Array overwrites create errors.

\section{Specification}

This document proposes the following changes to the Tcl core:

\subsection{New C API}

Add a new public \textit{Tcl\_LinkArray} function to provide links of single variable and array variables. The new function would have the same parameters as the \textit{Tcl\_LinkVar} function, plus an additional \textit{int size}. If the given size is 1, then we have the same functionality as before. With \textit{size} \tiprangle{} 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.

\begin{quote}
int \textbf{Tcl\_LinkArray}(Tcl\_Interp *\textit{interp}, const char *\textit{varName}, char *\textit{addr}, int \textit{type}, int \textit{size})
\end{quote}

The following link types will be supported:

\begin{quote}
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
\end{quote}

Of these, TCL\_LINK\_CHARS and TCL\_LINK\_BINARY are new, and are as defined below:
\begin{description}
\item[TCL\_LINK\_CHARS]
The address of the C variable is used as a \textit{char *}. The address remains always the same (different to TCL\_LINK\_STRING) and contains a \(\backslash\)0 terminated string. The \(\backslash\)0 counts towards the given \textit{size}. The Tcl variable is used as a string and can contain up to \textit{size -1} characters.
\item[TCL\_LINK\_BINARY]
The address of the C variable is used as a \textit{unsigned char *}. The address remains always the same. Read and write operations must always contain the full sized binary string.
\end{description}

\section{Reference Implementation}

See [\url{https://sourceforge.net/support/tracker.php?aid=1992824}].

\section{Notes}

The original TIP proposed a \textit{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.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
