TIP:		160
Title:		Improvements to Terminal and Serial Channel Handling
State:		Draft
Type:		Project
Tcl-Version:	8.5
Vote:		Pending
Post-History:	
Version:	$Revision: 1.1 $
Author:		Donal K. Fellows <donal.k.fellows@man.ac.uk>
Created:	17-Oct-2003

~ Abstract

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.

~ 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 [35].  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:
''-closemode''.  This will have two legal values:

 drain: Closing the channel will result in a delay until the entire
 contents of the OS buffers are written.  This is the current default.

 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.

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.

~ 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): ''-inputmode''.  This will have three legal values:

 normal: This will turn on both echoing and cooking of input, and can
 be considered to be the default configuration for all terminals.

 password: This will turn off echoing but leave cooking turned on.

 raw: This will turn off both echoing and line-cooking.

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
''-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 ''-inputmode'' option will be
system- and configuration-dependant, since users can use the ''stty''
program to configure their terminals prior to calling Tcl.

~ Copyright

This document has been placed in the public domain.
