\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#340: Const Qualification of Tcl\_SetResult's Argument}
\date{November 14, 2008}
\author{Jan Nijtmans}
\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 \#340}&\textbf{Const Qualification of Tcl\_SetResult's Argument}\\\hline
Author&

Jan Nijtmans \tipmail{nijtmans}{users.sourceforge.net}
\\
Created&Friday, \(\text{14}^{\text{th}}\) November 2008\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Withdrawn\\
Vote&Pending\\
Version&\tipversion$Revision: 1.8 $\\
Keywords&Tcl\_SetResult\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

As a follow-up of \cite{tip27}, in Tcl 8.6 and Tk 8.6 much work has been done to clean up the remaining places where pointers were not \textit{const} qualified. The question is, how can we prevent that in the future similar ``mistakes'' are made. The gcc compiler warning \textit{-Wwrite-strings} helps in that, therefore this TIP proposes to add that to the CFLAGS\_WARNING flag in Tcl and Tk when using gcc. But for this flag to be introduced, all warnings will have to be eliminated. In the HEAD, this is done already, except for one function: \textbf{Tcl\_SetResult}. This function is explicitely mentioned in \cite{tip27} not to be modified, because it cannot be handled without unsafe casting. This TIP proposes to deprecate \textbf{Tcl\_SetResult} in full, and provide a new macro \textbf{Tcl\_SetStringResult} in its place.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The gcc manual mentions for the flag -Wwrite-strings:

\begin{quote}
When compiling C, give string constants the type \textit{const char[length]} so that copying the address of one into a non-\textit{const char *} pointer will get a warning .... These warnings will help you find at compile time code that can try to write into a string constant, but only if you have been very careful about using const in declarations and prototypes. Otherwise, it will just be a nuisance; this is why we did not make -Wall request these warnings.
\end{quote}

Now that all Tcl and Tk API's are modified to be very careful about using const, this opens the way to add \textit{-Wwrite-strings} to CFLAGS\_WARNING when building with gcc. Other extensions can start to do the same, if they want to find out about this type of potential problem.

When considering the elimination of the warning when using \textit{'Tcl\_SetResult}, I originally see two alternatives:
\begin{itemize}
\item{}
Change the implementation such that \textbf{Tcl\_SetResult}(\textit{i, s, f}) does the same as \textbf{Tcl\_SetObjResult}(\textit{i}, \textbf{Tcl\_NewStringObj}(\textit{s}, -1)), ignoring the last parameter.

This can be done without an unsafe type cast, but it has the disadvantage that after a (modified) \textbf{Tcl\_SetResult} call the result is no longer available in interp-\tiprangle{}result. Older extensions might expect that, those will be silently broken. A the moment, serveral tests fail when doing this, because in various places of the Tcl core there are hack which still support older extensions which still use interp-\tiprangle{}result directly. It's a little short before Tcl 8.6 to do it now, but it should certainly be considered for the future.
\item{}
The solution that originally was proposed in this TIP was to leave the \textbf{Tcl\_SetResult} implementation as it is, only add a single type cast to prevent a gcc warning.

This violates the \cite{tip27} conditions, but is in fact not more dangerous than the current situation. It is only dangerous, when the Tcl\_SetResult call has another value than TCL\_STATIC or TCL\_VOLATILE as last argument
\item{}
The final proposal is a new macro \textbf{Tcl\_SetStringResult} that takes over the function of \textbf{Tcl\_SetResult}. The function \textbf{Tcl\_SetResult} will be deprecated in full.
\end{itemize}

There has been a discussion stating that changing the \textbf{Tcl\_SetResult} signature is wrong, because \textbf{Tcl\_SetResult} cannot be made const-correct.

Most \textbf{Tcl\_SetResult} calls use TCL\_STATIC or TCL\_VOLATILE as last argument. In this case, the second argument is expected to be a const. The macro \textbf{Tcl\_SetStringResult} takes care of that, since it is implemented in terms of \textbf{Tcl\_SetObjResult} and \textbf{Tcl\_NewStringObj}.

Very few \textbf{Tcl\_SetResult} calls have some other value as last argument, most likely TCL\_DYNAMIC. This TIP proposes to deprecate \textbf{Tcl\_SetResult} for all values of freeProc. If the value is TCL\_STATIC or TCL\_VOLATILE, there is a new macro \textbf{Tcl\_SetStringResult} which can be used in stead. For other values the call can be replaced with \textbf{Tcl\_SetStringResult} as well, but then the caller is responsible to free the memory after the \textbf{Tcl\_SetStringResult} call.

It turns out that Tcl had only 4 deprecated (as defined by this TIP) \textbf{Tcl\_SetResult} calls, one of them was wrong [Bug 2308236], two of them were in tclTest.c meant to test the \textbf{Tcl\_SetResult} function itself. Tk had only 5 such calls. All those calls have been modified now. Tcl and Tk now only calls \textbf{Tcl\_SetResult} with either TCL\_STATIC or TCL\_VOLATILE

This proposal does not have the ``forward compatibility'' problem, that extensions using \textbf{Tcl\_SetStringResult} compiled. it is even possible for extensions to use \textbf{Tcl\_SetStringResult} with Tcl 8.5 and before:
\begingroup\small\begin{verbatim}
 #ifndef
 #   define Tcl_SetStringResult(i,s) \
     Tcl_SetObjResult(i, Tcl_NewStringObj(s, -1))
 #endif
\end{verbatim}
\endgroup

\section{Reference Implementation}

A new patch will be available in issue \#2315890 [\url{http://sourceforge.net/support/tracker.php/?aid=2315890}].

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#27]{tip27}
Kevin Kenny,
\emph{CONST Qualification on Pointers in Tcl API's},
on-line at \url{http://purl.org/tcl/tip/27.html}
\end{thebibliography}
\end{document}
