\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#160: Improvements to Terminal and Serial Channel Handling}
\date{October 17, 2003}
\author{Donal K. Fellows}
\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 \#160}&\textbf{Improvements to Terminal and Serial Channel Handling}\\\hline
Author&

Donal K. Fellows \tipmail{donal.k.fellows}{man.ac.uk}
\\
Created&Friday, \(\text{17}^{\text{th}}\) October 2003\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.3 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Terminals and other kinds of serial lines have other capabilities and requirements that are not currently controllable using Tcl. This TIP adds new options to [fconfigure] to allow these advanced capabilities to be supported within Tcl in a straight-forward way.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Serial Line Discard Control}

Serial lines are much slower devices than virtually anything else on a modern computer, and it is quite possible for them to take a very long time to read data. Often, making sure all the data gets across is important. But this is not universally the case, and sometimes it is more useful to discard the output bound for the serial line that is pending in the operating system's own buffers. This can't be enabled by default in any configuration though, since there is no trivial way to distinguish automatically between terminals that are having debugging information written to them and serial lines that were opened for data manipulation and where closing quickly is desirable (you can't tell them apart even by device major/minor numbers due to the way that /dev/tty is aliased inside the kernel on many Unixes.) This was even the subject of a subtle bug (\#525783) in \cite{tip35}. But since it is still useful, having it controllable by an explicit option is useful.

I propose a new option for serial channels on all platforms: \textit{-closemode}. This will have two legal values:
\begin{description}
\item[drain]
Closing the channel will result in a delay until the entire contents of the OS buffers are written. This is the current default.
\item[discard]
Closing the channel will result in any data in the OS buffers to be thrown away. This can result in data that is being written by other processes being lost.
\end{description}

This option will be supported on all platforms where the underlying serial API is sufficiently capable. Where it is not supported, the option will not be defined on serial channels.

\section{Echo and Cooking Control}

Terminals have a number of modes of operation. Two of the most useful things that can be set relate to echoing and cooking.

Echoing is fairly simple to understand. If a terminal has echoing turned on, every character read is written to the terminal automatically without any action from the program reading from the terminal. Most of the time this is a good thing as people want to see what they have typed, but sometimes it is not so good. Examples include where someone is typing in a password (when they also want their lines cooked) and where an application is being controlled by single key-presses (which is a case where neither echoing or cooking are desirable, with echoing being a problem because the key press is causing a different set of visible changes in the program's output.)

Cooking is also fairly simple. A terminal is producing cooked input when it is working in simply-editable line-at-a-time mode. When the terminal isn't in cooked mode, it delivers raw input directly and immediately to the program. Cooked input is the default and is useful for a lot of purposes, but sometimes (when the application wants to use single key-presses to control it) raw input is definitely preferable. Example uses of raw input include text editors (such as vi or emacs) or terminal-based menu systems.

I propose supporting these operation modes within Tcl through a single new option to the [fconfigure] command (to definitely be implemented on Unix serial channels --- because that is the type of stdin in a normal interactive session --- and suitably on other platforms if possible): \textit{-inputmode}. This will have three legal values:
\begin{description}
\item[normal]
This will turn on both echoing and cooking of input, and can be considered to be the default configuration for all terminals.
\item[password]
This will turn off echoing but leave cooking turned on.
\item[raw]
This will turn off both echoing and line-cooking.
\end{description}

I'm not aware off-hand of any use-cases for echoed raw mode. While there is theoretically a problem due to cross-talk between channels (similar to that which was observed with the rationale for the \textit{-closemode} option), it is practically unlikely to be one since applications that take parsed input from several serial lines are very rare.

Officially, the default value of the \textit{-inputmode} option will be system- and configuration-dependant, since users can use the \textit{stty} program to configure their terminals prior to calling Tcl.

\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 \#35]{tip35}
Rolf Schroedter,
\emph{Enhanced Support for Serial Communications},
on-line at \url{http://purl.org/tcl/tip/35.html}
\end{thebibliography}
\end{document}
