\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#206: Add an [ftruncate] Command}
\date{June 25, 2004}
\author{Joe Mistachkin}
\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 \#206}&\textbf{Add an [ftruncate] Command}\\\hline
Author&

Joe Mistachkin \tipmail{joe}{mistachkin.com}
\\
Created&Friday, \(\text{25}^{\text{th}}\) June 2004\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Rejected\\
Vote&Done\\
Version&\tipversion$Revision: 1.5 $\\
Post History&\\
Obsoleted By&208\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a new command \textbf{ftruncate} for truncating open files.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Note}

This TIP has been effectively rolled into \cite{tip208}.

\section{Rationale}

In Tcl, there is currently no way to truncate a file while it is open even though all modern operating systems support such an operation. The current workaround is to close the file and reopen it. However, in cases where the file must be held open (e.g. on Unix where the file has already been deleted and is just being used as scratch space) this workaround cannot be used.

\section{Specification}

\begin{quote}
\textbf{ftruncate} \textit{channelId} ?\textit{length}?
\end{quote}

The channel specified by \textit{channelId} must refer to a file that was opened for writing. The \textit{length} argument must be greater than or equal to zero and can be bigger than the current size of the file. If the \textit{length} argument is omitted, the file will be truncated at the current access position. This command will return any errors received from the operating system.

\subsection{Example Usage}
\begingroup\small\begin{verbatim}
# Open the file for reading and writing...
set file [open "test.txt" {RDWR}]
# Write some data to the file...
puts $file "test data"

# Some time later...
# ... ... ...
ftruncate $file
# ... ... ...

# We are done, close the file...
close $file
\end{verbatim}
\endgroup

\section{Proposed C API Changes}

A new function named \textbf{Tcl\_TruncateChannel} would be added to the Tcl C API (taking two arguments, the channel to truncate and the length (as a wide integer to facilitate use with large files) to truncate it to in bytes). The channel API would be modified to add the new functionality for standard disk file channels and to allow extension authors to implement it for their custom channel types through specifying in their \textit{Tcl\_ChannelType} structure a value for the new field \textit{truncateProc} (of type pointer to \textit{Tcl\_DriverTruncateProc}, which will be a function with the obvious type signature). Finally, the maximum TCL\_CHANNEL\_VERSION would be increased to TCL\_CHANNEL\_VERSION\_4 to accommodate this new field.

\section{Reference Implementation}

A reference implementation does \textit{not} yet exist.

\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 \#208]{tip208}
Jeff Hobbs,
\emph{Add a 'chan' Command},
on-line at \url{http://purl.org/tcl/tip/208.html}
\end{thebibliography}
\end{document}
