\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#208: Add a 'chan' Command}
\date{July 02, 2004}
\author{Jeff Hobbs}
\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 \#208}&\textbf{Add a 'chan' Command}\\\hline
Author&

Jeff Hobbs \tipmail{jeffh}{activestate.com}
\\
Created&Friday, \(\text{2}^{\text{nd}}\) July 2004\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.8 $\\
Keywords&Tcl\\
Obsoletes&206\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes adding a \textbf{chan} command that would serve as a top-level command container for all the related channel commands that have proliferated over time, as well as future new channel-based commands.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Tcl's channel system has evolved over time from a thin layer on top of the OS into a very complex, multi-platform system. There are numerous top-level commands for channels already, with more being proposed for Tcl 8.5. This command would centralize them, making it easier for new users to see all the related channel commands, much as \textbf{string} or \textbf{file} operate today.

The name \textbf{chan} was chosen over ``channel'' because it is a clearly recognizable abbreviation, much like \textbf{eval} vs. ``evaluate'' and \textbf{interp} vs ``interpreter''.

\section{Specification}

A new command \textbf{chan} will be added with the following syntax:
\begingroup\small\begin{verbatim}
      chan blocked    ; # fblocked
      chan close      ; # close
      chan configure  ; # fconfigure
      chan copy       ; # fcopy
      chan eof        ; # eof
      chan event      ; # fileevent
      chan flush      ; # flush
      chan gets       ; # gets
      chan names      ; # file channels
      chan puts       ; # puts
      chan read       ; # read
      chan seek       ; # seek
      chan tell       ; # tell
      chan truncate   ; # ftruncate (if TIP#206 had been accepted)
\end{verbatim}
\endgroup

Each represents the existing command that is commented. The arguments to each would remain what the current command takes.

Note that \textbf{open} is not included above, as it is a channel creation function, just like \textbf{socket}.

\subsection{Specification of the 'truncate' Subcommand}

[See \cite{tip206} for Rationale]

\begin{quote}
\textbf{chan truncate} \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. The result of this command will normally be the empty string; any errors from the filesystem when truncating will generate error results in the normal fashion.

\subsection{Deprecation of Existing Commands}

In addition, I would recommend only the following commands be marked deprecated so as to help systematize their names better:
\begingroup\small\begin{verbatim}
      fblocked
      fconfigure
      fcopy
      fileevent
      file channels
\end{verbatim}
\endgroup

\section{Related 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).

\begin{quote}
int \textbf{Tcl\_TruncateChannel}(Tcl\_Channel \textit{chan}, Tcl\_WideInt \textit{length})
\end{quote}

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}

The implementation of the Tcl-level TIP is really a simple command that makes use of the existing command implementations. It could be a namespace ensemble or a C-based command. The \textbf{chan truncate} part will require C code.

\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 \#206]{tip206}
Joe Mistachkin,
\emph{Add an [ftruncate] Command},
on-line at \url{http://purl.org/tcl/tip/206.html}
\end{thebibliography}
\end{document}
