<!doctype linuxdoc system>
<article>
<title> Text-Terminal-HOWTO
<author> David S. Lawyer <url url="mailto:dave@lafn.org">
<date> v1.43 March 2013 

<!--
Change log
v1.43 Mar. 2013 Putty's pterm emulation.  Cleanup.  Shuford's website
 now defunct.  Looking for a new maintainer.  Wyse data missing from
 Internet.  Rewrote abstract.  Clarity in stty raw problem. Links to Wikipedia
v1.42 Jan. 2010  PuTTY serial terminal emulator, cutecom (dumb
 emulator), colors, links to wikipedia,  Boundless still selling
 terminals, small footprint terminals, link to art. on text browsers.
v1.41 Feb. 2008  Better clarity re emulation.  Illusion when
 reverse-video is reversed.  Problem with slow scrolling.  Wyse text
 terminals discontinued and Boundless went bankrupt.  Update on text web
 browsers.  gtkterm, X Window now has many terminal emulators.
 Symantec no longer selling Procomm.
v1.40 Dec. 2006 Picocom is like minicom.  Devfs obsolete so removed
 tts/1, etc.  Updated pseudo terminals.  More about telnet, ssh, and
 non-serial port interfaces.  IBM terminal emulation over telnet.
 Kermit for MS does terminal emulation.  Ports of minicom to Mac.
 Fixed/removed broken links.  "reset" is an alias for "tset"
v1.39 Aug. 2006 Typo your -> you're; Termcap Manual = Termcap Library; Fixed
 several broken links.  Found link to mapchan program.
v1.38 Feb. 2006 Fixed typos "the the"
v1.37 Feb. 2006 "file-transfer" cables, typo: VT012=>VT102, url to
 Text-Terminal source fixed, not revised every few months anymore,
 edited key cleaning
v1.36 Aug. 2004 Typo for "quit", etc.  Should be ^\
v1.35 Mar. 2004 Wyse 60 emulator
v1.34 Dec. 2003: All ~ (tildes) are now in text version (formatting problem with Linuxdoc)
v1.33 Nov. 2003: revised setserial section; using minicom with
directly connected terminals
v1.32: Sept. 2003: man page console_codes, name: serial
monitor/console, "init string" rewrite, netrik text browser, new url
for terminfo
v1.31 Jan. 2003: more on printer port, error char. appearance.
Removed all mention of obsolete /dev/cua, pin numbering, new
X-Terminal HOWTO, Hydra date is 1998 (not 1988), edited thin clients
v1.30 Sept. 2002: fixed typos, redid Windows Terminal Server (Linux client
possible)
v1.29 Mar. 2002: key-switch spring and bending "contact", getty: 
 Red Hat url, getty: source code -> executable code	
v1.28 Jan. 2002: Wyse "manuals" online, fixed a few broken links
v1.27 Nov. 2001: spell checked, more on stuck keys
v1.26 Nov. 2001: text browsers, fixed link to cca.org (was caa.org),
 about 20 typos fixed
v1.25 Oct. 2001: Linux Terminal Server Project, bad line in inittab
may cause respawning too rapidly, Evolution of the "terminal server"
had contents in title (my format error), eliminating overstrikes in
files
v1.24 Aug. 2001: Respawning too rapidly due to no such device, block mode
obsolete,troubleshooting: displays escape sequences, detective work
for repair
v1.23 July 2001: 10-cond. is not RJ45/48 ?, corrupted character attributes
v1.22 May 2001: Clarity: 8-bit, ASCII, national replacement characters,
 CP1252=MS-ANSI
v1.21 April 2001: More on mgetty, getty-login sequence, agetty parity
 problem, types of "terminal servers", parity set shows upper 128
 chars., Correction: PCTerm doesn't work with MS DOS, troubleshooting:
 no CD signal
v1.20 Feb. 2001: Revised: Is hardware flow control done by hardware ?,
 Bash bugs (with terminals), stuck key, PCTerm could work w/Linux
v1.19 Jan. 2001: more on stuck on line 25, more on DEC MMJ cabling,
 dual signal ground wires, programs use terminfo w/o ncurses
v1.18 Dec. 2000: mesg command, respawning error cause, chaos when 2
 processes open same terminal, rebooting
v1.17 Dec. 2000: Don't run getty from the command line,
 XDM-and-X-Terminal mini-HOWTO, substitutes for "local mode",
 character mapping with "mapchan"
v1.16 October 2000: Thin clients+; NC Howtos; Correction of bad typo
 "text terminals are fully obsolete".  Meant to say "not fully
 obsolete".  typo Unbounded => Boundless.  (3 updates this month)
v1.15 October 2000: Thin Clients; some broken url's changed or deleted
v1.14 October 2000: Suse distribution uses /etc/securetty (didn't
 formerly), url of terminfo source, Serial Terminal Linux, pseudo
 terminals, ctty (DOS)
v1.13 June 2000: killing getty permanently, reset bug+, man lilo
v1.12 May 2000: lilo.conf for serial console, reset -> setterm -reset
 (due to bug), scrolling region 25-line problem, sharing+,
 JavaStation-HOWTO.
v1.11 2 March 2000: New link to vtprint, links to char-sets +, typos
v1.10 22 Dec. 1999: Modem status interrupts work, Rubini said no.  
 DoubleVision.  Emulation software, Wyse 60
v1.09 28 November 1999: About 20 changes/clarifications suggested by 
 Rubini, serial-console+
v1.08 October 1999: parity login-loop, slow due to IRQ, removed 
 m4_define TorS, ncurses +
v1.07 August 1999: wyse urls +, terminfo locations +, bits/char prob.
 m4-includes for copyright, setserial (2.15), and stty.  raw mode
 during login, half-duplex set by mistake, only xmit parity, ttysnoop
 details
v1.06 June 1999: typos, more re serial-console, half-duplex, lower hardware
 costs ?
v1.05 May 1999: booting w/o monitor, chatting, dmesg doesn't show all messages
v1.04  April 1999: bit control codes, fixed "If no DTR then elim DTR to
 CTS wire", New Vers., echos ng, serial-console (+ baud patch).  DTR
 at terminal (not computer), full DTR/DSR flow control
v1.03 Jan.1999: screen package, fixed wysetterl link, terms have low
 load on PC, fixed credits, IGNOREEOF, "exit" for logout
v1.02 Nov. 1998: vttest, Don't use TERM for emulation, Mac-Terminal,
 fixed links
v1.01 Oct. 1998: Run levels 456 to 23 in Greg's getty entry. Typos.
 Fixed broken links.  Corrections. Minor changes.
v1.00 Sept. 1998: Major revision. Added Set-Up Options and Esc Sequence
 sections, etc.  Many minor changes.  Merged in info from Greg's
 Serial-HOWTO.
v0.05 June 1998: Elim. DSR from term. flow control.  CTS->RTS.
 Clarity. More on Term server.  Term not client-server.
v0.04 June 1998: Warn against making cables per Serial-HOWTO.  More on
 DTR flow control.  New terminology section.  Better clarity.
 Dial-in/out reversed.  PC as terminal server: Interrupts.   Ref. to
 Serial-Programming-HOWTO.  Login restrictions.  /etc/terminfo ->
 terminfo.src.  Stopped reviewing at Trouble-Shooting.
v0.03 11 May 1998: Added version #.  No version # on earlier ones.
 Added more other names for terminals.  A few typos & more apt words.
 Break signal is +12v (not -12v).  Removed calling smart terminals a
 niche market.
v0.02 May 1998: Interchanged definitions of mark and space.
v0.01 April 1998: Changed Hayes URL.  Changed info on hardware flow
 control to include old-fashioned RTS/CTS handshaking and DTR/DSR flow
 control.  Organizational changes.
v0.00 April 1998:  After reading it over on hikes in Griffith Park and
 correcting many mistakes, etc. I finally submitted it.
-->

<abstract>
This document was originally written for real text terminals which were
like monitors (with keyboards), but could only display text with a command
line interface (no pictures).  They were widely used to access mainframe
computers in the late 1970's and 1980's but use of them declined in the
1990's and they are seldom used anymore.  However much of this howto
also applies to command-line interfaces on Linux PC's which are in wide
use today.  It's not about the user programs one might run on the
command line, but about setting up, managing, and understanding the
interface itself Such as using  a monitor as a virtual (text-only)
console, using a text-window in a GUI such as xterm, connecting to a
remote computer over a network via ssh, telnet, etc., or even using
software on another PC to turn it into a serial-port text-terminal.  All
these 4 methods are known as "text-terminal emulation".

But unfortunately, the main emphasis in this howto is real text
terminals and the coverage of emulation is inadequate for the first 3
methods of emulation mentioned above.  The Keyboard-and-Console-HOWTO
filled much this gap but it was written for Linux 2.0 and now needs
rewriting (or merging into this Text-Terminal howto).  A new author is
needed that has time to do all this.

For the seldom used real text-terminals, it explains how they work, explains how
to install and configure them, and provides some info on how to repair
them.  This HOWTO also provides a brief overview of modern GUI
terminals.
</abstract>
<toc>

<sect> Introduction <label id="intro">

<p> For a quick attempt to install a text-terminal see <ref id="quick_install"
name="Quick Install">.

<sect1> Copyright, Trademarks, Disclaimer, & Credits
<sect2> Copyright
<p> Copyright 1998-2010 by David S. Lawyer.<url url="mailto:dave@lafn.org">
<!-- license.D begin -->

Please freely copy and distribute (sell or give away) this document
in any format.  Send any corrections and comments to the document
maintainer.  You may create a derivative work and distribute it
provided that you:

<enum>
<item> If it's not a translation: Email a copy of your derivative work
 (in a format LDP accepts) to the author(s) and maintainer (could be
 the same person).  If you don't get a response then email the LDP
 (Linux Documentation Project): submit@en.tldp.org.
<item>License the derivative work in the spirit of this license or use
  GPL.  Include a copyright notice and at least a pointer to the
  license used.
<item>Give due credit to previous authors and major contributors.
</enum>

If you're considering making a derived work other than a
translation, it's requested that you discuss your plans with the
current maintainer.

<sect2>Disclaimer
<p> While I haven't intentionally tried to mislead you, there are
likely a number of errors in this document.  Please let me know about
them.  Since this is free documentation, it should be obvious that I
cannot be held legally responsible for any errors.

<sect2>Trademarks.
<p> Any brand names (starts with a capital letter such as MS Windows)
should be assumed to be a trademark).  Such trademarks belong to their
respective owners. <!-- license.D end -->


<sect2> Credits
<p> 
Greg Hankin's  Serial-HOWTO v.1.11 (1997) section "How Do I Set Up A
Terminal Connected To My PC?" was incorporated into v1.00 at various
places (with Greg's permission).  v1.09 of Text-Terminal-HOWTO had
about 25 changes (and error corrections) suggested by Alessandro
Rubini.  For v1.26 I fixed about 25 typos, etc. found by Alain
Cochard.  Jeremy Spykerman told me about using a keyboardless terminal
as a console for a monitorless PC (using ttysnoop).  Numerous other
people have made a suggestion or two or found a few typos.  Thanks.

<sect1> Future Plans: You Can Help
<p>The author is looking for someone to take over maintaining this
howto.  Since real text terminals are pretty much obsolete, there is not
a lot of work to do except that links sometimes disappear and
automatically finding devices such a dumb terminals on a serial port may
not work right.  One project is to rewrite this howto oriented towards
text-terminal emulation with the command line interface.  Another
project would be to start with the brief overview of GUI terminals in
this HOWTO and create a new and up-to-date HOWTO on thin clients or the
like.

Please let me know of any errors in facts, opinions, logic,
spelling, grammar, clarity, links, etc.  But first, if the date is
over a couple of years old, check to see that you have the latest version.
Please send me any info that you think belongs in this document.

In order to fully utilize all the features of a certain real terminal,
one needs the terminal manuals that came with the terminal when it was
new.  If you don't have a manual, this HOWTO may be of some help.  One
way to have solved this problem would be for terminal manufacturers to
put their manuals on the Internet but they never did.  Except that Wyse
made available some of their user manuals and someone scanned old VT-100
manuals.  

<sect1> New Versions of this HOWTO
<p> New versions of the Text-Terminal-HOWTO should be released every
couple of years.  To get the latest version go to an LDP mirror sites (see:
<url url="http://www.tldp.org/mirrors.html">).   To quickly check the date
of the latest version look at <url
url="http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/Text-Terminal-HOWTO.html"
name="Text-Terminal-HOWTO.html">.  The version your are currently
reading is: v1.43 March 2013 .  

For a full revision history going back to the first version in
1998 see the source file (in linuxdoc format):<url
url="http://cvs.tldp.org/go.to/LDP/LDP/howto/linuxdoc/Text-Terminal-HOWTO.sgml?view=markup" name="(cvs) Text-Terminal-HOWTO.sgml">

<itemize>
<item> v1.43 Mar. 2013 Putty's pterm emulation.  Cleanup.  Shuford's website
 now defunct.  Looking for a new maintainer.  Wyse data missing from
 Internet.  Rewrote abstract.  Clarity in stty raw problem. Links to Wikipedia.
<item>v1.42 Jan. 2010  PuTTY serial terminal emulator, cutecom (dumb
 emulator), colors, links to wikipedia,  Boundless still selling
 terminals, small footprint terminals, link to art. on text browsers.
</itemize>

<sect1> Related HOWTOs <label id="related_howtos">
<p> Go to the nearest mirror site (per above) to get HOWTOs.
<itemize>
<item> Serial-HOWTO has info on Multiport Serial Cards used for both
terminals and banks of modems.  It has general technical info on the
serial port including troubleshooting it.
<item> NCURSES-Programming-HOWTO
<item> MacTerminal mini-HOWTO
<item> Modem-HOWTO
<item> Serial-Programming-HOWTO
<item> NC mini-HOWTO
<item> NCD-X-Terminal mini-HOWTO
<item> XDM-and-X-Terminal mini-HOWTO
<item> Connecting-X-Terminals-to-Linux-Mini-HOWTO
<item> NCD-HOWTO
<item> Thinclient-HOWTO
<item> Xterminals-HOWTO 
<item> Xterm-Title-HOWTO (only for changing the title of a window)
</itemize>

<sect1> Terminology Used in this Document
<p> Configuration means the same as set-up.  While Linux commands take
options (using - or -- symbols), options in a broader sense include
various other types of choices.  Install in the broad sense includes
setting up (configuring) software and hardware.  A statement that I
suspect is true (but may not be) ends with 2 question marks: ??  If
you know for sure, let me know.

<sect1> What is a Terminal ?
<p> A terminal consists of a screen and keyboard that one uses to
communicate remotely with a computer (the host).  One uses it almost
like it was a personal computer but the terminal is remote from its
host computer that it communicates with (on the other side of the room
or even on the other side of the world).  Programs execute on the host
computer but the results display on the terminal screen.  Originally
terminals were stand-alone devices with no computational ability and
thus they were once much cheaper in cost than computers.  They had no
pictures or audio, but could only display text and were thus called
"text terminals".  Today, the cost of PC computers is so low that one
may use a PC like a text terminal by running a software program to
make it behave like an old text terminal.  You formerly found real
text terminals at libraries and schools.

<sect1>Real Text Terminals
<p> In the olden days of mainframes, from the mid 1970's to the mid
1980's, most communication with large computers was done by people
sitting in front of real text-terminals.  And in the 1970's, before
the advent of personal computers, it was the only way to interactively
communicate with any computer.  These real text-terminals were neither
computers nor emulated text-terminals.  They consisted only of a
screen, keyboard, and only enough memory to store a screenfull or so
of text (a few kilobytes).  Users typed in programs, ran programs,
wrote documents, issued printing commands, etc.  A cable connected the
terminal to the computer (often indirectly).  It was called a terminal
since it was located at the terminal end of this cable.  Some
text-terminals were called "graphic" but the resolution was poor, the
speed slow, and little software was available to support such
graphics.

Today, real terminals are becoming rarities for most all computer
users.  But there is still some specialized uses for them as
point-of-sale devices and for access to mainframes and servers where
graphics and pictures are not needed.  However, if a text terminal is
needed people will sometimes use a personal computer to emulate a
terminal.

Almost everyone who uses Linux also uses terminal emulation.  When you are
not using an X Window GUI at a Linux PC, you are likely using a text
interface (virtual terminal).  It's also called a "command line
interface".  In X Window one can also get a command line interface
using one or more terminal windows by using an x-terminal-emulator
with names such as xterm, gnome-terminal, or konsole (KDE).  All these
use software to emulate a real terminal.  However in these cases, one
doesn't need most of the information provided by this HOWTO since such
emulation is automatically set up for the user.  However if one
emulates a terminal using a software program and then connects that
emulated terminal to another computer via a serial port cable, then
this HOWTO should be more useful (provided your PC has a serial port
on it --almost all recent PCs made after 2009 didn't have them anymore).

A real text-terminal is different from a monitor or
x-terminal-emulator because the simple character images that get
displayed on the text-terminal are stored right inside the terminal in
it's memory.  For a monitor or x-terminal-emulator, the images  are
stored in the video card of the PC and/or in the PC's memory itself.
The text-terminal's keyboard plugs into the terminal and is part
of the terminal while a PC's keyboard plugs into the computer.

For a monitor, the video images are sent by a short cable running from
the video card to the monitor while for a text-terminal there is a
bi-directional flow of character bytes in a long cable between the
computer's serial port and the PC it's connected to.  Most text
terminals do not have mice.

In network client-server terminology, one might think that a real
terminal is the client and that the host computer is the server.  The
terminal has been called a "thin client" by some.  But it is not
actually a "client" nor is the host a "server".  The only "service"
the host provides is to receive every letter typed at the keyboard and
react to this just like a computer would if you typed at its own
keyboard.  The terminal is like a "window" into the computer just like
a monitor (and keyboard) are.  You may have already used virtual
terminals in Linux (by pressing Left Alt-F2, etc.).  A real terminal
is just like running such a virtual terminal but you run it on its own
terminal screen instead of having to share the monitor screen.  In
contrast to using a virtual terminal at the console (monitor), this
allows another person to sit at another real terminal and use the same
computer simultaneously with others.  Such multi-user interfaces are
not "clients" and a server..

<sect> Types of Terminals

<sect1> Dumb Terminals

<p> There are various conflicting definitions of "dumb terminal" but
as time goes by, more and more terminals are called dumb.  This
document mainly covers text terminals which display only text on the
screen.  It could have been titled "Dumb-Terminal-HOWTO".   But in
some magazines articles, any terminal, no matter how smart, including
ones which present a full graphical user interface (GUI), are called
dumb.  If all terminals are "dumb" then there is no point of prefixing
the word "dumb" to terminal (except as a sales pitch to sell computers
or the like instead of terminals).  Due to the ambiguous meaning of
"dumb terminal" it is not classified here as a type of terminal.

<sect1> Text Terminals

<p> For a text terminal, a 2-way flow of information between the
computer and the terminal takes place over the cable that connects
them together.  This flow is in bytes (such as ASCII) where each byte
is an integer that usually represents a printable character.  Bytes
typed at the keyboard go to the host computer and most bytes from the
computer are displayed on the terminal screen.  Special control bytes
(or sequences of bytes) from the computer tell the terminal where to
move the cursor to, what to erase, where to begin and end underlining
and/or blinking and/or bold, etc.  There are often hundreds of such
special coded commands and most real terminals can even change fonts.

The communication uses characters (letters) encoded using a code chart
for the character set being used.  Usually, the first 128 bytes out of
256 possible bytes use ASCII codes.  Terminals for Unix-like systems,
normally connect to computers via a cable running between the
asynchronous serial ports (RS-232-C = EIA-232-D) of the host computer
and the terminal.  Prior to about 2004, most new PCs had serial ports,
but today (2009) almost no new PCs come with serial ports.  Sometimes
the connection is via modem or terminal server, etc.

Other names for "text terminal" are "general purpose terminal",
"general display terminal", "serial monitor", "serial console" (if
it's used like a console), "serial terminal", "dumb terminal",
"character-cell terminal", "character terminal", "ASCII/ANSI
terminal", "asynchronous terminal", "data terminal", "video terminal",
"video display terminal" (VDT), and "green terminal" (since many used
green displays).  These names (especially "dumb terminal") are
sometimes used to mean emulating a text terminal on a PC with a
command line interface such as Linux.  In olden days "video display
unit" (VDU) meant text terminal but strictly speaking, it excludes the
keyboard.

"Block mode" was used exclusively by old IBM mainframe terminals but
many modern terminals also have this capability (which is not used
much).  In block mode, the characters you type are temporarily
retained in the terminal memory (and may possibly be edited by a
built-in editor at the terminal).  Then when one presses the send key
(or the like) a block of characters (sometimes just a line of
characters) is sent to the computer all at once.  Block mode (as of
late 1998) is not supported by Linux.  See section <ref id="block"
name="Block Mode">.

<sect1> Graphic GUI Capabilities of Text Terminals 
<p> While emulated text terminals don't display images, many real text
terminals can display bit-mapped images, but not in color.
Unfortunately, the popular image formats used on the Internet are not
supported.  Thus the display of images is seldom used.  The protocols
for terminal graphics include: Tektronix Vector Graphics, ReGIS (DEC),
Sixel (DEC), and NAPLPS (North American Presentation Level Protocol
Syntax).

Even without bit-mapped images, ordinary text terminals can sort of
display images.  One may form  arrows <--- and draw boxes with |__|,
etc.  With special graphic character sets that have a lot of special
characters for line drawing, much more is possible.  But even without
a graphic character set, one may produce "ascii graphics" art.  The
term "graphics terminal" usually means a terminal that can display bit
mapped images.  However, this term is sometimes applied also to
text-only terminals since text is a limited form of graphics.

<sect2> Graphics GUI displays <label id="vector_graphics"> 
<p> There are two basic types of graphics displays: raster and vector
(rarely used).  Raster graphics (bit-mapped) puts dots on the screen
by horizontal scan lines drawn by an electron beam (or by activating
pixels or dots on a flat screen).  Vector graphic displays were
intended to be used for monochrome screens that don't have any dots.
They use smart electronics to draw lines and curves with an electron
beam that can continuously move in any direction (just like a pen or
pencil).  True vector graphics draws high quality lines without
noticeable zig-zags but is both rare and expensive.  For more details
see <url url="http://www.cca.org/vector/">.  Raster graphics is almost
universally used today for both PCs and text terminals.  For PCs,
images encoded in vector graphic format can't be drawn as continuous
lines due to the electronic limitations but they can be translated to
raster graphics format for display (with a resulting drop in image
quality).

<sect>  Thin Clients Terminals 

<sect1> Introduction 
<p> Since "thin clients" are not text terminals, this HOWTO only
provides a brief overview of them.  There are other HOWTOs that cover
them in more detail but (as of 2010) they are unfortunately not up to
date. See <ref id="related_howtos" name="Related HOWTOs, etc.">.  Thin
clients are thin (minimal) client computers that behave something like
terminals.  Since text terminals (except for very old ones) run an
embedded operating system, they are also like a computer.  In contrast
to text-terminals, thin clients all display a modern high-speed GUI.
They are dependent on more powerful computers (servers) for their
operation.  

For a true thin client terminal, the computing work and
disk storage will all be done on the server.  At the other extreme,
most of this work and storage is done at the thin client but some
things such as administration, still depend on the server.  Since such
a client is not really "thin" it may more correctly be called a "fat
client".

Instead of "thin client" they could have been simply called "graphic
terminals" but promoters of this technology wanted a catchy name to
get customers to believe that it was perhaps a totally different
technology.  This trend of renaming what is basically just graphic
terminals (with new features) continues unabated.  Some of these names
are "Virtual Desktop" and "Cloud Computing".

Thin clients may be created from an ordinary PC by using software or
may be a stand-alone piece of hardware.  But such stand-alone hardware
may often be just a conventional PC monitor plus a small box for the
computer part of the hardware.  Linux seems to favor the use of PCs as
clients.

Some claim that text-terminals are also a type of thin client but they
are not really since they don't conform to the client-server model.
However, connecting a terminal via telnet does invoke the
client-server model in the use of telnet as a means of transport of
data.  But the relation of the text-terminal to it's host is not one
of client-server.  The text-terminal is just another means of access
to the computer just like the monitor and its keyboard is to access a
PC.  One could apply this same reasoning to a thin client and say that
the client-server relationship is only for the transport of data.

Thus a thin client is like a terminal.  It has a GUI with a mouse that
makes it seem like you are using a computer.  You are, but that
computer may be far away and have many other people using it at the
same time you are.  Communication is over a high speed network
(wireless and/or cable) or even over the Internet.  Some thin clients
can, in addition, emulate a text terminal and have a serial port
connector for that purpose.  Recent ones also have USB interfaces as
well as ethernet.

There are various types of thin clients.  One type is the "Window
Terminal" which runs under MS servers (and software).  Another type is
the "network computer" which is supposed to be platform neutral.  This
implies they should work with both MS Windows and Linux but early
models may not be easy to use with Linux.  For Linux, the X Window
protocol is used.  See <ref id="linux_thin_clients" name="Thin clients
and NCs under Linux">

<sect1> MS Window terminals
<p>These are true terminals since all the computing work is done by a
server running Windows.  They are also called "Window-based Terminals"
(WBT).  These terminals (clients) are something like computers since
they often run an embedded operating system such as Linux or
Microsoft's CE, NT, or XP.  It's often stored in flash memory so that
it may be updated.   Also, ordinary PCs can be used as clients
(including, in some cases, Linux PCs) with the appropriate software,
Some clients can support X Window (from a Linux server) and some can
emulate text-terminals.  Many so called "network computers" can also
run X Window.  This will be discussed in the next section.

The server for these clients usually runs MS's Terminal Services (for
Windows 2000 servers).  Prior to this there was Windows NT Terminal
Server Edition (starting mid 1998 with codename "Hydra").  MS uses RDP
(Remote Desktop Protocol) which is based on the ITU T.120 protocol.
In addition, there is an optional ICA protocol (with added features)
which can inter-operate with RDP.

Prior to this there was a modified Windows NT 3.51 (1995) called
"WinFrame" by Citrix using the proprietary ICA protocol (Independent
Computing Architecture).  After MS came out with its own terminal
server, Citrix still remained on the scene.  It created MetaFrame
software (formerly pICAsso) as an add-on to MS's Terminal Server (or
Services) so that it could support ICA-based terminals and provide
other additional features.  Before MS got into the act, there were
other proprietary systems for terminals that could display the MS
Windows GUI but later on they all switched to support Microsoft's
system.

PCs running Linux can be turned into ICA based client terminals using
"free" (in price only) proprietary ICA client software from Citrix:
<url url= "http://support.citrix.com/article/CTX879408" name="Installing
the Linux Client">.  Unfortunately, MS requires that you purchase a
license to cover the clients, even if the clients all run Linux.  So
if you want to save money on software costs by using Linux, you'll
have to go all-Linux and use both Linux servers and clients using the
free X-Window protocol.

The above is sometimes called "network computing" since the terminals
and servers connect to each other over a network (such as the common
TCP/IP based network used by both Linux and MS).  Network computers
may be somewhat different as described below.

<sect1> Network computers (NC's) 
<p>See <url url="http://en.wikipedia.org/wiki/Network_Computer"
name="Network Computer - Wikipedia"> which claims that NC's are
defunct as a type of hardware, but that NC is used as a synonym for
"thin client".

These are neither true computers nor true terminals but are
something in-between.  One type of network computer (NC's) is a
computer with a CPU but no hard Disk.  The OS it needs to run is sent
to it over a network.  NCs are full-graphics and use the services of a
server computer.  They are a little different from terminals since
some (or most) of the programs they run may execute on their own CPU
chip.  Running a browser was supposed to be one of their primary
functions and thus Java code applets may be sent to them for
execution.  Many NCs support X Window so that one may use a Linux
server to support it.  Such a server may be called a "Linux Terminal
Server".  IBM called their NC a "NetStation" but now calls it
"NetVista".  They should work on Intranet type networks and NetVista
can run the Linux OS.

Wintel came out with a "NetPC" which, unlike the above, is almost a PC
computer.  However, it has no removable disks so users can't install
their own software or obtain copies of anything.

<sect1> Thin clients and NCs under Linux <label id="linux_thin_clients">

<p> There is a "Linux Terminal Server Project" (LTSP or ltsp) to use
Linux as a server for diskless thin clients.  They use X Window and by
default, applications run on the server.  But with additional effort,
one can set it up so that some or all applications run on the
"terminal".  See <url url="http://www.ltsp.org/">.  

"Terminal" in LTSP is actually a thin (or fat) client.  This project's
client can also run a telnet session and thus behave like a
text-terminal.  A software package named "lts" for the LTSP is
available in the major Linux distributions.

It's claimed that if one has only a few "terminals", they will work
without the ltsp software.  But if one has many "terminals", ltsp
software is needed.  So use ltsp if what you want to do is to use old
PCs, etc. as diskless thin clients.  It works OK on systems with over
100 thin-client workstations.

Linux provides NFS (Network File System) so that if ordinary computers
are connected to each other via a network, then a person on one
computer can run programs on another computer.  Such a program sends
messages over the network so that it appears just like a program was
being run by your local computer.   But such a program is actually
being run on another computer on the network.  It works also with X
Window so that one may see GUI images generated on another computer.

Linux also allows a computer to be diskless and boot over a network.
See the "Terminal Server Project" above which has special software for
this purpose.  Network-boot-HOWTO gives an overview.  Older documents
are Diskless-HOWTO and Diskless-root-NFS-HOWTO.  Thus using a diskless
computer which runs NFS enables you to run programs on another
computer (the server).  This is just like using a NC (Network
Computer).  It's not really a NC but it's emulating a type of NC.
It's also often called a "terminal" and in some sense it is.

Thus if you have an old PC with an ethernet card (NIC) you may be able
to use it as a NC.  One source of info on this is Thinclient-HOWTO.
Even if your old PC doesn't have a NIC, you could still use it to
emulate a text-terminal.  See <ref id="term_emulation" name="Terminal
Emulation">.

There are also a number of genuine Network Computers (NC) that will
work with a Linux server.  Today some NCs run the Linux OS inside the
NC.  Before Linux became popular, NCs didn't run the Linux OS but
required some other OS.  But even if the NC uses a non-linux OS, it's
often possible to make it work with a Linux Server.  The non-linux OS
is simply stored as files on the Linux Server.  Then when the NC
starts up it sends a message to the Linux Server asking for the
non-linux OS files.  This non-linux OS is thus sent to the NC over the
network and the NC boots.

The Linux Server runs the NFS and X Window both of which must be
supported by the NC.  This enables one to use the NC as if it were an
X Window terminal.

There are some Linux HOWTOs for certain brands of NCs:

<itemize>
<item> JavaStation-HOWTO (by Sun) 
<item> NC-HOWTO (IBM NetStation)
<item> NCD HOWTO (NCD-ThinSTAR)
<item> NCD-X-Terminal HOWTO 
<item> XDM-and-X-Terminal HOWTO
</itemize>

<sect1> Hardware hookups 
<p> There are 3 different types of hardware arrangements for thin
clients.  The first type just uses a PC computer as a thin client by
emulating a thin client.  It really isn't a thin client but it behaves
like one.  The second type (no longer made ?) looks just like a
text-terminal.  It just looks like a monitor, with a connector for a
keyboard and another connector for a network cable.  It's a dedicated
thin client and can't be used for anything else.  The third type looks
like a tiny computer.  It uses a standard PC monitor and keyboard both
of which plug into a small box which is a "thin" computer.  This box
provides an interface between the monitor/keyboard and the network.

<sect1> History and the future
<p> Promoters of NCs and related Window-Terminals projected that they
would soon replace millions of PCs.  In 1998 about .7 million thin
clients were sold worldwide with (about 27% of them being NCs).  In
1999 it dropped to .6 million but went up to .9 million in 2000 (vs.
1.3 million predicted).  In 2001 it reached 1.09 million with 1.4
million predicted for 2002.

Microsoft servers (as of 2003) still dominate the market, but the
clients may run Linux for which users still have to pay license fee
for each Linux client to Microsoft.  Thus free all-linux systems are
gaining ground.

A major reason why growth was not as rapid as predicted is that PCs
have come down in price in recent years so that they are often not
much more expensive than a thin client.  However, it's argued that
even though thin clients may cost the same as PCs, the maintenance and
administration costs are less.  Note that thin clients sometimes
replace text terminals instead of PCs.

<sect> Quick Text-Terminal Install <label id="quick_install">

<p> This is a quick procedure to install a terminal without going
through a <ref id="setup_" name="Setup"> procedure for both the
terminal and the host computer.  It probably will not work right if
the terminal happens to have been set up incompatible with the
computer.  If you don't understand some of it you'll need to consult
other parts of this document for more info.

To install a terminal, first look in <tt>/etc/termcap</tt> or
<tt>terminfo.src</tt> to find an entry for it (see <ref id="termcap2"
name="Terminfo and Termcap (detailed)">).  Figure out what serial port
you'll connect it to and what the tty designation is for that port
e.g. ttyS1, see <ref id="dev_names" name="Device Names">).  As the
root user, edit <tt>/etc/inittab</tt> and add a getty command next to
the other getty commands.  The format of the getty command depends on
which getty program you use.  <tt/agetty/ (called just <tt/getty/ in
the Debian distribution) is the easiest (no configuration file).  See
the "<tt/info/" or "<tt/man/ re <tt/getty/.  For getty parameters use
the terminfo (or termcap) name (such as vt100) for your terminal.
Type in a baud-rate that the terminal supports.  But if you set the
baud too high you may need to use (See<ref id="flow_control"
name="Flow Control">).

Then physically connect the main serial port of the terminal to the
chosen serial port of the computer with a file-transfer (null modem)
cable and turn on the terminal.  Don't expect most ready-made cables
to be wired correctly for hardware flow control.  Make sure the
baud-rate of the terminal is set the same as you gave to getty and
that its "data bits" is 8.  Then at the computer console type "init q"
to apply the changes you made to the inittab file.  You should now see
a login prompt at the terminal.  If you don't, tap the terminal's
return key.  If this doesn't work read more of this document and/or
see <ref id="trouble_shoot" name="Trouble-Shooting">.

<sect>Why Use a Terminal ?

<sect1> Intro to Why Use a Terminal 
<p>Many of these arguments apply also to GUI "thin-client" type of
terminal.  The case for such terminals is frequently being made today
and promoters are devising new slogans and names in an attempt to
market the modern terminal concept under another name.  For example "Cloud Computing".	

PC's are so powerful today that just one PC can often support
several persons using it at once, especially if they are doing
low-load tasks such as text editing, data entry, etc.  One way to do
this is to connect a number of terminals to a single PC (or other host
computer) by modems or direct cable connection.  To do this, it's
usually best to have a multi-user operating system such as Linux so
that each user at a terminal can use the computer independently.  This
has been called "time sharing" but it's not good terminology today
since "distributed" computing over a network is also a type of time
sharing.  It might be better described as "centralized" computing.
But the central computer may be connected to the rest of the world via
a network so that terminal users may send email, browse the Internet,
etc.  So it's not exactly "centralized" either.

Prior to about 2000, terminals were seldom used with PC's because the
popular operating systems used for them (Windows, DOS, and Mac) were
not multiuser until 1998 (available for MS Windows NT) and previously
could not support terminals very well.  Now that Linux, a multiuser
operating system, is freely available for PC's, the use of terminals
with PC's becomes more feasible.  While text terminals are not smart
enough to support the type of graphical user interface (GUI) that most
computer users today expect, thin client type terminals are.

<sect1> Lower Hardware Costs ?  
<p> When Computers (including PCs) were quite expensive, lower
hardware costs was a significant advantage of using terminals.  Today
with cheap PCs, the cost savings is problematical.  I wrote the next
three paragraphs years ago when PCs were more expensive.  They are still
valid today but of less significance:

If several people use the same computer as the same time, there is a
reduction in the amount of hardware needed for the same level of
service.  One type of savings is due to code sharing.  The application
files on hard disks are shared as well as shared libraries in memory
(even when people are running different programs provided they use
some of the same functions in their code).  Another type of savings is
due to reduction of peak load.  The hardware of a single PC may be
idle most of the time as people slowly type in information, think,
talk, or are away from their desks.  Having several people on the same
computer at once makes good use of much of this idle time which would
otherwise be wasted.

These savings are substantial.  One may roughly estimate (using
statistical theory) that for 9 persons (8 terminals & 1 console) the
shared PC only needs only about 3 times as much capacity (in memory,
disk storage, CPU power, etc.) as a single PC in order to provide the
same level of service per person.  Thus the computational hardware for
such a shared system should only cost about 1/3 as much per user.
However, the cost of the display hardware (CRT's, keyboards, video
electronics, etc.) is about the same for both cases.  The terminals
have the added cost of requiring additional physical cable connectors
(such as serial ports) at the host computer.

For a fair comparison with PC's, the terminals should have the same
capabilities as the PC monitors.  Unfortunately, color graphic
terminals for Linux (X Window) with high speed communication cost
about as much as a PC so in this case there not much (if any) savings
in hardware costs.  But for text terminals there will be some savings,
especially if the terminals are obtained used at low cost.

<sect1> Control of Software 
<p> For centralized computing, software (and the updates to software)
only need be installed and configured on one host computer instead of
several.  The person in charge of this computer may control and
configure the software which is installed on it.  This is advantageous
if the person controlling the host computer does an excellent job and
knows about the needs and preferences of the other users.  Users can
be restricted in playing games or surfing the Internet, etc.
Whether or not centralized control is desirable depends on the
situation.  It's in a sense depriving users of their "right" to
controls what they do with their computer including things that would
improve their efficiency at work and/or entertain them.

<sect1> Hardware Upgrades 
<p> With terminals, the computer hardware
upgrades take place on only one computer instead of many.  This saves
installation labor effort.  While the cost of the hardware for the
host computer upgrade will be more than that for a single PC (since
the host needs more computing power than a PC), the cost will be
significantly less than upgrading the hardware of a number of PC's
being used instead of terminals.

<sect1> Other Advantages of Terminals 
<p> <itemize>
<item> The elimination of noise from fans and disk drives (unless
you're using a PC to emulate a terminal).
<item> The users of the terminals can share data and files and send
e-mail to each other.  But they could also do this if the used PC on a
local network or via email over the internet.

</itemize>

<sect1> Major Disadvantages of Text Terminals 
<p><itemize>
<item>  For the case of text terminals there is no high-speed graphic
  display (or high resolution graphics) although they can often use
  graphic character sets to draw boxes, etc.  This lack limits the
  software that may be used on it.
<item> A detailed display of progress will sometimes greatly increase
  the time taken to do the job. For example, when copying a large
  number of files and displaying the name of each, the terminal may
  only be able to display the full path names of say 30 files per
  second so only 30 files per second will be copied.  But the computer
  hardware is capable of copying at a rate many times higher.  This
  can often be fixed by using options of application programs for a
  minimal display of progress.  See <ref id="slow_scroll"
  name="Problem with Slow Scrolling">
<item>Most new computers don't have serial ports anymore, making it
  difficult to use them to emulate text terminals that connect over a
  serial line.  One could perhaps connect by dialup using an analog
  modem, but with high speed cable or DSL modems, the analog modem is
  becoming obsolete.
</itemize>

<sect1> Major Disadvantages of All Terminals 
<p><itemize>
<item> If the host computer goes down, then no one can use the
  terminals either (unless there is a "standby" host computer to connect
  to).
<item>As compared to a laptop, it's not portable.  That is, you can't
easily take it around with you, unless you have some way of connecting
to your host computer where ever you go.
</itemize>

<sect1> Are Text Terminals Obsolete ?  
<p> Text terminals are technologically obsolete because for a slightly
higher cost of hardware, one can build a smarter terminal (with the
same quality of display).  This wasn't always the case since around
1980 memory cost thousands of dollars per megabyte.  Today with low
costs for memory and processors, one could turn a text terminal into a
GUI graphic terminal for only about a 10% or 20% increase in hardware
cost.

Since a PC can emulate a terminal, almost everyone using computers had
a terminal emulator available until PCs started removing the serial
port from new models during the 2000-2010 decade.  You might think
that now text terminals would be more in demand since emulating a
directly connected terminal is only feasible with newer PC's (with no
serial ports)  only if one purchases such ports.  But if one wants to
connect text terminals (including  emulated ones) to a PC via the
serial port they will be out of luck if the Linux PC doesn't have a
serial port.  Thus the disappearing serial port tends to make the text
terminal even more obsolete.

The reasons that text terminals are (or were) not fully obsolete are: 
<itemize>
<item> The resolution of characters on the screen was better on
 monochrome terminals than for cheaper PC monitors in text mode.
 But for high resolution monitors the character resolution is fine.
<item> Some people don't need full screen graphics.
<item> Since running a text-terminal (in contrast to a GUI-graphics
terminal) doesn't consume much of a modern PC's resources, a large
number of terminals may be efficiently run from one PC.
</itemize>

<sect> Overview of How Text Terminals Work (in Linux) <label id="overview">

<p>  See also section <ref id="HowTermsWorkDetail" name="Some Details
on How Terminals Work">

<sect1> Device Names  <label id="dev_names"> 
<p> Each terminal is connected to a serial port on the host computer
(often just a PC).  The ports have names/numbers.  The first few are:
ttyS0, ttyS1, ttyS2, etc.  

These are represented by special files found in the /dev (device)
directory.  ttyS0) corresponds to COM1 in DOS or Windows.  ttyS1) is
COM2, etc.  See <ref id="devices_" name="Terminal Special Files"> for
details on these and related "devices". 

<sect1> Login/Logout 
<p> When the host computer starts up it runs the program getty.  The
getty program runs the "login" program to log people in.  See <ref
id="getty_" name="Getty (used in /etc/inittab)">.  A "login:" prompt
appears on the screen.  People at the terminals and/or console log in
(after giving their passwords) and then have access to the computer.
When it's time to shut the terminal down, everyone must log off and
(and power off their terminal).  See <ref id="login_restr" name="Login
Restrictions"> regarding restricting logins (including allowing the
root user to log in at terminal).

<sect1> Half/Full Duplex <label id="half_duplex"> 
<p>  If one watches someone typing at a terminal, the letters one
types simultaneously appear on the screen.  A naive person might think
that what one types is being sent directly from the keyboard to the
screen with a copy going to the computer (half-duplex like, see next
paragraph).  What is usually going on is that what is typed at the
keyboard is directly sent only to the host computer which in turn
echoes back to the terminal each character it receives (called
full-duplex).  In some cases (such as passwords or terse editor
commands) the typed letters are intentionally not echoed back.

Full-duplex means that there are two (dual) one-way communication
links.  Full-duplex is the norm for terminals.  Half-duplex is half of
a duplex, meaning that there is only a single one-way communication
link.  This link must be shared by communications going in both
directions and only one direction may be used at a time.  In this case
the computer would not be able to echo the characters you type (and
send to it) so the terminal would need to also send each character you
type directly to the terminal screen.  Some terminals have a
half-duplex mode of operation which is seldom used.

<sect1> Terminal Memory 
<p> The image on a CRT tube will fade away almost instantly unless it
is frequently redrawn on the screen by a beam of electrons shot onto
the face of the tube.  Since text sent to a terminal needs to stay on
the screen, the image on the screen must be stored in the memory chips
of the terminal and the electron beam must repeatedly scan the screen
(say 60 times per second) to maintain the image.  See <ref
id="term_mem_detail" name="Terminal Memory Details"> for more details.

<sect1> Commands for the Terminal 
<p> The terminal is under the
control of the computer.  The computer not only sends the terminal
text to display on the screen but also sends the terminal commands
which are acted on.  These are <ref id="control_codes" name="Control
Codes"> (bytes) and <ref id="esc_seq" name="escape sequences">.  For
example, the CR (carriage return) control code moves the cursor to the
left hand edge of the screen.  A certain escape sequence (several
bytes where the first byte is the "escape" control code) can move the
cursor to the location on the screen specified by parameters placed
inside the escape sequence.

The <ref id="early_terms" name="first terminals"> had only a few such
commands but modern terminals have hundreds of them.  The appearance
of the display may be changed for certain regions: such as bright,
dim, underline, blink, and reverse video.   A speaker in a terminal
can "click" when any key is pressed or beep if a mistake has occurred.
Function keys may be programmed for special meanings.  Various fonts
may exist.  The display may be scrolled up or down.  Specified parts
of the screen may be erased.  Various types of flow control may be
used to stop the flow of data when bytes are being sent to the
terminal faster than the terminal can handle them.  There are many
more as you will see from looking over an advanced terminal manual or
from the Internet links <ref id="esc_seq_lists" name="Esc Sequence
List">

<sect1> Lack of Standardization Solved by Terminfo 
<p> While terminals
made for the US all used the same ASCII code for the alphabet (except
for IBM terminals which used EBCDIC), they unfortunately did not all
use the same escape sequences.  This happened even after various ANSI
(and ISO) standards were established since these standards were never
quite advanced enough.  Furthermore, older terminals often lacked the
capabilities of newer terminals.  This might cause problems.  For
example, the computer might send a terminal an escape sequence telling
it to split the screen up into two windows of specified size, not
realizing that the terminal was incapable of doing this.

To overcome these problems a database called "termcap" (meaning
"terminal capabilities") was established.  Termcap was later
superceded by "terminfo".  This database resides in certain files on
the computer and has a section of it (sometimes a separate file) for
each model of terminal.  For each model (such as VT100) a list of
capabilities is provided including a list of certain escape sequences
available.  For example blink=\E5m means that to make the cursor start
blinking the terminal must be sent: Escape 5 m.  See Section <ref
id="termcap2" name="Termcap and Terminfo (detailed)" > for more
details.  Application programs may utilize this database by calling
certain C-Library functions.  One large set of such programs (over
200) is named "ncurses" and are listed in the manual page for
"ncurses" which comes with a developer's ncurses package.  There is
also a NCURSES-programming-HOWTO.

<sect1> The Interface 
<p> The environment variable TERM is the type of
terminal Linux thinks you are using.  Most application programs use
this to look up the capabilities in the terminfo database so TERM
needs to be set correctly.   But there is more to a correct interface
than the computer knowing about the capabilities of the terminal.

For bytes to flow from the computer to the terminal the terminal must
be set to receive the bytes at the same baud rate (bits per second) as
they are sent out from the terminal.  If the terminal is set to
receive at 19,200 baud and the computer sends out characters at 9600
baud, only garbage (or perhaps nothing) will be seen on the screen.
One selects the baud rate for a terminal (as well as many other
features) from the terminals "set-up" menus at the terminal.  Most
terminals have a large number of options in their "set-up" menus  (see
<ref id="term_conf_details" name="Terminal Set-Up (Configure)
Details">).  The computer serial port has options also and these
options must be set up in a compatible way (see <ref
id="comp_conf_details" name="Computer Set-Up (Configure) Details">.

<sect1> Emulation

<p> Most terminals today have more than one emulation (personality or
"terminal mode").  The terminal model numbers of terminals formerly
made by DEC (Digital Equipment Corporation now Compaq) start with VT
(e.g. VT100).  Many other terminals which are not VT100 may be set up
to emulate a VT100.  Wyse was a major terminal manufacturer until
about 2005.  Most of their terminals can emulate various DEC terminals
such at VT100 and VT220.  Thus if you want to, say, use a VT320
terminal you may either use a real VT320 in "native" personality or
possibly use some other terminal capable of emulating a VT320.

The "native" personalities usually have more capabilities so, other
things being equal, "native" is usually the best to use.  But other
things may not be equal.  Since the Linux console emulates a VT102 it
you may want to have a terminal emulate this (or something close to it
such as VT100).  This will help insure that some programs that may not
handle terminals properly will still work OK on your terminal.  Some
programs will assume that you are using a VT102 if the program can't
find a terminfo for your terminal (or can't find a certain
capability).  Thus the failure of a program to work correctly with
your non-vt102 terminal may well be your fault if you don't provide a
good terminfo file for your terminal.  Using "native" and then
reporting any bugs will help discover and fix bugs which might not
otherwise get detected.

The most common type of emulation is to use a PC like it was a vt100
terminal (or the like).  Programs loaded into the PC's memory do the
emulation.  In Linux (unless you're in X Window) the PC monitor
(called the console) emulates a terminal of type "Linux" (close to
vt100).  Even certain windows within X Window emulate terminals.  See
<ref id="term_emulation" name="Terminal Emulation">.

<sect1> The Console

<p> On a PC, the monitor is normally the console.  It emulates a
terminal of type "Linux".  One logs on to it as a virtual terminal.
See <ref id="console_dev" name="The Console">.  It receives messages
from the kernel regarding booting and shutdown progress.  One may have
the messages that normally go to the console, go to the terminal.  To
get this you must manually patch the kernel, except that for kernel
2.2 (or higher) it is a "make config" option.  See <ref
id="term_as_console" name="Make a Serial Terminal the Console">.

<sect> Terminal Special Files such as /dev/tty <label id="devices_">

<p> "tty" is an abbreviation for "Teletype".  The first terminals were
Teletypes (like remotely controlled typewriters).  See subsection <ref
id="teletype" name="Teletypes">.  A list of Linux devices (the stuff
in the /dev directory) may be found in "Linux Allocated Devices" which
should be included with kernel sources.  It "describes" what each
device used for in only a word or two but doesn't tell you how to use
them.

<sect1> Serial Port Terminals 
<p> The computer considers each serial
port to be a "device".  It's sometimes called a terminal device since
at one time terminals were the most common use for a serial port.  For
each such serial port there is a special file in the /dev (device)
directory.  /dev/ttyS0) is the special file for the serial port known
as COM1 in the DOS/Windows world. 

To send text to a terminal you may redirect standard output of some
command-line command to the appropriate special file.  For example
typing "echo test > /dev/ttyS1" at the command prompt should send the
word "test" to the terminal on ttyS1 (COM2) provided you have write
permission on /dev/ttyS1.  Similarly, typing "cat my_file >
/dev/ttyS0" will send the contents of the file my_file to COM1
(ttyS0).

<sect1>Pseudo Terminals

<p> Pseudo terminals are pairs of devices such as  /dev/ptyp3 and
/dev/ttyp3.  There is no physical device directly associated with
either of them, not even a serial port connector.   But if a program
treats ttyp3 like it was a serial port, what is read and written to
that port appears on the other member of the pair ptyp3 which another
program uses to read and write to.  Thus two programs talk to each
other via this method and one program on ttyp3 thinks it's talking to
a serial port.  It's something like a "pipe" between these two tty's.

For talking to ttyp3, any program designed to talk to a serial port
will do.  But for the other program that talks to ptyp3, it must have
been specially written to talk to it.  It's mainly programmers that
must concern themselves with pseudo terminals and most users don't
need to worry about them.

Here's an example:  If someone connects via telnet to your computer
over a network (you are a telnet server), the part of the telnet
program handling this connection on your computer may wind up
connected to the pseudo terminal ptyp2.  A getty program should be
running on the corresponding ttyp2.  Getty thinks it's talking to a
terminal.  When telnet gets a character from the remote client, it
goes thru ptyp2 to ttyp2 to getty which then sends back "login:"
routed via ttyp2, ptyp2, your server telnet program, and then out to
the network back to the client.  Here the login program and the telnet
server program talk to each other via a "pseudo terminal".  Note that
there is no pseudo terminal used on the client computer, just telnet.
Of course the server allocates a pseudo terminal (on the server) for
each client.

In X Window, the terminal emulator programs (such as xterm) use pseudo
terminals.  Ham radio programs under Linux also use them.  By using
certain application software, it is possible to have 2 or more pseudo
terminals attached to the same physical serial port.

For a pseudo terminal pair such as ptyp3 and ttyp3, the pty... is the
master or controlling terminal and the tty...  is the slave.

There are only 16 ttyp's: ttyp0-ttypf (f is a hexadecimal digit).  To
get more pairs, more letters such as q, r, s are used instead of p.
For example the pair ttys8, ptys8 is a pseudo terminal pair.  Later
on, even more letters were added so as to allow even more pseudo
terminals.  And when z was reached, they wrapped around to a.  This is
confusing but old habits are difficult to change.  Today Linux allow
say ttyp189 but it's not used.  The device file system, which was
abandoned in 2004, would have used tty/s189.  Be sure not to type say
ttys2 if you mean ttyS2 (a real serial port).

The master and slave are really the same "port" but the slave is used
by the application program and the master is used by a network program
(or the like) which supplies (and gets) data to/from the slave port.
The program using the slave port can run "as is" since it thinks it is
talking to a serial port.

Unix98 pseudo terminals (available on Linux) is more advanced than the
above but the basic concepts are the same (only the device names and
methods of creating them change).  It creates pseudo terminal devices
on request so there is no need to check if the pseudo terminal you
might want to use in in use.  By opening /dev/ptmx a new pseudo
terminal pair is created.  The master doesn't show up as a device but
is just a file descriptor number passed to the computer program that
opened /dev/ptmx.  But the slave is put into the /dev/pts directory:
for example" /dev/pts/3. 

The /dev/pts directory is considered to be a file system of type
devpts and appears in the lists of mounted filesystems.  While the
"file" /dev/pts/3 looks like an entry in the now obsolete device
filesystem, /dev/pts Is really a wholly different kind of filesystem.

See the Linux manual pages "pty" and "pts" (Unix 98 style) for more
details.  For programmers there's the man-page openpty/forkpty (either
name displays the same man-page) which assumes that you already
understand pseudo terminals.  There is a usr/include/pty.h file for
use by programmers.  In earlier versions of Linux there was a pty.o
module, but it now seems that it's been built into the kernel.  Here's
an example of some options available when you are compiling a Linux
2.6 kernel:

<tscreen><verb> CONFIG_UNIX98_PTYS=y CONFIG_LEGACY_PTYS=y
CONFIG_LEGACY_PTY_COUNT=256 </verb></tscreen>

<sect1> The Controlling Terminal /dev/tty 
<p> /dev/tty stands for the
controlling terminal (if any) for the current process.  To find out
which tty's are attached to which processes use the "ps -a" command at
the shell prompt (command line).  Look at the "tty" column.  For the
shell process you're in, /dev/tty is the terminal you are now using.
Type "tty" at the shell prompt to see what it is (see manual pg.
tty(1)).  /dev/tty is something like a link to the actually terminal
device name with some additional features for C-programmers: see the
manual page tty(4).

<sect1> /dev/ttyIN "Terminals" 
<p> N stands for an integer.  One use
of these in Linux is with the ISDN driver package: isdn4linux.  The
ttyIN is something like ttySN but it emulates a modem and can be given
modem commands.

<sect1> The Console: ttyN or vc/N<label id="console_dev"> 
<p> In Linux the PC monitor is usually called the console and has
several device special files associated with it: vc/0 (tty0), vc/1
(tty1), vc/2 (tty2), etc.  When you log in you are on vc/1.  To go to
vc/2 (on the same screen) press down the 2 keys Alt(left)-F3.  For
vc/3 use Left Alt-F3, etc.  These (vc/1, vc/2, vc/3, etc.) are called
"virtual terminals".  vc/0 (tty0) is just an alias for the current
virtual terminal and it's where messages from the system are sent.
Thus messages from the system will be seen on the console (monitor)
regardless of which virtual terminal it is displaying.

You may log in to different virtual terminals and thus have a few
different sessions with the computer going on at the same time.  Only
the system or the root user may write to /dev/vc/0 to which
/dev/console is sometimes linked.  For more info on the console see
<ref id="console_" name="The Linux Console">.

<sect1> Creating a Device with "mknod" 
<p> The /dev directory comes
supplied with many device special files.  If you need something that's
not there you may try to create it with the "mknod" command.  See the
manual page ttys(4) for how to do this for serial ports.  To use
<tt/mknod/ you must know the major and minor device numbers.  You
might be able to infer the numbers you need by using the "<tt/ls -l/"
command in the /dev directory.  It will display the major and minor
numbers of existing special files.

<sect> Some Details on How Terminals Work <label
id="HowTermsWorkDetail">

<p> If you know almost nothing about terminals, it's suggested that
you first read <ref id="intro" name="Introduction"> and also read <ref
id="overview" name="Overview of How Terminals Work">.

<sect1> Terminal Memory Details <label id="term_mem_detail"> 
<p> The
terminal screen refreshes itself at perhaps 60 times per second from
an image stored in the memory of the terminal.  For a PC the monitor's
image is stored on the video card inside the computer but for a
terminal, the equivalent of the video card is inside the terminal.
For a text terminal the storage of the image uses little memory.
Instead of putting every dot (pixel) on the screen into memory and
requiring the storage of about a quarter-million dots, a much more
efficient method of storage is used.

A screen-full of text may be represented inside the terminal memory by
ASCII bytes, one for each character on the screen.   An entire screen
only takes about 2K ASCII bytes.  To display these characters, the
terminal must also know the bit-map (the shape) of each of the almost
100 printable ASCII characters.  With a bit-map of a character using
say 15 bytes, only about 1.5K of memory is needed for the bit-maps of
all the ASCII characters (the font).  This ASCII text and font memory
is scanned so that the resulting image is put on the screen about 60
times each second.  This is a form of shared memory where a single
bit-map of a letter such as the letter e, is shared by all of the many
letter e's which appear on a screen-full of text.  Low memory
requirements meant low costs to produce monitors in the early 1980's
when the cost of memory was several thousand times higher than it is
today (costing then several dollars per kilobyte).

<sect1> Early Terminals  <label id="early_terms"> 
<p> The first terminals were something like remotely controlled
typewriters which could only "display" (print on paper) the character
stream sent to them from the computer.  The earliest models were
called <ref id="teletype" name="Teletypes">.  The name "tty" is just
an abbreviation for "Teletype".   Early terminals could do a line feed
and a carriage return just like a typewriter and ring a bell when a
bell character was received.  Due to the lack of significant
capabilities this was the first type of terminal to be labeled "dumb".
This type of terminal interface (using a terminal type called "dumb")
is sometimes used today when the computer can't figure out what kind
of a terminal it is communicating with.

<sect1> Escape Sequences and Control Codes (intro) 
<p> Terminals have
many capabilities some of which are always present and some of which
require commands from the computer to change or activate.  To exercise
all these capabilities under the control of the computer requires that
special codes be established so that the computer can tell the
terminal what to do.  There are two major type of such codes: escape
sequences and control codes (control characters).  There are many
times more escape sequences than control codes.

<sect2> Control codes  <label id="control_codes"> 
<p> The control
codes (or control characters) consist of the first 32 bytes of the
ASCII alphabet.  They include the following: carriage-return (cursor
to far left), line-feed (cursor down one line), backspace,
escape-character, tab, and bell.  They do not normally show on the
screen.  There is usually a command which you may give to your
terminal which will result in them being displayed when they are
received by the terminal.  It's called something like "Display
Controls" or "Monitor".  If you do this then the display may look a
mess since escape sequences, which all start with the ESC (escape)
control character, are no longer executed.  Words which should appear
at the top or bottom of the screen will show up in other locations.
The escape sequences to reposition the cursor display on the screen
but the cursor doesn't move to where the escape sequence says.

<sect2> Escape sequences <label id="esc_seq"> 
<p> Since there are not
nearly enough control codes to do everything (and for some reason, not
all of them are utilized) many escape sequences are used.  They
consist of the "escape" (ESC) control character followed by a sequence
of ordinary characters.  Upon receiving an escape character, the
terminal examines the characters following it so that it may interpret
the sequence and carry out the intended command from the computer.
Once it recognizes the end of a valid sequence, further characters
received just display on the screen (unless they are control codes or
more escape sequences).  Some escape sequences may take parameters (or
arguments) such as the coordinates on the screen to move the cursor
to.  The parameters become a part of the escape sequence.  An <ref
id="esc_seq_lists" name="Esc Sequence List"> is on the web for some
terminals, but it's terse.

A list of the escape sequences for your terminal should be in the
"programmers manual" for the terminal.  Except for very old terminals,
there may be two or three hundred such sequences.  If you don't have a
such manual it's not easy to find them.  Some of the sequences are
available on the Internet.  One link is <ref id="esc_seq_lists"
name="Esc Sequence List">.  By searching the Internet for one sequence
(such as ESC&lsqb;5m) you may come across a long list of them.

Another way to determine some of them is to find the terminfo entry
(termcap) for the terminal and mentally decode it.  See <ref
id="termcap2" name="Terminfo and Termcap (detailed)"> in this document
and/or the <ref id="termcap_docs" name="Termcap Manual"> on the
Internet.  Unfortunately, the terminfo (termcap) for a terminal often
does not list all of the escape sequences which the terminal has
available for use, but fortunately, the most important ones are
usually there.

<sect1> Display Attributes & Magic Cookies <label
id="display_attributes"> <p> Terminals have various methods of
generating character attributes such as bold, reverse-video,
underlining, etc.  There should be no need for the user to worry about
how this is done, except that it creates problems for some old
terminals and there is sometimes an option for this in the set-up menu
of newer terminals.

The magic cookie method is obsolete.  It's the simplest (and worst)
method of defining attributes: Use a certain byte for the start of an
attribute and another to end that attribute.  For example, a "start
underlining" magic cookie byte is placed just before the first word to
be underlined.  These extra bytes are put into the memory of the
screen page, just like character bytes that display as characters.
But this might foul up the count of the number of characters per line
since non-printable magic cookie characters are intermingled with
other printable characters.  This sometimes causes problems.

A better method which uses more memory is to assign an attribute byte
(or half=byte, etc.) to each displayed character.  This method is used
by PC video cards (for text) for the common PC monitor.

<sect> Special Features/Types of Some Terminals

<sect1> Terminal Uses a PC Monitor
<p>One may use a PC (including it's monitor) to emulate a terminal.
But PCs have become so powerful that only a small portion of the PC's
capacity is utilized to run the emulation.  So why not make a tiny PC
that has low computing capability so it is barely able do the task of
emulating a terminal.  Then call this tiny device a text terminal and
point out that one must supply and plug in a PC monitor in order to
use this terminal.  Such devices exist and are only about an inch
high.  They are sometimes referred to as small footprint terminals.
Their advantage is that they are cheap, take up little space, and
might be able to use surplus monitors that otherwise might be
discarded.

<sect1> Color 
<sect2>Emulated text terminals
<p>In contrast to the monochrome or most real text terminals, an
emulated text terminal usually has colors since it displays on a PC
color monitor.  See <ref id="colors" name="Colors on Emulated Terminals">

<sect2>Old real text terminal
<p>Some real terminals had color displays but most had either no color
or fixed "color" displays other than white such as green or amber.  All
terminals had black (electron beam turned off = zero brightness).  A
real color terminal can change the color of the text and background to
many different colors while a monochrome terminal can only change the
brightness of a fixed color.

However, changing the brightness, etc. gives a lot of possibilities.
For example, a black and white (monochrome) terminal can have white,
grey, and black by varying the brightness.  Some words can be black on
a light grey background while other are highlighted by black on white.
In addition there is white on black, underlining, and blinking.

Real color works like the color on a computer monitor or TV screen.
The CRT has three colors of dots permanently on it with the brightness
of each color controlled by its own electron beam (3 beams).  The
monochrome of real text terminals had inherently better resolution
since it didn't depend on dots permanently fixed on the screen.  For
text terminals the only use of color is to differentiate text and this
advantage was often not worth the cost of worse resolution.  Thus
monochrome may have historically been better since it also cost less.
But today color displays have are ubiquitous and have improved in
resolution since the olden days of the real text terminal.

<sect1> Multiple Sessions 
<p> For dual sessions the terminal has two
serial ports of equal status.  Each port is connected to a serial port
on a different computer.  Thus one may log in to two different
computers with each session displaying in a split-screen window.
Alternatively, each session may run full-screen with a "hot" key (or
the like) to switch between sessions.  One could also connect to two
different serial ports on the same computer and log in twice (similar
to "virtual terminals" at the console).  The program "screen" will
make any ordinary terminal (single session) connected to a single
computer run two or more "sessions".

<sect1> Printer/Auxiliary Port 
<p> Many terminals have a connector on
the rear for such a port.  It may be labeled as "Aux" or "Printer",
etc.  Some printer ports are for parallel printers while others are
for serial printers.  If a printer is connected to the printer or
auxiliary port, then pressing certain keys will print the screen.  One
may also have everything that displays on the screen go also to the
printer.  If the port is an auxiliary port, one may connect this to
another computer and almost have dual sessions as above.  However, the
video memory inside the terminal may not retain both sessions so you
may need to refresh the screen when switching to the other session.
There will likely not be a hot key either but possibly a programmable
function key may be programmed to do this.  There exists various key
combinations and escape sequences for controlling such a port.  See
<ref id="printer_esc" name="Printer Esc">.

There is a program called <tt/vtprint/ which is designed to send a
print job (text only) to your terminal to be printed on a printer
attached to the terminal.  It's homepage is <tt><url
url="http://vtprint.sourceforge.net/" name="vtprint"></tt>.  It's also
included in the Debian distribution of Linux.  <tt/xprt/ (also in
Debian) seems to do something similar, but only for X Window terminals
??

Using the printer port to print may be useful if you don't have an
extra port on your PC for a printer or for "point of sale" use in a
store.  "Transparent print mode" is where whatever the PC sends out to
the terminal goes instead to the printer.  If you want the printer to
be able to send bytes to the PC (in the reverse direction) then (per
Wyse) it's "bidirectional mode".  The Wyse "auxiliary print mode" is
just transparent print mode where the terminal screen monitors what's
being printed.

<sect1> Pages <label id="pages_"> 
<p> Many terminals permit the
storage of more than one page in their video memory.  Sometimes the
page size is the same as the screen, but sometimes it is larger so
that scrolling will reveal unseen parts of a page.  So when one looks
at a screen, there may be hidden text on the same page above or below
the display.  In addition, if there is more than just one page, there
may be hidden text on these other pages.  One use for pages is on
terminals that support dual sessions.  Each session may have its own
page and one may switch back and forth between them.

Even if you only have a one-page-terminal with the page sized equal to
what is displayed on the screen, you will still see other pages of a
file (etc.) as the host sends more data to the terminal.  One
advantage to having additional pages stored in the terminal memory is
so that you can jump to them instantly without waiting a second or so
for them to be transmitted from the host.

Multiple pages is supported by ncurses.  There is also a commercial
program called "Multiscreen" which supports multiple pages but
probably not for Linux ??  Multiscreen is reported to be part of SCO
and is something like the virtual terminals on a Linux PC console.
The Linux program "screen" makes it look like you have multiple pages
but they are stored in the computer and but you can have only one
page-like window for each running program.

<sect1> Character-Sets <label id="char_sets">

<p> A character-set is normally represented by a list (or table or
chart) of characters along with the byte code assigned to each
character.  The codes for a byte range from 0 to 255 (00 to FF in
hexadecimal).  In MS-DOS, character-set tables are called
"code-pages".  You should examine such a table if you're not familiar
with them.  They are sometimes included in printer and terminal
manuals but also are found on the Internet.

Many character sets include letters from foreign languages.  But they
may also include special characters used to draw boxes and other
special characters.

ASCII was the traditional English character set used on text terminals
It is a 7-bit code but will usually work OK even if your terminal is
set to 8-bit mode.  In 8-bit mode with ASCII, the high order bit is
always set to zero.  Other character-sets are usually available and
usually use 8-bit codes (except on very old terminals where the only
choice is ASCII).  The first half of most character-sets are the
conventional 128 ASCII characters and the second half (with the
high-order bit set to 1) belong to a wide variety of character-sets.
Character sets are often ISO standards.  To get specialized character
sets on a terminal, you may need to download a soft-font for that
character-set into the memory of the terminal.  Many terminals have a
number of built-in character sets (but perhaps not the one you need).

Here are some common 8-bit character sets.  CP stands for Code Page
character sets invented by IBM: CP-437 (DOS ECS), ISO-8859-1
(Latin-1), CP-850 (Multilingual Latin 1 --not the same as ISO
Latin-1), CP-1252 (WinLatin1 = MS-ANSI).  MS Windows uses CP-1252
(WinLatin1) while the Internet often uses Latin-1.  There are several
ISO-8859- character sets in addition to Latin-1.  These include Greek
(-7), Arabic (-6), Eastern European (-2), and a replacement for
Latin-1 (-15) called Latin-9.  There are many others.  For example,
KOI8-R is more commonly used for Russian than IS0-8859-5.  Unicode is
a very large character-set where each character is represented by 2
bytes instead on just one byte.

More info re character-sets are: 
<itemize>
<item> Manual pages: charsets, iso_8859-l or latin1 (covers 8859 series), ascii
<item> HOWTO's for various languages (often written in that language).
<item> <url url="http://czyborra.com/charsets/iso8859.html"
name="ISO-8859 Alphabet Soup"> More than just iso8859.  Extensive.
<item> <url url="http://www.cs.tut.fi/~jkorpela/chars.html" name="A
tutorial on character code issues"> Clearly written.
<item> <url url="http://www.w3.org/International/O-charset-lang.html"
name="Languages, Countries and Character Sets">
<item> <url url="http://www.osk.3web.ne.jp/logos/" name="Languages of
the World by Computers ...">
<item> <url url="ftp://kermit.columbia.edu/kermit/e/isok7.txt" name="...
International Character Sets">
</itemize>

Once you've found the character set name (or alpha-numeric
designation) you are interested in, you may search for more info about
it on the Internet.

<sect2> Graphics (Line Drawing, etc.) 
<p> There are special characters
for drawing boxes, etc.  There are also numerous non-ASCII symbols
such as bullets.   These may either be part of an 8-bit character set
(such as WinLatin1 = CP-1252) or provided as a separate font (in vt100
terminals).  Your terminfo may be set up to use them.  But if you see
a row of letters when there should be a line, it may mean that
terminfo hasn't implemented them.

You need to know the following if your graphics don't work right.  The
default graphic character set is the vt-100 ANSI graphics.  Otherwise
the string acsc must be defined in your terminfo.  It establishes a
map between the vt-100 graphic characters codes and the actual codes
used on your terminal.  So even if your terminal doesn't have the
vt-100 graphics, it can likely still generate such graphics with some
other character set.  If terminfo has it right, this will happen
automatically.

If character sets must be switched then the terminfo variables: enacs,
rmacs, and smacs should be defined.  Note acs = Alternate Character
Set.  Even if the upper half of the normal character set contains the
graphic characters it may be considered a separate 7-bit character set
that needs to be switched to.

<sect2> National Replacement Characters (obsolete) 
<p> In the 1960's,
the ASCII 7-bit code was devised to map 7-bit bytes to English
letters, numbers, punctuation marks, etc.  Other countries adopted
ASCII, but most of them had some additional letters which were not
present in the ASCII code.  What to do?  Various people decided to
purge certain symbols (such as ^, }) from ASCII and to substitute
national letters (ones with dots over them, etc.) for the ASCII
letters.  In other words they replaced ASCII letters with "National
Replacement Characters"

There were a lot of problems with this, since it was done mostly by
companies which sold computer terminals with a resulting lack of
standardization.  Another problem was that sometimes the purged
symbols were needed.  This problem was solved in the 1980's and 1990's
with the adoption of 8-bits/byte character sets which had many more
letters.

Many West-European languages only needed several additional letters
which were not in ASCII.  To get them in 7-bit code, they borrowed the
codes for seldom used ASCII symbols:<newline> @  [  \  ]  ^  `  {  \
}  &tilde<newline> The symbols $ and # are sometimes used also.   So
when using these replacement character sets, you are deprived of using
certain of these ASCII symbols since they now are used for the new
non-ASCII letters.  Now that 8-bit character codes have replaced 7-bit
ones, it's better to use an 8-bit code which has both all the ASCII
symbols plus the non-ASCII characters for various languages.  There's
also Unicode which replaces 8-bit codes with the same code scheme to
cover all languages (well almost all significant ones).

ISO-646 (for 1972 and later) permitted using National Replacement
Characters (7-bit).  It specified that the above mentioned character
codes may be borrowed, but doesn't specify which national characters
are to replace them.  Some countries standardized the replacements
by registering them with ECMA.

Many terminals exist which support these national replacement
characters but you probably don't want to implement this support
unless you have some old files to read.  Very old terminals may only
support the national characters for the country in which they were
sold.  Later terminals offered a choice of languages.  Modem terminals
are 8-bit and don't need "national replacements".  Replacement
characters exist for the following languages/countries: British, Cuba
(Spanish), Dutch, Finnish, French, French Canadian, German, Hebrew,
Hungarian, Italian, Norwegian/Danish, Portuguese, Spanish, Swedish,
Swiss (German).

Here's tables for some character sets taken from Kermit and Unisys
documents:

<tscreen><verb>
			      Swedish     Danish
ASCII           German        Finnish      Norwegian    French

@ at-sign       section       -------      -------      a-grave
[ left-bracket  A-diaeresis   A-diaeresis  AE-digraph   degree
/ backslash     O-diaeresis   O-diaeresis  O-slash      c-cedilla
] right-bracket U-diaeresis   A-circle     A-circle     section
^ circumflex    ------        U-diaeresis  -------      -------
` accent-grave  ------        e-acute      -------      -------
{ left-brace    a-diaeresis   a-diaeresis  ae-digraph   e-acute
| vertical-bar  o-diaeresis   o-diaeresis  o-circle     u-grave
} right-brace   u-diaeresis   a-circle     a-circle     e-grave
~ tilde         ess-zet       u-diaeresis  --------     diaeresis

ASCII		 Italian     Spanish

@ at-sign        section     section
[ left-bracket   degree      inverted-exclamation
/ backslash      #-pound     N-tilde
] right-bracket  e-acute     inverted-question-mark
^ circumflex     -------     -------
` accent-grave   u-grave     -------
{ left-brace     a-grave     degree
| vertical-bar   o-grave     n-tilde
} right-brace    e-grave     --------
~ tilde          i-grave     --------
</verb></tscreen>

<sect1> Fonts

<p> Most terminals made after the mid 1980's can accept downloaded
soft-font.  This means that they can display almost any character set
provided that you can find the soft-font for it.  If you can't find
the needed soft-font, you can always create your own.  A free font
editor for this is called BitFontEdit (written by the author of this
document) and is at<newline>
<url url="http://www.ibiblio.org/pub/Linux/utils/terminal/"><newline>
For mapping the keyboard (and screen) for use of various fonts see
<ref id="mapchan_" name="Character Mapping: mapchan">

<sect1> Keyboards & Special Keys

<p>Terminal keyboards often have a number of keys that one doesn't find
on a PC keyboard.  Few (if any) actual terminals will have all of
these keys and most will have additional keys not listed here.  Some
have a large number of special purpose keys such as terminals made for
use with cash registers.  There are often many more key meanings than
shown here since these keys often have extended meanings when used in
conjunction with other keys (such as shift and control).

<itemize>
<item> BREAK sends a very long 0 bit (space = +12 V) of duration 300
to 700 milliseconds to the host.  The host may interpret this as an
interrupt if stty has set brkint or ignore it if ignbrk is set.

<item> NO SCROLL stops the screen from scrolling like ^S does.
Depressing it again resumes scrolling.  Uses flow control signals to
do this.

<item> REPEAT if held down with an other key, forces repeated output of
that other key even if the auto-repeat option is set to off.

<item> LINE FEED sends the line feed character ^J to the host.  Seldom
used.

<item> SET-UP allows the manual configuration of the terminal via
menus.  Sometimes purposely disabled by putting a block under it so it
can't be pressed down.  Sometimes another key such as shift or control
must be pressed at the same time. See <ref id="enter_setup"
name="Getting Into Set-Up (Configuration) Mode">.

<item> LOCAL disconnects the terminal from the host.  In local, what
one types goes directly to the screen.  Useful for testing.

<item> RETURN is the same as the "enter" key on a PC.  It usually
sends a carriage return to the host which normally get translated to a
new-line character by the host's device driver.  On some terminals it
may be set up to send something else.

<item> F1, F2, ... or PF1, PF2, ... are function keys which sometimes
may be programmed to send out a sequence of bytes (characters).  See
<ref id="funct_keys" name="Function Keys">
</itemize>

<sect1> Mouse
<p> A few text-terminals support a mouse.  When the mouse is clicked,
an escape sequence is sent to the host to tell it where the mouse is.
An article for a mouse on VT terminals was once at 
http://www.cs.utk.edu/~shuford/terminal/dec_vt_mouse.html but it's now a
dead link (2013).  Try the "Wayback" machine." These escape codes for
mice are called "DEC Locator sequences". The FALCO Infinity Series of
terminals, model ANSI-G supports it. Did any linux applications support
this ??  

<sect> Terminal Emulation (including the Console) <label id="term_emulation">

<sect1> Intro to Terminal Emulation
<p> A trivial type of terminal emulation is where you set up a real
terminal to emulate another brand/model of terminal.  To do this you
select the emulation you want (called "personality" in Wyse jargon)
from the terminal's set-up menu.  This section will not discuss this
case.

Since a PC has a screen and keyboard (as does a real terminal) but
also has much more computing power, it's easy to use some of this
computing power to make the PC computer behave like a real text
terminal.   Still a third type is where you just use a text-based
interface (at the console --usually just the monitor) to your Linux
PC, either by a terminal screen (such as xterm) in Xwindow or by a
"virtual terminal".  

To fully emulate a real terminal on a PC requires that a serial
port of the computer will be used to connect the emulated terminal to
another computer.  This would be either with a direct cable connection
from serial port to serial port, or via a modem.  But in other cases,
the serial port will not be used directly as the interface.  Instead,
the interface may be a network and the flow of bytes to and from the
terminal will travel in network packets via either a modem on a serial
port or via an ethernet port.

Emulation for connection to a remote computer provides more that just
a real text-terminal since the PC doing the emulation can also do
other tasks at the same time it's emulating a terminal.  For example,
for serial port connections, kermit or zmodem may be run on the PC to
enable transfer of files over the serial line (and possibly over the
phone line via a modem) to the other computer that you are connected
to.  The emulation needs only to be run on one of the virtual consoles
of the PC, leaving the other virtual consoles available for using the
PC in command-line-interface.

For Linux see <ref id="pc_as_terminal" name="Make a Linux PC a serial
port terminal">.  Emulation software for this also available for use
under MS Windows.  See <ref id="non_linux_pc" name="Make a non-Linux
PC a terminal">  This can be used to connect a Windows PC (as a
Text-Terminal) to a Linux PC.

Most Linux free software can only emulate a VT100, VT102, or
VT100/ANSI, xterm, pterm, or Wyse60 (but not fully).  Since most PC's
have color monitors while VT100 and VT102 were designed for a
monochrome monitor, the emulation usually adds color capabilities
(including a choice of colors).  Sometimes the emulation is not 100%
perfect but this usually causes few problems.  None of them provide
programmable function keys.  The non-free emulation software running
under MS Windows can emulate many more terminals than free Linux can.

<sect1> Don't Try to Use TERM Variable for Emulation
 <label id="term_not_for_emulation">
<p> Some have erroneously thought that they could create an emulator
at a Linux console (monitor) by setting the environment variable TERM
to the type of terminal they would like to emulate.  This does not
work.  The value of TERM only tells an application program what
terminal you are using.  This way it doesn't need to interactively ask
you this question (and it's too dumb to be able to probe the terminal to
find out what type it is).  If you're at a Linux PC monitor (command
line interface) it's a terminal of type "Linux", and since you can't
change this, TERM must be set to "Linux".  But this "Linux" should be
set automatically, without you needing to do anything.

If you set it to something else, you are fibbing to an application
program.  As a result, it will incorrectly interpret certain escape
sequences from the console resulting in a corrupted interface.  Since
the Linux console behaves almost like a vt100 terminal, it could still
work almost OK if you falsely claimed it was a vt100 (or some other
terminal which is close to a vt100).  In this case it may seeming work
OK most of the time but once in a while will give errors.

<sect1> Serial Communication programs 
<p>while the newer free PuTTY and Terra-Term programs can connect
directly to a serial line but can't dial out, most of the older
programs did dialing out via a serial port modem.  Some dialing
programs are for making a PPP connection to the Internet via a modem,
such as wvdial, and don't normally include any terminal emulation.
But some other programs (such as minicom or seyon) do both terminal
emulation and modem dialing (without PPP so it's not easy to use them
to connect to the internet).  But since these programs connect to a
modem via a specified serial port (including "internal" serial ports
that have no connector on the back of the PC), they may be used to
connect to a serial line via a possible serial port connector on the
back of a PC.  For this case you just set them up to connect without
dialing a phone number.  The program "picocom" just does terminal
emulation although it's possible to type in a modem command and a
phone number to dial out manually.  These programs are also useful for
testing modems.  Seyon is only for use with X Window and can emulate
Tektronix 4014 terminals.  In the past (before the Internet was
widespread) one could use dialing programs to dial up some public
libraries to use their catalogs and indexes, or even read magazine
articles on line.  But today such activity is almost always done using
the Internet where there is a much larger choice of connections and no
long-distance telephone bills.  

The communication program C-Kermit (sometimes just called kermit)
doesn't do terminal emulation for Linux (in 2006).  But Kermit can
emulate many terminals in its non-free MS Windows versions so you`ll
see lots of claims that Kermit can do terminal emulation.  With Linux,
it's merely a semi-transparent pipe between whatever terminal you are
on and the remote site you are connected to.  Thus if you use kermit
on a Linux PC the terminal type will be "Linux".  If you have a Wyse60
connected to your PC and run kermit from that, you will appear as a
Wyse60 to the remote computer (which may not be able to handle Wyse60
terminals).  Minicom emulates a VT102 and if you use it on Wyse60
terminal vt102 the remote host will think you are a vt102 and send you
vt102 escape sequences.  These will flow into your computer's serial
port and will get translated to the Wyse escape sequences before going
out another serial port on your computer to your Wyse60 terminal.
C-Kermit can't do this sort of thing.

Emulators exist under DOS such as <tt/telix/ and <tt/procomm/ work
just as well.  The terminal emulated is often the old VT100, VT102, or
ANSI (like VT100).

<sect2> Emulation under X Window
<p>There are many terminal emulation programs (such as xterm, uxterm.
gnome-terminal, and konsole) which may be run under X Window.  They can
usually emulate a VT102, but some may be able to emulate at VT220, or
Tektronix 4014.  They provide a command line interface to the computer
but they don't communicate via the serial port like a text terminal.
See <url
url="http://packages.ubuntu.com/dapper/virtual/x-terminal-emulator"
name="Ubuntu -- x-terminal-emulator"> for a brief list of such
emulators.  Some are multilingual.  Your Linux distribution has likely
installed one for you.

<sect2> Real terminals once were better
<p> Unless one was using X Window with a large display, a real
terminal was often nicer to use than emulating one.  It often had
better resolution for text (since it's monochrome), and had no disk
drives to make annoying noises.  Today, the resolution of modern color
displays is better than that of the old text-terminals and disk drives
are quieter.

<sect1> Testing Terminal Emulation
<p> For the VT series terminals there is a test program: <tt/vttest/
to help determine if a terminal behaves correctly like a vt53, vt100,
vt102, vt220, vt320, vt420 etc.  There is no documentation but it has
menus and is easy to use.  To compile it run the configure script and
then type "make".  It may be downloaded from: <url
url="http://www.ibiblio.org/pub/Linux/utils/console/">

<sect1> The Linux Console <label id="console_">
<p> The console for a PC Linux system is normally the computer monitor
in text mode.  It emulates a terminal of type "Linux" and the escape
sequences it uses are in the man page: console_codes.  There is no way
to make this interface emulate anything else.  But of course you can run
emulation software on your PC so that the monitor and keyboard will
emulate a text terminal while that software program is running.
Setting the TERM environment variable to any type of terminal other
than "Linux" will not result in emulating that other terminal.  It
will only result in a corrupted interface since you have falsely
declared (via the TERM variable) that your "terminal" is of a type
different from what it actually is: Linux.  See <ref
id="term_not_for_emulation" name="Don't Use TERM For Emulation">

In X Window, using a terminal emulator gives you the equivalent of a
console.  For KDE they chose to call this emulation "konsole".
In some cases, the console for a Linux PC is a text-terminal.  One may
recompile Linux to make a terminal receive most of the messages which
normally go to the console.  See <ref id="term_as_console" name="Make
a Serial Terminal the Console">.

The "Linux" emulation of the monitor is flexible and has features
which go well beyond those of the vt102 terminal which it was intended
to emulate.  These include the ability to use custom fonts and easily
re-map the keyboard.  These extra features reside in the console
driver software (including the keyboard driver).  The console driver
only works for the monitor and will not work for a real terminal even
if it's being used for the console.  Thus the "console driver" is
really a "monitor driver".  In the early days of Linux one couldn't
use a real terminal as the console so "monitor" and "console" were
once always the same thing.

The stty commands work for the monitor-console just like it was a real
terminal.  They are handled by the same terminal driver that is used
for real terminals.  Bytes headed for the screen first go thru the
terminal (tty) driver and then thru the console driver.  For the monitor
some of the stty commands don't do anything (such as setting the baud rate).
You may set the monitor baud rate to any allowed value (such as a slow
300 speed) but the actual speed of putting text on the monitor screen
will not actually change.  The file /etc/ioctl.save stores stty
settings for use only when the console is in single user mode (but you
are normally in multiuser-user mode).  This is explained (a little) in the
init man page.

Many commands exist to utilize the added features provided by the
console-monitor driver.   Real terminals, which use neither scan codes
nor VGA cards, unfortunately can't use these features.  To find out
more about the console see the Keyboard-and-Console-HOWTO.  Also see
the various man pages about the console (type "man -k console").
Unfortunately, much of this documentation is outdated.

<sect1> Emulation Software
<p> Since there are free programs to emulate the most common
terminals, you will unlikely need to use any non-free software.  But
if you need to purchase software you should try to throughly check out
what other customers have to say about it.

<sect2> Make a Linux PC a serial port terminal <label
id="pc_as_terminal"> 
<p> Unless you want to emulate the standard vt100
(or close to it), xterm, or a Wyse 60, there doesn't seem to be much
free terminal emulation software available for Linux.  The free
programs are minicom, picocom, and for GUI: seyon and PuTTY.  Seyon
can emulate either xterm or vt100 while PuTTy uses its own termcap
(terminfo) named "putty" (put the terminal type "putty" in
/etc/inittab).  Putty's "pterm" can be used as a replacement for
xterm.

PuTTY is much newer than most other emulations and a major use of it
is as an SSH client but you can set its configuration for a serial
port connection.  Seyon is much older but with more features (some of
which are seldom needed).  There are also more recent (but weaker)
"emulators" for a GUI interface: gtkterm and cutecom, neither of which
can emulate any terminal except of type "dumb" ??).  Seyon can also
emulate a Tektronix 4014 terminal.  For Wyse see <url
url="http://gutschke.com/wy60/" name="Wyse 60 emulator">.

Both gtkterm (and likely cutecom) don't use escape sequences, and
might be said to emulate a terminal of type "dumb" so they would be
quite slow if used as a text terminal for editing files on the host
computer using the vim editor, etc.  gtkterm is simple to set up and
very weak in capabilities but it does show its current status at the
bottom of the screen.

Minicom, PuTTY, picocom, gtkterm, or cutecom may be used to emulate a
directly connected terminal by simply starting one of them.  For
minicom, you must configure it for the serial port used).  Picocom is
like a mini-minicom and doesn't have automatic dialout capability.
Gtkterm might be called a "mini-mini-minicom".

Minicom : For the case of minicom you obviously don't try to dial-out.
When you want to quit minicom (after you logout from the other PC) you
use minicom's q command to quit without reset since there is no modem
to reset.  When minicom starts, it automatically sends out a modem
init string to the serial port.  But since there's no modem there, the
string gets put after the "login:" prompt.  If this string is mostly
capital letters, the getty program (which runs login) at the other PC
may think that your terminal has only capital letters and try to use
only capital letters.  To avoid this, configure the modem init strings
sent by minicom to null (erase the init strings).

The non-free terminal emulator "Procomm" (which is from the MS world),
can be used on a Linux PC if you run dosemu to emulate Dos or possibly
in a mode emulating MS Windows.  The last version of it seems to be
4.8 released in around 2000 so it will likely not work with modern MS
systems.  It was sold by Symantec which has many files supporting it
which may be found using their search engine at <url
url="http://www.symantec.com/">.  And if you check the Internet (in
2008), it's still being sold here and there.

There was a specialized Linux distribution: Serial Terminal Linux.  It
would turn a PC to into a minicom-like terminal.  It's small (fits on a
floppy) and will not let you use the PC for any other purpose (when it's
running).  The link to it is broken, but one similar to it (in 2013),
but on CD, is <url url="http://www.asashi.net/pages/pitux.html"
name="ASASHI DOT NET: PITUX, micro SERIAL TERMINAL LINUX">

TERM (non-free commercial software from Century Software) <url
url="http://www.centurysoftware.com/terminal_emulator/advanced_terminal_emulator.php"
name="Terminal Emulator">  can emulate Wyse60, 50; VT 220, 102, 100,
52: TV950, 925, 912; PCTERM; ANSI; IBM3101; ADM-1l; WANG 2110.  Block
mode is available for IBM and Wyse.  It runs on a Linux PC.

<sect2> Make a Linux PC an IBM network terminal
<p>This happens automatically when you run programs like telnet or
ssh, provided of course that your computer is connected to a network
(perhaps via a modem).  Telnet normally uses a network (often the
Internet) to connect your console, which emulates a terminal of type
"Linux", to a remote computer for you to log in to.  However, there
are some  free programs that allow you to use telnet with IBM terminal
emulation on your PC to connect with IBM mainframes.

One IBM program emulates an IBM tn5250 terminal and printer and
another emulates an IBM c3270.  There's also one that emulates an IBM
pr3287 printer (the mainframe thinks it's connected to the printer).
The Debian distribution has these.  It's reported that the tn5250
emulates a vt keyboard under Linux and not a 5250 keyboard like it
should.  Also, it's reported that the documentation and keyboard
mapping for the MS Windows version are better than for the Linux
version.

<sect2> Make a non-Linux PC a terminal <label id="non_linux_pc">
<p> Emulators exist which run on non-Linux PCs.  They permit you to
use a non-Linux-PC as a terminal to connected to a Linux-PC.  Under DOS
there were many programs that not only emulated a terminal but let you
dial out with a modem so that you could connect to other computers
over telephone lines (without getting connected to the Internet).  Of
historical interest is an article in Byte magazine from Feb 1994
entitled "DOS Serial Communications.  It was onetime at
http://www.byte.com/art/9402/sec8/art1.htm.

Today Windows comes with "HyperTerminal" (formerly simply called
"Terminal" in Windows 3.x and DOS).  Competing with this is both the
free (open source) PuTTY and the non-free "HyperTerminal Private
Edition" <url url="http://www.hilgraeve.com/htpe/index.html"> which is
non-free to business.  It can emulate vt-220.  PuTTY emulates xterm and
supposedly also vt-102 but it doesn't have file transfer capabilities
(such as zmodem) like HyperTerminal does.  But PuTTY permits a display
with a height of over 24 lines (set the Linux shell variable LINES to
say 32 by typing: LINES=32).  Turbosoft's TTWin (non-free) can emulate
over 80 different terminals under Windows.  See <url
url="http://www.ttwin.com/"> or <url
url="http://www.turbosoft.com.au/"> (Australia).  See also <url
url="http://www.wrq.com/" name="WRQ">

For using a Mac computer to emulate a common terminal use either
PuTTY, Linux's "minicom" (ported to the  Mac OS X) or the old "zterm"
(shareware).  For very old Macs prior to OS X, see the mini-howto:
Mac-Terminal.  <url
url="http://www.carnationsoftware.com/carnation/HT.Carn.Home.html"
name="Carnation Software"> has non-free software to emulate a wide
variety of terminals on a Mac.  Mac OS X has a "terminal" program that
gives you a terminal window just like the xterm window in Linux's X
Window.  In that window you may run "minicom" (if it's available).
Both the "fink" and "darwinports" projects have ported minicom to the
Mac, but they may not have the most recent version and you might need
to compile minicom yourself.


<sect1>Colors on Emulated Terminals <label id="colors">
<p>Since displays used for text terminal emulation are almost always
color displays, you can utilize color coding of words.  Besides
displaying directories this way (See <ref id="ls_color" name="Example
for ls Function">) some other Linux programs display color-coded text.
It seems to mostly happen without any configuring but there may be
color conflicts.  For example, if you have set the background color
green, then if a programs sends you green text, it will be difficult
or impossible to read.

Color usually works by programs sending ANSI escape sequences to the
terminal.  One might think that an emulated terminal would show the
ANSI escape codes in the <ref id="termcap1" name="terminfo">.
for the terminal.  But this is not usually the case since if a terminal
support colors it seems to be assumed that these color will be sent to
the terminal using the ANSI encoding.

If you want to see what these encodings are, look at "man
console_codes".  The ECMA-48 color codes in this man page appear to be
a subset of the ANSI color codes.  For excruciating details see <url
url="http://en.wikipedia.org/wiki/ANSI_escape_code" name="ANSI escape
code - Wikipedia">.  Note that these ANSI codes cover more than just
colors.

For PuTTY one can select the precise color to display for every ANSI
code by using the settings menu and clicking on "Colours".  For
example if you have your screen background light green, then you can
remap that ANSI color to some shade of brown that you select.  Note
that light green is called "Green Bold".  It's bold because it
contains a lot of white which makes it a light color.

<sect> Flow Control (Handshaking) <label
id="flow_control">

<p> Flow control (= handshaking = pacing)  is to prevent too fast of a
flow of bytes from overrunning a terminal, computer, modem or other
device.  Overrunning is when a device can't process what it is
receiving quickly enough and thus loses bytes and/or makes other
serious errors.  What flow control does is to halt the flow of bytes
until the terminal (for example) is ready for some more bytes.  Flow
control sends its signal to halt the flow in a direction opposite to
the flow of bytes it wants to stop.  Flow control must both be set at
the terminal and at the computer.

There are 2 types of flow control: hardware and software (Xon/Xoff or
DC1/DC3).  Hardware flow control uses dedicated signal wires such as
RTS/CTS or DTR/DSR while software flow control signals by sending DC1
or DC3 control bytes in the normal data wires.  For hardware flow
control, the cable must be correctly wired.

The flow of data bytes in the cable between 2 serial ports is
bi-directional so there are 2 different flows (and wires) to consider:
<enum>
<item> Byte flow from the computer to the terminal
<item> Byte flow from the terminal keyboard to the computer.
</enum>

<sect1> Why Is Flow Control Needed ?
<p> You might ask: "Why not send at a speed slow enough so that the
device will not be overrun and then flow control is not needed?"  This
is possible but it's usually significantly slower than sending faster
and using flow control.  One reason for this is that one can't just
set the serial port baud rate at any desired speed such as 14,500,
since only a discrete number of choices are available.  The best
choice is to select a rate that is a little higher than the device can
keep up with but then use flow control to make things work right.

If one decides to not use flow control, then the speed must be set low
enough to cope with the worst case situation.  For a terminal, this is
when one sends escape sequences to it to do complex tasks that take more
time than normal.  In the case of a modem (with data compression but
no flow control) the speed from the computer to the modem must be slow
enough so that this same speed is usable on the phone line, since in
the worst case the data is random and can't be compressed.  If one
failed to use flow control, the speed (with data compression turned
on) would be no faster than without using any compression at all.

Buffers are of some help in handling worst case situations of short
duration.  The buffer stores bytes that come in too fast to be
processed at once, and saves them for processing later.

<sect1> Padding <label id="padding">
<p> Another way to handle a "worst case" situation (without using flow
control or buffers) is to add a bunch of nulls (bytes of value zero) to
escape sequences.  Sometimes DEL's are used instead provided they have
no other function.  See <ref id="rec_del" name="Recognize Del">.

The escape sequence starts the terminal doing something, and while the
terminal is busy doing it, it receives a bunch of nulls which it
ignores.  When it gets the last null, it has completed its task and is
ready for the next command.  This is called null padding.  These nulls
formerly were called "fill characters".  These nulls are added just to
"waste" time, but it's not all wasted since the terminal is usually
kept busy doing something else while the nulls are being received.  It
was much used in the past before flow control became popular.  To be
efficient, just the right amount of nulls should be added and figuring
out this is tedious.  It was often done by trial and error since
terminal manuals are of little or no help.  If flow control doesn't
work right or is not implemented, padding is one solution.  Some of
the options to the <tt/stty/ command involve padding.

<sect1> Overrunning a Serial Port
<p> One might wonder how overrunning is possible at a serial port
since both the sending and receiving serial ports involved in a
transmission of data bytes are set for the same speed (in bits/sec)
such as 19,200.  The reason is that although the receiving serial port
electronics can handle the incoming flow rate, the hardware/software
that fetches and processes the bytes from the serial port sometimes
can't cope with the high flow rate.

One cause of this is that the serial port's hardware buffer is
quite small.  Older serial ports had a hardware buffer size of only
one byte (inside the UART chip).  If that one received byte of data in
the buffer is not removed (fetched) by CPU instructions before the
next byte arrives, that byte is lost (the buffer is overrun).  Newer
UART's, namely most 16550's, have 16-byte buffers (but may be set to
emulate a one-byte buffer) and are less likely to overrun.  It may be
set to issue an interrupt when the number of bytes in its buffer
reaches 1, 4, 8, or 14 bytes.  It's the job of another computer chip
(usually the main CPU chip for a computer) to take these incoming
bytes out of this small hardware buffer and process them (as well as
perform other tasks).

When contents of this small hardware receive buffer reaches the
specified limit (one byte for old UART'S) an interrupt is issued.
Then the computer interrupts what it was doing and software checks to
find out what happened.  It finally determines that it needs to fetch
a byte (or more) from the serial port's buffer.  It takes these
byte(s) and puts them into a larger buffer (also a serial port buffer)
that the kernel maintains in main memory.  For the transmit buffer,
the serial hardware issues an interrupt when the buffer is empty (or
nearly so) to tell the CPU to put some more bytes into it to send out.

Terminals also have serial ports and buffers similar to the computer.
Since the flow rate of bytes to the terminal is usually much greater
than the flow in the reverse direction from the keyboard to the host
computer, it's the terminal that is most likely to suffer overrunning.
Of course, if you're using a computer as a terminal (by emulation),
then it is likewise subject to overrunning.

Risky situations where overrunning is more likely are:  1. When
another process has disabled interrupts (for a computer).  2. When the
serial port buffer in main (or terminal) memory is about to overflow.

<sect1> Stop Sending
<p> When its appears that the receiver is about to be overwhelmed by
incoming bytes, it sends a signal to the sender to stop sending.  That
is flow control and the flow control signals are always sent in a
direction opposite to the flow of data which they control (although
not in the same channel or wire).  This signal may either be a control
character (^S = DC3 = Xoff) sent as an ordinary data byte on the data
wire (in-band signalling), or a voltage transition from positive to
negative in the dtr-to-cts (or other) signal wire (out-of-band
signalling).  Using Xoff is called "software flow control" and using
the voltage transition in a dedicated signal wire (inside the cable)
is called hardware flow control.

<sect1> Keyboard Lock <label id="keybrd_lock">
<p> With terminals, the most common case of "stop sending" is where
the terminal can't keep up with the characters being sent to it and it
issues a "stop" to the PC.  Another case of this is where someone
presses control-S.  Much less common is the opposite case where the PC
can't keep up with your typing speed and tells the terminal to stop
sending.  The terminal "locks" its keyboard and a message or light
should inform you of this.  Anything you type at a locked keyboard is
ignored.  When the PC catches up on it's work, then the keyboard
should unlock.  When it doesn't, there is likely some sort of deadlock
going on.

Another type of keyboard lock happens when a certain escape sequence
(or just the ^O control character for Wyse 60) is sent to the
terminal.  While the previous type of lock is done by the serial
driver, this type of lock is done by the hardware of a real terminal.
It's a catch-22 situation if this happens since you can't type any
commands to escape out of this lock.  Going into setup and resetting
might work (but it failed on my Wyse 60 and I had to cycle power to
escape).  One could also send an "unlock keyboard" escape sequence
from another terminal.

The term "locked" is also sometimes used for the common case of where
the computer is told to stop sending to a terminal.  The keyboard is
not locked so that whatever you type goes to the computer.  Since the
computer can't send anything back to you, characters you type don't
display on the screen and it may seem like the keyboard is locked.
Scrolling is locked (scroll lock) but the keyboard is not locked.

<sect1> Resume Sending
<p> When the receiver has caught up with its processing and is ready
to receive more data bytes it signals the sender.  For software flow
control this signal is the control character ^Q = DC1 = Xon which is
sent on the regular data line.  For hardware flow control the voltage
in a signal line goes from negative (negated) to positive (asserted).
If a terminal is told to resume sending the keyboard is then unlocked
and ready to use.

<sect1> Hardware Flow Control (RTS/CTS etc.) <label
id="hdw_flow_control">

<p> Some older terminals have no hardware flow control while others
used a wide assortment of different pins on the serial port for this.
For a list of various pins and their names see <ref
id="null_modem_pinout" name="Standard Null Modem Cable Pin-out">.  The
most popular pin to use seems to be the DTR pin (or both the DTR pin
and the DSR pin).

<sect2> RTS/CTS, DTR, and DTR/DSR Flow Control
<p> Linux PC's use RTS/CTS flow control, but DTR/DSR flow control
(used by some terminals) behaves similarly.  DTR flow control (in one
direction only and also used by some terminals) is only the DTR part
of DTR/DSR flow control.

RTS/CTS uses the pins RTS and CTS on the serial (EIA-232) connector.
RTS means "Request To Send".  When this pin stays asserted (positive
voltage) at the receiver it means: keep sending data to me.  If RTS is
negated (voltage goes negative) it negates "Request To Send" which
means: request not to send to me (stop sending).  When the receiver is
ready for more input, it asserts RTS requesting the other side to
resume sending.  For computers and terminals (both DTE type equipment)
the RTS pin sends the flow control signal to the CTS pin (Clear To
Send) on the other end of the cable.  That is, the RTS pin on one end
of the cable is connected to the CTS pin at the other end.

For a modem (DCE equipment) it's a different scheme since the modem's
RTS pin receives the signal and its CTS pin sends.  While this may
seem confusing, there are valid historical reasons for this which are
too involved to discuss here.

Terminals usually have either DTR or DTR/DSR flow control.  DTR flow
control is the same as DTR/DSR flow control but it's only one-way and
the DSR pin is not used.  For DTR/DSR flow control at a terminal, the
DTR signal is like the signal sent from the RTS pin and the DSR pin is
just like the CTS pin.

<sect2> Connecting up DTR or DTR/DSR Flow Control 
<p> Some terminals use only DTR flow control.  This is only one-way
flow control to keep the terminal from being overrun.  It doesn't
protect the computer from someone typing too fast for the computer to
handle it.  In a standard file-transfer serial cable the DTR pin at
the terminal is connected to the DSR pin at the computer.  But Linux
doesn't support DTR/DSR flow control (although drivers for some
multiport boards may support DTR/DSR flow control.)  A way around this
problem is to simply wire the DTR pin at the terminal to connect to
the CTS pin at the computer and set RTS/CTS flow control (stty
crtscts).  The fact that it's only one way will not affect anything so
long as the host doesn't get overwhelmed by your typing speed and drop
RTS in a vain attempt to lock your keyboard.  See <ref
id="keybrd_lock" name="Keyboard Lock">.  For DTR/DSR flow control (if
your terminal supports this two-way flow control) you do the above.
But you also connect the DSR pin at the terminal to the RTS pin at the
computer.  Then you are protected if you type too fast.

<sect2> Old RTS/CTS handshaking is different
<p> What is confusing is that there is the original use of RTS where
it means about the opposite of the previous explanation above.  This
original meaning is: I Request To Send to you.  This request was
intended to be sent from a terminal (or computer) to a modem which, if
it decided to grant the request, would send back an asserted CTS from
its CTS pin to the CTS pin of the computer: You are Cleared To Send to
me.  Note that in contrast to the modern RTS/CTS bi-directional flow
control, this only protects the flow in one direction: from the
computer (or terminal) to the modem.

For older terminals, RTS may have this meaning and goes high when the
terminal has data to send out.  The above use is a form of flow
control since if the modem wants the computer to stop sending it drops
CTS (connected to CTS at the computer) and the computer stops sending.

<sect2>  Reverse Channel
<p> Old hard-copy terminals may have a reverse channel pin (such as
pin 19) which behaves like the RTS pin in RTS/CTS flow control.  This
pin but will also be negated if paper or ribbon runs out.  It's often
feasible to connect this pin to the CTS pin of the host computer.
There may be a dip switch to set the polarity of this signal.

<sect1> Is Hardware Flow Control Done by Hardware ?
<p> Some think that hardware flow control is done by hardware but
only a small part of it is done by hardware.  Most of it is actually
done by your operating system software.  UART chips and associated
hardware usually know nothing at all about hardware flow control.
When a hardware flow control signal is received (due to the signal
wire flipping polarity) the hardware gives an electrical interrupt
signal to the CPU.  However, the hardware has no idea what this
interrupt means.  The CPU stops what it was doing and jumps to a table
in main memory that tells the CPU where to go to find a program which
will find out what happened and determine what to do about it.  In
this case this program stops the outgoing flow of bytes.

But even before this program stops the flow,  it was already stopped by
the interrupt which interrupted the work of the CPU.  This is one
reason why hardware flow control stops the flow faster.  It doesn't
need to wait for a program to do it.  But if that program didn't
command that the flow be stopped, the flow would resume once
that program exited.   So the program is essential to stop the flow
even though it is not the first to actually stop the flow.  After the
interrupt happens any bytes (up to 16) which were already in the
serial port's hardware transmit buffer will still get transmitted.  So
even with hardware flow control the flow doesn't instantly stop.

Using software flow control requires that each incoming byte be
checked to see if it's an "off" byte.  These bytes are delayed by
passing thru the 16-byte receive buffer.  If the "off" byte was the
first byte into this buffer, there could be a wait while 15 more bytes
were received.  Then the 16 bytes would get read and the "off" byte
found.  This extra delay doesn't happen with hardware flow control.

<sect1> Obsolete ?? ETX/ACK or ENQ/ACK Flow Control
<p> This is also software flow control and requires a device driver
that knows about it.  Bytes are sent in packets (via the async serial
port) with each packet terminated by an ETX (End of Text) control
character.  When the terminal gets an ETX it waits till it is ready to
receive the next packet and then returns an ACK (Acknowledge).  When
the computer gets the ACK, it then send the next packet.  And so on.
This is not supported by Linux ??   Some HP terminals use the same
scheme but use ENQ instead of ETX.

<sect> Physical Connection <label id="cable">

<sect1> Introduction
<p> A terminal may be connected to its host computer either by a
direct cable connection, via a modem, or via a terminal server.  The
flow of data may be either a direct sequence of bytes (such as from a
serial port) or packets on a network (such as TCP/IP).

<sect1> Multiport I/O Cards (Adapters)
<p> Additional serial cards may be purchased which have many serial
ports on them called "multiport boards".  These boards are not covered
in this HOWTO but there is a list of some of them (with URLs) in the
Serial-HOWTO.

<sect1> Direct Serial Cable Connection.
<p> The simplest way to connect a terminal to a host computer is via a
direct connection to a serial port on the computer.  You may also use
some the info in this section for connecting one computer to another
(via the serial port).  Most desktop PC's come with a serial port or
two, one of which may be used by a mouse.  For the EIA-232 port, you
need a null modem cable (PC-to-PC cable) that crosses over the
transmit and receive wires.  In ethernet terminology it would be
called a "crossover cable" (but the ethernet cable will not work for
the serial port).  If you want hardware flow control, you will
probably use the DTR pin (or both the DTR and DSR pins).

Make sure you have the right kind of cable.  A null modem cable
bought at a computer store may do it (if it's long enough), but it
probably will not work for hardware flow control.  Such a cable may be
labeled as a serial printer cable.   Only larger computer stores are
likely to stock such cables.  A "modem cable" will not work since the
wires go straight thru (and don't cross over).  See <ref
id="buy_or_make_cable" name="Buy or Make"> your own cable.  Make sure
you are connecting to your PC's serial port at the male DB25 or the
DB9, and not to your parallel port (female DB25).

<sect2>Pin numbering
<p>Pin numbers are often printed on the plastic right next to the
pins.  You may need a bright light and/or a magnifying glass to read
them.  Looking at the male pins of a DB connector with the wider row
up, the pin in the upper left is 1 (there is no pin 0).  Then the next
pin in this row is 2, etc.  At the end of this row is pin 5 or 13.
Then the next pin (6 or 14) is in the next row all the way to the left
and below pin 1.  If you look at the female connector with the wider
row up, then pin 1 is in the upper right corner.

<sect2> Null Modem cable pin-out (3, 4, or 5 conductor)
<p> These 3 diagrams are for real text-terminals.  But you could use
them to connect up 2 PCs if you substitute RTS for DTR and CTS for
DSR.  (Don't use 4-conductors for PC-to-PC).  For terminals, if you
only have DTR flow control (one-way) you may eliminate the RTS-to-DSR
wire.  If you have no hardware flow control, then you may also
eliminate the CTS-to-DTR wire.  Then if you have 2@ twisted pairs, you
may then use 2 wires for signal ground per <ref id="twist_pair_kludge"
name="A Kludge using Twisted-Pair Cable">.  For a DB25 connector on
your PC, you need:

<tscreen><verb>
  PC male DB25				Terminal DB25
    TxD   Transmit Data       2 --> 3       RxD   Receive Data
    RxD   Receive Data        3 <-- 2       TxD   Transmit Data
    SG    Signal Ground       7 --- 7       SG    Signal Ground
    CTS   Clear To Send       5 <--20       DTR   Data Terminal Ready
    RTS   Request To Send     4	--> 6       DSR   Data Set Ready
</verb></tscreen>

If you have a DB9 connector on your PC, try the following:
<tscreen><verb>
	PC DB9   			       Terminal DB25
    RxD   Receive Data        2 <-- 2	    TxD   Transmit Data
    TxD   Transmit Data       3 --> 3	    RxD   Receive Data
    SG    Signal Ground       5 --- 7 	    SG    Signal Ground
    CTS   Clear To Send       8 <--20       DTR   Data Terminal Ready
    RTS   Request To Send     7	--> 6       DSR   Data Set Ready   **
</verb></tscreen>

If you have a DB9 connector on both your serial port and terminal:
<tscreen><verb>
	PC DB9   			       Terminal DB9
    RxD   Receive Data        2 <-- 3	    TxD   Transmit Data
    TxD   Transmit Data       3 --> 2	    RxD   Receive Data
    SG    Signal Ground       5 --- 5 	    SG    Signal Ground
    CTS   Clear To Send       8 <-- 4       DTR   Data Terminal Ready
    RTS   Request To Send     7	--> 6       DSR   Data Set Ready   **
</verb></tscreen>

The above don't have modem control lines so be sure to give a "local"
option to getty (which is equivalent to "stty clocal").  Also if you
need hardware flow control it must be enabled at your computer (use a
-h flag with agetty) ( equivalent to "stty crtscts" ).

<sect2> Standard Null Modem cable pin-out (7 conductor)
<label id="null_modem_pinout">
<p> The following 3 diagrams show full "standard" null modem cables.
One that you purchase may be wired this way.  Another pinout is for 20
and 6 to cross over and to have 8 cross over to both 4 and 5.  This
will not provide hardware flow control (RTS/CTS) for directly
connected computers.   Both of the above will work for terminals using
software (Xon/Xoff) flow control (or no flow control).  None of these
cables will work for terminal hardware flow control since most real
terminals support DTR or DTR/DSR flow control (handshaking) but Linux
doesn't yet (2000).

<tscreen><verb>
PC male DB25     			Terminal DB25
DSR   Data Set Ready        6 <--|
DCD   Carrier Detect        8 <--|- 20    DTR   Data Terminal Ready
TxD   Transmit Data         2 ----> 3     RxD   Receive Data
RxD   Receive Data          3 <---- 2     TxD   Transmit Data
RTS   Request To Send       4 ----> 5     CTS   Clear To Send
CTS   Clear To Send         5 <---- 4     RTS   Request To Send
SG    Signal Ground         7 ----- 7     SG    Signal Ground
DTR   Data Terminal Ready  20 -|--> 8     DCD   Carrier Detect
                               |--> 6     DSR   Data Set Ready


</verb></tscreen>
<label id="DB_pin-out">
Alternatively, a full DB9-DB25 file-transfer (null-modem) cable (will
not work with terminal hardware handshaking; see above):

<tscreen><verb>
PC DB9      				Terminal DB25
RxD   Receive Data          2 <---- 2     TxD   Transmit Data
TxD   Transmit Data         3 ----> 3     RxD   Receive Data
                               |--> 6     DSR   Data Set Ready
DTR   Data Terminal Ready   4 -|--> 8     DCD   Carrier Detect
SG    Signal Ground         5 ----- 7     SG    Signal Ground
DCD   Carrier Detect        1 <--|
DSR   Data Set Ready        6 <--|- 20    DTR   Data Terminal Ready
RTS   Request To Send       7 ----> 5     CTS   Clear To Send
CTS   Clear To Send         8 <---- 4     RTS   Request To Send
RI   Ring Indicator        9 (not needed)
</verb></tscreen>
(Yes, the pins 2 and 3 really do have opposite meanings for DB9 and
DB25 connectors!)

Here's how to connect two DB9's together (but DTR flow control will
not work):
<tscreen><verb>
PC DB9      				DB9
RxD   Receive Data          2 <----- 3     TxD   Transmit Data
TxD   Transmit Data         3 -----> 2     RxD   Receive Data
                                |--> 6     DSR   Data Set Ready
DTR   Data Terminal Ready   4 --|--> 1     DCD   Carrier Detect
GND   Signal Ground         5 ------ 5     GND   Signal Ground
DCD   Carrier Detect        1 <--|
DSR   Data Set Ready        6 <--|-- 4     DTR   Data Terminal Ready
RTS   Request To Send       7 -----> 8     CTS   Clear To Send
CTS   Clear To Send         8 <----- 7     RTS   Request To Send
RI   Ring Indicator         9 (not used)
</verb></tscreen>

Using the above 2 connections provide full modem control signals and
seemingly allow one to set "stty -clocal".  Then one must turn on the
terminal first (asserts DTR) before the port may be opened in a normal
manner by getty, etc.  But there is likely to be trouble if you fail
to turn on the terminal first (see <ref id="rapid_respawn" name="Getty
Respawning Too Rapidly">).  For this reason one should use "stty
clocal" which is the default (ignores modem control lines) and the
additional wires in these cables then serve no useful purpose.

In olden days when it may not have been this easy to ignore modem
control signals etc, the following "trick" was done for cables that
lacked conductors for modem control: on your computer side
of the connector, connect RTS and CTS together, and also connect DSR,
DCD and DTR together.  This way, when the computer needs a certain
handshaking signal to proceed, it will get it (falsely) from itself.

<sect2> Overcoming length limitations <label id="length_">
<p> A cable longer than a 50 feet or so may not work properly at high
speed.  Much longer lengths sometimes work OK, especially if the speed
is low and/or the cable is a special low-capacitance type and/or the
electronics of the receiving end are extra sensitive.  It is claimed
that under ideal conditions at 9600 baud, 1000 feet works OK.  One way
to cover long distances is to install 2@ line drivers near each serial
port so as to convert unbalanced to balanced (and conversely) and then
use twisted pair cabling.  But line drivers are expensive.

Another way to increase the distance is to try to cancel out much of
the magnetic field created by the currents in the transmit and receive
data wires: TxD and RxD.  To do this, ground return lines,  which have
current which is roughly equal (but in the opposite direction) are
placed next to the transmit and received wires.  Twisted pair has
the best cancellation.  Some DEC terminals have two signal ground
wires for this purpose.  For example, one pair would be TxD and
SG(TxD) where SG is signal ground.  If you use ribbon cable, insure
that the TxD and SG(TxD) wires are right next to each other.
Similarly for the RxD.

If there is only one signal ground wire provided by both the PC and
the terminal, it may be split into two wires in a twisted pair cable
for this purpose.  You might think that return currents will be
equally split between the two signal ground wires.  This would cancel
out only about half of the magnetic field.  But it's better
cancellation than this because return current prefers the path of
least impedance.  The return path of a data signal (such as TxD) has
the lowest impedance (due to lower inductance) if it flows back in the
same twisted pair.  Although I've haven't seen any experimental test
results for this method, it should allow longer cable lengths.

<sect2> Hardware Flow Control cables
<p> If you expect to use hardware flow control (handshaking) you will
likely need to make up your own cable (or order one made).  Of course,
if the connecters on the ends of a used cable remove, you might rewire
it.  See <ref id="db_conn_install" name="Installing DB Connectors">.
You will need to determine whether or not the terminal uses the
DTR pin for this, and if not, what pin (or pins) it uses.  The set-up
menus may give you a clue on this since there may be an option for
enabling "DTR handshaking" (or flow control) which of course implies
that it uses the DTR pin.  It may also use the DSR pin.  See <ref
id="hdw_flow_control" name="Hardware Flow Control"> for a detailed
explanation of it.  Older terminals may have no provision for hardware
flow control.

<sect2> Cable tips
<p> The normal "straight thru" cable will not work unless you are
using it as an extension cable in conjunction with either a null modem
(crossover or file-transfer) cable or a null modem adapter.  Make sure
that the connectors on the cable ends will mate with the connectors on
the hardware.  One may use telephone cable which is at least
4-conductor (and possibly twisted pair).  Shielded, special
low-capacitance cable computer cable is best.

<sect2> A kludge using twisted-pair cable <label
id="twist_pair_kludge">
<p> See also <ref id="length_" name="Overcoming Length Limitations">.
Although none of the EIA-232 signals are balanced for twisted pair
one may attempt to use twisted-pair cable with it.  Use one pair for
transmit and another for receive.  To do this connect signal ground to
one wire in each of these 2 pair.  Only part of the signal ground
current flows in the desired wire but it may help.  Due to the lower
inductance of the twisted pair circuit (as compared to ground return
current by some other path)  more return (ground) current will confine
itself to the desired twisted pair than one would expect from only
resistance calculations.  This is especially true at higher
frequencies since inductive impedance increases with frequency.  The
rectangular wave of the serial port contains high frequency harmonics.

<sect2> Cable grounding
<p> Pin 1 (of a DB25) should be chassis ground (also earth ground) but
on cheap serial ports it may not even be connected to anything.  A
9-pin connector doesn't even have a chassis ground.  The signal ground
is pin 7 and is usually grounded to chassis ground.  This means that
part of the signal current will flow thru the ground wires of the
building wiring (undesirable).  Cable shields are supposed to be only
grounded at one end of the cable, but it may be better to ground both
ends since it's better to have current in the shield than in the
building wiring ??

<sect1> Modem Connection

<p> By using a terminal-modem combination (without a computer) one may
dial out to other computers.  Up to the mid 1990s in the US, there
were many "bulletin boards" one could dial out to.  Some even provided
connections to the Internet.  But bulletin boards lost out in favor of
the Internet.

<sect2> Dialing out from a terminal
<p> Instead of connecting a terminal (or computer emulating a
terminal) directly to a host computer using a cable it may be
connected to the host via a telephone line (or dedicated private line)
with a modem at each end of the line.  The terminal (or computer) will
usually dial out on a phone line to a host computer.

Most people use a PC and modem for dialing out.  The PC could have a
terminal connected to a serial port and the person at the terminal
may dial out using the PC.   Connecting a real terminal directly to an
external modem is more difficult since the real terminal isn't very
intelligent and doesn't give as much feedback to the user.  For
dialing out, many terminals can store one or more telephone numbers as
messages which may be "set-up" into them and are sent out to the modem
by pressing certain function keys.  Many modems can also store phone
numbers.  The modem initiation sequence must precede the telephone
number.  When the outgoing call is answered by another modem at the
other end of the phone line, the host computer on this modem may
run a getty program to enable you to log in.

<sect2> Terminal gets dialed into
<p> It's common for a computer running Linux to get dialed into.  The
caller gets a login prompt and logs in.  At first glance, it may seem
strange how a dumb terminal (not connected to any computer) could
accept an incoming call, but it can.  One possible reason for doing
this is to save on phone bills where rates are not symmetric.  Your
terminal needs to be set up for dial-in: Set the modem at your
terminal for automatic answer (Register S0 set to 2 will answer on the
2nd ring).  You turn on the terminal and modem before you expect a
call and when the call comes in you get a login prompt and log in.

The host computer that dials out to your terminal needs to do
something quite unusual.  As soon as your modem answers, it needs to
run login (getty).   A host may do this by running the Linux program
"callback" sometimes named "cb".  Callback is for having computer A
call computer B, and then B hangs up and calls A back.  This is what
you want if you are using computer A to emulate a terminal.  For the
case of a real terminal this may be too complex a task so the host may
utilize only the "back" part of the callback program.  The setup file
for callback must be properly configured at the host.  Callback makes
the call to the terminal and then has mgetty run a login on that port.
Mgetty by itself (as of early 1998) is only for dial-in calls but
there is work being done to incorporate callback features into it and
thus make it able to dial-out.  As of early 1999 it didn't seem to have
been done.

<sect1> Telnet and ssh
<p>Telnet is a program which lets a text terminal (or a PC console)
connect to a host computer over a network.  No serial ports are used
for the telnet connection.  Of course if you are sitting at a real
text terminal there is a serial connection to your own host.  But when
you run telnet, your host connects to another host via serial-less
telnet.

Telnet uses tcp/ip packets over various networks: the Internet, LANs,
etc.  You run telnet (as a client) and it connects to a telnet server
on another computer on a network.  Then you get a login prompt and log
in just as if you were directly connected via a cable to a serial
port.

Ssh is "Secure Shell" and is like telnet.  At one time it was much
more secure than the conventional telnet which sent passwords in the
clear (no encoding).  But now (2006) there are packages "telnet-ssl"
which offer secure telnet.  But since telnet was slow in introducing
security, ssh may have become more popular.

Telnet may put each character you type inside a packet and naturally
there's a lot of overhead with this.  But there's an option for sending
one line at a time.  To use telnet as a client, you need to have an
account on another computer on that runs a telnet server.  Then you
give the telnet command and specify the address of the computer that
will accept a connection from you.

What kind of terminal does telnet emulate?  It doesn't.  Instead, it
connects you to a remote computer using whatever kind of terminal you
are currently using.  If you're on a Linux console, it's a terminal of
type Linux.  The remote computer needs to somehow find out what type
of terminal you're on so it can send the correct escape sequences.

So using telnet is much like connecting up a dumb terminal to a serial
port except that instead of a cable between you and the computer,
there is a stream of packets flowing over the Internet between you and
some distant computer.

<sect1> Terminal Server Connection
<sect2> What is a terminal server ?
<p> A terminal server is something that serves to connect a bunch of
terminals to a host computer(s) via a network.  Today this server is
often located nearby or inside the host computer.  If you directly
connect some terminals to a PC or connect them via dial-up modems thru
serial ports at each end, you don't need a terminal server.

But if the terminals are connected to the host over a network, then
you may need a terminal server to make the serial-to-network
conversions.  This is useful for devices such as printers and
terminals that have no built-in network support.  However the
definition of "terminal server" has broadened to the case where all
data flows entirely over a network (except of course within the
computer itself) and where no serial ports are involved.  The term
"terminal" may include a thin client type terminal with a GUI.  The
network usually uses tcp/ip and/or ppp but other protocols (including
protocol conversion) are sometimes supported.

One way to connect a "terminal" (your PC console) to a network is to
run telnet on your PC (assuming your PC has a network connection).  At
one time, terminal servers were dedicated hardware which could be used
only as terminal servers.  Today a PC can simultaneously serve as a
terminal server, thereby serving many terminals.

Today, most terminal servers serve thin client terminals rather than
text-terminals.  The "Linux Terminal Server Project" is an example. 
But it can also serve text terminals using telnet.  Such a text-terminal
is likely to be just a PC monitor emulating a terminal of type
"Linux".  The terminal server is just software running on the host
computer.  Telnet server software is like a simple terminal server.

A host that only has directly connected terminals (or modem
connections without tcp/ip or ppp) is sometimes called a "terminal
server".  Although it's doing the same job as a real terminal server,
it strictly speaking is not a terminal server. 

<sect2> Evolution of the "terminal server"
<p>Originally a terminal server served real text-terminals via the
serial port.  A server for real text-terminals would have a number of
serial ports.  The user would log in to the server and then get
connected via tcp/ip, etc. to a host computer where s/he would login a
second time again.  Sometimes the first login would be automatic, or
perhaps there would be a choice given the user as to what host
computer (or printer) to connect to (or what protocol to use).

The use of real text-terminals declined as the PC replaced mainframes.
But the PC could emulate a terminal (using say minicom (Linux) or
(hyper)terminal for MS).   One could could then dial-out via a modem
to a bulletin-board or the like.  There would be a bank of modems to
accept such calls and each modem would be connected to a serial port.
The serial port could either be on a multiport card or on a dedicated
terminal server.  Note that in both the above cases there is no client
software.  It's not a client-server model.

When the Internet became popular, one would run the PPP protocol on
the phone line and still go thru a modem and "terminal server" at the
ISP.  This server would handle PPP and ultimately connect one to the
Internet.  But the PC was no longer emulating a text terminal since
browser images were being displayed.  Today with ISPs getting only
digital signals from the phone company, they don't need real modems
anymore.  So what was once a "terminal server" evolved into a "remote
access server".  It's infrequently been called a "digital terminal
server".  Note that 56k modem service requires that an ISP have a
digital connection to the phone company.

With remote access servers, instead of many individual telephone line
cables connected to a terminal server, one now finds just a few cables
with many digitized telephone calls on each cable (multiplexed).  The
multitude of connectors needed for large numbers of terminals or
modems is no longer present on a remote access server and thus the
successor to this type of terminal server can't readily serve
text-terminals anymore.

More recently with the advent of thin clients terminals, the term
"terminal server" was revived to apply to the hosts that served the
thin clients.  Both MS Windows and Linux can serve thin clients.

<sect1> Connector and Adapter Types
<p> A connector is more-or-less permanently attached to the end of a
cable or to a hardware unit.  There are two basic types of connectors
used in serial communications: 1. DB types with pins (DB 9 or DB25) and 2.
modular telephone-style connectors.

An adapter looks about like a connector but it has two ends with pins.
It is just like a cable that is so short that there is no cable part
left at all --just different connectors on each end is all that
remains.  The adapter just plugs in to two other connectors on each side
of it.  It allows two incompatible connectors to mate with each other
by going in between them.  Except that even for two connectors that
will mate with each other, an adapter may be used to connect the cable
conductors together in other than straight-thru.  Obviously, one may
use a special cable (perhaps homemade) as a substitute for an adapter.

<sect2> Sex of connector/adapters
<p> Connectors (or one side of adapters) are either male or female.
The connectors that have pins are male and the ones that have sockets
(sometimes also called pins) are female.  For modular connectors, the
ones with exposed contacts are plugs while the ones with internal
contacts (not easy to see) are jacks.  Plugs are male; jacks are
female.

<sect2> Types of adapters
<p> There are three basic types of adapters: null modem, gender
changers and port adapters.  Some adapters perform more than one of
these three functions.
<itemize>
<item> null modem adapter: Reroutes wires, like a null modem cable.
<item> gender changer: Changes the sex of a cable end.  Two connectors
 of the same sex can now connect (mate) with each other.
<item> port adapter: Goes from one type of connector to another (DB9
 to DB 25, etc.)
</itemize>

<sect2> DB connectors <label id="db_conn">
<p> (For how to install a DB connector on the ends of a cable see <ref
id="db_conn_install" name="Installing DB Connectors">.)  These come in
9 or 25 pins.  The EIA-232 specs. call for 25 pins but since most of
these pins are not used on ordinary serial ports, 9 pins is
sufficient. See <ref id="DB_pin-out" name="DB9-DB25"> for the pin-out.
The pins are usually numbered if you look closely enough or use a
magnifying glass.

<sect2> RJ modular connectors <label id="rj_conn">
<p> RJ means Registered Jack.  These look like modern telephone
connectors but are sometimes not compatible with telephone connectors.
See also <ref id="rj_conn_install" name="Installing RJ Connectors">.
For use with serial ports they may be 6 or 8 conductor.  A few are
10-conductor but may not officially belong to the RJ series.

<sect3> 6-conductors: RJ11/14, RJ12,  and MMJ
<p> RJ11 are all the same size but may have  2, 4, or 6 conductors.
If it has two conductors, it should be called a RJ11.  If it has 4
conductors, some call it a RJ14.  If it has 6 conductors, many call it
a RJ12 (but a RJ12 per the phone company has only 4 conductors).
Seems confusing but they are all the same size and differ mainly by
the number of conductor contacts present.

A look-alike (almost) is a MMJ connector (6-conductor) used on later
model VT (and other) terminals.  It's sometimes referred to as a
DEC-423 or a DEC RJ11.  MMJ has an offset tab and is not compatible
with RJ ones (unless the tab is cut off).  However, some connectors
have been made that are compatible with both MMJ and the RJ ones.
Since MMJ connectors are both hard to find and may be expensive some
people have forced a RJ (6 conductor) to fit MMJ by filing off the
offset tab with a file.

The MMJ (DEC) pinout is: 1-DTR, 2-TxD, 3-TxD_Gnd, 4-RxD_Gnd, 5-RxD,
6-DSR.  Cyclades Cyclom-8Ys RJ12 has: 1-DTR, 2-TxD, 3-Gnd, 4-CTS,
5-RxD, 6-DCD.  Specialix IO8+ has: 1-DCD, 2-RxD, 3-DTR/RTS, 4-Gnd,
5-TxD, 6-CTS.  The pins of the RJ (and MMJ) are numbered similar to
the RJ45.

<tscreen><verb>
       Plug                         Jack (or socket)
  (Looking at the end           (Looking at the cavity
   end of a cable)               in a wall or PC back)
     .________.                       .________.
     | 654321 |                       | 123456 |
     |__.  .__|                       |__.  .__|
        |__|                             |__|
</verb></tscreen>

A standard MMJ file-transfer (null-modem) cable has a MMJ connector at
each end.  It connects to the PC using a MMJ-to-DB adapter.  This
adapter plugs into a DB (say 25 pin) connector on the back of the PC
and the MMJ connecter plugs into it.  If you don't have such an
adapter, you can make a custom cable with a MMJ (or filed RJ)
connector on one end and a DB connector on the other end.

The standard file-transfer (null-modem) cable with two MMJ (or
RJ11/14) connectors will connect: 1-6, 2-5, and 3-4.  Note that such a
cable supports DTR/DSR flow control which is not supported (yet) by
Linux.  Making up your own standard 6-conductor file-transfer cable is
very simple if you understand that the ordinary 4-conductor telephone
cable from the wall to your telephone, used in hundreds of millions of
homes, is also a file-transfer cable.  Find one and wire your cable the
same way.

If you lay such a cable flat on the floor (with no twists) you will
note that both plugs on the ends have their gold contacts facing up
(or both facing down).  Although it's symmetrical, it is also
file-transfer if you think about it a bit.  One may put a few such
cables together with inline couplers and everything works OK because
each inline coupler is also a file-transfer (null-modem) adapter.  Two
file-transfer cables in series result in a straight-thru connection.

Here's a custom cable diagram (by Mark Gleaves) for connecting MMJ to
a 9-pin serial port using RTS/CTS flow control:
<tscreen><verb>
  DEC MMJ                            Linux PC DB9
Pin  Signal                           Signal  Pin
===  ======                           ======  ===
 1    DTR -----------------------|---> DSR     6
				 |---> CTS     8
 2    TxD ---------------------------> RxD     2
 3    SG (TxD)--------------------|--- SG      5
 4    SG (RxD)--------------------|
 5    RxD <--------------------------- TxD     3
 6    DSR <-----------------------|--- RTS     7
				  |--> DTR     4
				  |--> CD      1
		       (no connection) RI      9
</verb></tscreen>
<sect3> 8-conductors and 10-conductors
<p> RJ45 and RJ48 are 8-conductor modular telephone plugs.
There exists some 10-conductor connectors which are allegedly wider
and will not mate with the 8-conductor ones.  People have called the
10-conductor ones RJ45 and/or RJ48 but this may be incorrect.  These
connectors are used for both flat telephone cable and round twisted
pair cable.  The cable end of the connector may be different for round
and flat cable.  RJ48 has an extra tab so that a RJ48 plug will not
push into a RJ45 jack (but a RJ45 plug will mate with a RJ48 jack).
They're used on some multiport serial cards and networks.  Heres the
pin numbers for an 8-conductor:

<tscreen><verb>
  Plug                          Jack (or socket)
  (Looking at the end           (Looking at the cavity
   end of a cable)               in a wall)
     .__________.                   .__________.
     | 87654321 |                   | 12345678 |
     |__.    .__|                   |__.    .__|
        |____|                         |____|
</verb></tscreen>

<sect1> Making or Modifying a Cable
<sect2> Buy or make ? <label id="buy_or_make_cable">
<p> You may try to buy a short, null modem cable.  Just a "modem
cable" will not work.  Null modem cables were once labeled as "serial
printer" cables but serial printers are not popular today (2004).
They also may be labeled as "file-transfer" cables or "PC-to-PC"
cables.  Hardware flow control will work on them for PC-to-PC
connections (terminal emulation) but not for the DTR flow control used
by most real text terminals.  If Linux supported DTR flow control,
real terminals would work OK .  Make sure the connectors on the cable
ends will fit the connectors on your computer and terminal.

But if you need longer cables to connect up terminals or need hardware
flow control, how do you get the right cables?  The right ready-made
cables may be difficult to find (you might find them by searching the
Internet), especially if you want to use a minimum (say 4) of
conductors.  One option is to get them custom made, which is likely to
be fairly expensive although you might find someone to make them at
prices not too much higher than ready-made cable (I did).

A low-cost alternative is to buy used cables (if you can find them).
If you get a used terminal, ask if they have a cable for it.  Another
alternative is to make your own.  Even if you get used cables, they
may need some changes to the pin wiring.  In either case, this may
require special tools.  Most connectors that come with short cables
are permanently molded to the cable and can't be rewired but most
custom-made and homemade cables have connectors that can be rewired.
One advantage of making your own cable is that the skills you learn
will come in handy if a cable breaks (or goes bad) or if you need to
make up another cable in a hurry.

<sect2> Pin numbers of 9 and 25 pin connectors
<p> The pin numbers are often engraved in the plastic of the
connector but you may need a magnifying glass to read them.
Note DCD is sometimes labeled CD.  The numbering of the pins on a
female connector is read from right to left, starting with 1 in the
upper right corner (instead of 1 in the upper left corner for the male
connector as shown below).  --> direction is out of PC.

<tscreen><verb>
  ___________                    ________________________________________
  \1 2 3 4 5/  Looking at pins   \1  2  3  4  5  6  7  8  9  10 11 12 13/
   \6 7 8 9/  on male connector   \14 15 16 17 18 19 20 21 22 23 24 25/
    ------                         -----------------------------------
</verb></tscreen>

<sect2>	Installing DB connectors on cable ends <label id="db_conn_install">
<p> See <ref id="db_conn" name="DB Connectors"> for a brief description
of them.  Unfortunately, most cables one purchases today have molded
connectors on each end and can't be modified.  Others have connectors
which unscrew and can be rewired.  If you are making up cable or
modifying an existing one then you need to know about pins.  There are
two types: soldered and crimped.

The crimped pins require a special crimping tool and also need an
"insertion/extraction" tool.  But once you have these tools, making up
and modifying cable may be faster than soldering.  If you are
connecting two wires to one pin (also needed if you want to jumper one
connected pin to another pin) then soldering is faster (for these
pins).  This is because the crimped pins can only take one wire each
while the soldered ones can accept more than one wire per pin.

To insert crimped pins just push them in by hand or with the insertion
tool.  Using the tool for either insertion of removal first requires
putting the tool tip around the wire.  The tool tip should completely
encircle the wire at the back of the pin.

Removing a pin with this tool is a little tricky.  These directions
can be best understood if you have both the tool and wires in front of
you as you read this.  With the tool tip around the wire insert the
tool as far as it will go into the hole (about 1 1/2 cm.  Some tools
have a mark (such as a tiny hole) on them to indicate how far to
insert it.  The tool tip should have a tapered gap so that you may get
the tip around the wire by starting it in where the gap is wider than
the wire.  The tool may have 2 tips.  The one that is the most
difficult to get around the wire is also the one that removes the wire
the easiest since it almost completely envelops the wire.

With the tip properly inserted pull on both the tool and the wire
with a gentle pull.  If it doesn't come out, the tool was likely not
inserted correctly so either push it in more or twist it to a
different position (or both).   Perhaps you should have used another
tip that fits tighter around the pin.  Using this tool, one may
readily convert a straight-thru cable to a file-transfer (null-modem)
cable, etc.

There can be problems using the "insertion/extraction" tool.  If the
tools will not insert on the back of the pin, it could be that the pin
was not neatly crimped to the wire and is sort of square where it
should be round, etc.  If a pin starts to come out but will not pull
out all the way, the pin may be bent.  Look at it under a magnifying
glass.  Straightening a pin with needle-nose pliers may damage the
gold plating but you may have to straighten it to remove it.
Sometimes a stuck pin may be pushed out with a thick screwdriver blade
tip (or the like) but if you push too hard you may gouge the plastic
hole or bend the pin:.

Don't try soldering unless you know what you're doing or have read
about how to do it.

<sect2>	Installing RJ connectors <label id="rj_conn_install">
<p> These are telephone modular connecters one type of which is used
for most ordinary telephones.  But there are many different types (see
<ref id="rj_conn" name="RJ Modular Connectors">).

These are not easy to reuse.  You might be able to pull the wires out,
push in something wedged that would lift up the gold-colored contacts
and reuse the connector.  There are special crimping tools used to
install them; a different tool for each type.

If you don't have a crimping tool, installation is still possible (but
difficult) using a small screwdriver (and possibly a hammer).  Push in
the cable wires and then push each gold-colored contact down hard with
a small screwdriver that will just fit between the insulating ridges
between the contacts.  You may damage it if you fail to use a
screwdriver with a head almost the same thickness as the contacts or
if the screwdriver slips off the contact as you are pushing it down.
You may also use a small hammer to pound on the screwdriver (push
first by hand).

Be sure to not hurt the "remove lever" on the connecter when you push
in the contacts.  Don't just set it down on a table and push in the
contacts.  Instead, put a shim (about 1 mm thick) that fits snugly
in the crevice between the lever and the body.  For such a shim you
may use thick cardboard, several calling cards, or wood.  Since the
bottom of the connector (that you will put on the table) isn't level
(due to the "remove lever), make sure that the table top has something
a little soft on it (like a sheet of cardboard) to help support the
non-level connector.  Even better would be to put another 1mm shim
under the first 6mm of the connector, supporting it just under where
you see the contacts.  A soft tabletop wouldn't hurt either.  Another
method (I've never done this) is to hold the connector in a vice but
be careful not to break the connector.

As compared to using a crimping tool, installing it per above takes a
lot longer and is much more prone to errors and failure but it's sometimes
more expedient and a lot cheaper than buying a special tool if you
only have one or two connectors to install.

<sect> Set-Up (Configure) in General <label id="setup_">

<sect1> Intro to Set-Up
<p> Configuring (Set-Up) involves both storing a configuration in the
non-volatile memory of the terminal, and putting commands in start-up
files (on your hard disk) that will run each time the computer is
powered on (or possibly only when the run-level changes).  This
section gives an overview of configuring and covers the configuring of
the essential communication options for both the terminal and the
computer.  The next two major sections cover in detail the
configuration of the terminal (see <ref id="term_conf_details"
name="Terminal Set-Up"> and the computer (see <ref  id="comp_conf_details"
name="Computer Set-Up (Configure) Details">.

<sect1> Terminal Set-Up (Configure) Overview <label id="term_conf_ov">
<p> When a terminal is installed it's necessary to configure the
physical terminal by saving (in its non-volatile memory which is not
lost when the terminal is powered off) the characteristics it will
have when it is powered on.  You might be lucky and have a terminal
that has already been set-up correctly for your installation so that
little or no terminal configuration is required.

There are two basic ways of configuring a terminal.  One is to sit at
the terminal and go thru a series of set-up menus.  Another is to send
escape sequences to it from the host computer.  Before you can send
anything to the terminal (such as the above escape sequences), its
<ref id="commun_config" name="Communication Interface"> options such
as the baud rate must be set up to match those of the computer.  This
can only be done by sitting at the terminal since the communications
must be set up right before the computer and the terminal can "talk"
to each other.  See <ref id="term_conf_details" name="Terminal
Set-Up">.

<sect1> Computer Set-Up (Configure) Overview
<p> Besides possibly sending escape sequences from the computer to
configure the terminal, there is the configuring of the computer
itself to handle the terminal.  If you're lucky, all you need to do is
to put a "getty" command in the /etc/inittab file so that a "login:"
prompt will be sent to the terminal when the computer starts up.  See
the section <ref id="getty_" name="Getty (used in /etc/inittab)"> for
details.

The computer communicates with the terminal using the serial device
driver software (part of the kernel).  The serial device driver has a
default configuration and is also partly (sometimes fully) configured
by the getty program before running "login" at each terminal.
However, additional configuration is sometimes needed using programs
named "stty" and "setserial".  These programs (if needed) must be run
each time the computer starts up since this configuration is lost each
time the computer powers down.  See <ref id="comp_conf_details"
name="Computer Set-Up (Configure) Details">.

<sect1> Many Options
<p> There are a great many configuration options for you to choose
from.  The communication options must be set right or the terminal
will not work at all.  Other options may be set wrong, but will cause no
problem since the features they set may not be used.  For example, if
you don't have a printer connected to the terminal it makes no
difference how the printer configuration parameters are set inside the
terminal.  This last statement is not 100% correct.  Suppose that you
have no printer but the computer (by mistake) sends the terminal a
command to redirect all characters (data) from the computer to the
printer only.  Then nothing will display on the screen and your
terminal will be dead.  Some terminals have a configuration option to
inform the terminal that no printer is attached.  In this case the
terminal will ignore any command to redirect output to the "printer"
and the above problem will never happen.  However, this doesn't help
much since there are many other erroneous commands that can be sent to
your terminal that will really foul things up.  This is likely to
happen if you send the terminal a binary file by accident.

In some cases a wrong setting will not cause any problem until you
happen to run a rare application program that expects the terminal to
be set a certain way.  Other options govern only the appearance of the
display and the terminal will work fine if they are set wrong but may
not be as pleasant to look at.

Some options concern only the terminal and do not need to be set at
the computer.  For example: Do you want black letters on a light
background?  This is easier on the eyes than a black background.
Should a key repeat when held down?  Should the screen wrap when a
line runs off the right end of the screen?  Should keys click?

<sect1> Communication Interface Options <label id="commun_config">
<p> Some of these communication settings (options) are for both the
terminal and the computer and they must be set exactly the same for
both: speed, parity, bits/character, and flow control.  Other
communication options are only set at the terminal (and only a couple
of these are essential to establish communications).  Still others
such as the address and interrupt (IRQ) of the physical port ttyS2 are
set only at the computer using the "setserial" command.  Until all of
the above essential options are compatibly set up there can be no
satisfactory serial communication (and likely no communication at all)
between the terminal and the computer.  For the terminal, one must set
these options manually by menus at each terminal (or by using some sort
of special cartridge at each terminal).  The host computer is
configured by running commands each time the computer is powered up
(or when people log in).  Sometimes the getty program (found in the
/etc/inittab file) which starts the login process will take care of
this for the computer.  See <ref id="getty_" name="Getty (used in
/etc/inittab)">

The settings for both the computer and the terminal are:
<itemize>
<item> <ref id="speed" name="Speed (bits/second) ">
<item> <ref id="parity_" name="Parity">
<item> <ref id="ch_size" name="Bits per Character ">
<item> <ref id="flow_control" name="Flow Control ">
</itemize>

Some essential settings for the terminal alone are:
<itemize>
<item> <ref id="port_select" name="Port Select">
<item> Set communication to full duplex (=FDX on Wyse terminals)
</itemize>

If the  <ref id="getty_" name="Getty (used in /etc/inittab)"> program
can't set up the computer side the way you want, then you may need to
use one (or both) of the <ref id="stty_setserial" name="Stty &
Setserial"> commands.

<sect2> Speed <label id="speed">
<p> These must be set the same on both the terminal and the computer.
The speed is the bits/sec (bps or baud rate).  Use the highest speed
that works without errors.  Enabling flow control may make higher
speeds possible.  There may be two speeds to set at the terminal:
Transmit and Receive, sometimes abbreviated T and R.  Usually they are
both set the same since stty in Linux doesn't seem to have the option
yet of setting them differently.  (There is an option to do this with
the "stty" command but it seems to actually set them both the same.)
Common speeds are 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, ...
The slower speeds (like 600) are for printers and hard-copy terminals.

<sect2> Parity & should you use it ? <label id="parity_">
<p> For a definition see <ref id="parity_def" name="Parity Explained">.
Parity-disabled is often the default.  To enable parity, you must both
enable it and then select either even or odd parity.  It probably
makes no difference if it's odd or even.  For terminals there are
sometimes settings for both transmit and receive parity.  You should
set both of these the same since stty at the computer doesn't permit
setting them differently.  The PC serial port usually can't support
different parities either.  Some terminal are unable to set receive
parity and will simply always ignore received parity bits.  On some
older terminals if you use 8-data-bits per byte then parity will not
work since there is no room in the hardware for the extra parity bit.

Should you use parity  at all?  Parity, while not really necessary, is
nice to have.  If you don't have parity, then you may get an incorrect
letter here and there and wind up trying to correct spelling errors
that don't really exist.  However parity comes at a cost.  First, it's
more complicated to set up since the default is usually no parity.
Secondly, parity will slow down the speed with which bytes travel over
the serial cable since there will be one more bit per byte.  This may
or may not slow down the effective speed.

For example, a hard-copy terminal is usually limited by the mechanics
of the printing process.  Increasing the bytes/sec when the computer
(its UART chip) is transmitting only results in more flow-control
"halt" signals to allow the mechanical printing to catch up.  Due to
more flow-control waits the effective speed is no better without
parity than with it.  The situation is similar for some terminals:
After you implement parity there may be fewer flow-control waits per
unit time resulting in more bits/sec (average).  However, due to the
added parity bits the bytes/sec (average) stays the same.

One option is to install terminals with no parity.  Then if parity
errors are noticed, it can be implemented later.  To spot possible
errors with no parity, look for any spelling errors you don't think
you made.  If you spot such an error, refresh the screen (retransmit
from the computer).  If the error goes away, then it's likely a parity
error.  If too many such errors happen (such as more than one every
few hundred screens) then corrective action is needed such as:  Enable
parity and/or reduce speed, and/or use a shorter/better cable.
Enabling parity will not reduce the number of errors but it will tell
you when an error has happened.

Just the opposite policy is to initially enable parity.  Then if no
parity errors (error symbols on the CRT) are ever seen (over a
reasonable period of time, say a month or two) it may be safely
disabled.

<sect2> Bits/Character <label id="ch_size">

<p> This is the character size (the number of data bits per character
excluding any parity bit).  To use international character sets you
need 8 bits.  But it's not of much use unless your terminal has the
fonts for them.  See <ref id="char_sets" name="Character-Sets"> If you
are only going to use ASCII characters, then select 7-bits since it's
faster to transmit 7 bits than 8.  Some very old terminals only
support 7-bit characters.


<sect2> Which Flow Control (Handshaking) ?

<p> The choice is between "hardware" (for example  dtr/cts)
or "software" (Xon/Xoff) flow control.  While hardware flow control
may be faster (if the one or two extra wires for it are available in
the cable and if the terminal supports it) in most cases Xon/Xoff
should work OK.  Some people report that they solved disturbing
problems (see below) by converting to hardware flow control but
software flow control has worked fine at other installations (and for
me personally).

If you use software (Xon/Xoff) flow control and have users who don't
know about it, then they may accidentally send an Xoff to the host and
lock up their terminal.  While it's locked, they may type frantically
in a vain attempt to unlock it.  Then when Xon is finally sent to
restore communication, all that was typed in haste gets executed,
perhaps with unexpected results.  They can't do this with hardware
flow control.  See <ref id="flow_control" name="Flow Control"> for an
explanation of flow control.

<sect2> Port select <label id="port_select">
<p> Since most terminals have two or more connectors on the back, it
is usually possible to assign one of these connecters to connect to
the host computer and assign another connector to be the printer port.
The connector may have a name next to it (inspect it) and this name
(such as Aux, Serial 2, or Modem) may be assigned to either be the
main host connection or the printer connection (or the like).

<sect1> Quick Attempt
<p> While all the above may seem overly complex, to get a terminal
working is often fairly simple.  The <ref id="quick_install"
name="Quick Install"> section describes a simple way to try to do
this.  But if that doesn't work or if you want to make the display
look better and perform better, more reading will be needed.

<sect> Terminal Set-Up (Configure) Details <label id="term_conf_details">

<p> Except for the next subsection on sending escape sequences to the
terminal, this section mainly presents the details of setting up the
terminal manually by sitting at the terminal and going thru menus.  If
you haven't already done so, you should read <ref id="term_conf_ov"
name="Terminal Set-Up (Configure) Overview">.  It's best if you have a
terminal manual, but even it you don't there is information here on
many of the options which you might possibly need to set.

The communication parameters such as its baud rate must always be set
up at the terminal since if this is not done there can be no
communication with the terminal.   Once communication is established
you have two choices for doing the rest of the terminal configuration.
You may continue to configure manually at the terminal and save the
results in the terminal's non-volatile memory or you may do this by
sending escape sequences to the terminal from the computer each time
the terminal is powered on (or the like).

If you know how to set up and save a good configuration inside the
terminal it may be the best way.  If you don't, you might want to just
send the init string from terminfo to your terminal each time you use
the terminal.  Perhaps doing nothing will still give you a usable
terminal.  You (or an application program) can always change
things by sending certain escape sequences to the terminal.

<sect1> Send Escape Sequences to the Terminal
<p> Once the communication interface is established, the rest of the
configuration of the terminals may sometimes be done by sending
escape sequences to the terminals from the computer.  If you have a
large number of terminals, it may be worthwhile to write (or locate) a
shell script to automatically do this.  There may (or may not) be a
command you can send to a terminal to tell it to save its current
set-up in its non-volatile memory so that it will be present the next
time the terminal is powered on.

There is an simple way to send these escape sequences and a complex
way.  Using the simple way, you never look up escape sequences but
issue commands that automatically find an appropriate escape sequence
in the terminfo database and send that.  Unfortunately, not all the
escape sequences which you might want to send are always in the
terminfo database.  Thus the more complex (but possibly better) way is
to directly send escape sequences.

For this complex method you'll need an advanced manual.  Old terminal
manuals once included a detailed list of escape sequences but newer
ones usually don't.  To find them you may need to purchase another
manual called the "programmers manual" (or the like) which is not
supplied with the terminal.  A <ref id="esc_seq_lists" name="Esc
Sequence List"> for some terminals is on the Internet but it's terse
and likely incomplete.

Even without a manual or the like, you may still send commands to
configure the terminal by using the programs "tput" and "setterm".
See <ref id="term_settings" name="Changing the Terminal Settings">.
You could just send the terminal an init string from the terminfo
entry if the init string sets up the terminal the way want it.  See
<ref id="init_string" name="Init String">.  Unless you plan to have
these sequences sent from the computer to the terminal each time the
terminal is powered on, you must somehow save the settings in the
non-volatile memory of the terminal.

<sect1> Older Terminals Set-Up
<p> On older terminals look at the keyboard for labels just above the
top row of numeric keys.  If they exist, these labels may be what
these keys do in set-up mode.  Some older terminals may have only one
"set-up" menu.  Still older ones have physical switches.  In some
cases not all the switches are well labeled but they may be well
concealed.  Of course, if you set something with a switch, it's
"saved" and there is no need to save the setting in non-volatile
memory.

<sect1> Getting Into Set-Up (Configuration) Mode <label id="enter_setup">
<p> To select options (configure) at the terminal, you must first
enter "set-up" mode and then select options (i.e. configure) using
menus stored inside the terminal and displayed on the screen.  To do
this, the terminal does not even need to be connected to a computer.
How to get into set-up mode is covered in the terminal's manual, but
here's some hints that may help:

If there's a "set-up" key try pressing it.  Also try it shifted.
<itemize>
<item> Wyse: First try the shifted "Select" key; then substitute
 Ctrl for shifted in all of the above.
<item> VT, Dorio: F3 may be the set-up key.  On VT420 and later models
 this key may have been programmed to do something else so turn off the
 power.  When you turn on the power again, hit the F3 key as soon as
 you get an initial screen message.
<item> IBM: 3151: Ctrl-ScrollLock.  3153: Ctrl-Minus_on_Keypad (or
 like 3151)
</itemize>

To move around in the set-up menus, try the arrow keys.  Use Return,
Space, or a special key ("toggle" on old terminals) to select.
To exit set-up mode select exit from a menu (or on some older
terminals press the set-up key again).

<sect1> Communication Options
<p> For the terminal to work at all, speed, parity, :its/character,
and communication mode must be set correctly.  Incorrect flow control
may cause loss and/or corruption of data seen on the screen. The
essential communication options were dealt with (for both the terminal
and computer) in another section:  See <ref id="commun_config"
name="Communication Interface">.  The following list provides some
links to that section, as well as some additional communication
options set only at the terminal.

<itemize>
<item> <ref id="speed" name="Speed (bits/second) ">
 (baud rate): 9600, 19200, etc.
<item> <ref id="parity_" name="Parity"> none, even, odd, mark, space
<item> <ref id="ch_size" name="Bits per Character "> {Data}: 7 or 8
<item> <ref id="flow_control" name="Flow Control:"> or Handshake
 {Hndshk}: none, Xon-Xoff, or hardware (DTR, etc).
  <itemize>
  <item> Receiver Handshake {Rcv Hndshk} protects data being Received
   by the terminal by transmitting flow-control signals to the host.
  <item> Transmitter Handshake {Xmt Hndshk} is protection of data being
   Transmitted by the terminal.   The terminal receives flow-control
   signals (and locks/unlocks the keyboard).  Includes "Incoming Xon/Xoff".
  </itemize>
<item> number of stop bits: 1 or 2. See <ref id="byte_seq" name=
 "Voltage Sequence for a Byte">
<item> Flow control level {Rcv Hndshk Level} {{Xoff at ...}}: Flow
 control will send "stop" when this number of bytes in the terminal's
 buffer is exceeded.
<item> <ref id="half_duplex" name="Communication Mode"> {Comm}: <ref
 id="half_duplex" name="Full Duplex {FDX}, Half Duplex {HDX}"> {{Local
 Echo}}, <ref id="local_mode" name="Local Mode"> {{Online/Local}}
<item> Transmit Rate (Speed) Limit {Xmt Lim}: limits the transmit rate
 to the specified cps (chars/sec) even though the baud rate setting may
 be at a higher speed.
<item> Function-Key Rate Limit: as above but for function key
 messages.
<item> <ref id="port_select" name="Port Select">: Which physical connecter
 is for the host {Host Port} ?
</itemize>

<sect1> Saving the Set-up
<p> Your set-up must be saved in the non-volatile memory of the
terminal so that it will be effective the next time you turn on the
terminal.  If you fail to save it, then the new settings will be lost
when you turn off the terminal.  Before you go to the trouble of
setting up a terminal, make sure that you know how to save the
settings.  For modern terminals the save command is done via a menu.
In some older terminals, only the manual tells how to save.  For many
of these you press Ctrl-S to save.

<sect1> Set-Up Options/Parameters <label id="set_up_pars">

<p> What follows in this section describes some of the options which are
available in the set-up menus of many terminals.  Options are also
called parameters or features.  Many options may be called "modes".
Setting options is often called "configuring".  Many of these options
may also be set by sending certain escape sequences to the terminal.
Different models and brands of terminals have various options and the
same option may be called by different names (not all of which are
given here) Terse names used by Wyse are enclosed in {...}.  Names
used mostly for VT terminals are enclosed in {{...}}.

<sect1> Emulation {Personality} {{Terminal Modes}}
<p> Most modern terminals can emulate several other terminals.  The
terminal can likely do more if it is set to emulate itself (actually
no emulation) {native personality}.   Sometimes there are 2 different
emulations for the same model of terminal.  For example VT220-7
emulates a VT220 with 7-bits/byte while VT220-8 emulates a VT220 with
8-bits/byte (256 possible characters).

Older models of terminals usually have fewer features than newer
models.  Suppose one wanted to emulate an old terminal but also wanted
some of the advanced capabilities of the later model terminal they are
sitting at.  This is sometimes possible (to some degree).  This
feature is sometimes called {Enhance} (or Enhanced ??).

<sect1> Display Options
<sect2> Character Cell Size {Char Cell}
<p> This is the size of the cell in which a character fits.  It is
measured in pixels (=tiny dots).  The more dots, the better the
resolution.   10x16 is 10 dots wide by 16 dots high (16 rows and 10
columns).  Note the notation is inverted as compared to the notation
for matrix dimensions which gives rows (height) first..  Also, the
character cell includes rows and columns of pixels allocated for the
space between adjacent characters so the cell size which defines the
boundaries of an actual character may be smaller.

<sect2> Columns/Lines
<p> Usually 80 columns and 24 or 25 lines.  This means that there may
be up to 80 characters in a row (line) on the screen.   Many terminals
have a 132 column option but unless you have a large screen, the tiny
characters may be hard to read. {{Set 132 column mode}}.  If you set
25 lines, make sure that this is in the terminfo.  You should also put
"export LINES=25" into /etc/profile and also use: "stty -F /dev/ttySx
rows 25".  If you don't it might result in a scrolling problem (see
<ref id="no_scroll_25" name="Terminal doesn't scroll">

<sect2> Cursor
<p> The cursor may be set to appear as a rectangle (= block) {Blk}.
Other options are underline {Line} or blinking.  I prefer non-blinking
{Steady} block since it's big enough to find quickly but there is no
distractive blinking.  If you set it invisible (an option on some
terminals) it will disappear but new letters will appear on the screen
as you type at the invisible cursor.

<sect2> Display Attributes (Magic Cookies)
<p> <ref id="display_attributes" name="Display Attributes"> may either
be magic cookies or be attribute bytes assigned to each character.
For magic cookies, there is a limit to their extent: Are they in
effect to the end of the line or to the end of the page?  It's best to
use attribute bytes (which could actually be half-bytes = nibbles).

<sect2> Display Control Characters {Monitor}
<p> May be called various names such as "Display Controls".  When off
(normal) it's "Interpret Controls".  When set on, you see the escape
sequences from the host (which you normally never see on the screen).
So that these sequences may be viewed in sequence on a line, they are
not acted upon (interpreted) by the terminal.  Except that a CR LF
sequence creates a new line.  See <ref id="control_codes"
name="Control Codes">.

<sect2> Double Width/Height
<p> Some terminals can have their characters double width and/or
double height.  This feature is seldom needed.  When changing a line
to double width (DW) the right half (RH) is pushed off the screen and
there is the question of whether or not to delete (erase) it.
"Preserve" means to keep the RH of DW lines.  When in double height
mode, it may be necessary to send each such line twice (the 2nd time
down one row) in order to get a double-height line on the screen.

<sect2> Reverse Video {Display} (Background Light/Dark)
<p> Normal video is light (white, green, amber) letters (foreground)
on a dark (black) background.  Reverse video {Display Light} is the
opposite: black text on a light background.  This is easier on the
eyes (unless the room is dark).

<sect2> Status Line
<p> A status line is a line at the top or bottom of the screen that
displays info about the application program you are running.  It's
often highlighted in some way.  With a status line enabled, an
application can send the terminal a special escape sequence which
means that the text that follows is for the status line.  However,
many applications don't use this feature but instead only simulate a
real status line by direct cursor positioning.  The ordinary user
looking at it doesn't know the difference.

<sect2> Upon 80/132 Change: Clear or Preserve?
<p> When switching the number of columns from 80 to 132 (or
conversely) should the data displayed in the old format be erased
(cleared) or preserved? {80/132 Clr} {{Screen Width Change}}.  It
should make no difference how you set this option since if an
application program uses 132 columns, it should set this option
appropriately via a control sequence.

<sect1> Page Related Options
<p> For a Wyse terminal to be able to access multiple pages of display
memory {Multipage} must be set to on.

<sect2> Page Size
<p> The terminal memory may be divided up into a number of pages.
See <ref id="pages_" name="Pages"> and <ref id="pages_def" name="Pages
(definition)"> for explanations of pages.  You may partition the page
memory into a number of pages of selected length.  Linux applications
don't seem to use pages at present so it shouldn't make much
difference how you set this up.

<sect2> Coupling (of cursor & display)
<p> The terminal memory may be divided up into a number of pages.
See <ref id="pages_" name="Pages"> and <ref id="pages_def" name="Pages">
for explanations of pages.  When the cursor is moved to a location in
video memory not currently displayed (such as another page, or on the
same page but to a location not displayed on the screen) should the
display change to let one view the new cursor location?  If so, this
is called "Coupling".  For cursor movement within the same page there
is "Vertical Coupling" and "Horizontal Coupling".  For movement to
another page there is "Page Coupling".

<sect1> Reporting and Answerback
<p> The terminal will identify itself and its state, or send out a
pre-recorded message in response to certain escape sequences.

<sect2> Answerback Message (String)
<p> You may write a short message during set-up which may optionally
be sent to the host at power-up or be sent to the host in response to
a request from the host (perhaps the ENQ (inquire) control character).

<sect2> Auto Answerback
<p> If set, sends the answerback message to the host at power-on
without the host asking for it.  Do any "getty" processes look for
this ??

<sect2> Answerback Concealed
<p> If set, will never let anyone see the answerback message (except
of course the host computer).  If it needs to be changed, deselect
"answerback concealed" and the formerly concealed message will be
destroyed so you then may enter a new message (but you don't get to
see the old one).

<sect2> Terminal ID {ANSI ID}
<p> The terminal sends this reply in answer to a request for identity.

<sect1> Keyboard Options
<sect2> Keyclick
<p> When set, pressing any key makes a click (broadcast by a tiny
loudspeaker in the keyboard).  These clicks annoy some people and I
think it's best to set keyclick off.

<sect2> Caps Lock {Keylock}
<p> When the Caps-Lock key is down, should only the alphabetic keys
generate shifted characters?  If set to {Caps} or upper-case-only
then hitting a number key with the Caps-Lock on will type the number.
To get the symbol above the number one must manually hold down the
shift key.  This is the normal mode.  If set to {Shift} then all keys
type the shifted character when Caps-Lock is on (hitting the 5 key
should type % without holding down Shift, etc.).

<sect2> Auto Repeat {Repeat}
<p> If a key is held down then that key is repeatedly "typed".  This
is handy for repeatedly typing the same character to create a line across
the page.

<sect2> Margin Bell
<p> When the cursor is 8 columns away from the right side of the
display, a bell is rung (like on an old typewriter).  Almost all
editors will automatically create a new line if needed (no need to
hit the Return key) so this feature is seldom needed.

<sect2> Remapping the Keys
<p> The code sent to the host when a key is pressed is normally the
ASCII code for that key (depends also on Shift and Control key).  On
some terminals you may make any key send any code you wish.  That is,
you may completely remap the keyboard by setting up the terminal that
way.  This may be useful for some foreign languages and Dvorak
keyboard layouts, etc. which permit one to type faster.  Even for
terminals that don't have the feature, there is software to remap the
keyboard (and screen also).  It's something like a device driver
which uses a pseudo terminal.  See <ref id="mapchan_" name="Character
Mapping: mapchan">

<sect2> Corner Key (for Wyse only)
<p> Wyse terminals have a key near the lower left corner which may be
set to do various things.  Its may be labelled "Funct", "Compose
Character", "Alt", "Hold" or "Scroll Lock".  Early models don't have
all of the following options:

<itemize>
<item>Hold: No-Scroll.  Hitting it stops the flow of data (using flow
control) to the terminal.  Hitting the key again restores normal flow.
<item>Compose: Hitting it followed by certain other keys permits one
to generate a limited number of pre-defined non-Latin characters.
<item>Meta: Holding it down while typing another key sets the
high-order bit on each byte.  Are there models where it acts like a
toggle to lock in the meta effect ??
<item>Funct: Holding it down while typing any alphanumeric key
gets a header (SOH) and trailer (CR) byte framing the ASCII byte code.
<item>Kpd Compose: Holding it down while typing a decimal number
on the numeric keys (followed by "enter") sends out the same number in
hexadecimal ??
</itemize>

<sect2> Numeric Keypad or Arrow Keys Sends
<p> The numeric keypad (the rectangle of mostly numeric keys to the
right of the main part of the keyboard) can be set to send special
codes which will do special things in certain application programs.
Ditto for the arrow keys.  There is thus a "normal" mode where they
send what is shown on the keycap (or the normal code sequence for an
arrow-key) and an "application" mode where special escape sequences
are sent.  In some cases there is a "hex" numeric mode which is almost
like normal numeric mode except that 6 non-numeric keys send the
letters A-F.  Thus one may type for example "B36F" on the numeric
keypad.

<sect2> What does shifted-del and shifted-bs send?
<p> Depending on how they're set up, shifted-del sometimes sends the
control character CAN and shifted backspace sometimes sends DEL.

<sect2> PC Scan Codes
<p> Many terminals can emulate a PC keyboard by sending PC scancodes
(see Keyboard-and-Console-HOWTO) instead of ASCII codes.  This is
mostly used with special Multiuser DOS OSs.  It won't work with
ordinary MS DOS.  See <ref id="non_linux" name="Non-Linux OSs">
However, hardly any Linux programs that run via the serial port can
accept scancodes.  If this is the latest version of this HOWTO, let me
know if any programs do this.  I think Foxpro can do it.  You need to
define smsc and rmsc in the terminfo, and perhaps pctrm.

When using scancodes it's best to use hardware flow control since
normal software flow control conflicts with some of the codes (??).
If you do use software flow control, you must use the XPC type of flow
control.  It uses 0x65 and 0x67 for on and off characters.  It must be
set this way both in the terminal and by stty for the PC.

<sect2> Alternate Characters
<p> Some keys may have alternative letters on them.  When keys is set
to "Typewriter" they send what they would normally send on a
typewriter.  When keys is set to something else the alternative
characters are sent.

<sect1> Meaning of Received Control Codes
<sect2> Auto New Line {Newline}
<p> In this case "New Line" means a new line starting at the left
margin below the current line.  In Linux and C "new line" (NL) may
have a different meaning: the line-feed control character LF also
called new-line or NL.  This is because in Linux text files, the LF
character means a "new line starts here" so it's labeled NL.
Normally, a LF (NL) sent to a terminal only results in the cursor
jumping down one line below where is was and does not move the cursor
back to the start of this "new line".

If Auto New Line is set, the above "normal" situation is canceled and
a physical new line is created on the display upon receiving a LF from
the host.  This is exactly what one wants in Linux.  Except that (when
Auto New Line is set) the Return (or Enter) key sends a CR LF sequence
to the host (for Wyse and VT100, but for VT420 ??).  Since Linux uses
LF as a "new line" marker in files, Linux would like only a LF to be
sent (and not a CR LF).  Thus the "New Line" option is seldom used.
Instead, the required translations are made by the serial port device
driver by default.  It is as if one gave the command "stty onlcr
icrnl".  But you don't need to do this since it's the default.

<sect2> Auto Line Feed {Rcv CR}
<p> This is just another type of "Auto New Line".  When a CR (carriage
return) character is received, a LF (line feed) action is added
resulting in a new line being displayed.  Since Linux marks the end of
lines with LF, this option is not used.

<sect2> Recognize Del (Wyse Only ??) or Null <label id="rec_del">
<p> If off, the DEL character received by the terminal is ignored.  If
on the DEL performs a destructive backspace.  Null characters are
usually ignored in any case.  Both DEL and NULL are sometimes used for
padding.  See <ref id="padding" name="Padding">

<sect1> Where New Text Goes
<sect2> Line Wrap
<p> Also called "Auto Wrap(around)".  What happens when the right edge
of the screen is reached (col. 80, etc) and no return character (or
the like) has been sent from the host?  If Line Wrap is set, then the
rest of the line displays on the line below, etc.  Otherwise, the rest
of the line is lost and is not seen on the screen.  Any good
application should handle the situation correctly (provided the
terminfo knows how Line Wrap is set).  Thus even if Line Wrap is not
set, the application should either wrap the screen for long lines or
provide another way for you to view the cutoff tail of long lines (by
use of the arrow keys, etc).  But a raw copy command (and other
situations) may not do this so it's often best to set line wrap.

For an 80 col. screen, most terminals only wrap if the 81st character
from the host is a graphic (printable) character.  This allows for the
case where 81st character from the host might be "return" or a
"newline" (non-graphic characters) which means that the application is
handing the wrapping OK and intervention by the terminal is not
needed.

<sect2> Scrolling
<p> Scrolling {Scrl} is where all the lines on the screen move up or
down.  Its also called "panning" which includes movement sideways.  In
ordinary scrolling lines roll off the bottom or top of the screen and
disappear, and new lines from the host appear at the opposite edge
(top or bottom).  There are 3 types of this: smooth, jump, or burst.
Burst is not really scrolling since its an instant replacement of an
old screenfull by a new one (although some lines on the new screen may
be from the old screen).  Jump is where new lines jump into view one
at a time.  Smooth {Smth} is where the text moves at a steady speed
upward or downward.  If the smooth scroll rate is slow enough, one may
read the newly visible lines when they are still scrolling (in motion).

Smooth scrolling on slow terminals was once useful since one could
continue reading as the display was scrolling.  But with higher baud
rates, jump scroll is so fast that little time is lost as the new
display appears.  Since it takes a little longer to read scrolling
text than fixed text, it may actually waste more time if smooth
scrolling is selected.

If (auto)scrolling {Autoscrl} is disabled, then new text from the host
must go somewhere so it is put at the top of the display.  If the old
text is not erased, the new text merges (nonsensically) into the old.
If the old text is erased, then the new text is out of context.  So
keep (auto)scrolling enabled.

<sect2> New Page?
<p> See <ref id="pages_" name="Pages"> and <ref id="pages_def"
name="Pages"> for explanations of pages.  When the current page is
full (the last line is finished) should the page scroll, or should a
new page be created (leaving the previous page stored in the
terminal's display memory).  If {Autopage} is set, then a new page is
created.  Since you are probably not using pages, you should probably
set this to off.

<sect1> Function Keys <label id="funct_keys">
<p> These are the keys labeled F1, F2, etc.  On older terminals they
may be labeled PF1, PF2, etc. where the P stands for Programmable.
Some keyboards have both.  One may program (redefine) these keys to
send out a string of user-defined bytes.  This doesn't work for older
terminals such as vt100 or for the Linux command-line interface (how
sad).  They may often be easily "programmed" using a certain set-up
menu {FKey}.  On some terminals, one may also specify where this
string is sent to when the key is pressed.  In "normal" mode, pressing
the key is just like typing the string at the keyboard.  In "local"
mode pressing the key sends it to the terminal (just like if the
terminal was in local mode).  This may be used to send escape
sequences to the terminal so as to configure it in a special way.  In
"remote" mode, the string is always sent out the serial port to the
host computer (even if the terminal is in local mode).

<sect1> Block Mode Options
<p> Some options are only for the case of <ref id="block" name="Block
Mode">.  This option is powerful since it provides forms and takes
load off the host computer by transmitting in bursts.  But it's more
complicated to set up and is thus not used too much.

<sect2> Forms Display
<p> In block mode some regions of the screen are for the text of forms
and are thus write-protected "Prot" {WPRT}.  Options may set the characters
in these regions to appear dim, reverse video {WPRT Rev}, and/or
underlined {WPRT Undrln}.  {WPRT Intensity} may be set to dim, normal,
or even blank (invisible)

<sect2> Send Entire Block ?
<p> Should write-protected text (the original text in the form) be
sent to the host upon transmission of a block: {Send All} or is
write-protected text also read-protected: {Send Erasable}

<sect2> Region to Send
<p> Should the entire screen be sent or just the scrolling region?
{Send Area}.  Should the sending stop when the current cursor position
is reached?  If {Xfer Term} is set to Cursor, only the data on the
screen up to the cursor is sent.

<sect2> Block/Page terminator
<p> What is the termination symbol to be appended to a block of data?
{Blk End} or at the end of a page {Send Term}ination.

<sect1> Locks
<p> There are various types of Locks.  One is the Locked keyboard due
to flow control.  See <ref id="keybrd_lock" name="Keyboard Lock">
Another lock {Feature Lock} is that which prohibits the host computer
from changing the terminal set-up by sending certain escape sequences
to the terminal.  Placing such a lock may result in unexpected
behavior as application programs send escape sequences to the
terminals that are ignored.  Not all set-up parameters lock.  Unless
you have a good reason to do so, you should not enable such locking.

A Function Key lock will prohibit the computer from redefining what a
programmable function key sends.  You may want to use this if you have
something important programmed into the function keys.

<sect1> Screen Saver {Scrn Saver}
<p> Also called "CRT Saver".  This turns off (or dims) the screen
after the terminal is not used for a period of time.  It may prolong
the life of the screen and save some energy.  Hitting any key will
usually restore the screen and may "execute" that key so it's best to
hit the shift-key, etc.

<sect1> Printer
<p> For Wyse, if there is no {Printer Attached} set it to Off.  It's
not essential to do this, but if you do it any escape sequence to send
text to the printer (instead of the terminal) will be ignored.

Setting up the printer port is about the same (usually simpler) as
setting up the communications on the main port.  There are a couple of
options specific to the printer.  Is the printer a serial or parallel
printer?  If it's parallel it should be designated as such in setup
and connected to the parallel port on the terminal (if there is one).
Should a FF (form feed) be sent to the printer at the end of a print
job?  If {Print Term} is set to FF, this will happen.

<sect> Computer Set-Up (Configure) Details <label id="comp_conf_details">
<p> There are various files to edit to set up the computer for
terminals.  If you're lucky, you'll only need to edit /etc/inittab.
One does this by editing at the console (or from any working terminal).

<sect1> Getty (used in /etc/inittab)  <label id="getty_">
<sect2> Introduction to Getty
<p> In order to have a login process run on a serial port (and the
terminal connected to it) when the computer starts up (or switches run
levels) a getty command must be put into the /etc/inittab file.
Running getty from the command line may cause problems (see <ref
id="stopped_" name="If getty run from command line: Programs get
stopped"> to see why ).  Getty GETs a TTY (a terminal) going.  Each
terminal needs its own getty command.  There is also at least one
getty command for the console in every /etc/inittab file.  Find this
and put the getty commands for the real terminals next to it.  This
file may contain sample getty lines for text terminals that are
commented out so that all you need to do is to uncomment them (remove
the leading #) and change a few arguments.

The arguments which are permitted depend on which getty you
use:<newline>
Two gettys best for directly connected terminals are:
<enum>
<item> agetty (sometimes just called getty):  Easy to set up with no config
required.  See <ref id="agetty_" name="agetty">
<item> <ref id="getty_ps" name="getty (part of getty_ps)"> More
advanced with config file. 
</enum>
Two gettys best for dial-in modems (avoid for directly connected
terminals) are:
<enum>
<item> mgetty: the best one for modems; works for terminals too but inferior
<item> uugetty: for modems only; part of the getty_ps package
</enum>
Simple gettys to use if you don't use a real text-terminal.  Most
Linux users use one of these at their monitor:
<enum>
<item> mingetty
<item> fbgetty
<item> fgetty
<item> rungetty
</enum>

Your Linux distribution may come with either getty_ps or agetty for
text-terminals.  Some distributions supply neither.  Unfortunately,
they often just call it "getty".  If you need to determine which one
you have look at the man page for "getty".  As of 2007 agetty (in the
"util-linux package) seems to be more widely used then getty_ps which
was at:
<url
url="http://rpmfind.net/linux/rpm2html/search.php?query=getty_ps&amp;subm"
name="getty_ps">

As a last resort to try to determine which getty you have, you might
check out its executable code (usually in /sbin).  getty_ps has
/etc/gettydefs embedded in this code.  To search for it, go
to /sbin and type:<newline> 
<tt>strings getty | grep getty </tt><newline>
If getty is actually agetty the above will result in
nothing.  However if you have agetty typing:<newline>
<tt>getty -h</tt><newline> should show the agetty options [-hiLmw].

The source codes for various gettys may be downloaded from <url url=
"http://ibiblio.org/pub/Linux/system/serial/getty/" name="Getty
Software">.

If you are not using modem control lines (for example if you only use
the minimum number of 3 conductors: transmit, receive, and common
signal ground) you should let getty know this by using a "local" flag.
The format of this depends on which getty you use.

<sect2> Getty exits after login (and can respawn)
<!-- getty_seq.D begin (in MM, TT)
This is the sequence of events that happens after getty starts up.
<sect2> How getty respawns
-->
<p>After you log in you will notice (by using "top", "ps -ax", or
"ptree") that the getty process is no longer running.  What happened
to it?  Why does getty restart again if your shell is killed?  Here's
why.

After you type in your user name, getty takes it and calls the login
program telling it your user name.  The getty process is replaced
by the login process.  The login process asks for your password,
checks it and starts whatever process is specified in your password
file.  This process is often the bash shell.  If so, bash starts and
replaces the login process.  Note that one process replaces another
and that the bash shell process originally started as the getty
process.  The implications of this will be explained below.

Now in the /etc/inittab file, getty is supposed to respawn (restart) if
killed.  It says so on the line that calls getty.  But if the bash shell
(or the login process) is killed, getty respawns (restarts).  Why?
Well, both the login process and bash are replacements for getty and
inherit the signal connections establish by their predecessors.  In
fact if you observe the details you will notice that the replacement
process will have the same process ID as the original process.  Thus
bash is sort of getty in disguise with the same process ID number.  If
bash is killed it is just like getty was killed (even though getty
isn't running anymore).  This results in getty respawning.

When one logs out, all the processes on that serial port are killed
including the bash shell.  This may also happen (if enabled) if a
hangup signal is sent to the serial port by a drop of DCD voltage by
the modem.  Either the logout or drop in DCD will result in getty
respawning.  One may force getty to respawn by manually killing bash
(or login) either by hitting the k key, etc. while in "top" or with
the "kill" command.  You will likely need to kill it with signal 9
(which can't be ignored).


<sect2> If getty run from command line: Programs get stopped
 <label id="stopped_">
<p> You should normally run getty from inside <tt>/etc/inittab</tt>
and not from the command line or else some programs running on the
terminal may be unexpectedly suspended (stopped).  Here's why (skip to
the next section if the why is not important to you).  If you start
getty for say ttyS1 from the command line of another terminal, say tty1,
then it will have tty1 as its "controlling terminal" even though the
actual terminal it runs on is ttyS1.  Thus it has the wrong
controlling terminal.  But if it's started inside the inittab file
then it will have ttyS1 as the controlling terminal (correct).

Even though the controlling terminal is wrong, the login at ttyS1 works
fine (since you gave ttyS1 as an argument to getty).  The standard
input and output are set to ttyS1 even though the controlling terminal
remains tty1.  Other programs run at ttyS1 may inherit this standard
input/output (which is connected to ttyS1) and everything is OK.  But
some programs may make the mistake of trying to read from their
controlling terminal (tty1) which is wrong.  Now tty1 may think that
these programs are being run in the background by tty1 so an attempt
to read from tty1 (it should have been ttyS1) results in stopping the
process that attempted to read.  (A background process is not allowed
to read from its controlling terminal.).  You may see a message
something like: "<tt>[1]+  Stopped</tt>" on the screen.  At this point
you are stuck since you can't interact with a process which is trying
to communicate with you via the wrong terminal.  Of course to escape
from this you can go to another terminal and kill the process, etc.

<sect2> agetty (may be named getty) <label id="agetty_">
<p>agetty means "alternative getty" and it was an easier-to-use
alternative to the original getty (getty_ps).<newline>
An example line in /etc/inittab: <newline>
<tscreen><verb>
S1:23:respawn:/sbin/getty -L 19200 ttyS1 vt102
</verb></tscreen>
S1 is from ttyS1.  23 means that getty is run upon entering run levels
2 or 3.  respawn means that if getty (or a process that replaced it
such as bash) is killed, getty will automatically start up (respawn)
again.  /sbin/getty is the getty command.  The -L means Local (ignore
modem control signals).  -h (not shown in the example) enables
hardware flow control (same as stty crtscts).  19200 is the baud rate.
ttyS1 means /dev/ttyS1 (COM2 in MS-DOS).  vt102 is the type of
terminal and this getty will set the environment variable TERM to this
value.  There are no configuration files.  Type "init q" on the
command line after editing getty and you should see a login prompt.

<sect3> Agetty's auto-detection of parity problems
<p> The <tt/agetty/ program will attempt to auto-detect the parity set
inside the terminal (including no parity).  It doesn't support 8-bit
data bytes plus 1-bit parity.  See <ref id="parity_8-bit" name="8-bit
data bytes (plus parity)">.  If you use <tt/stty/ to set parity,
<tt/agetty/ will automatically unset it since it initially wants the
parity bit to come thru as if it was a data bit.  This is because it
needs to get the last bit (possibly a parity bit) as you type your
login-name so that it can auto-detect parity.  Thus if you use parity,
enable it only inside the text-terminal and let <tt/agetty/
auto-detect it and set it at the computer.  If your terminal supports
received parity, the login prompt will look garbled until you type
something so that getty can detect the parity.  The garbled prompt
will deter visitors, etc. from trying to login.  That could be just
what you want.

There is sometimes a problem with auto detection of parity.  This
happens because after you first type your login name, <tt/agetty/
starts the <tt/login/ program to finish logging you in.
Unfortunately, the <tt/login/ program can't detect parity so if the
<tt/getty/ program failed to determine the parity then <tt/login/ will
not be able to determine it either.  If the first login attempt fails,
<tt/login/ will let you try again, etc. (all with the parity set
wrong).  Eventually, after a number of failed attempts to login (or
after a timeout) <tt/agetty/ will start up again and start the login
sequences all over again.  Once getty is running again, it may be able
to detect the parity on the second try so everything may then work OK.

With wrong parity, the <tt/login/ program can't correctly read what
you type and you can't log in.  If your terminal supports received
parity, you will continue to see a garbled screen.  If getty fails to
detect parity an /etc/issue file is usually dumped to the screen just
before the before the prompt, so more garbled words may appear on the
screen.

Why can't agetty detect parity by the first letter typed?  Here's an
example: Suppose it detects an 8-bit byte with its parity bit 0
(high-order bit) and with an odd number of 1-bits.  What parity is it?
Well, the odd number of 1 bits implies that it's odd parity.  But it
could also just be an 8-bit character with no parity.  There's no way
so far to determine which.  But so far we have eliminated the
possibility of even parity.  The detection of parity thus proceeds by
a process of elimination.

If the next byte typed is similar to the first one and also only
eliminates the possibility of even parity, it's still impossible to
determine parity.  This situation can continue indefinitely and in rare
cases login will fail until you change your login-name.  If agetty
finds a parity bit of 1 it will assume that this is a parity bit and
not a high-order bit of an 8-bit character.  It thus assumes that you
don't use meta-characters (high bit set) in your user name (i.e that
your name is in ASCII).

One may get into a "login loop" in various ways.  Suppose you only
type a single letter or two for your login name and then hit return.
If these letters are not sufficient for parity detection, then login
runs before parity has been detected.  Sometimes this problem happens
if you don't have the terminal on and/or connected when agetty first
starts up.

If you get stuck in this "login loop" a way out of it is
to hit the return key several times until you get the getty login
prompt.  Another way is to just wait a minute or so for a timeout.
Then the getty login prompt will be put on the screen by the getty
program and you may try again to log in.

<sect3> 8-bit data bytes (plus parity) <label id="parity_8-bit">
<p> Unfortunately, agetty can't detect this parity.  As of late 1999
it has no option for disabling the auto-detection of parity and thus
will detect incorrect parity.  The result is that the login process
will be garbled and parity will be set wrong.  Thus it doesn't seem
feasible to try to use 8-bit data bytes with parity.

<sect2> getty (part of getty_ps) <label id="getty_ps">
<p>The name has often been misspelled as <tt>ps_getty</tt>. (Most of
this is from the old Serial-HOWTO by Greg Hankins)<newline> For this
getty one needs to both put entries in a configuration file and add an
entry in <tt>/etc/inittab</tt>.  Here are some example entries to use
for your terminal that you put into the configuration file
<tt>/etc/gettydefs</tt>.

<tscreen><verb>
# 38400 bps Dumb Terminal entry
DT38400# B38400 CS8 CLOCAL # B38400 SANE -ISTRIP CLOCAL #@S @L login: #DT38400

# 19200 bps Dumb Terminal entry
DT19200# B19200 CS8 CLOCAL # B19200 SANE -ISTRIP CLOCAL #@S @L login: #DT19200

# 9600 bps Dumb Terminal entry
DT9600# B9600 CS8 CLOCAL # B9600 SANE -ISTRIP CLOCAL #@S @L login: #DT9600
</verb></tscreen>
<p> Note that the DT38400, DT19200, etc. are just labels and must
be the same that you use in <tt>/etc/inittab</tt>.

If you want, you can make <tt/getty/ print interesting things in the
login banner.  In my examples, I have the system name and the serial
line printed.  You can add other things:
<tscreen><verb>
@B    The current (evaluated at the time the @B is seen) bps rate.
@D    The current date, in MM/DD/YY.
@L    The serial line to which getty is attached.
@S    The system name.
@T    The current time, in HH:MM:SS (24-hour).
@U    The number of currently signed-on users.  This is  a
      count of the number of entries in the /etc/utmp file
      that have a non-null ut_name field.
@V    The value of VERSION, as given in the defaults file.
To display a single '@' character, use either '\@' or '@@'.
</verb></tscreen>

When you are done editing <tt>/etc/gettydefs</tt>, you can verify that
the syntax is correct by doing:
<tscreen><verb>
linux# getty -c /etc/gettydefs
</verb></tscreen>

Make sure there is no other <tt/getty/ or <tt/uugetty/ config file for
the serial port that your terminal is attached to such as
(<tt>/etc/default/{uu}getty.ttyS</tt><em/N/ or
<tt>/etc/conf.{uu}getty.ttyS</tt><em/N/), as this will probably
interfere with running <tt/getty/ on a terminal.  Remove such
conflicting files if they exits.

Edit your <tt>/etc/inittab</tt> file to run <tt/getty/ on the serial
port (substituting in the correct information for your environment -
port, speed, and default terminal type):
<tscreen><verb>
S1:23:respawn:/sbin/getty ttyS1 DT9600 vt100
</verb></tscreen>
Restart <tt/init/:
<tscreen><verb>
linux# init q
</verb></tscreen>

At this point, you should see a login prompt on your terminal.  You
may have to hit return to get the terminal's attention.

<sect2> mgetty
<p> The "m" stands for modem.  This program is primarily for modems
and as of mid 2000 it will require recompiling to use it for
text-terminals (unless you use hardware flow control --and that
usually requires a hand-made cable).  For the documentation for
directly connected terminals see the "Direct" section of the manual:
<tt>mgetty.texi.</tt>

Look at the last lines of <tt>/etc/mgetty/mgetty.config</tt> for an
example of configuring it for a terminal.  Unless you say "toggle-dtr
no" it will think that you have a modem and drop (negate) the DTR pin
at the PC in a vain attempt to reset the non-existent modem.  In
contrast to other gettys, mgetty will not attach itself to a terminal
until someone hits any key of that terminal so you'll see a ? for the
terminal in <tt/top/ or <tt/ps/ until this happens.  The logs in
<tt>/var/log/mgetty/</tt> may show a few warning messages which are
only applicable to modems which you may ignore.

Here's an example of the simple line you put in <tt>/etc/inittab:</tt>

<tscreen><verb>
s1:23:respawn:/sbin/mgetty -r ttyS1
</verb></tscreen>

<sect1> Stty & Setserial <label id="stty_setserial">
<p> There is both a "stty" command and a "setserial" command for
setting up the serial ports.   Some (or all) of the needed stty
settings can be done via getty and there may be no need to use
setserial so you may not need to use either command.  These two
commands (stty and setserial) set up different aspects of the serial
port.  Stty does the most while setserial configures the low-level
stuff such as interrupts and port addresses.  To "save" the settings,
these commands must be written in certain files (shell scripts) which
run each time the computer starts up.  Distributions of Linux often
supply a shell script which runs <tt/setserial/ but seldom supply one
which runs <tt/stty/ since on seldom need it.

<sect1> Setserial <label id="set_serial">
<!-- setserial.D  begin  (in MM TT SS)
<sect1>What is Setserial ? <label id="set_serial">
Change Log:
May 2000: <sect2> IRQs near end ttyS0 -> ttyS1 + clarity
Nov. 2000: auto_irq may work on the 2nd try
Dec. 2000: saving state of serial module
June 2001 OK to use setserial with Laptops
Nov. 2002 Debian's /var/lib/serial.conf
Nov. 2003 Major revision.  Plug-and-play dominates
May 2004 Old Debian 1999 bug reported by me removed (fixed in 1999)
Feb.2005 Where config files reside
 /var/lib/setserial/autoserial.conf
-->
<p> This part is in 3 HOWTOs: Modem, Serial, and Text-Terminal.  There
are some minor differences, depending on which HOWTO it appears in.

<sect2>Setserial problems with linmodems, laptops
<p> 
If you have a Laptop (PCMCIA) don't use <tt/setserial/ until you
read <ref id="laptops_" name="Laptops: PCMCIA">.

<sect2> Introduction
<p><tt/setserial/ is a program used for the user to communicate with
the serial device driver.  You normally never need to use it, provided
that you only use the one or two serial ports that come as standard
equipment with a PC.  Even in other cases, most extra serial ports
should be auto-detected by modern kernels.  Except you'll need to use
setserial if you have an obsolete ISA serial port set by jumpers on the
physical hardware or if your kernel (such as 2.2 or older) doesn't
both detect and set your add-on PCI serial ports.  In some cases the
setserial program may have been previously used and the wrong serial
port data has been manually given by the some past user (perhaps by
you).  If setserial hasn't been configured to accept what the kernel
says, it will override the (likely correct) kernel data with what
someone previously set.

<tt/setserial/ allows you (or a shell script) to talk to the serial
software.  But there's also another program, tt/stty/, that also deals
with the serial port and is used for setting the port speed, etc.
<tt/setserial/ is really a misnomer, it doesn't set any information on
the serial card.  Example: it can't change the irq set on the card.
More details on this later

<tt/setserial/ deals with the lower-level configuring of the serial
port, such as dealing with IRQs (such as 5), port addresses (such as
3f8), and the like.  A major problem with it is that it can't
set or configure the serial port hardware: It can't set the IRQ or
port addresses into the hardware.  Furthermore, when it seemingly
reports the configuration of the hardware, it's sometimes wrong since
it doesn't actually probe the hardware unless you specifically tell it
to.  Even then, it doesn't do the modern type of bus probing and some
hardware may never be found by it.  Still, what it shows is right most
all the time but if you're having trouble getting a serial port to
work, then there's a fair chance it's wrong.

In olden days, when the IRQ and port address was set by jumpers on the
serial card, one would use <tt/setserial/ to tell the driver how these
jumpers were set.  Today, when plug-and-play methods detect how the
jumperless serial port is set, <tt/setserial/ is not really needed
anymore unless you're having problems or using old hardware.
Furthermore, if the configuration file used by <tt/setserial/ is
wrong, then there's trouble.  In this case, if you use <tt/setserial/
to try to find out how the port is configured, it may just repeat the
incorrect information in the setserial configuration file.

<tt/setserial/ can sometimes be of help to find a serial port.  But 
it's only of use if you know the port address and use the right
options.  For modern ports, there's usually better ways to look for
them by plug-and-play methods.

Thus the name <tt/setserial/ is somewhat of a misnomer since it
doesn't set the I/O address nor IRQ in the hardware, it just "sets"
them in the driver software.  And the driver naively believes that
what <tt/setserial/ tells it, even if it conflicts with what the driver
has found by using plug-and-play methods.  Too bad that it fails to
at least issue a warning message for setserial such a conflict.  Since the
device driver is considered to be part of the kernel, the word
"kernel" is often used in other documentation with no mention made of
any "serial driver". 

Some distributions (and versions) set things up so that <tt/setserial/
is run at boot-time by an initialization shell script (in the
/etc directory tree).   But the configuration file which this script
uses may be either in the /etc tree or the /var tree.  In some cases,
if you want <tt/setserial/ to run at boot-time, you may have to take
some action.  <tt/setserial/will not work without either serial
support built into the kernel or loaded as a module.  The module may
get loaded automatically if you (or a script) attempt to use
<tt/setserial/.

While <tt/setserial/ can be made to probe the hardware IO port
addresses to try to determine the UART type and IRQ, this has
severe limitations.  See <ref id="probing_ss" name="Probing">.  It
can't set the IRQ or the port address in the hardware of PnP or PCI
serial ports (but the plug-and-play features of the serial driver may
do this).  It also can't directly read the PnP data stored in
configuration registers in the hardware.  But since the device driver
can read these registers and setserial tells you what the device
driver thinks, it might be correct.  Or it could be telling you what
<tt/setserial/ had previously (and perhaps erroneously) told the
driver.  There's no way to know for sure without doing some other
checks.

The serial driver (for Linux Kernels 2.4 and 2.6) looks for a few
"standard" legacy serial ports, for PnP ports on the ISA bus, and for
all supported port hardware on the PCI bus.  If it finds your ports
correctly, then there's no need to use <tt/setserial/ unless they have
been "set" incorrectly in the setserial configuration file.  The driver
doesn't probe for the IRQs of old ISA serial ports set with jumpers on
the card and may get these wrong.

Besides the man page for <tt/setserial/, check out info in
<tt>/usr/doc/setserial.../</tt> or <tt>/usr/share/doc/setserial</tt>.
This should tell you how setserial is handled for your distribution of
Linux.  While <tt/setserial/ behaves the same in all distributions,
the scripts for running it, how to configure such scripts (including
automatic configuration), and the names and locations of the script
files, etc., are all distribution-dependent.  If your serial port is Plug-and-Play you may need to consult other
HOWTOs such as Plug-and-Play or Serial.

<sect2>Serial module unload
<p>If a serial module gets unloaded, the changes previously made by
<tt/setserial/ will be forgotten by the driver.  But while the driver
forgets it, a script provided by the distribution may save it in a
file somewhere so that it can the restored if the module is reloaded.
Also changes made by setserial may be stored in setserial's
configuration file (see the documentation for your distribution, this
info is not in the man page).

  

<sect2>Giving the <tt/setserial/ command
<p>Remember, that <tt/setserial/ can't set any I/O addresses or IRQs
in the hardware.  That's done either by plug-and-play software (run by
the driver) or by jumpers for legacy serial ports.  Even if you give
an I/O address or IRQ to the driver via <tt/setserial/ it will not set
such values and assumes that they have already been set.  If you give
it wrong values, the serial port will not work right (if at all).

For legacy ports, if you know the I/O address but don't know the IRQ
you may command setserial to attempt to determine the IRQ.

You can see a list of possible commands by just typing <tt/setserial/
with no arguments.  This fails to show you the one-letter options such
as -v for verbose which you should normally use when troubleshooting.
Note that setserial calls an IO address a "port".  If you type:
<tscreen><verb>
setserial -g /dev/ttyS*
</verb></tscreen>
You'll see some info about how the device driver is configured for
your ports.  In many cases you'll see some ports displayed with what
appears at first glance to be erroneous IRQs and addresses.  But if
you also see: <tt>"UART: unknown"</tt> just ignore the entire line
since no serial port exists at that address. 

If you add -a to the option -g you will see more info although few
people need to deal with (or understand) this additional info since
the default settings you see usually work fine.  In normal cases the
hardware is set up the same way as "setserial" reports.  But if you are
having problems there is a good chance that <tt/setserial/ has it wrong.
In fact, you can run "setserial" and assign a purely fictitious I/O
port address, any IRQ, and whatever uart type you would like to have.
Then the next time you type "setserial ..." it will display these
bogus values you've supplied to the driver.  They will also be officially
registered with the kernel as displayed (at the top of the screen) by
the "scanport" command (Debian).  Of course the serial
port driver will not work correctly (if at all) if you attempt to use
such a port.  Thus, when giving parameters to <tt/setserial/, "anything
goes".  Well almost.  If you assign one port a base address that is
already assigned (such as 3e8) it may not accept it.  But if you use
3e9 it will accept it.  Unfortunately 3e9 is actually assigned since it
is within the range starting at base address 3e8.  Thus the moral of
the story is to make sure your data is correct before assigning
resources with setserial.

<sect2>Configuration file
<p>While assignments made by setserial are lost when the PC is powered
off, a configuration file may restore them when the PC is started
up again.  In newer versions, what you change by setserial might get
automatically saved to a configuration file.  When <tt/setserial/ runs
it uses the info from the configuration file.

Where this configuration file resides depends on your distribution.
Look at the start-up scripts somewhere in the /etc/ tree (such as
/etc/init.d/ or /etc/rc.d/) and read the startup script for "serial"
or "setserial" or the like.  It should show where the configuration
file(s) reside.  In Debian there are 4 options for use of this
configuration file:

<enum>
<item>Don't use this file at all.  At each boot, the serial driver
alone detects the ports and setserial doesn't ever run.  ("kernel" option)
<item>Save what <tt/setserial/ reports when the system is first
shutdown and put it in the configuration file.  After that, don't ever
make any changes to the configuration file, even if someone has made
changes by running the <tt/setserial/ command on the command line and
then shuts down the system. ("autosave-once" option)
<item>At every shutdown, save whatever <tt/setserial/ detects to the
configuration file.  ("autosave" option)
<item>Manually edit the configuration file to set the configuration.
Don't ever do any automatic saves to it. ("manual" option)
</enum>

In olden days (perhaps before 2000), there wasn't any configuration
file and the configuration was manually set (hard coded) inside the
shell script that ran <tt/setserial/.  See <ref id="old_sets_script"
name="Edit a script (prior to version 2.15)">.

<sect2> Probing <label id="probing_ss">
<p>You probe for a port with <tt/setserial/ only when you suspect that
it has been enabled (by PnP methods, the BIOS, jumpers, etc.).
Otherwise <tt/setserial/ probing will never find it since its address
doesn't exist.  A problem is where the software looks for a port at
specified I/O addresses.  Prior to probing with "setserial", one may
run the "scanport" (Debian) command to check all possible ports in one
scan.  It makes crude guesses as to what is on some ports but doesn't
determine the IRQ.  It's a fast first start.  It may hang your PC but
so far it's worked fine for me.  Note that non-Debian distributions
don't seem to supply "scanport".  Is there another scan program?

With appropriate options, <tt/setserial/ can probe (at a given I/O
address) for a serial port but you must guess the I/O address.  If you
ask it to probe for /dev/ttyS2 for example, it will only probe at the
address it thinks ttyS2 is at (2F8).  If you tell setserial that ttyS2
is at a different address, then it will probe at that address, etc.
See <ref id="probing_ss" name="Probing">

The purpose of such probing is to see if there is a uart there, and if
so, what its IRQ is.  Use <tt/setserial/ mainly as a last resort as
there are faster ways to attempt it such as wvdialconf to detect
modems, looking at very early boot-time messages, or using <tt>pnpdump
--dumpregs</tt>, or lspci -vv.  But if you want to detect hardware
with <tt/setserial/ use for example :<newline> <tt>setserial
/dev/ttyS2 -v autoconfig</tt><newline>
If the resulting message shows a uart type such as 16550A, then you're
OK.  If instead it shows "<tt/unknown/" for the uart type, then there
is supposedly no serial port at all at that I/O address.  Some cheap
serial ports don't identify themselves correctly so if you see
"<tt/unknown/" you still might have a serial port there.

Besides auto-probing for a uart type, setserial can auto-probe for
IRQ's but this doesn't always work right either.  In one case it first
gave the wrong irq but when the command was repeated it found the
correct irq.  In versions of setserial >= 2.15, the results of your
last probe test could be automatically saved and put into a
distribution-specific configuration file such as
<tt>/etc/serial.conf</tt> or <tt>/etc/sysconfig/serial</tt> or
<tt>/var/lib/setserial/autoserial.conf</tt> for Debian.  This will be
used next time you start Linux.  

It may be that two serial ports both have the same IO address set in
the hardware.  Of course this is not normally permitted for the ISA
bus but it sometimes happens anyway.  Probing detects one serial port
when actually there are two.  However if they have different IRQs,
then the probe for IRQs may show IRQ = 0.  For me, it only did this if
I first used <tt/setserial/ to give the IRQ a fictitious value.

<sect2>Boot-time Configuration <label id="sets_boot_time">
<p>While <tt/setserial/ may run via an initialization script,
something akin to <tt/setserial/ also runs earlier when the serial
module is loaded (or when the kernel starts the built-in serial driver
if it was compiled into the kernel).  Thus when you watch the start-up
messages on the screen it may look like it ran twice, and in fact it
has. 

If the first message is for a legacy port, the IRQs shown may be wrong
since it didn't probe for IRQs.  If there is a second report of serial
ports, it may the result of a script such as /etc/init.d/setserial.
It usually does no probing and thus could be wrong about how the
hardware is actually set.  It only shows configuration data that got
saved in a configuration files.  The old method, prior to setserial
2.15, was to manually write such data directly into the script.

When the kernel loads the serial module (or if the "module equivalent"
is built into the kernel) then all supported PnP ports are detected.
For legacy (non-PnP) ports, only <tt/ttyS{0-3}/ are auto-detected
and the driver is set to use only IRQs 4 and 3 (regardless of what
IRQs are actually set in the hardware).  No probing is done for IRQs
but it's possible to do this manually.  You see this as a boot-time
message just as if <tt/setserial/ had been run.

To correct possible errors in IRQs (or for other
reasons) there may be a script file somewhere that runs
<tt/setserial/.  Unfortunately, if this file has some IRQs wrong, the
kernel will still have incorrect info about the IRQs.  This file is
usually part of the initialization done at boot-time.  Whether it
runs or not depends on how you (and/or your distribution) have set
things up.  It may also depends on the runlevel.  

Before modifying a configuration file, you can test out a "proposed"
<tt/setserial/ command by just typing it on the command line.  In some
cases the results of this use of <tt/setserial/ will automatically get
saved somewhere such as /etc/serial.conf (or autoserial.conf or
serial) when you shutdown.  So if it worked OK (and solved your
problem) then there's no need to modify any configuration file.  See
<ref id="config_file" name="Configuration method using
/etc/serial.conf, etc.">.

<sect2> Edit a script (required prior to version 2.15)
 <label id="old_sets_script">
<p> This is how it was done prior to <tt/setserial/ 2.15 (1999)
The objective was to modify (or create) a script file in the /etc
tree that runs setserial at boot-time.  Most distributions provided
such a file (but it may not have initially resided in the /etc tree).

So prior to version 2.15 (1999) it was simpler.  All you did was edit
a script.  There was no /etc/serial.conf file (or the like) to
configure setserial.   Thus you needed to find the file that runs
"setserial" at boot time and edit it.  If it didn't exist, you needed
to create one (or place the commands in a file that ran early at
boot-time).  If such a file was currently being used it's likely
was somewhere in the /etc directory-tree.  But Redhat <6.0 has supplied it
in /usr/doc/setserial/ but you need to move it to the /etc tree before
using it.

The script <tt>/etc/rc.d/rc.serial</tt> was commonly used in the past.
The Debian distribution used <tt>/etc/rc.boot/0setserial</tt>.
Another file once used was <tt>/etc/rc.d/rc.local</tt> but it's may
not have run early enough.  It was reported that other processes may
try to open the serial port before rc.local ran resulting in serial
communication failure.  Later on it most likely was found in
/etc/init.d/ but wasn't normally intended to be edited.

If such a file was supplied, it likely contained a number of
commented-out examples.  By uncommenting some of these and/or
modifying them, you could set things up correctly.  It was important
use a valid path for <tt/setserial/, and a valid
device name.  You could do a test by executing this file manually
(just type its name as the super-user) to see if it works right.
Testing like this was a lot faster than doing repeated reboots to get
it right.

For versions >= 2.15 (provided your distribution implemented the
change, Redhat didn't at first) it may be more tricky to do since the
file that runs setserial on startup, /etc/init.d/setserial or the like
was not intended to be edited by the user.  See <ref id="config_file"
name="Configuration method using /etc/serial.conf, etc.">.

An example line in such a script was:
<tscreen><verb>
/sbin/setserial /dev/ttyS3 irq 5 uart 16550A  skip_test
</verb></tscreen>

or, if you wanted setserial to automatically determine the uart and the
IRQ for ttyS3 you would have used something like this:

<tscreen><verb>
/sbin/setserial  /dev/ttyS3 auto_irq skip_test autoconfig
</verb></tscreen>

This was done for every serial port you wanted to auto configure,
using a device name that really does exist on your machine.  In some
cases it didn't work right due to the hardware. 

<sect2> Configuration method using /etc/serial.conf, etc.
<label id="config_file">
<p> Prior to setserial version 2.15 (1999), the way to configure
setserial was to manually edit the shell-script that ran setserial at
boot-time.  See <ref id="old_sets_script" name="Edit a script (before
version 2.15)">.  This was simple, but the simple and clear method has
been changed to something that is unnecessarily complex.  Today the
script and configuration file are two different files instead of one.
This shell-script is not edited but gets its data from a configuration
file such as <tt>/etc/serial.conf</tt> (or
<tt>/var/lib/setserial/autoserial.conf</tt>).

Furthermore you may not even need to edit serial.conf (or the like)
because using the "setserial" command on the command line may
automatically cause serial.conf to be edited appropriately.  This was
done so that you may not need to edit any file in order to set up (or
change) what setserial does each time that Linux is booted.

What often happens is this:  When you shut down your PC the script
that ran "setserial" at boot-time is run again, but this time it only
does what the part for the "stop" case says to do:  It uses
"setserial" to find out what the current state of "setserial" is, and
it puts that info into the serial configuration file such as
<tt>serial.conf</tt>.  Thus when you run "setserial" to change
the serial.conf file, it doesn't get changed immediately but only when
and if you shut down normally.

Now you can perhaps guess what problems might occur.  Suppose you
don't shut down normally (someone turns the power off, etc.) and the
changes don't get saved.  Suppose you experiment with "setserial" and
forget to run it a final time to restore the original state (or make a
mistake in restoring the original state).  Then your "experimental"
settings are saved.  And worst of all, unless you know which options
were set in the configuration file, you don't know what will happen.
One option in Debian (and likely other distributions) is known as
"AUTOSAVE-ONCE" which saves changes only for the first time you make
them with the setserial command.

If the option "###AUTOSAVE###" is set and you manually edit
serial.conf, then your editing is destroyed when you shut down because
it gets changed back to the state of setserial at shutdown.  There is
a way to disable the changing of serial.conf at shutdown and that is
to remove "###AUTOSAVE###" or the like from first line of serial.conf.
In the Debian distribution, the removal of "###AUTOSAVE###" from the
first line was once automatically done after the first time you
shutdown just after installation.  To retain this effect the
"AUTOSAVE-ONCE" option was created which only does a save when time
the system is shut down for the first time (just after you install or
update the setserial program).

The file most commonly used to run setserial at boot-time (in
conformance with the configuration file) is now /etc/init.d/setserial
(Debian) or /etc/init.d/serial (Redhat), or etc.,  but it should not
normally be edited.  For 2.15, Redhat 6.0 just had a file
/usr/doc/setserial-2.15/rc.serial which you have to move to
/etc/init.d/ if you want setserial to run at boot-time.

To disable a port, use <tt/setserial/ to set it to "uart none".  This
will not be saved.  The format of /etc/serial.conf appears to be just
like that of the parameters placed after "setserial" on the command
line with one line for each port.  If you don't use autosave, you may
edit /etc/serial.conf manually.

In order to force the current settings set by setserial to be saved to
the configuration file (serial.conf) without shutting down, do what
normally happens when you shutdown: Run the shell-script
<tt>/etc/init.d/{set}serial stop</tt>.  The "stop" command will save
the current configuration but the serial ports still keep working OK.

In some cases you may wind up with both the old and new configuration
methods installed but hopefully only one of them runs at boot-time.
Debian labeled obsolete files with "...pre-2.15".

<sect2> IRQs

<p> By default, both ttyS0 and ttyS2 will share IRQ 4, while ttyS1 and
ttyS3 share IRQ 3.  But while sharing serial interrupts (using them in
running programs) is OK for the PCI bus, it's not permitted for the
ISA bus unless you: 1. have kernel 2.2 or better, and 2. you've
compiled in support for this, and 3. your serial hardware supports it.
See
Serial-HOWTO: Interrupt sharing and Kernels 2.2+.


If you only have two serial ports, ttyS0 and ttyS1, you're still OK
since IRQ sharing conflicts don't exist for non-existent devices.

If you add a legacy internal modem (without plug-and-play) and retain
ttyS0 and ttyS1, then you should attempt to find an unused IRQ and set
it in your serial port (or modem card) and then use setserial to
assign it to your device driver.  If IRQ 5 is not being used for a
sound card, this could be used for a modem.

<sect2> Laptops: PCMCIA <label id="laptops_">
<p>If you have a Laptop, read PCMCIA-HOWTO for info on the serial
configuration.  For serial ports on the motherboard, setserial is used
just like it is for a desktop.  But for PCMCIA cards (such as a modem)
it's a different story.  The configuring of the PCMCIA system should
automatically run setserial so you shouldn't need to run it.  If you
do run it (by a script file or by /etc/serial.conf) it might be
different and cause trouble.  The autosave feature for serial.conf
shouldn't save anything for PCMCIA cards (but Debian did until
2.15-7).  Of course, it's always OK to use setserial to find out how
the driver is configured for PCMCIA cards.

<!-- setserial.D  end -->

<sect1> Stty <label id="stty_">
<!-- stty.D begin <sect1> Stty <label id="stty_">
In Serial and Text-Terminal
Feb. 2005: Put redirection info into Obsolete section
-->
<sect2> Introduction
<p> <tt/stty/ does much of the configuration of the serial port but
since application programs (and the getty program) often handle this,
you may not need to use it much.  It's handy if you're having problems
or want to see how the port is set up.  It also configures the terminal
interface which is not only used by the serial port but is also used
anytime you use a command-line interface in Linux.  Try typing ``stty
-a'' at your terminal/console to see how it's now set.  Also try typing
it without the -a (all) for a short listing which shows how it's set
different than "normal" which is how it's set using the command
<tt>"stty sane"</tt>.  Don't try to learn all the settings unless you
want to become a serial historian since many of the settings are only
for slow antique dumb terminals of the 1970's.  Most of the defaults
should work OK.

<tt/stty/ is documented in the man pages with a more detailed account
in the info pages.  Type <tt>"man stty"</tt> or <tt>"info stty"</tt>.

Many of the stty options (or settings) start with an "o" (output) or an
"i" (input).  For example: <tt/onlcr/.  Output is the flow of bytes out
of the computer while input is the flow of bytes into the computer.  The
"point of view" is the computer, not the serial port or the device
connected to the serial port.  For example, received input data comes in
on a cable and goes to the serial port chip.  This chip, after
converting the bits from the serial to parallel representation, then
sends it (via a program read) to the large serial port buffer in main
computer memory.  Thus the chip has both input and output but since it's
input data to the computer, its output is considered to be input.  The
situation is similar for output flowing thru this chip.  The "input" and
"output" refer to the direction of flow with respect to the computer and
not the serial port hardware (the chip).

Whereas <tt/setserial/ only deals with actual serial ports, stty is used
for terminals regardless of whether they are accesses via a serial port,
network, or by a virtual terminal on Linux PC monitor, or a GUI
terminal window such as xterm.  For the PC monitor, xterm, or a network
many of the stty settings are meaningless.  Changing the baud rate, etc.
doesn't appear to actually do anything.

Here are some of the items stty configures: speed (bits/sec), parity,
bits/byte, # of stop bits, strip 8th bit?, modem control signals, flow
control, break signal, end-of-line markers, change case, padding, beep
if buffer overrun?, echo what you type to the screen, allow background
tasks to write to terminal?, define special (control) characters (such
as what key to press for interrupt).  See the <tt/stty/ man or info
page for more details.  Also see the man page: <tt/termios/ which
covers the same options set by stty but (as of mid 1999) covers
features which the stty man page fails to mention.
For use of some special characters see <ref
id="stty_chars" name="Special (Control) Characters">

With some implementations of getty (getty_ps package), the commands
that one would normally give to stty are typed into a getty
configuration file: /etc/gettydefs.  Even without this configuration
file, the getty command line may be sufficient to set things up so
that you don't need stty.

One may write C programs which change the stty configuration, etc.
Looking at some of the documentation for this may help one better
understand the use of the stty command (and its many possible
arguments).  Serial-Programming-HOWTO may be useful but it's outdated.
The manual page: termios contains a description of the C-language
structure (of type termios) which stores the stty configuration in
computer memory.  Many of the flag names in this C-structure are
almost the same (and do the same thing) as the arguments to the stty
command.

<sect2> Flow control options
<p> To set hardware flow control use "crtscts".  For software flow
control there are 3 settings: ixon, ixoff, and ixany.

ixany: Mainly for terminals.  Hitting any key will restart the flow
after a flow-control stop.  If you stop scrolling with the "stop
scroll" key (or the like) then hitting any key will resume scrolling.
It's seldom needed since hitting the "scroll lock" key again will do
the same thing.

ixon: Enables the port to listen for Xoff and to stop transmitting
when it gets an Xoff.  Likewise, it will resume transmitting if it gets
an Xon.

ixoff: enables the port to send the Xoff signal out the transmit line
when its buffers in main memory are nearly full.  It protects the
device where the port is located from being overrun.

For a slow dumb terminal (or other slow device) connected to a fast
PC, it's unlikely that the PC's port will be overrun.  So you seldom
actually need to enable ixoff.  But it's often enabled "just in case".

<sect2> Using stty at a "foreign" terminal
<p>How do you use stty to view or set a terminal other than the
terminal you are currently using?  It's usually impossible to do it if
the foreign terminal is in use and has a shell running on it.  In
other cases for dealing with say ttyS2 while typing at another
terminal (such as tty1) use <tt> stty -F /dev/ttyS2 ...</tt> (or
--file instead of F).  If ... is -a it displays all the stty settings
(-a means all).

But if the foreign terminal (ttyS2 in this example) has a shell
running on it, then what you see will likely be deceptive and trying
to set it will not work.  This problem exists for virtual terminals
also such as dealing with tty3 from tty1, etc.  See <ref
id="two_term_interfaces" name="Two interfaces at a terminal"> to
understand it.

<sect2> Two interface modes at a terminal <label id="two_term_interfaces">
<p> When using a shell (such as bash) with command-line-editing
enabled there are two different terminal interfaces (or line
disciplines: what you see when you type stty -a).  When you type in
modern shells at the command line you have a temporary "raw" interface
(or raw mode) where each character is read by the shell's
command-line-editor as you type it.  Once you hit the &lt;return&gt;
key, the command-line-editor is exited and the terminal interface is
changed from raw to the nominal "cooked" interface (cooked mode) for the
terminal using the stty configuration that was used for the last cooked
mode (the shell has saved it and it gets restored).  This cooked mode
lasts until the next prompt is sent to the terminal (which is only a
small fraction of a second) but it exists during the execution of the
command (or at least during the first stage of the command execution).
Note that one never gets to type any command into this cooked mode but
what was typed in raw mode on the command line starts execution by the
shell while in cooked mode.

When a prompt is sent to the terminal, the terminal goes from "cooked"
to "raw" mode (just like it does when you start an editor such as vim.
The prompt signals starting the command-line editor.  The settings for
the "raw" mode are based only on the basic stty settings taken from the
"cooked" mode.  Raw mode keeps these setting but changes several other
settings in order to change the mode to "raw".  It is not at all based
on the settings used in the previous "raw" mode (as contrasted to
"cooked" mode which gets restored by the shell to its previous
settings).  Thus if one uses stty to change settings for the raw mode,
such settings will be permanently lost as soon as one hits the
&lt;return&gt; key at the terminal.

Now when one types stty to look at the terminal interface, one may
either get a view of the cooked mode or the raw mode.  You need to
figure out which one you're looking at.  It you use stty from a
foreign terminal (other than the terminal you are currently typing at)
then you will likely see the raw mode settings since the terminal is in raw
mode almost all the time.  Any changes made will only be made to the raw
mode and will be lost when someone presses &lt;return&gt; at the foreign
terminal you tried to "set".  But if you type a stty command to
view/change the configuration of the terminal you are using, and then
hit &lt;return&gt; it's a different story.  The &lt;return&gt; puts the
terminal in cooked mode and your changes are saved by the shell before it
returns to raw mode.  Since going into raw mode doesn't change all stty
settings, some of the changes you made via stty may still be present in
raw mode and will not get destroyed by &lt;return&gt;.

This situation can create problems.  For example, suppose you corrupt
your terminal interface so that it's not displaying what you type, etc.
To restore it you go to another terminal (on the same PC) and type "stty
-F dev/ttyS1 sane" (or the like).  It will not work because the terminal
is in raw mode!  Of course you can try to type "stty sane ..." at the
terminal that is corrupted but you can't see what you typed.  All the
above not only applies to dumb terminals but to virtual terminals used
on a PC Monitor as well as to the terminal windows in X.  In other
words, it applies to almost everyone who uses Linux.

Luckily, when you start up Linux, any file that runs stty at boot-time
will likely deal with a terminal (or serial port with no terminal)
that has no shell running on it so there's no problem for this special
case.

<sect2> Where to put the stty command ? <label id="stty_where">
<p> Should you need to have <tt/stty/ set up the serial interface each
time the computer starts up then you need to put the <tt/stty/ command
in a file that will be executed each time the computer is started up
(Linux boots).  It should be run before the serial port is used
(including running getty on the port).  There are many possible places
to put it.  If it gets put in more than one place and you only know
about (or remember) one of those places, then a conflict is likely.
So make sure to document what you do.

One place to put it would be in the same file that runs setserial when
the system is booted.  The location is distribution and version
dependent.  It would seem best to put it after the setserial command
so that the low level stuff is done first.  If you have directories in
the /etc tree where every file in them is executed at boot-time
(System V Init) then you could create a file named "stty" for this
purpose.

<sect2> Obsolete redirection method
<p>Prior to about 2000 you needed to use the redirection operator "<"
if you wanted to use stty on a foreign terminal.  For example to use
stty on ttyS2 sitting at tty1 you would type: stty .... < /dev/ttyS2.
After 2000 (provided your version of setserial is >= 1.17 and stty >=
2.0) a better method was created using the -F option: stty -F
/dev/ttyS2.  This will work when the old redirection method fails.  

The old redirection example above makes ttyS2 the standard input to
stty.  This gives the stty program a link to the "file" ttyS2 so that
it may "read" it.  But instead of reading the bytes sent to ttyS2 as
one might expect, it uses the link to find the configuration settings
of the port so that it may read or change them.  In olden days, some
people tried to use ``stty ... &gt /dev/ttyS2'' to set the terminal.
This didn't work.  Instead, it takes the message normal displayed
by the stty command for the terminal you are on (say tty1) and sends
this message to ttyS2.  But it doesn't change any settings for ttyS2.

Here's a problem with the old redirection operator (which doesn't
happen if you use the newer -F option instead).  Sometimes when trying
to use stty, the command hangs and nothing happens (you don't get a
prompt for a next command even after hitting &lt;return&gt;).  This is
likely due to the port being stuck because it's waiting for one of the
modem control lines to be asserted.  For example, unless you've set
"clocal" to ignore modem control lines, then if no CD signal is
asserted the port will not open and stty will not work for it (unless
you use the newer -F option).  A similar situation seems to exist for
hardware flow control.  If the cable for the port doesn't even have a
conductor for the pin that needs to be asserted then there is no easy
way to stop the hang.

One way to try to get out of the above hang is to use the newer -F
option and set "clocal" and/or "crtscts" as needed.  If you don't have
the -F option then you may try to run some program (such as minicom) on
the port that will force it to operate even if the control lines say
not to.  Then hopefully this program might set the port so it doesn't
need the control signal in the future in order to open: clocal or
-crtscts.  To use "minicom" to do this you likely will have to
reconfigure minicom and then exit it and restart it.  Instead of all
this bother, it may be simpler to just reboot the PC or via using a
virtual terminal kill the process using "top" (or "ps" to get the
process number and then "kill" to kill that process.

The obsolete redirection method (which still works in later versions)
is to type ``stty ... &lt /dev/ttyS2''.   If the new method using -F
works but the obsolete one hangs, it implies that the port is hung due
to a modem control line not being asserted.  Thus the obsolete
redirection method might still useful for troubleshooting.
<!-- stty.D end -->


<sect1> Terminfo & Termcap (brief) <label id="termcap1">
<p> See <ref id="termcap2" name="Terminfo and Termcap (detailed)"> for
a more detailed discussion of termcap.  Many application programs that
you run use the terminfo (formerly termcap) data base.  This has an
entry (or file) for each model or type (such as vt100) of terminal and
tells what the terminal can do, what codes to send for various
actions, and what codes to send to the terminal to initialize it.

Since many terminals (and PC's also) can emulate other terminals and
have various "modes" of operation, there may be several terminfo
entries from which to choose for a given physical terminal.  They
usually will have similar names.  The last parameter of getty (for
both agetty and getty_ps) should be the terminfo name of the terminal
(or terminal emulation) that you are using (such as vt100).

The terminfo does more than just specify what the terminal is capable
of doing and disclose what codes to send to the terminal to get it to
do those things.  It also specifies what "bold" will look like (will
it be reverse video or will it be high intensity, etc.), what
the cursor will look like, if the letters will be black, white, or
some other color, etc.  In PC terminology these are called
"preferences".  It also specifies initialization codes to send to the
terminal (analogous to the init strings sent to modems).  Such strings
are not automatically sent to the terminal by Linux.  See <ref
id="init_string" name="Init String">.  If you don't like the way the
display on the screen looks and behaves you may need to edit (and then
update) the terminfo (or termcap) file.  See <ref id="tic"
name="Terminfo Compiler (tic)"> for how to update.

<sect1> Setting TERM and TERMINFO
<p> These are two environment variables for terminals: TERM and
TERMINFO, but you may not need to do anything about them.  TERM must
always be set to the  type of the terminal you are using (such as
vt100).  If you don't know the type (name) see <ref id="term_name"
name="What is the terminfo name of my terminal ?">.  TERMINFO contains
the path to the terminfo data base, but may not be needed if the
database is in a default location (or TERMINFO could be set
automatically by a file that comes with your distribution of Linux).
You may want to look at <ref id="tc_compiled_locs" name=" Compiled
database locations">.

Fortunately, the getty program usually sets TERM for you just before
login.  It just uses the terminal type that was specified on getty's
command line (in /etc/inittab).  This permits application programs to
find the name of your terminal and then look up the terminal
capabilities in the terminfo data base.  See <ref id="term_var"
name="TERM Variable"> for more details on TERM.

If your terminfo data base can't be found you may see an error message
about it on your terminal.  If this happens it's time to check out
where terminfo resides and set TERMINFO if needed.  You may find out
where the terminfo database is by searching for a common terminfo file
such as "vt100" using the "locate" command.  Make sure that your
terminal is in this database.  An example of setting TERMINFO is:
export TERMINFO=/usr/share/terminfo (put this in /etc/profile or the
like).  If the data for your terminal in this data base is not to your
liking, you may need to edit it.  See <ref id="termcap1"
name="Terminfo & Termcap (brief)">.

<sect2> What is the terminfo name of my terminal ? <label
id="term_name">
<p> You need the exact name in order to set the TERM environment
variable or to give to <tt/getty/.  The same name should be used by
both the termcap and terminfo databases so you only need to find it
once.  A terminal usually has alias names but if more than one name is
shown, use the first one.

To find it, try looking at the /etc/termcap... file (if you have it).
If not, then either look at the terminfo trees (see <ref
id="tc_compiled_locs" name=" Compiled database locations">) or try to
find the terminfo source code file (see <ref id="tc_source_loc"
name="Source-code database locations">.

<sect1> Rarely Needed /etc/ttytype File
<p> The configuration file /etc/ttytype is used to map /dev/ttySn's to
terminal names per terminfo.  tset/reset uses it, but if the TERM
environment variable is already set correctly, then this file is not
needed.  Since the Linux getty sets TERM for each tty, you don't need
this file.  In other Unix-like systems such as FreeBSD, the file
/etc/ttys maps ttys to much more, such as the appropriate getty
command, and the category of connection (such as "dialup").  An
example line of Linux ttytype: vt220 ttyS1

<sect1> Login Restrictions <label id="login_restr">
<p> By default, the root user may not login from a terminal.  To
permit this you must create (or edit) the file /etc/securetty per the
manual page "securetty".  To restrict logins of certain users and/or
certain terminals, etc. edit /etc/login.access (this replaces the old
/etc/usertty file ??).  /etc/login.def determines if /etc/securetty is
to be used and could be edited so as to make /etc/securetty not needed
(or not used).  /etc/porttime restricts the times at which certain
ttys and users may use the computer.  If there are too many failed
login attempt by a user, that user may be prohibited from ever logging
in again.  See the man page "faillog" for how to control this.

<sect1> Run Command Only If TERM=my_term_type
<p> Sometimes there are commands that one wants to execute at start-up
only for a certain type of terminal.  To do this for the stty command
is no problem since one uses the redirection operator < to specify
which terminal the command is for.  But what about shell aliases or
functions?  You may want to make a function for the ls command so it
will color-code the listing of directories only on color terminals or
consoles.  For monochrome terminals you want the same function name
(but a different function body) which will use symbols as a substitute
for color-coding.  Where to put such function definitions that are
to be different for different terminals?

You may put them inside an "if" statement in /etc/profile which runs
at startup each time one logs on.  The conditional "if" statement
defines certain functions, etc. only if the terminal is of a
specified type.

<sect2> Example for ls Function <label id="ls_color">
<p> While much of what this if statement does could be done in the
configuration file for dircolors, here's an example for the case of
the bash shell.  It makes the <em/ls/ command display colors if the
terminal is "linux" but uses <em/ls -F/ if you're using a dumb
terminal (VT220).  Note that the -F option uses symbols to give
information on file types just like color coding does. So there are
alternatives to using colors for the <em/ls/ command, although a color
display may look more impressive.

<code>
if [ "$TERM" = linux ]; then
    eval `dircolors`;
elif [ "$TERM" = vt220 ]; then
    ls () &lcub command ls -F $* ; &rcub
# to export the function ls():
    declare -xf ls
else echo "From /etc/profile: Unknown terminal type $TERM"
fi
</code>

<sect1> Character Mapping: mapchan <label id="mapchan_">
<p> There is a free program named "mapchan" which will map characters
(bytes) typed at a terminal keyboard (input) into different characters
per a user-supplied mapping table.  It can also map characters which
are sent to the screen (output).  This is nice for remapping the
keyboard for foreign language alphabets.  Most distributions don't
seem to supply it (let me know if any do).  Source code by Yura
Kalinichenko (Ukraine, partly in Russian ) <url
url="http://sourceforge.net/projects/mapchan/" name="download mapchan
etc.">

<sect>Terminfo and Termcap (detailed) <label id="termcap2">

<sect1> Intro to Terminfo

<p> Terminfo (formerly Termcap) is a database of terminal capabilities
and more.  For every (well almost) model of terminal it tells
application programs what the terminal is capable of doing.  It tells
what escape sequences (or control characters) to send to the terminal
in order to do things such as move the cursor to a new location, erase
part of the screen, scroll the screen, change modes, change appearance
(colors, brightness, blinking, underlining, reverse video etc.).
After about 1980, many terminals supported over a hundred different
commands (some of which take numeric parameters).

One way in which terminfo gives the its information to an application
program is via the "ncurses" functions that a programmer may put into
a C program.  For example, if a program wants to move the cursor to row
3, col 6 it simply calls: move(3,6).  The move() function (part of
ncurses) knows how to do this for your terminal (it has read
terminfo).  So it sends the appropriate escape sequence to the
terminal to make this particular move for a certain terminal.
Some programs get info directly from a terminfo files without using
ncurses.  Thus a Linux package that doesn't require ncurses may still
need a terminfo file for your terminal.

The terminfo abbreviations are usually longer than those of termcap
and thus it's easier to guess what they mean.  The manual pages for
terminfo are more detailed (and include the old termcap
abbreviations).  Also, the termcap entries had a size limitation which
is not present for terminfo.  Thus, unless you are already committed
to working with termcap, it's suggested you use terminfo.

<sect1> Terminfo Database <label id="database">
<sect2> Introduction
<p> The terminfo database is compiled and thus has a source part and a
compiled part.  The old termcap database has only a source part but
this source can, by a single command, be both converted to terminfo
source and then compiled.  Thus you may get by without having any
terminfo source since the termcap source can create the compiled
terminfo database.  To see a display of the database for the terminal
you're now using (including a PC monitor) type "infocmp" and you
should see the source terminfo "file" for it.

To see if your terminal (say vt100) is in the terminfo data base type
"locate vt100".  If you need to find the terminfo name for your
terminal, explore the listing of files in the compiled database or see
<ref id="term_name" name="What is the terminfo name of my terminal ?">

<sect2> Where is the database located ?
<sect3> Compiled database locations <label id="tc_compiled_locs">
<p> Typing "locate vt100" may show /usr/lib/terminfo/v/vt100,
/usr/share/terminfo/v/vt100, /home/.../.terminfo/v/vt100, and/or
/etc/terminfo/v/vt100.  All these are possible locations of the
compiled terminfo files.  Although the /etc/terminfo directory is not
a standard location for it, having a few terminal types there could be
useful in case the /usr directory is not accessible.  For example /usr
could be on a separate disk or partition that failed to mount.
Normally, programs that use your main terminfo data base are able to
find it if it's in at least one of the locations mentioned above.
Otherwise the environment variable TERMINFO may be set to the path to
this database.  Example: TERMINFO=/usr/share/terminfo

For the Debian Distribution of Linux, several commonly used terminals
(including the monitor-console) are in the ncurses-term package.
These are put into /etc/terminfo/.  All of the terminals in the
database are in the ncurses-bin package and go into
/usr/share/terminfo/.

If the compiled terminfo is in more than one location, everything is
usually OK until someone installs new terminfo files (from a newer
distribution, from the net, by editing the old one, etc.).  Each new
terminfo file should replace all the existing older copies of that file
(at various locations) unless you abolish redundant locations.  If you
don't ensure this gets done, then some application programs could wind
up still finding and using the old (and possibly buggy) terminfo data
that sill exists in a "possible" location.  Setting the environment
variable TERMINFO to the up-to-date location (as mentioned above)
would help avoid this problem.

<sect3> Source-code database locations <label id="tc_source_loc">
<p> While the source-code file may  not be installed on your computer
there's another way to get the source-code if you have the compiled
code.  Just use the "<tt/infocmp/" command.

The source code file (for all terminals) may be /etc/termcap and/or
terminfo.src (or another name).  See the man pages: terminfo(5) or
termcap(5) for the format required to create (or modify) these source
files.  The file terminfo.src may be in various locations on your
computer or it may not be included with your Linux distribution.  Use
the <tt/locate/ command to try to find it.  It is available on the web
at <url url="http://catb.org/terminfo/">.

<sect2> Terminfo Compiler (tic) <label id="tic">
<p> The data in the source files is compiled with the "tic" program
which is capable of converting between termcap format and terminfo
format.  Thus you can create a compiled terminfo data base from
termcap source.  The installation program which was used to install
Linux probably installed the compiled files on your hard disk so you
don't need to compile anything unless you modify /etc/termcap (or
terminfo.src ).  "tic" will automatically install the resulting
compiled files into a terminfo directory ready to be used by
application programs.  Which location it's installed in depends on ...
See "man tic" for the explanation.

<sect2> Look at Your Terminfo <label id="infocmp">
<p> It's a good idea to take a look at the terminfo entry for the
terminal you are using (source code of course) and read the comments.
A quick way to inspect it without comments is to just type "infocmp".
But the comments may tell you something special about the terminal
such as how you need to set it up so that it will work correctly with
the terminfo database.

<sect2> Deleting Data Not Needed
<p> In order to save disk space, one may delete all of the terminfo
database except for the terminals types that you have (or might need
in the future).  Don't delete any of the termcaps for a "Linux
terminal" (the console) or the ones used for x-terminal-emulation
such as xterm.  The terminal type "dumb" may be needed when an
application program can't figure out what type of terminal you are
using.  It would save disk space if install programs only installed
the terminfo for the terminals that you have and if you could get a
termcap for a newly installed terminal over the Internet in a few
seconds.

<sect1> Bugs in Existing Terminfo Files (and Hardware)
<p> Unfortunately, there are a number of bugs in the terminfo and
termcap files.  In addition, many of these terminfo files are
incomplete and do not define certain features available on the
terminals.  Sometimes you can get by without modifying the terminfo
but in other cases you need to modify it or possibly use another
emulation that has a good terminfo.

The sad state of the supplied terminfo files is due to a number of
reasons.  One is that during the 1980's when many of them were written
(often in termcap format), application programs did not utilize more
advanced terminal features.  Thus if such feature were not in the
termcap (or terminfo) file, no one complained.  Also, writing termcaps
was often done by volunteers who were in short supply.  Today,
programs such as vim use "context highlighting" and minicom uses the
terminal's graphics character set.  These often need more definitions
to be added to the old termcap.  This may (or may not) have already
been done.

Most terminals had hardware bugs (in their firmware) and sometimes
these were "fixed" by modifying the termcap.  Then the manufacturer
might send out replacement chips which would fix the bug.  Not all
owners would bother to get the replacement chips.  Thus there may be 2
or more terminfos for your terminal, depending on what firmware chips
it has in it.  This situation was often not noted in the termcap and
only one of these termcaps may be supplied with Linux.  Some hardware
bugs which existed for features that were almost never used in the
past likely never did get fixed.  Also, some reported hardware bugs
may never have been fixed since they were not of much significance at
the time or because the terminal manufacturing company went out of
business, etc.

<sect1> Modifying Terminfo Files
<p> To do this you need a manual for your terminal showing what escape
sequences it uses.  Newer manuals from the 1990's often don't show
this.  You also need a terminfo manual (the man page "terminfo" is
one).  After you edit the terminfo source file you compile it using
"tic".  "tic" should automatically put the compiled terminfo file in
the correct directory reserved for it.

If you would like to find a better terminfo entry for a certain terminal
than the one supplied, you might try searching the Internet (but what
you find could be worse).  If your new terminfo entry is better than
the old one and it seems stable (you've used it for a while with no
problems) then you should send a copy to the maintainer of terminfo as
noted at the start of the source file for terminfo (or termcap).

<sect1> Init String <label id="init_string">
<p> Included in the terminfo are often a couple of initialization
strings which may be sent to the terminal to initialize it.  This may
change the appearance of the screen, change what mode the terminal is
in, and/or make the terminal emulate another terminal.  No
initialization string is automatically sent to the terminal to
initialize it.  One might expect that the getty program should do
this.  If it did, one could make a change to the set-up stored inside
the terminal but this change wouldn't happen because the init string
would override it.  Application programs don't seem to initialize
(send an init string per terminfo) either.

To actually send an init string you must use a command given on the
command line (or in a shell script such as /etc/profile).  Such
commands are: "reset" "tset", "tput init", or "setterm -initialize".
Sometimes there is no need to send an init string since the terminal
may set itself up correctly when it is powered on (using
options/preferences one has set up and saved in the non-volatile
memory of the terminal).

<sect1> TERM Variable <label id="term_var">
<p> The Environment variable TERM should be set to the name of
terminal which you are using.  If TERM hasn't been set yet and you
don't know the name of your terminal see <ref id="term_name"
name="What is the terminfo name of my terminal ?">.  It is normally
set by the terminal_type parameter passed to the getty program (look
at it in the /etc/inittab file).  This name must be in the Terminfo
data base.  Just type "set" at the command line to see what TERM is
set to (or type: tset -q).  At a console (monitor) TERM is set to
"linux" which is the PC monitor emulating a fictitious terminal model
named "linux".  Since "linux" is close to a vt100 terminal and many
text terminals are also, the "linux" designation will sometimes work
as a temporary expedient with a text terminal.

If more than one type of terminal may be connected to the same port
(/dev/ttyS...) (for example, if there is a switch to permit different
terminal types to use the same serial port, or if the port is
connected to a modem to which people call in from different types of
terminals) then TERM needs to be set each time someone connects to the
serial port.  There is often a query escape sequence so that the
computer may ask the terminal what type it is.  Another way is to ask
the user to type in (or select) the type of terminal s/he is using.
You may need to use tset for this or write a short shell script to
handle this.

<label id="reset_">
One way to do this is to use "reset" (same as "tset"; see the manual
page).  reset tries to determine the terminal name of the terminal you
are using.  Then it looks up the data in terminfo and sends your
terminal an init string.  It can also set the value of TERM.  For
example, a user dials in and logs in.  The .profile login script is
executed which contains within it the following statement: eval `tset
-s ?vt100`.  This results in: The user is asked if s/he is using a
vt100.  The user either responds yes or types in the actual terminal
type s/he is using.  Then "reset" sends the init string and sets TERM
to this terminal name (type).

<sect1> Terminfo/Termcap Documents <label id="termcap_docs">
<p> <itemize>
<item> manual pages for terminfo(5) (best) and/or termcap(5).
<url url="http://www.delorie.com/gnu/docs/termcap/termcap_toc.html"
 name="The Termcap Manual"> (2nd ed.) by Richard M. Stallman is a GNU
 manual also known as the "Termcap Library".  It's somewhat obsolete
 since it doesn't include terminfo.  It's also at:
<url
url="http://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html"
name="Termcap Library">
<item> the files: terminfo.src and
 /etc/termcap have info about various versions of termcap files,
 naming conventions for terminals, and special capabilities code named
 u6-u9. If you don't have one, go to <url
 url="http://catb.org/terminfo/">
<item> "Termcap and Terminfo" is a book published by O'Reilly in
 1988.
</itemize>

<sect> Using the Terminal

<sect1> Intro to Using the Terminal
<p> This section is about controlling the terminal-computer interface
and/or changing the terminal set-up while using the terminal.  It
explains (or points to explanations of) how the user of a terminal can
control and inspect the interface and how to use various commands
provided by the device driver.  It does not explain how to use the
many application programs, shells or most Linux utilities.  Two
commands commonly used at the terminal are:

<itemize>
<item> clear (to clear the screen)
<item> reset (to reset the terminal
<item> setterm -reset (alternative for "reset" in case of bug)
</itemize>

<sect1> Starting Up the Terminal
<p> Of course the power must be on for the terminal to work.  If you
don't see a login prompt hit the "return" (or "enter") key a few times.
Then type your account name (followed by a return/enter) and your
password when prompted for it (also followed by return/enter).  Make
sure not to type all capital letters.  If you do, the computer may
think that you have an old terminal that can't send lowercase letters
and the serial driver may set itself up to send only capital letters
to the terminal.

If nothing happens, make sure that both the host computer and the
terminal are OK.  If the host computer is shut down (no power) what
you type at the terminal keyboard may appear on the screen since the
transmit and receive pins at the computer may be connected together
resulting in echoing of characters by an "off" computer.  If you can't
log in when the host computer is running, see <ref id="trouble_shoot"
name="Trouble-Shooting">.

<sect1> Terminal (Serial) Device Driver
<p> When typing at the command line, the shell (such as the Bash
shell) is reading what you type and reacting to it.  What you type
first passes thru the terminal driver part of your operating system.
This driver may translate certain characters (such as changing the
"return" character generated by the "return" key into a "new-line"
character for Linux files).  It also recognizes certain control codes
which you may type at the keyboard such as ^C to interrupt the
execution of a program.  It also normally echoes what you type back to
the display.   <ref id="stty_" name="Stty"> may be used to configure
how this terminal driver behaves, including disabling some (or all) of
its functionality.

<sect1> Problems with Editors
<p> There may be some problems with using both emacs and vi on some
terminals.  A few terminals have no escape key (ESC) so you may need
to type Ctrl-[ to get ESC.

<sect2> emacs
<p> If software flow control exists, then the ^S command in emacs will
freeze the display.  The ^Q command will unfreeze the display.  One
fix is to map this to another key-press by configuring emacs that way.
Some terminals have meta keys although you may need to setup the
terminal to create a meta key.

<sect2> vi and Cursor-Keys <label id="vi_k_keys">
<p> Vi uses the esc-key as a command to exit insert mode.
Unfortunately for most terminals the arrow-keys send an escape
sequence (starting with the ESC character) to the host.  Vi must
distinguish between these two meanings of ESC.  A smart vi (such as
vim if configured for it) is able to detect the difference by noting
the time between the ESC and the next key.  If it's a short time, then
it's likely that a cursor key was pressed.  Use "help cursor-keys" in
vim to find out more.

Here's another way to fix this.  On VT terminals the left-arrow-key
may be either set to send ESC [ D or ESC O D.  The other arrow keys
are similar but use A, B, and C instead of D.  If you're having
problems, choose ESC [ D since the "O" in the other alternative could
be interpreted by vi as a command to "Open a line".  The "[" should be
interpreted by vi to mean that an arrow-key has been pressed.  ESC [ D
will be sent provided "Cursor Key Application Mode" has not been set.
ESC [ D is normally the default so everything is seemingly OK.  Except
that many termcaps contain a string (not the init string) which sets
what you want to avoid: "Application Mode".  Editors may send this
string to the terminal when the editor starts up.  Now you are in
trouble.

This string has the termcap code "ks" (smkx in terminfo) meaning
enable the function (and related) keys (including the arrow keys).  An
application enables these keys by sending the "ks" string to the
terminal.  Whoever wrote the termcap reasoned that if an application
wants to enable these keys, then they should be put into "Application
Key Mode" since this is an "application", but you don't want this.

The Linux console has no "ks" string so you can't fall into this trap
at the console.  For other terminals you may need to edit the termcap
(or terminfo) or use another termcap entry.  You need to change not
only the "ks" string but also the termcap definitions of what they
send: kd, kl, kr, ku.  Then run tic to install it.

For vim (vi iMproved) there is a way to set it up to work OK with ESC
O D (so you don't need to edit termcap): See vim help for
"vt100-cursor-keys".  You may run "gitkeys" and then press your cursor
keys to see what they send but they may be set to send something
different when you're in an editor.

<sect1>Problem with Slow Scrolling <label id="slow_scroll">
<p>The scrolling speed of the text terminal is limited by the speed
over the serial line.  This limitation is good in one respect since
the scrolling speed is slow enough that you can almost read what is
scrolling on the screen before it disappears off the bottom of the
screen.

But there is a downside to this.  For example, if you copy a large
number of files (like everything on your hard drive) and use options
to display the full name (path name) of each file copied, then the
speed limitations of the serial line may only display 30 files per
second on the screen.  But your hard drive can copy many times faster
than this but the terminal will slow down the transfer to the speed at
which it can be displayed by the terminal.  It does this by
<ref id="flow_control" name="Flow Control">.

The fix is to disable "progress" information being displayed on the
screen for cases where it slows down the "progress".  If it just
updates progress numbers a few times per second or less, it shouldn't
be a problem.

<sect1> Bugs in Bash ? <label id="bash_bug">
<p> One problem still outstanding is that if certain terminal keys
send bytes with the high order bit set to 1, then Bash seems to ignore
the meaning for them as defined in a terminfo entry.  This may be
because, unless one is using 7-bit ASCII, bytes with the high order
bit set to 1, may represent a non-English letter.  I reported this as
a bug in Bash (but years later realized that it may not have been a
bug).  Other programs such as the vim editor and the lynx browser work
OK with such keys (when they are set to use 7-bit ASCII).

To work around this problem, one may define what these keys should do
in Bash by putting such definitions into <tt>/etc/inputrc.</tt>  For
example, A Wyse 60 will send D0-D3 when the arrow-keys are hit
provided the terminal is in "application key mode".   After modifying
the terminfo to reflect this, they still wouldn't work on the command
line in the Bash shell.  So I explicitly defined the arrow-keys in
<tt>/etc/inputrc</tt> like this:

<tscreen><verb>
# Arrow keys in 8 bit keypad mode: Sends d0-d3.  -ap means application.
$if term=wy60-25-ap
set enable-keypad on
"\xd0":		backward-char
"\xd1":		forward-char
"\xd2":		next-history
"\xd3":		previous-history
$endif
</verb></tscreen>

If the terminal is already in "application key mode" there's no need
to "set enable-keypad on".  enable-keypad will send the terminal the
escape sequence named smkx in terminfo (which for wyse60 is \E&tilde;3
and makes the arrow keys send D0-D3).  Many other applications  (other
than Bash) send this without needing to be told to do so.

<sect2>A fixed Bash bug
<p>There have been problems with the readline interface to the Bash
shell.  Bash 2.01 (1998) had a readline interface which was quite
corrupted if one used a dumb terminal.  This was fixed in later
versions.  

<sect1>Color ls Corruption
<p> If <tt/ls/ is corrupting your terminal emulation with the color
feature, turn it off.  <tt/ls --color/, and <tt/ls --colour/ all use
the color feature.  Some installations have <tt/ls/ set to use color
by default.  Check <tt>/etc/profile</tt>, etc.  for <tt/ls/ aliases.
See <ref id="ls_color" name="Example for ls Function"> for how to
have <tt/ls/ do color for the console and do monochrome for terminals.

<sect1> Display Freezes (hung terminal) <label id="display_freezes">
<p> The symptom of a hung terminal is where what you type doesn't display
on the terminal (or in some cases displays but doesn't do anything).
If what you type is invisible (or does nothing) type ^Q to restart flow
(if flow control stopped it).  Hanging may also be due to:<newline>
<ref id="sent_bin" name="Sent terminal binary"> or
<ref id="abnormal_exit" name="Abnormally exited a program"><newline>
If you didn't do any of these two, then the program you're running
could by buggy or you interaction with it fatally illegal.

If you want to quit the program you were running and you can't do it
by the usual methods (some programs have special keys you must hit to
exit) then try killing it from another terminal using "top" or "kill".
If the process refuses to die, then kill it with signal 9 from top (or
use "kill" on the command line). The "9" type of forced exit may leave
some temporary files lying around as well as a corrupted interface.
If this doesn't work, killing the login shell should result in a
startup of getty with a new login prompt.  If all else fails, you may
need to reboot the computer or even power it down.  Just rebooting may
not alter the possibly corrupted content of the serial port hardware
registers.

<label id="ctrl_s">
People new to Linux may unintentionally press Ctrl-S (^S) (or the "No
Scroll" key) which mysteriously freezes the screen (although that is
what this key is supposed to do if you use software flow-control).  To
restore normal screen interaction, press Ctrl-Q (^Q).  Note that
everything typed during the "freeze" gets executed but you don't see
any report of this until you hit ^Q.  Thus when it's frozen, don't
type anything drastic that might destroy files, etc.  One argument for
using hardware flow-control is to prevent such freezes.

<sect1> Corrupted Terminal Interface <label id="corrupt_interface">
<p> This includes the case of a "frozen display" = "hung terminal" of
the previous section.

<sect2> Symptoms and some fixes <label id="symptoms_">
<p> When the display doesn't look right, or when what you type doesn't
display correctly (if at all), or nothing happens when you type a
command, you may have a corrupted terminal interface.  In rare cases,
when the serial port hardware gets itself corrupted, the only fix may
be to cycle power (turn off the PC and reboot).  In some cases just
cycling power for the terminal will fix it.  Sometimes logging in again
will solve the problem.  To do this, kill the shell process running on
the terminal (or kill getty if it's running).  You may do this from
another terminal.  Once killed, a new getty process respawns which
hopefully will end the corruption.  Recycling power (or resetting) for
the terminal may help too.

The corruption may be due to things such as:
<itemize>
<item>A bug in the program you're using (including a program which
 erroneously assumes that you are using a terminal of type "linux")
<item>A hardware failure (including an obscure hardware defect that
 you can normally live with)
<item>Incorrect configuration (including an error in the terminfo or
 the terminal type)
</itemize>
If everything was working normally but it suddenly goes bad, it may be
that the interface got corrupted by something you did.  Three mistakes
you might have made to corrupt the interface are:

<itemize>
<item> <ref id="sent_bin" name="Sent terminal binary">
<item> <ref id="abnormal_exit" name="Abnormally exited a program">
<item> <ref id="ctrl_s" name="Typed ctrl-S by mistake">
</itemize>

<sect2> Sent terminal binary characters <label id="sent_bin">
<p> Your terminal will change its characteristics if sent certain
escape sequences or control characters.  It you inadvertently try to
display a binary file, it might by chance contain such sequences which
may put your terminal into some strange mode of operation or even make
it unusable.  Always view or edit a binary file with programs designed
for that purpose so that this doesn't happen.  Most editors and pagers
will handle binary OK so as not to corrupt the interface.  Some may
display a message telling you that they can't edit binary.  But you're
likely to corrupt things if you: "cat ...." or "cp .... /dev/tty.." or
run a program which sends binary output to "standard output" (unless
you redirect such output with >, etc.).

Corruption can also happen when using a communications program where
a remote computer may send binary to your screen.  There are numerous
other ways it can happen so be prepared for it.  Even a supposedly
text file could contain unwanted control codes.

To fix this problem reset the terminal.  Type either just "reset" or
"tset" or "setterm -reset" (followed by a &lt;return&gt of course --
what you type will likely not be readable on the screen).  This will
send the reset string from the terminfo entry to the terminal.  As an
alternative to this, if the correct set-up has been saved inside the
terminal then pressing a special key(s) (perhaps in setup mode) may
restore the settings.  Then you might still need to use "reset" to send
the init string if you use it to set up your terminal.

<sect2> Reset command was broken but now fixed
<p>Note that in 2000 the "reset" command appeared to be broken for
terminals that needed "clocal" set since "reset" seemed to unset
"clocal".  In 2001 it appears to be fixed so you may not need to read
the rest of this paragraph.  If you have this problem, using "reset"
will only make the situation worse by disabling communication between
the terminal and computer.  You will likely need to log in again and
hope the getty sets "clocal".  If you see a login prompt without
asking for it, you're in luck.  Otherwise see <ref id="symptoms_"
name="Symptoms and some fixes"> for how to get a login prompt.  You
should try out "reset" before you need it and use "setterm -reset" if
"reset" logs you out or otherwise doesn't work right.  I submitted a
bug report in Mar. 2000 but never got a "fixed" notice.

<sect2> Character corruption
<p>For the case where you see strange "graphic" characters instead of
the normal ones, pressing ^O may switch back to the normal letters.
The "reset" command also does this but it resets everything else too.

There's the case where all letters have the wrong attribute (too dim,
bright, blinking, or even invisible :-) but the whitespace created by
tab characters is normal.  This was caused by an escape sequence which
set this attribute but the attribute doesn't apply to the whitespace
created by tab characters.  Fix by resetting, etc.

<sect2> Abnormally exited a program <label id="abnormal_exit">
<p> Large application programs (such as editors) often use the stty
command (or the like) in their code to temporarily change the stty
configuration when you are running the program.  This may put the
device driver into "raw" mode so that every character you type goes
directly thru to the application program.  Echoing by the driver is
disabled so that everything you see on the screen comes directly from
the application program.  Thus many control commands (such as ^C) may
not work within such applications.

When you tell such an application to quit, the application program
first restores the stty settings to what they were before the
application program started.  If you abnormally exit the program then
you may still be in "raw mode" on the command line.  You should
suspect this has happened when what you type no longer displays on the
screen.

To get out of raw mode and restore the normal stty settings type "stty
sane".  However, you must type this just after a "return" and end it
with a "return".   But hitting the "return" key doesn't do the job
since the "return" code no longer gets translated to the new-line
characters that the shell is waiting for.  So just type new-line (^J)
instead of "return".  The "sane" terminal interface may not be exactly
the same as the normal one but it usually works.  "stty sane" may also
be useful to get out of a corrupted interface due to other causes.

<sect1> Special (Control) Characters <label id="stty_chars">
<p> A number of control characters which you may type at the keyboard
are "caught" by the terminal driver and perform various tasks.  To see
these control commands type: stty -a and look at lines 2-4.  They are
tersely explained in the stty manual pages.  They may be changed to
different control characters or disabled using the stty command.  Thus
your control characters might be different than those described below.
They are used for command-line editing, interrupting, scrolling, and
to pass the next character thru transparently.

<sect2> Command-Line Editing
<p> While the terminal driver has a few commands for command-line
editing, some shells have a built-in real editor (such as "readline"
in the Bash shell).  Such an editor is normally on by default so you
don't need to do anything to enable it.  If it's available you don't
need to learn many of the following commands although they often still
work along with the command-line editor.  The most important to learn
are ^C (interrupt), ^D, and how to stop scrolling.

<itemize>
<item> Delete-key (shown by stty as ^?) erases the last character
<item> ^U kills (deletes) the line
<item> ^W deletes a word backwards
<item> ^R reprints the line.  Useful mainly on hard copy terminals ??
</itemize>

<sect2> Interrupting (& Quit, Suspend, EOF, Flush)
<p> <itemize>
<item> ^C interrupts.  Exits the program and returns you to the
 command-line prompt.
<item> ^\ quits.  Same as interrupt.  Also may dump a "core" file
 (which you likely have no use for) into your working directory.
<item> ^Z suspends.  Stops the program and puts it in the background.
 Type fg to restart it.
<item> ^D end of file.  If typed at the command-line prompt, exits the
 shell and goes to where you were before the shell started.
<item> ^O flush (or discard).  Not yet implemented in Linux (but
 proposed).  Sends output to /dev/null.
<item> ^T display driver status.  Not yet implemented in Linux (but
 proposed).  Displays a status line for the interface (number of bytes
 sent, etc.).
</itemize>

<sect2> Stop/Start Scrolling
<p> If what you want to see scrolls off the bottom of the screen,
you may prevent this by sending a "stop" signal (^S or Xoff) to the
host (provided Xon-Xoff <ref id="flow_control" name="Flow Control"> is
enabled).  Send a "start signal to resume (^Q or Xon).  Some terminals
have a "No Scroll" key which will alternately send Xoff and Xon or
possibly send the hardware flow control signals ??   Here's what
ctrl-S (^S) and ctrl-Q (^Q) do:

<itemize>
<item> ^S stops scrolling (Xoff)
<item> ^Q resume scrolling (Xon)
</itemize>

If you want to both stop scrolling and quit, use ^C.  If you want to
stop scrolling to do something else but want to keep the program that
was generating the output in memory so you can resume scrolling later,
use ^Z suspend.

An alternative scrolling method is to pipe the output thru a pager
such as more, less, or most.  However, the output might not be
standard output but could be error output which the pager doesn't
recognize.  To fix this you may need to use redirection "2>&1" to get
the pager to work OK.  It is often simpler to just use ^S and ^Q
unless you need to scroll backwards.

At a PC console (emulating a terminal) you may scroll backwards by
using Shift-PageUp.  This is frequently needed since the scrolling is
often too fast to stop using ^S.  Once you've scrolled backwards
Shift-PageDown will scroll forward again.

<sect2> Take next character literally
<p> ^V sends the next character typed (usually a control character)
directly thru the device driver with no action or interpretation.
Echoed back are two ASCII characters such as ^C.

<sect1> Viewing Latin1 Files on a non-Latin1 terminal
<p> Some "text" files are 8-bit Latin1 (=ISO-8859-1).  See <ref
id="char_sets" name="Character-Sets">.  If you have a terminal that
will not display Latin1 (or don't have the Latin1 character set
installed), then certain symbols (such as a bullet) will display wrong.
When viewing manual pages (they are Latin1) you may give the option -7
to man so as to translate everything to ASCII.  Are there some pagers
that make these translations ??

<sect1> Eliminating Overstriking in Files
<p>If one uses the "man" command to view a manual page but instead
redirects the output to a file, that file will have overstrikes in it.
Overstrikes are where some printed characters appear bold by printing
them twice in the same location.  Thus to print an overstrike
character the file contains a backspace after the character and then
the same character repeated.  If this is in a file, it's fine if you
are going to print it on a printer (unless the normal output from the
printer is so darks that overstriking makes little improvement).   But
it's not so good if you want to use the file to email or edit.

One way to get rid of the overstrikes is to use the "ul" (underline)
command.  You type: ul -t dumb my_overstruck_file > output_file
The ul command converts overstrikes to bold for whatever terminal is
specified and adds escape sequences to the output_file to generate the
bold.  But the terminal of type "dumb" has no escape sequences so you
get the desired result.  There are other ways to do this but this is a
possible use for a terminal of type "dumb".

<sect1> Inspecting the Interface
<p> These utility programs will provide information about the terminal
interface:
<itemize>
<item> gitkeys: shows what byte(s) each key sends to the host.
<item> tty: shows what tty port you are connected to.
<item> set: shows the value of TERM (the terminfo entry name)
<item> stty -a: shows all stty settings.
<item> setserial -g /dev/tty?? (you fill in ??) shows UART type, port
	address and IRQ number.
<item> infocmp: shows the current terminfo entry (less comments)
</itemize>

<sect1> Changing the Terminal Settings <label id="term_settings">
<p> The terminal settings are normally set once when the terminal is
installed using the setup procedures in the terminal manual.  However,
some settings may be changed when the terminal is in use.  You
normally would not give any "stty" or "setserial" commands when the
terminal is in use as they are likely to corrupt the terminal
interface.  However, there are changes you may make to the appearance
of the terminal screen or to its behavior without destroying the
integrity of the interface.  Sometimes these changes are made
automatically by application programs so you may not need to deal with
them.

One direct method of making such changes is to use the setup key (or
the like) at the terminal and then use menus (or the like) to make the
changes.  To do this you may need to be familiar with the terminal.
<label id="setterm_"> <label id="tput"> The other 3 methods send an
escape sequence from the computer to the terminal to make the changes.
These 3 examples show different methods of doing this to set reverse
video:

<enum>
<item> setterm -reverse
<item> tput -rev
<item> echo ^&lsqb&lsqb;7m
</enum>

<sect2> setterm
<p> This is the easiest command to use.  It uses long options (but
doesn't use the normal -- before them).  It consults the terminfo
database to determine what code to send.  You may change the color,
brightness, linewrap, keyboard repeat, cursor appearance, etc.

<sect2> tput
<p> The "tput" command is similar to "setterm" but instead of using
ordinary words as arguments, you must use the abbreviations used by
terminfo.  Many of the abbreviations are quite terse and hard to
remember.

<sect2> echo
<p> In the example "echo ^&lsqb&lsqb;7m" to set reverse video, the
^&lsqb is the escape character.  To type it type ^V^&lsqb (or ^V
followed by the escape key).  To use this "echo" method you must find
out what code to use from a terminal manual or from terminfo or
termcap.  It's simpler to use setterm or tput if you are typing on the
command line.  Since "echo ..." will execute faster (since it doesn't
do any lookups) it's good for using in shell scripts which run at
start-up, etc.

<sect2> Saving changes
<p> When you turn off the terminal the changes you made will be lost
(unless you saved them in non-volatile terminal memory by going into
set-up mode and saving it).  If you want to use them again without
having to retype them, put the commands in a shell script or make it a
shell function.  Then run it when you want to make the changes.  One
way to make the changes semi-permanent is to put the commands in a
file that runs each time you login or start up the computer.

<sect1> Multiple Sessions
<p> The "<tt/screen/" package runs multiple sessions something like
virtual terminals on the console: See <ref id="console_dev" name="The
Console: /dev/tty?">.  You can switch back and forth between the
sessions.  The non-free Facet Term software also does this.  See <url
url="http://www.facetcorp.com/ft_overview.html" name="FacetTerm">

<sect1> Logging Out
<p> To log out type either "logout" or "exit".   Under some
circumstances your request will be refused, but you should be told why.
One reason for refusal is if you are not in the same shell that
you logged into.  Another way to log out is to press ^D.  Since ^D is
also used for other purposes, you may not want it to log you out.  If
you set IGNOREEOF in the Bash shell then ^D will no longer log you
out.

<sect1> Chatting between Terminals, Spying
<p> If two persons logged into terminals on the same host computer
want to chat with each other they may use the "write" or the "talk"
(better) program.  One may prevent anyone (except the superuser) from
writing (sending messages) to their terminal by using the "mesg"
command.

For spying on what someone else is doing at their terminal use the
"ttysnoop" program.  In "ttysnoop" the two terminals have the same
status and anything typed on either keyboard appears on both screens
(in the same location).  So if you're really spying and don't want to
be detected, you shouldn't type anything.

"ttysnoop" can be used for training with instructor and trainee
sitting side-by-side, each at their own terminal.  The instructor may
watch what the trainee is typing and can correct any mistakes by
typing it correctly.  The trainee can watch what the instructor types
and then try typing it.  It's just like they used one terminal with
both people having their hands on the keyboard at the same time.

There's one shortcoming to "ttysnoop" and that is that the terminals
involved should all be (or emulate) the same type of terminal (such as
vt100).  Since the "Linux" emulation done by a console (monitor) and
the "minicom" (or "picocom") emulation are close to vt100 one may use
ttysnoop using two PCs, one running "minicom" which emulates a
terminal.

There's a non-free program called "DoubleVision" that is something
like ttysnoop but does much more.  Terminals may be of different types
and it can remember and playback sessions on terminals so you can
observe what happened in the past.  The webpage is at <url
url="http://www.tridia.com">.

<sect1> Sharing the Serial Port
<p> It's possible to use the same serial port for both a text-terminal
and another serial device such as a printer or modem.  Making the
physical connection is easy using one of these methods: 
<itemize>
<item> Just unplug the terminal cable and plug in the other device
<item> Use an AB switch to switch between the terminal and other
device (uses 3 cables)
<item> Use the printer (or aux) port on the terminal for the other
device
</itemize>

When you are not using the serial port for a terminal, then you need
to make sure that no characters intended for the terminal are sent to
the other device by mistake.  One unsafe way to do this is to let the
programs running on the terminal keep running, provided they don't
send out anything for the terminal when you are using the other
device.  This sometimes works since a terminal running on a serial
port doesn't prevent another program (process) from opening the same
port.  This sometimes works if the other device is a printer.  But if
the other device should send bytes to the serial port on the computer,
then the program(s) for the terminal which are still running on the
port will often send back some bytes for the terminal which will
actually go to the other device as garbage.

To avoid this, it's best to kill all programs (processes) running on
the terminal before using the other device.  This is not quite as easy
as it sounds.  You normally have a shell (such as Bash) running on the
port and if you kill Bash (by logging out for example) then the
program "getty" will start up on the port to try to log you in again.
If you kill getty, it will respawn and start up again.  So at first
glance it seems impossible to kill all processes on the terminal's
serial port.

One way to work around this problem is to switch runlevels so that no
getty program or shell is running on the port.  For the runlevel fix,
you may create another runlevel in which no getty program runs on the
port.  Then you enter this new runlevel and use the serial port for
something else.  To set this up you need to edit <tt>/etc/inittab</tt>
and check and/or set the runlevels at which getty runs.  For example
the line: <tt>"S1:23:respawn:/sbin/getty</tt> ..." means that getty
will run (on ttyS1) in runlevels 2 and 3.  Now you could have it only
run in level 2 (by deleting "3") and then go to runlevel 3 when you
want to use the other serial device.  Thus to use the serial port for
something else, the super-user would type "init 3" to switch to
runlevel 3.  Type "init 2" to get back to runlevel 2.  Note that each
runlevel may have a different set of initialization scripts but you
can change this if you want, so that the same scripts are run in both
runlevels.  How the scripts and runlevels work are distribution
dependent.  For the Debian distribution, the explanation of this is in
<tt>/usr/doc/sysvinit</tt>, but also look in <tt>/usr/share/doc.</tt>

There's also the problem of the stty configuration of the port.  When
the port is being used for the terminal it has certain configurations but
when say "init 3" is used to switch runlevels and disable getty on the
port, the original (boot-time) configuration of the port is not
restored.  You are likely to wind up with the port configured in a
"raw" mode.  This means that the serial port likely needs to be fully
reconfigured by stty, either by a script you write or by the next
application which runs on the port.  Some applications such as
printing from the serial port may not capable of fully reconfiguring.
The obsolete version of /etc/printcap could only partially reconfigure
(but the new one under "lprng" can).  Thus you might need to write a
script to do it.  The stty configuration of a terminal will be
different depending on whether a shell is running on it, whether it's
at the "login" prompt, etc.  Thus the stty configuration after
switching runlevels may vary.

<sect1>Browsers for Text-Terminals
<p>See <url url="http://www.linuxjournal.com/article/8148" name="2005 
Text Mode Browser Roundup"> for a review of text browsers.

The "lynx" browser works correctly with all text terminals.  There
are some other text browsers: "w3m", "links2" (formerly "links",  and
"elinks" that only work perfectly with the Linux console, xterm, or
vt100 terminals.  But links2 and elinks will work with any terminal by
classifying the type as dumb like the <ref id="early_terms"
name="first terminals">.  However, such an interface is slower.

The "netrik" browser requires a color terminal.  For "links2" and
"elinks" you must set your terminal to 8-bits with no parity. (I filed
a bug report years ago for elinks since it should work with parity and
finally in 2008 I got a message that it was fixed in version 0.13
and might become fixed in 0.11 and 0.12 also).  All (including netrik
??) support ssl (secure socket layer) for encoded communication.

"w3m", "links2", and "elinks" overcome some of the "lynx" deficiencies.
"elinks" is just a more advanced "links".  They can usually display
tables better and can display frames side-by-side.  Unfortunately, the
width of what they try to display (for tables and frames) is often
wider than the terminal width so the text may run off the right side
of the screen.  This requires scrolling sideways to see everything.
Doing this may cause the names of the table rows to disappear from the
screen.  So in some cases, using "lynx" may be better.

Unfortunately "w3m", "links2", and "elinks" don't have numbered links
like lynx does, nor do they have good support for cookies.  Support
for Javascript may be a problem.  Elinks and netrik have partial
support. Links2 also has support (full ?).  Both netrik and links2 has a
graphic mode for use in X Window. 

There are still other text browser projects.  Some of them seem to be
dead.

<sect> Special Uses for a Terminal
<sect1>Make a Serial Terminal the Console <label id="term_as_console">

<p> This will turn a text-terminal (or emulator PC) into a "serial
console".  Many messages from the system are normally only sent to the
console (the PC monitor).  Some of the messages sent to the console at
boot-time may also be seen on any terminal after the boot succeeds by
typing the command: dmesg.  If the boot failed this will not be of any
use since the terminal can't work without an operating system.  It's
possible to modify the Linux kernel so as to make a terminal serve as
the console and receive all the messages from Linux intended for the
console.  Unfortunately, the messages from the BIOS (which display on
the monitor when a PC is first started) will not display on this
terminal (but still display on the monitor).

There's a Remote-Serial-Console-HOWTO on this topic.  Some people use
a serial console when they run a PC without a monitor or keyboard.
Normally, a PC will not start up without a keyboard and video card but
some BIOSs permit it.  If you are lucky enough to have such a BIOS
that supports "console re-direct" you will likely then need to setup
the BIOS using the CMOS menus when you start your PC.

The method of creating a "serial console" depends on your kernel
version.  In any case serial support needs to be compiled into the
kernel and not supplied as a module.

<sect2> For Kernels 2.2 or higher
<p> The instructions for creating a serial-console are included with
the kernel documentation in: Documentation/serial-console.txt.
Kernel 2.4+ has better documentation and mentions the need to run
getty on the serial port.  Normally, the device /dev/console is linked
to tty0 (the PC console).  For a serial-console you create a new
/dev/console by
<tscreen><verb>
mknod -m 622 console c 5 1
</verb></tscreen>
You must also put statements regarding the serial-console into
/etc/lilo.conf and then run lilo.  This is because the equivalent of
"setserial" needs to be run early before the kernel is loaded so that
the serial-console can display the booting.  See the above mentioned
kernel documentation and the man page for lilo.conf for more details.

Here is an example <tt>/etc/lilo.conf</tt> file contents (for ttyS0):
<tscreen><verb>
prompt
timeout=50
boot = /dev/sda
vga = normal # force sane state
install = /boot/boot.b
message = /boot/message
image = /vmlinuz
root = /dev/sda1
label = console
serial = 0,9600n8
append = "console=ttyS0"
</verb></tscreen>

The same PC may have more than one serial console but the last console
mentioned in the "append" statement becomes the main console that you
interact with ??  See the kernel docs (but it's not too clear).

<sect2> Serial-Console For Kernels before 2.2
<p> The Linux Journal in April 1997 had an article on patching
the Linux kernel.  You add a couple of #defines at the start of
src/linux/drivers/char/console.c:

<tscreen><verb>
#define CONFIG_SERIAL_ECHO
#define SERIAL_ECHO_PORT 0x2f8  /* Serial port address  */

The following was not in the Linux Journal article.
In kernel 2.+ (and earlier ??) you need to also set the baud
rate (unless 9600 is OK).  Find these 2 lines:

serial_echo_outb(0x00, UART_DLM); /* 9600 baud */
serial_echo_outb(0x0c, UART_DLL);

Change 0x0c in the line above (depending on the baud rate you want):

115200 baud: 0x01	19200 baud: 0x06	2400 baud: 0x30
57600 baud: 0x02	 9600 baud: 0x0c	1200 baud: 0x60
38400 baud: 0x03	 4800 baud: 0x18
</verb></tscreen>

If you currently use the console to select which operating system to
boot (using LILO), but would like to do this from a terminal, then you
need to add a line to the /etc/lilo.conf file.   See the manual page
for lilo.conf and search for "serial=".

<sect1> Run Linux without a Monitor
<p> One way to do this is to just use a terminal (serial console) for
the monitor See <ref id="term_as_console" name="Make a Serial Terminal
the Console">.  You may still need a video card since many BIOSs
require one to get the PC started.  Your BIOS may also require a
keyboard to get started or it may have an option where you can set the
BIOS not to require a keyboard.

If you boot without a monitor, make sure that the boot loader (such as
LILO or GRUB) doesn't try to present any image on the screen.  A
text-terminal can't display it and the booting may hang.

If you have a keyboardless terminal, it can also be used as a monitor
by use of the ttysnoop program.  As of yet, it doesn't work like a
console since it doesn't get all the initial boot-time messages.  See
<ref id="keyboardless_terminal" name="Use a Keyboardless Terminal as
the Monitor">

<sect1> Use a Keyboardless Terminal as the Monitor <label
id="keyboardless_terminal">
<sect2> How it works
<p> While you might think that a terminal without a keyboard is
useless it is possible to use it as the monitor and type on the PC's
own keyboard.  This may be done by using the spy program
<tt/ttysnoop/.  This program permits a person at one terminal to spy
on (or snoop) what someone else is typing at another terminal (or the
PC console-monitor).

Now suppose you are typing away at the monitor tty1.  Imagine that
someone with a terminal on ttyS2 is spying on you (with ttysnoop) and
has a screen that looks just like your screen.  Everything you type
at tty1 also displays on ttyS2.  Now move the spy terminal (on ttyS2)
so it is side-by-side with your monitor (on tty1).  Everything you
type on the PC keyboard will now display on the two screens in front
of you: the monitor and the spy terminal.  Now just look only at the
spy terminal as you type.  Disconnect both the monitor and the
terminal keyboard since you're not using either.  Thus you are now
using a keyboardless terminal as a monitor.  What a simple but clever
solution!

One possible problem (which turns out to be no problem at all) is
that normally, the type of spy terminal should be the same as the type
of terminal being spied upon.  Since the monitor is normally declared
as a terminal of type "linux" (which is close to vt100), you might
think that the real terminal should also be (or at least emulate) a
vt100.  Not necessarily so!  For example, if you have a wyse60
terminal you simply falsely declare that you have a wyse terminal on
tty1 (tell the getty program for tty1 that it's a wyse60).

Here's why you can get away with this.  Go back the scenario where
you have both the monitor and the wyse60 terminal in front of you,
both displaying the same thing (or trying to).  Ttysnoop will be
sending the wyse60 the same bytes as are going to the monitor.  If
you've falsely claimed that the monitor is a wyse60, then you'll have
wyse60  escape sequences going to both the monitor and the wyse60
terminal (via ttysnoops).  The display on the wyse60 is fine but the
display on the monitor is corrupted since it's getting wyse60 escape
sequences.  Since you will not use the monitor (and are about to
disconnect it) this corruption is never a problem (you simply don't
see it).

<sect2> Example configuration
<p> This is not the ideal setup since ttysnoop runs so late that the
login prompt doesn't appear.  This example is for a wyse60 terminal on
ttyS2 and the missing monitor/PC-keyboard on tty1.  It uses the agetty
program for getty as supplied by the Debian distribution.   Your getty
may require a different format.

In <tt>/etc/inittab:</tt>
<tscreen><verb>
1:2345:respawn:/sbin/getty 38400 tty1 wyse60 -ln /usr/sbin/ttysnoops
</verb></tscreen>

Note that <tt>ttysnoop/ttysnoops</tt> is a client-server combo so the
"s" is not a typo.  If you don't use -n you may not see a login prompt
on the terminal.  With no -n, agetty issues the prompt before the
ttysnoop is activated.  With -n, agetty doesn't issue the prompt (but
login does instead).  If you use -n, agetty will no longer
automatically detect parity but if you don't use parity all is OK.

In <tt>/etc/snooptab:</tt>
<tscreen><verb>
# tty	    snoopdev	  type	  execpgm
tty1	    /dev/ttyS3	  init	  /usr/local/bin/sterm
</verb></tscreen>
In the above, a script named sterm is used to run the stty program.
You may not need this or may want to use it for another purpose.
Here's the example sterm script in <tt>/usr/local/bin/sterm:</tt>

<tscreen><verb>
#!/bin/sh
stty rows 24
/bin/login $@
</verb></tscreen>

<sect> Trouble-Shooting <label id="trouble_shoot">

<p> If you suspect that the problem is a hardware problem, see the <ref
id="repair_" name="Repair and Diagnose"> section.  If it's the
keyboard see <ref id="keyboards_" name="Keyboards">.  If it responds
incorrectly (if at all) to what you type. see <ref
id="corrupt_interface" name="Corrupted Terminal Interface">.  If the
problem involves the serial port itself see the Serial-HOWTO.

Here is a list of possible problems:
<itemize>
<item><ref id="term_OK" name="Is the Terminal OK ?">
Suspect the terminal is defective.
<item><ref id="display_freezes" name="Display Freezes (hung
terminal)">
<item><ref id="displays_foreign" name="Displays Foreign/Weird
Characters/Symbols">
<item><ref id="displays_esc-seqs" name="Displays Escape Sequences">
<item><ref id="flow_ctrl_ng" name="Missing Text"> Either skips
over some text or displays some text OK and hangs.
<item><ref id="keys_erratic" name="All Keys Work Erratically; Must Hit
a Key a Few Times">
<item><ref id="stopped_" name="If getty run from command line: Programs
get stopped">  with message "Stopped"
<item><ref id="rapid_respawn" name="Getty Respawning Too Rapidly">
(console error message)
<item><ref id="after_login" name="Fails Just After Login">
<item><ref id="cant_login" name="Can't Login"> but login prompt is
OK.
<item><ref id="garbled" name="Garbled Login Prompt">
<item><ref id="no_login_prompt" name="No Login Prompt">
<item><ref id="cursor_jumps" name="Cursor Jumps">
</itemize>

There are two cases where the terminal goes bad.  One is when it's
been recently working OK and suddenly goes bad.  This is discussed in
the next sub-section.  The other case is where things don't work right
just after you install a terminal.  For this case you may skip over
the next section.

<sect1> Terminal Was Working OK <label id="term_was_ok">
<p> When a formerly working terminal suddenly goes bad it is often
easy to find the problem.  That's because (except for hardware
failures) the problem is likely due to something that you did (or
something the software that you used did).

The problem may be obvious such as an error message when the terminal
is first turned on.  If it makes a strange noise it likely needs
repair.  See <ref id="repair_" name="Repair & Diagnose">.  First,
think about what has been done or changed recently as it's likely the
cause of the problem.  Did the problem happen just after new system
software was installed or after a change in the configuration?

If the terminal isn't responding correctly (if at all) to what you
type to it, you may have a <ref id="corrupt_interface" name="Corrupted
Terminal Interface">.

<sect1> Terminal Newly Installed <label id="trouble_shoot_new">
<p> If you've just connected up a terminal to a computer per
instructions and it doesn't work this section is for you.  If a
terminal that formerly worked OK doesn't work now then see <ref
id="term_was_ok" name="Terminal Was Working OK"> If you suspect
that the serial port on your computer may be defective you might try
running a diagnostic test program on it.  At present (June 1998) it
seems that Linux doesn't yet have such a diagnostic program so you may
need to run diagnostics under MS DOS/Windows.  There are some programs
to monitor the various serial lines such at DTR, CTS, etc. and this
may help.  See <ref id="serial_mon" name="Serial
Monitoring/Diagnostics">

One approach is to first see if the terminal will work by trying
to copy a file to the terminal (cp my_file /dev/ttyS?) under the most
simple situation.  This means with the modem control lines disabled
and at a show speed that doesn't need flow control (make sure that any
hardware flow control is disabled).  If this copy works, then make the
situation a little more complicated and see if it still works, etc.,
etc.  When the trouble appears just after you made a change, then that
change is likely the source of the trouble.  Actually, its more
efficient (but more complex) to jump from the simple situation to
about half way to the final configuration so that the test eliminates
about half of the remaining possible causes of the problem.  Then
repeat this methodology for the next test.  This way it would only
take about 10 tests to find the cause out of a thousand possible
causes.  You should deviate a little from this method based on hunches
and clues.

<sect1> Is the Terminal OK ? <label id="term_OK">
<p> Many terminals will start up with some words on the screen.  If
these words convey no error message, it's probably OK.  If there is no
sign of power (a dark screen, etc.) re-plug in the computer power cord
at both ends.  Make sure there is power at the wall jack (or at the
extension cord end).  Try another power cord if you have one.  Make
sure the terminal is turned on and that its fuse is not blown.  A
blank (or dim) screen may sometimes be fixed by just turning up the
brightness and contrast using knobs or a keyboard key in set-up mode.

A terminal that's been stored for a long time may take a while to
"warm up" as the electrolytic capacitors heal themselves under
voltage.  If it still won't work See <ref id="repair_" name="Repair &
Diagnose"> for tips on repairing it.

If the terminal starts up OK, but you suspect that something may be
wrong with it, go into "local mode" where is works like a typewriter
and try typing on it.  See <ref id="local_mode" name="Local Mode">.
Before you have trouble, you should find out if your terminal displays
error messages if the hardware is bad.  One way to test a terminal
for this is to turn it on with the keyboard unplugged and see if it
displays an error message.

<sect1> Missing Text <label id="flow_ctrl_ng">
<p>  If several lines or text displays on the terminal OK and then it
stops without finishing (in the middle of a word, etc.) or if big
chunks of text are missing, you likely have a problem with flow
control.  If you can't figure out right away what's causing it,
decrease the speed.  If that fixes it, it's likely a flow control
problem.  It may be that flow control is not working at all due to
failure to configure it correctly, or due to incorrect cable wiring
(for hardware flow control).  See <ref id="flow_control" name="Flow
Control">

If you can type OK at the terminal but when text is sent to the
terminal, only about 1 in every 16 characters sent gets thru, then you
may have given the wrong UART to setserial.  This will happen if the
port is an obsolete 16550 (or lower) but you've told setserial it's a
16550A or higher.

If single characters are missing, perhaps the serial port is being
overrun by too fast a speed.  Try a slower baud rate.

If your device is under 1200 baud (probably a very slow old hard-copy
terminal or printer) and the text gets truncated, then the problem may
be in the serial device driver.  See Printing-HOWTO under "Serial
devices" on how to fix this.

<sect1> All Keys Work Erratically; Must Hit a Key a Few Times
<label id="keys_erratic">
<p> This is where you need to hit a key a few times before it works
(and see the letter you typed on the screen).  If you type a word,
some (or even all) of the letters may be missing on the screen.  If
letters are missing from a command it doesn't work and even if all
letters are present you may need to hit the return-key several times
to get the command to execute.

This may be due to two different processes opening the serial port.  Both
try to read what you type.  Sometimes one process (the right one
--perhaps the shell) reads what you type and at other times the other
process reads what you type.  An example is where the other process is
for a serial mouse (such as gpm) which doesn't echo what you type.
So another process running on the same ttySx is eating some of what
you type.  To fix this, use "ps -alx" to see what else is running on
your ttySx and kill that process.

You might think that lockfiles would prevent two programs from using
the same serial port at the same time.  But neither the terminal nor
the gpm mouse program uses lockfiles.  Since others may need to write
to your terminal, it's reasonable not to use lockfiles.  See
Lock-Files in the Serial-HOWTO.

<sect1> ... respawning too fast: disabled for 5 minutes
<label id="rapid_respawn">

<sect2>What's happening
<p>You see a message on the console like: "Getty respawning too fast:
disabled for 5 minutes".  Instead of "Getty" it may display a label
(such as: Id "S2") where S2 is the label for the line in /etc/inittab
from where from where getty was called.

When getty starts up, it tries to send a login message to the serial
port.  But if there is something seriously wrong, getty will be
immediately killed.  Since the /etc/inittab file line for getty says
to "respawn", getty is started again, only to be killed again, etc.
Thus getty rapidly respawns over and over.  But the operating system
intervenes and stops this nonsense (for 5 minutes).  The following
sections show possible causes and fixes.

<sect2>Getty line in /etc/inittab file incorrect
<p>Make sure the line which calls getty in /etc/inittab is
correct.  A typo in "ttySx" (or "DTxxxx" for uugetty) or in "getty"
may cause this problem.  

<sect2> No modem control signal
<p> If the terminal doesn't send the PC a CD signal on one of the pins
of the serial port, getty will be killed unless the "local" option has
been used with getty.  So a quick fix is to just use a "local" option
(-L for agetty, "CLOCAL" in /etc/gettydefs for getty_ps).

Another approach is to determine why CD is not being asserted.  In
many cases the cable to the terminal simply doesn't have a wire for
the CD pin so you must use the "local" option.  If there is a wire for
the CD pin then there may not be any signal on it until the terminal
is powered on.  Note that the CD pin signal is sometimes supplied by
the DTR pin of the terminal (or the PC) by using jumper wires inside
the connector.

<sect2> No such serial device
<p>If the device (such as /dev/ttyS2) is bogus (doesn't physically
exist or has been disabled), then getty will be killed.  You may use
"scanport" (Debian only ??) and/or "setserial" to probe for the device
or try another ttyS.  Perhaps the device has been disabled in the
CMOS.  See "Serial-HOWTO".

<sect2> No serial support
<p> Linux provides serial support either by selecting it when
compiling the kernel or by loading the serial module: serial.o.  This
"respawning" error happens if serial support has neither been built
into the kernel nor provided by a serial module.  You many use the
"lsmod" command to see if the serial module is loaded.  To see if
serial support is built into the kernel, check a kernel configuration
file (in /boot, in the source tree, etc.)

<sect2> Key shorted <label id="key_shorted_getty">
<p> Another possible cause of getty respawning too rapidly is if a
keyboard key is shorted.  This can happen if the key gets stuck in the
down position.  With auto-repeat enabled, this "types" thousands of
characters to the login prompt.  Look for a screen filled with all the
same character (in some cases, with 2 or more different characters).

<sect1> Fails Just After Login <label id="after_login">
<p> If you can login OK but then you can't use the terminal it may be
because the starting of the login shell has reconfigured the terminal
(to an incorrect setting) by a command which someone put into one of
the files that are run when you login and a shell starts.  These files
include /etc/profile and &tilde;/.bashrc.  Look for a command starting with
"stty" or "setserial" and make sure that it's correct.  Even if it's
done OK in one initialization file, it may be reset incorrectly in
another initialization file that you are not aware of.  Ways to get
into the systems to fix it are to use another terminal or console, use
a rescue diskette, or type: "linux single" at the lilo prompt which
puts you into single user mode without running startup files.

<sect1> Can't Login <label id="cant_login">
<p> If you get a login prompt but get no response (or perhaps a
garbled response) to your login attempts a possible cause is that the
communication is bad one-way from the terminal to the computer.  It
could be a bad or mis-wired cable/connector.  If you're not already
using the "local" option with getty, do so to disable the modem
control lines.  See <ref id="getty_" name="Getty (used in
/etc/inittab)">.  You might also disable hardware flow control (stty
-crtscts) if it was enabled.  If it now works OK then your modem
control lines are likely either not wired correctly or there's a
mistake in your set-up.  Some terminals allow setting different values
(such as baud rate) for send and receive so the receive could be OK
but the send bad.

You should also try at another terminal (such as the console) "stty -F
/dev/ttyS1" (or ttyS whatever) to see that it's set up correctly.  It
will often be in raw mode (and this is probably OK) with -icanon and
-echo etc.  If the terminal incorrectly set at half-duplex (HDX), then
one set of the characters you see when you type are coming from the
terminal itself.  If the characters are doubled, then the echos from the
computer are OK and you may switch to full-duplex to fix this.  But if
half-duplex is set and you only see what looks like normal "echos", then
they are not coming from the computer as they should be.

If you get a message saying something like "login failed" then if
there is no error in typing or in the password, there may be some
restrictions on logins which will not allow you to log in.
Unfortunately, this message, may not tell you why it failed.  See <ref
id="login_restr" name="Login Restrictions">

<sect1> Garbled Login Prompt  <label id="garbled">
<p> This may be due to using the wrong character set, transmission
errors due to too high of a baud rate, incompatible baud rates,
incompatible parity, or the wrong number of bits per byte.  If it's a
variety of strange characters you have the wrong character set or a
high order bit is being set by mistake.  If words are misspelled, try
a lower baud rate.  For baud, parity, or bits/character incompatibilities
you see a lot of the same "error character" which represents a real
character that can't be displayed correctly due to an error in parity
or baud rate.  The "error character" may be an upside-down question
mark or some other strange looking character such as a rectangle.

If you are using agetty (often just named getty), the agetty program
will detect and set parity and/or bits/character if you type something.
Try it with a return to see if it fixes it.

<sect1> No Login Prompt <label id="no_login_prompt">
<p> If there's no login prompt displayed after hitting the return-key
a few times then check the following:  Use the "top" or "ps" programs
to make sure that a getty (or login) process is actually running on
the terminal.  Is the terminal getting power?  Is the null modem cable
plugged in to the correct ports on both the terminal and computer?

Check that getty isn't hanging because there is no CD signal (or no CD
wire in the cable).  If such a CD signal doesn't exist you should have
specified "local" to getty by either:
<itemize>
<item>If getty_ps (Redhat, etc.) two CLOCAL flags in /etc/gettydefs
(See <ref id="getty_ps" name="getty (part of getty_ps)">).
<item>If agetty (Debian, etc.) a -L flag in /etc/inittab (See <ref
id="agetty_" name="agetty">).
</itemize>

If getty (or login) isn't running, carefully check the format for calling getty
in /etc/inittab.  Make sure that it includes the current runlevel
(shown by typing the command "runlevel") and that it is valid for your
flavor of getty.  Sometimes killing getty or login (it will restart
automatically) helps.

<sect2> Terminal was working OK
<p> Although hardware failures are possible, the problem is likely due
to something that someone did by mistake.  Did someone do something
that might have loosened a cable?  Did someone modify /etc/inittab or
make some other change to the software so as to prevent terminal
login?  If this doesn't reveal the cause, continue reading.

<sect2> More diagnose
<p> The above should solve most cases (unless you've just installed a
terminal).  Other causes include defective hardware or cables (must be
file-transfer), terminal setup at wrong baud-rate, terminal in local
mode, etc.  At this point two different avenues of approach are (you
may pursue more than one at a time).

<itemize>
<item> <ref id="consoleD" name="Diagnose problem from the console">
<item <ref id="measure_volts" name="Measure voltages">
</itemize>

<sect2> Diagnose problem from the console <label id="consoleD">
<p> One test is to try to copy a something to the terminal (It might
be a good idea to try this near the start of the installation process
before setting up getty).  You may use the Linux copy command such as:"cp
file_name /dev/ttyS1".  Or your could use: "echo any_word >
/dev/ttySx".  If it doesn't work, use stty to make the interface as
simple as possible with everything disabled (such as hardware flow
control: -crtscts; parity, and modem control signals: clocal).  Be
sure the baud rates and the bits/byte are the same.  If nothing
happens verify that the port is alive with a voltmeter per the next
section.

<sect2> Measure voltages <label id="measure_volts">
<p> If you have a voltmeter handy check for a negative voltage (-4v to
-15v) at pin 3 or 2 (receive data) at the terminal side of the
file-transfer cable.  The positive lead of the meter should be
connected to a good ground (a metal connector on the end of the cable
may not be grounded).  If there is no such negative voltage then
check for it at the transmit pin (TxD) on the computer (see <ref
id="DB_pin-out" name="DB9-DB25"> for the pin-out).  If it's present
there but not at the receive pin (RxD) at the terminal, then the cable
is bad (loose connection, broken wire, or not a file-transfer aka
null-modem).  If this voltage is absent at the computer, then its
serial port is dead.  Test it with a software diagnostic test or
replace it.

If the serial port is alive, you may want to send a file to it (with
modem controls disabled) and watch the signal on a voltmeter (or other
electronic gadget).  To check for a transmitted signal with a voltmeter,
check for a steady negative voltage when the line is idle.  Then start
sending a file (or start getty).  On an analog meter you should see
the needle dropping to almost 0 and fluttering about 0 as it measures
short-run averages of the bit stream.  On a digital meter you will not
see the fluctuations as well but you can switch to the AC scale to see
the AC voltage created by the flow of bits.  If your meter fails to
block out DC on the AC scale (the default of most analog meters), then
you could get a false high AC reading when looking at the idle DC of
-12v (or -5v) on the AC scale.  Without a meter, you could connect a known
good device (such as another terminal or an external  modem) to the
serial port and see if it works OK.

<sect1> Displays Foreign/Weird Characters/Symbols
<label id="displays_foreign">
<p> Don't confuse this with <ref id="displays_esc-seqs" name="Displays
Escape Sequences">.  If what you type or see on the screen is not
what's expected but looks like a foreign alphabet, math symbols,
line-drawing character, etc. then it could be that the many of bytes
that are sent to your terminal have the high order bit set (when it
shouldn't be).  You are looking at the character set (or part of a
character set) which has the high order bit set.  This may happen if
you have the baud rate wrong or parity set wrong (per stty).  If you
have parity set per stty but inside the terminal it's 8-bit no-parity,
then the high order bit (= parity bit) will often be erroneously set.
Try stty -F /dev/ttyS?  from another terminal to check if the baud
rate and parity are correct.

Perhaps the wrong character set (font) has been installed.  An
erroneous escape sequence sent to the terminal could have switched
character sets.  If you are using the mapchan program to change the
keyboard mapping, it could be incorrect.

<sect1> Displays Escape Sequences <label id="displays_esc-seqs">
<p>You may see something like "5;35H22,1" or "3;4v" or "1;24r" or
"^[[21;6H", etc., etc.  Of course, the numbers and letters will be
different.  They will be scattered about (either randomly or in a
strange sense of order).  The display will look a mess and will likely
have other defects.  Some application and commands will result in
corrupted displays.

What you see are escape sequences (or fragments of them) that were
sent to your terminal in order to control it, but your terminal didn't
recognize them and passed them on to the screen.  It's likely that the
program you're using erroneously thinks you are using another type of
terminal.  Thus it sends escape sequences that your terminal doesn't
understand.  This can sometimes do strange things to your display.
Check that the TERM environment variable is set correctly (type: echo
$TERM).

<sect2>Telnet
<p>The problem of getting TERM right can be a bit more complex if you use
telnet.  Telnet doesn't emulate a terminal but passes the value of
your TERM variable to the remote computer.  If the remote computer
doesn't support your type of terminal, or changes the value of TERM to
a wrong value (on the remote) then there's trouble.  Telnet
should initially set the value of TERM correctly on the remote.  But
changes to the value of TERM (on the remote) could be caused by an
incorrect shell configuration file there.  The first thing to do is to
check the value of TERM, both on your computer and on the remote.  The
above is overly simplified since it's possible for your telnet client
to present the remote server with a list of possible TERM values which
your computer supports (if telnet knows that your computer can emulate
more than one terminal type).

<sect2>Terminal set to display escape sequences
<p>Another possible cause is that your terminal happens to be in a
special mode where it displays the escape sequences instead of
executing them.  Then you'll also see them on the screen but they will
display in an orderly fashion.  This mode is more precisely, one that
displays control codes.  But since each escape sequence starts with a
control code (the "escape" character), the whole escape sequence is
not recognized by the terminal and is passed along to the screen.  See
<ref id="control_codes" name="Control Codes">.

<sect1> Slow: pauses of several seconds between bursts of characters
<p> You likely have mis-set interrupts>  See the Serial-HOWTO section
starting with "Slow:"

<sect1>Cursor Jumps <label id="cursor_jumps">
<p>This error happens when you expect the cursor to move to the next
character but instead it seems to jump to another character.  It can
happen in the vim editor when you've selected "showmatch" to highlight
matching brackets (or parentheses).  There is nothing wrong with the
terminal and the cursor isn't jumping, but it looks like it is.

What is happening is that the cursor is reverse video and the
highlighting is also reverse video.  So suppose you highlight (or
emphasize) a character by reverse video and then put a reverse-video
cursor over it.  The cursor's reverse video will then reverse
the existing reverse video of the character and result in normal
video.  The result is that both the cursor and character highlighting
have disappeared for that character and the cursor is invisible (until
you move it to a non-highlighted character).

OK, so the cursor suddenly disappears, but what makes it jump?  For
the vim "showmatch" when you move the cursor to an opening bracket it
also highlights the closing bracket.  Thus the closing bracket
suddenly becomes reverse video and it looks just like the cursor has
jumped there, but it hasn't.  Similar "illusions" happen when you move
the cursor to a closing bracket (or parenthesis).  This illusion when
you reverse reverse-video happens in other cases besides the vim
example just presented.

<sect1> Terminal doesn't scroll <label id="no_scroll_25">
<p> One reason may be that something is wrong with terminfo.  Another
reason could be that you are outside the scrolling region set for the
terminal.  Some stupid programs just assume that your terminal has 24
lines and set the scrolling region for 24 lines (by an escape sequence
sent to the terminal) without consulting terminfo to see how many
lines there actually are.  Then when you use another program it may
leave the cursor on line 25 where it becomes trapped and the terminal
will not scroll.  To avoid this problem, create an environment
variable "export LINES=25" and also "stty -F /dev/ttySx rows 25".
Then the programs that assume 24 lines will hopefully use 25 lines set
the scrolling region accordingly.

<sect1> Serial Monitoring/Diagnostics <label id="serial_mon">
<p> A few Linux programs will monitor the modem control lines and
indicate if they are positive (1) or negative (0).
<itemize>
<item> statserial (in Debian distribution)
<item> The "file": /proc/tty/driver/serial.  Use "watch head ..." to
monitor it.  Has info on errors and byte flow.
<item> modemstat (only works on Linux PC consoles.  Will coexist with
the command line)
</itemize>
You may already have the above programs.  If not, go to <url url=
"http://ibiblio.org/pub/Linux/system/serial/" name="Serial
Software">.  When using these, bear in mind that what you see is the
state of the lines at the host computer.  The situation at the
terminal will be different since some wires are often missing from
cables while other wires cross over.  As of June 1998, I know of no
diagnostic program in Linux for the serial port.

<sect1> Local Mode <label id="local_mode">
<p> In local mode, the terminal disconnects from the computer and
behaves like a typewriter (only it doesn't type on paper but on the
screen).  Going back into on-line mode reconnects to the computer
allowing you to resume activities at the same point where you left off
when you went into "local".  This is useful both for testing the
terminal and for educational purposes.  For some terminals  there is
no "local mode" but "block mode" may substitute for it.  If there is
no "block mode", "half duplex" mode might work, except that what you
type gets sent to the computer also.  In this case the computer may
echo the characters sent to it resulting in two characters displayed
on the screen for every character you type.  To prevent this you could
shut down the computer, disconnect the RS-232 cable, etc.

When in local mode you may type escape sequences (starting with the
ESC key) and observe what they do.  If the terminal doesn't work
correctly in local mode, it's unlikely that it will work correctly
when connected to the computer.  If you're not exactly sure what an
escape sequence does, you can try it out in local mode.  You might
also use it for trying out a terminal that is for sale.  To get into
local mode on some terminals you first enter set-up mode and then
select "local" from a menu (or press a certain key).  See <ref
id="enter_setup" name="Getting Into Set-Up (Configuration) Mode">.

<sect1> Serial Electrical Test Equipment <label id="ser_elect_test">
<!-- begin ser_elect_test.D.  in Serial, Text-Terminal -->
<sect2> Breakout Gadgets, etc.
<p> While a multimeter (used as a voltmeter) may be all that you need
for just a few serial ports, simple special test equipment has been
made for testing serial port lines.  Some are called "breakout ... "
where breakout means to break out conductors from a cable.  These
gadgets have a couple of connectors which connect to serial port
connectors (either at the ends of serial cables or at the back of a
PC).  Some have test points for connecting a voltmeter.  Others have
LED lamps which light when certain modem control lines are asserted
(turned on).  The color of the light may indicate the polarity of the
signal (positive or negative voltage).  Still others have jumpers so
that you can connect any wire to any wire.  Some have switches.

Radio Shack sells (in 2002) a "RS-232 Troubleshooter" (formerly called
"RS-232 Line Tester") Cat. #276-1401.  It checks TD, RD, CD, RTS, CTS,
DTR, and DSR.  A green light means on (+12 v) while red means off (-12
v).  They also sell a "RS-232 Serial Jumper Box" Cat.
#276-1403.  This permits connecting the pins anyway you choose.  Both
these items are under the heading of "Peripheral hookup helpers".
Unfortunately, they are not listed in the index to the printed
catalog.  They are on the same page as the D type connecters so look
in the index under "Connectors, Computer, D-Sub".  A store chain named
"Active Components" may have them.

<sect2> Measuring voltages
<p> Any voltmeter or multimeter, even the cheapest that sells for
about $10, should work fine.  Trying to use other methods for checking
voltage is tricky.  Don't use a LED unless it has a series resistor to
reduce the voltage across the LED.  A 470 ohm resistor is used for a
20 ma LED (but not all LED's are 20 ma).  The LED will only light for
a certain polarity so you may test for + or - voltages.  Does anyone
make such a gadget for automotive circuit testing??  Logic probes may
be damaged if you try to use them since the TTL voltages for which
they are designed are only 5 volts.  Trying to use a 12 V incandescent
light bulb is not a good idea.  It won't show polarity and due to
limited output current of the UART it probably will not even light up.

To measure voltage on a female connector you may plug in a bent paper
clip into the desired opening.  The paper clip's diameter should be no
larger than the pins so that it doesn't damage the contact.  Clip
an alligator clip (or the like) to the paper clip to connect up.  Take
care not to touch two pins at the same time with any metal object.

<sect2> Taste voltage
<p> As a last resort, if you have no test equipment and are willing to
risk getting shocked (or even electrocuted) you can always taste the
voltage.  Before touching one of the test leads with your tongue, test
them to make sure that there is no high voltage on them.  Touch both
leads (at the same time) to one hand to see if they shock you.  Then
if no shock, wet the skin contact points by licking and repeat.  If
this test gives you a shock, you certainly don't want to use your
tongue.

For the test for 12 V, Lick a finger and hold one test lead in it.
Put the other test lead on your tongue.  If the lead on your tongue is
positive, there will be a noticeable taste.  You might try this with
flashlight batteries first so you will know what taste to expect.
<!-- end ser_elect_test.D in Serial, Text-Terminal -->


<sect> Repair & Diagnose <label id="repair_">
<p> Repairing a terminal has much in common with repairing a monitor
and/or keyboard.  Sometimes the built-in diagnostics of the terminal
will display on the screen.   By the symptoms, one may often isolate
the trouble to one of the following: bad keyboard, CRT dead, power
electronics failure (distorted display), or digital electronics
failure.  It's best to have a service manual, but even if you don't
have one, you can often still repair it.

<sect1> Repair Books & Websites <label id="repair_info">
<sect2> Books
<p> Bigelow, Stephen J.: Troubleshooting & Repairing Computer
Monitors, 2nd edition, McGraw-Hill, 1997.  Doesn't cover the character
generation electronics nor the keyboard.

<sect2> Websites
<p> The FAQ <url url="http://www.repairfaq.org"> for the newsgroup:
sci.electronics.repair is long and comprehensive, although it doesn't
cover terminals per se.  See the section "Computer and Video
Monitors".  Much of this information is applicable to terminals as are
the sections: "Testing Capacitors", "Testing Flyback Transformers",
etc.  Perhaps in the future, the "info" on repair in this HOWTO will
consist mainly of links to the above FAQ (or the like).

<sect1> Safety
<p> CRT's use high voltage of up to 30,000 volts for color (less for
monochrome).  Be careful not to touch this voltage if the set is on
and the cover off.  It probably won't kill you even if you do since
the amount of current it can supply is limited.  But it is likely to
badly burn and shock you, etc.  High voltage can jump across air gaps
and go thru cracked insulation so keep your hands a safe distance from
it.  You should notice the well-insulated high voltage cable connected
to one side of the picture tube.  Even when the set is off, there is
still enough residual voltage on the picture tube cable connection to
give you quite a shock.  To discharge this voltage when the set is
unplugged use a screwdriver (insulated handle) with the metal blade
grounded to the picture tube ground cable with a jumper wire.  Don't
use chassis ground.

The lower voltages (of hundreds of volts) can be even more dangerous
since they are not current limited.  It is even more dangerous if your
hands are wet or if you are wearing a metal watchband, ring or the
like.  In rare cases people have been killed by it so be careful.  The
lowest voltages of only several volts on digital circuitry are fairly
safe but don't touch anything (except with a well insulated tool)
unless you know for sure.

<sect1> Appearance of Display
<p> If the display is too dim, turn up the brightness and/or contrast.
using knobs on the exterior of the unit (if they exist).  If the
width, height or centering is incorrect, there are often control knobs
for these.  For some older terminals one must press an arrow key
(or the like) in set-up mode.

You may need to remove the cover to make adjustments, especially on
older models.  You could arrange things so that a large mirror is in
front of the terminal so as to view the display in the mirror while
making adjustments.  The adjustments to turn may be on a printed
circuit board.  While a screwdriver (possibly Phillips-head) may be
all that's needed, inductors may require special TV alignment tools
(plastic hex wrenches, etc.).  The abbreviated name of the adjustment
should be printed on the circuit board.  For example, here are some
such names:

<itemize>
<item> V-Size adjusts the Vertical height (Size)
<item> H-Size adjusts the Horizontal width (Size).  It may be an inductor.
<item> V-Pos adjusts the Vertical Position
<item> H-Pos adjusts the Horizontal Position
<item> V-Lin adjusts Vertical Linearity (Use if width of scan lines
			differs at the top and bottom of the screen)
<item> V-Hold adjusts Vertical Hold (Use if screen is uncontrollable
						scrolling)
<item> Bright adjusts brightness (an external knob may also exist)
<item> Sub-Bright adjusts brightness of subdued intensity mode (often
the normal mode: dimmer than bold or bright mode).
</itemize>

Changing linearity may change the size so that it will need to be
readjusted.  A terminal that has been stored for some time may have a
small display rectangle on the screen surrounded by a large black
Before adjusting it, leave the terminal on for a while since it will
likely recover some with use (the black borders will shrink).

<sect1> Diagnose
<sect2> Terminal Made a Noise or Smoked
<p> If the terminal made some noise just before it failed (or when you
turn it on after it failed) that noise is a clue to what is wrong.  If
you hear a noise or see/smell smoke, immediately turn the terminal off
to prevent further damage.  A pop noise may be a capacitor exploding
or a fuse blowing.  A buzzing noise is likely due to arcing.  The
problem may be in the high voltage power supply of several thousand
volts.

Remove the cover.  Look for discoloration and bulging/cracked
capacitors.  If the bad spot is not evident, turn it on again for a
short time and look for smoking/arcing.  For arcing, a dimly lit room
will help find it.  The high voltage cable (runs between the flyback
transformer and the side of the picture tube) may have broken
insulation that arcs to ground.  Fix it with high-voltage insulating
dope, or special electrical tape designed say for 10,000 volts.

The flyback transformer (high voltage) may make only a faint clicking
or sparking noise if it fails.  You may not hear it until you turn the
terminal off for a while and then turn it back on again.  To track
down the noise you may use a piece of small rubber tubing (such as
used in automobiles) as a stethoscope  to listen to it.  But while you
are listening for the noise, the terminal is suffering more damage so
try find it fast (but not so fast as to risk getting shocked).

A shorted power supply may cause a fuse to blow.  Replacing a blown
fuse may not solve the problem as the same short may blow the fuse
again.  Inspect for any darkened spots due to high heat and test those
components.  Shorted power transistors may cause the fuse to blow.
They may be tested with a transistor checker or even with an
ohm-meter.  Use the low ohm scale on an ohm-meter so that the voltage
applied by the meter is low.  This will reduce the possible damage to
good components caused by this test voltage.

If the terminal has been exposed to dampness such as being stored in a
damp place or near a kitchen with steam from cooking, a fix may be to
dry out the unit.  Heating a "failed" flyback transformer with a blow
dryer for several minutes may restore it.

<sect2> Terminal Made No Noise

<p> A blank screen may be due to someone turning the brightness
control to the lowest level or to aging.  The next thing to do is to
check the cables for loose or broken connections.  If there is no sign
of power, substitute a new power cord after making sure that the power
outlet on the wall is "hot".

If the keyboard is suspected, try it on another terminal of the same
type or substitute a good keyboard.  Wiggle the keyboard cable ends
and the plug.  Wires inside cables may break, especially near their
ends.  If the break is verified by wiggling it (having the problem go
on and off in synchronization with the wiggles), then one may either
get a new cable or cut into the cable and re-solder the breaks, etc.

One of the first things to do if the keyboard works is to put the
terminal into <ref id="local_mode" name="Local Mode">.  If it works OK
in local, then the problem is likely in the connection to the host
computer (or incorrect interface) or in the UART chips of the
terminal.

<sect1> Detective work
<p>By carefully inspecting the circuitry, one may often find the cause
of the problem.  Look for discoloration, cracks, etc.  An intermittent
problem may sometimes be found by tapping on components with a
ball-point pen (not the metal tip of course).  A break in the
conductor of a printed circuit board may sometimes be revealed by
flexing the board.  Solder that looks like it formed a drop or a
solder joint with little solder may need re-soldering.  Soldering may
heat up transistors (and other components) and damage them so use a
heat sink if feasible.  One failure may cause others, so unless you
find the original cause, the failure may reoccur.

If you have a common brand of terminal, you may be able to search the
Internet (including newsgroup postings) to find out what the most
frequent types of problems are for your terminal and perhaps
information on how to fix it.  If you find that a certain component
is bad you may search for this component (for example R214 wyse) and
hopefully find a report by someone else who had the same problem.
Such a report may indicate other components that failed at the same
time.  If a component is damaged so badly that its value can't be
read, then you might find it on the Internet.  The manufacturer may
have on-line data that search engines don't index.

To see if the digital electronics work, try (using a good keyboard)
typing at the bad terminal.   Try to read this typing at a
good terminal (or the console) using the copy command or with a
terminal communication program such as picocom.  You may need to hit
the return key at the terminal in order to send a line.  One may
ask the bad terminal for its identity etc. from another terminal.
This will show if two-way communication works.

<sect1> Error Messages on the Screen
<p> You are in luck if you see an error message on the screen.  This
usually happens when you first turn the terminal on.

<sect2> Keyboard Error
<p> This usually means that the keyboard is not plugged in, or that
the connection is loose.  For more serious problems see <ref
id="keyboards_" name="Keyboards">

<sect2> Checksum Error in NVR
<p> NVR is "Non-Volatile RAM".  This means that the NVR where the
set-up information is stored has become corrupted.  The terminal will
likely still work but the configuration that was last saved when
someone last configured the terminal has likely been lost.  Try
configuring again and then save it.  It might work.  On very old
terminals (early 1980's) there was a battery-powered CMOS to save the
configuration so in this case the problem could be just a dead
battery.  Sometimes the EEPROM chip (no battery needed) goes bad after
too many saves.  It may be hard to find.  If you can't fix it you are
either stuck with the default configuration or you may have escape
sequences sent to the terminal when you start it up to try to
configure it.

<sect1> Capacitors

<p> Electrolytic capacitors have a metal shell and are may become weak
or fail if they set for years without being used.  Sometimes just
leaving the terminal on for a while will help partially restore them.
If you can, exercise any terminals you have in storage by turning them
on for a while every year or so.

Note that cheap electrolytic capacitors designed for use in audio
circuits may fail if used in high frequency horizontal circuitry.  For
this, you need low resistance (low ESR) capacitors.  Replace
non-polarized capacitors (NP) with the same (or with "bi-polar").

If the terminal display takes several minutes of warmup before it's 
OK then it's likely that you have one or more bad electrolytic
capacitors.  One trick to find the bad one is to parallel each
suspected bad one with a good one (of at least the same voltage rating
and capacitance of roughly the same order of magnitude).  If the
display improves a lot when you do this, then you've likely found the
bad capacitor.  Be careful not to get shocked when doing this.  The
actual voltage with respect to ground may be much higher than the
voltage rating of the capacitor.

<sect1> Keyboards <label id="keyboards_">
<sect2> Interchangeability
<p> The keyboards for terminals are not the same as keyboards for
PC's.  The difference is not only in the key layout but in the codes
generated when a key is pressed.  Also, keyboards for various brands
and models of terminals are not always interchangeable with each
other.  Sometimes one get an "incompatible" keyboard to partially work
on a terminal:  All the ASCII keys will work OK, but special keys such
as set-up and break will not work correctly.

<sect2> How They Work
<p> Most keyboards just make a simple contact between two conductors
when you press a key.  Electronics inside a chip in the keyboard
converts this contact closure into a code sent over the keyboard's
external cable.  Instead of having a separate wire (or conductor)
going from each key to the chip, the following scheme is used:
Number the conductors say from 1-10 and A-J.  For example: conductor 3
goes to several keys and conductor B goes to several keys, but only
one key has both conductors 3 and B going to it.  When that key is
pressed, a short circuit is established between 3 and B.  The chip
senses this short and knows what key has been pressed.  Such a scheme
reduces the number of conductors needed (and  reduces the number of
pins needed on the chip).  It's a similar scheme to what is called a
"crossbar switch".

<sect2> Modern vs Old Keyboards
<p> While the modern keyboard and the old fashioned type look about
the same, the mechanics of operation are different.  The old ones have
individual key switches under the key-caps with each switch enclosed
in a hard plastic case.  The modern ones use large flexible plastic
sheets (membrane) the size of the keyboard.  A plastic sheet with
holes in it is sandwiched between two other plastic sheets containing
printed circuits (including contact points).  When you press a key,
the two "printed" sheets are pressed together at a certain point,
closing the contacts printed on the sheets at that point.

<sect2> One Press Types 2 Different Characters <label id="two_chars">
<p> If, due to a defect, conductors 3 and 4 become shorted together
then pressing the 3-B key will also short 4 and B and the chip will
think that both keys 3-B and 4-B have been pressed.  This is likely to
type 2 different characters when all you wanted was one character.

<sect2> Keyboard doesn't work at all
<p> If none of the keys work try another keyboard (if you have one) to
verify that the keyboard is the problem.  One cause is a broken wire
inside the cord (cable) that connects it to the terminal.  The most
likely location of the break is at either end of the cord.  Try
wigging the ends of the cord while tapping on a key to see if it works
intermittently.  If you find a bad spot, you may carefully cut into
the cord with a knife at the bad spot and splice the broken conductor.
Sometimes just a drop of solder will splice it.  Seal up the cord with
electrical tape, glue, or caulk.  A keyboard that has gotten wet may
not work at all until it's dry.

<sect2> Typing b displays bb, etc. (doubled)
<p> If all characters appear double there is likely nothing wrong with
the keyboard.  Instead, your terminal has likely been incorrectly set
up for half-duplex (HDX or local echo=on) and every character you type
is echoed back both from the electronics inside your terminal and from
your host computer.  If the two characters are not the same, there may
be a short circuit inside your keyboard.  See <ref id="two_chars"
name="One Press Types 2 Different Characters">

<sect2> Row upon row of the same character appears
<p> This may happen when auto-repeat is enabled and a key is held
pressed down (or the like).  It may be a key that sticks down when
typed or it could be an electrical short that has the same
effect.

<sect3> Key sticks in down position (individual switches)
<p> First try tapping on it hard several times but it's not likely to
fix it.  Next, your can either remove the keycap (if it is removable)
and squirt a little cleaner on the push rod or work the key up and
down while pushing on it sideways (or both).  If this doesn`t work you
may need to take the switch apart and clean the components.

If you decide to remove the keycap see <ref id="kbd_sw"
name="Keyboards with individual switches">.  Press repeatedly on the
push rod until it works OK and also displays its character on the
screen.  At first, the cleaner may cause the key to fail to display
its character.  Some keys stick due to stickiness on the keycap bottom
surface..  If the key sticks in the fully down position this could be
the problem.  So you might need to clean this area too.

If you decide to push it sideways, use a small screwdriver to push
sideways with while pushing the key up and down with both your finger
and the screwdriver.  You should push it sideways in one of the four
directions and try different directions.  What you are doing by this
is attempting to force out a foreign particles that are rubbing on the
side of the key's push-rod and making it stick.  Again, the problem
may return later.

Always test the key just after fixing it and a short time later.  To test
the key, push it down very slowly and see if it sticks.  Also push it
sideways a little as you're pushing it down.  If you hit it fast or
push it straight down, then you may not observe the stickiness.  This
test will detect a key that seemingly  works OK but is likely to cause
trouble later on.

<sect3> Key electrically shorted
<p>If you suspect that a key is shorted out, fix it by cleaning the
contacts per <ref id="clean_keys" name="Cleaning Keyboard Contacts">.
If this problem happens at the login prompt see <ref
id="key_shorted_getty" name="Key shorted">.

<sect2> Liquid spilled on the keyboard
<p> If water or watery liquid has been spilled on the keyboard (or if
it was exposed to rain, heavy dew, or dampness) some (or all) keys may
not work right.  The dampness may cause a key to short out (like it
was pressed down all the time) and you may see the screen fill up with
that letter if auto-repeat is enabled.  If it's gotten wet and then
partially (or fully) dried out, certain keys may not work due to
deposits on the contact surfaces.  For the modern type of keyboard,
one may readily take apart the plastic sheets inside and dry/clean
them.  For the old type one may let it dry out in the sun or oven (low
temp.).  When it's dry it may still need contact cleaner on some keys
as explained below.

<sect2> Cleaning keyboard contacts  <label id="clean_keys">
<sect3> Keyboards with membranes
<p> On some newer keyboards, the plastic sheets (membranes) are easy
to remove for inspection and cleaning if needed.  You only need to
remove several screws to take apart the keyboard and get to the
sheets.  On some old IBM keyboards the sheets can't be removed without
breaking off many plastic tabs which will need to be repaired with
glue to put back (probably not worthwhile to repair).  Such a keyboard
may sometimes be made to work by flexing, twisting, and/or pounding
the assembly containing the plastic sheets.

<sect3> Keyboards with individual switches <label id="kbd_sw">
<p> What follows is for older keyboards that have separate hard
plastic switches for each key.  Before going to all the work of
cleaning electrical contacts first try turning the keyboard
upside-down and working the bad keys.  This may help dislodge dirt,
especially if you press the key hard and fast to set up vibration.
Pressing the key down and wiggling it from side to side, etc. often
helps.

If this doesn't work, you may try to clean the key switch with a
liquid contact cleaner (available at electronic supply stores) which
usually comes in a spay can.  To get to the switch, you first need to
remove the key-cap (the square that you hit with your finger while
typing).  Warning: Key-caps on modern keyboards can't be removed.
Often, the key-caps may be removed by prying them upward using a small
screwdriver with the tip placed under a key while preventing excessive
tilting of the key with a finger.  There exists a special tool known
as keycap puller but you can get by without it.  The key-cap may tilt
a bit and wobble as it comes loose.  It may even fly up into the air
and onto the floor.

Then you may have two choices on how to clean the contacts: Use
contact cleaner spray directly on top of the key switch, or take the
key switch apart and clean it (the best way if it comes apart easily).
Still another choice is to replace the key switch with a new or used
one but this is often more work (and more cost if you have to go thru
the trouble of finding a replacement.

Directly spraying contact cleaner into the top of the key switch,
without taking the switch apart, is the fastest method but the cleaner
may not reach the contacts it's supposed to clean.  Before spraying,
clean the area around it a little.  With the keyboard live (or with
the key contacts connected to an ohm-meter) use the plastic tube which
came with the spray to squirt cleaner so it will get inside the key
switch.  Try to move the key push rod up and down while spraying.
Don't let the cleaning liquid get under nearby keys where it may pick
up dust and then seep (with the dust) into adjacent key switches.  If
you make this mistake you may fix one key but damage nearby keys.  If
this should happen, immediately work (repeatedly press) the affected
nearby keys until they continue to work OK.

You might tilt the keyboard so that the cleaner flows better into the
contacts.  For the CIT101e terminal with an Alps keyboard, this means
tilting the top row of numeric keys up toward the ceiling.  While
moving the key switch up and down with a pen or small screwdriver
handle avoid getting the toxic cleaner liquid on your skin (or wear
gloves).  You might try turning the keyboard upside-down while working
the key to drain off remaining cleaner.  The more cleaner you squirt
in the more likely it will fix it but it is also more likely to do
more damage to the plastic or contaminate adjacent keys, so use what
you think is just enough to do the job.  Once the key works OK, work
it up and down a little more and test it a half minute later, etc. to
make sure it will still work OK.

Sometimes a key works fine when the contacts inside are saturated with
contact cleaner liquid.  But when the liquid dries a few minutes later
then the resulting scale deposit left from the evaporation of the
cleaning liquid on the contacts, prevents good contact.  Then the key
may work erratically (if at all).  Operating the key when the liquid
is drying inside may help.  Some switches have the contacts nearly
sealed inside so little if any contact cleaner reaches the contacts.
The cleaner that does get to the contacts may carry contamination with
it (cleaning around the tops before spraying helps minimize this).

If you want to disassemble the key switch, first inspect it to see 
if it comes apart (and if so, how).  Sometimes one may remove the cover
of the switch without removing the switch from the keyboard.  To do
this pry up (or pull up) the top of the key switch after prying apart
thin plastic tabs that retain it.  You may be able to use two small
screwdrivers for this and be able to pry up the switch while prying
apart the plastic retaining tabs.  Don't pry too hard or you may break
the plastic.  If this can't be done, you may have to unsolder the
switch and remove it in order to take it apart (or replace it).  Once
the switch has been taken apart you still may not be able to see the
contacts if the contact surfaces are sandwiched together (nearly
touching).  You may put contact cleaner on the contacts by squirting
some cleaner on an edge so it can penetrate onto the contacts.  Insert
a tiny screwdriver blade just a little so as to pry apart the edges as
you apply the cleaner.  This will help the cleaner reach the contacts.
Work the contacts open and closed with a screwdriver to help clean
them and note if the key is working by looking at the terminal screen.  

There may be some kind of clip holding the contact surfaces together
which needs to be removed so you can pry them apart.  Take care not to
loose small parts as they may fly up into the air when taking apart a
key switch.  As a last resort, you may try bending the moving part
that the push-rod pushes so as to make a stronger contact.  In my
terminal, this part looks like the electrical contact but it just
pushes the real electrical contact thru a thin insulator.

When putting the key switch back together, make sure that the spring
is in the right place.  If, after you assemble the switch, the key
pushes down too hard or too easy, the spring is likely not positioned
right.  If the spring is supposed to be recessed into a hole on the
push rod, one way to temporarily "glue" the spring into the push-rod
is to use a half-drop of water on the end of the spring.  Then insert
this end into the push rod and assemble quickly before the water
dries.  This should keep the spring from falling out of the push rod
during assembly.  Instead of using water, you may stand the keyboard on
end (or upside-down) to keep the spring from falling out during
assembly.

<sect> Appendix A: General

<sect1> List of Linux Terminal Commands

<sect2> Sending a command to the terminal
<p><itemize>
<item> <ref id="setterm_" name="setterm">: long options
<item> <ref id="tput" name="tput">: terse options
<item> reset: initializes only
<item> tset: same as reset
<item> clear: clears screen
<item> setterm -reset: sends reset string
</itemize>

<sect2> Configuring the terminal device driver
<p><itemize>
<item> <ref id="set_serial" name="Setserial">:
<item> <ref id="stty_" name="Stty">
</itemize>

<sect2> Terminfo
<p><itemize>
<item> <ref id="tic" name="Terminfo Compiler (tic)"> terminfo compiler
& translator
<item> toe: shows list of terminals for which you have terminfo
files
<item> <ref id="infocmp" name="infocmp" > compares or displays terminfo
entries
</itemize>

<sect2> Other
<p><itemize>
<item> gitkeys: shows what bytes each key sends to the host.
<item> tty: shows what tty port you are connected to.
<item> reset -q: shows the value of TERM, the terminfo entry name
<item> <ref id="reset_" name="reset">: sets TERM interactively and initializes
</itemize>

<sect1> The Internet and Books

<sect2> Terminal Info on the Internet <label id="internet_">
<p> In the first decade of the 20th century,
http://www.cs.utk.edu/~shuford/terminal_index.html was Shuford's Website
at the University of Tennessee.  It was the major sit for information
about text terminals but is now (2013) defunct.  Perhaps one can find it
archived on the "Wayback" machine.
http://www.cs.utk.edu/~shuford/terminal/repair_hints_news.txt was
Shuford's repair archive of newsgroup postings on terminal repair. See
below for the vt100 part of this website which is still on the internet.

<itemize>
<item> <url url="http://www.vt100.net" name= "vt100 section of Shuford's Website"> 
<item> <url url="http://en.wikipedia.org/wiki/Text_terminal"
name="Text-terminal - Wikipedia">
<item> <url
url="http://en.wikipedia.org/wiki/POSIX_terminal_interface"
name="Terminal Interface per Wikipedia"> 
<item> <url url="www.gnu.org/manual/glibc/html_chapter/libc_12.html"
name="Low-Level Terminal Interface"> part of "GNU C Library Reference
Manual" (in libc (or glibc) docs package).  It covers the detailed
meaning of "stty" commands, etc.
<item> <url url="http://www.boundless.com/terminals.html"
name="Boundless"> purchased the VT and Dorio terminal business from
DEC.  Boundless used to have online Specs of their ADDS, VT, and
DORIO terminals but that link (in previous versions of this HOWTO) is
now dead.  
<item> Wyse had detailed info (such as escape sequences) in it's
knowledge base.  It's not as complete as a real manual since it mainly
cover "native" personality.  It was Wyse text-terminals database" at
http://www.wyse.com/service/support/kbase/wyseterm.aspi but it's defunct.
You may still access their knowledge base (does it still cover
text-terminals) by registering.  Start at <url url="www.wyse.com">.
<item> <url url="http://dickey.his.com/ncurses/ncurses.faq.html"
name="ncurses FAQ"> <item> comp.terminals is the newsgroup for
terminals </itemize>

<sect2> Books related to terminals
<p> <itemize>
<item> EIA-232 serial port see <ref id="RS232_books"
name="EIA-232 (RS-232) Books">.
<item> Repair see <ref id="repair_info" name="Repair Books &
Websites">.
<item> Terminfo database see <ref id="termcap_docs"
name="Termcap Documents">
</itemize>

<sect2> Entire books on terminals
<p> As far as I know, there is no satisfactory book on text terminals
Although this HOWTO has been published as a book, I don't suggest that
that you buy it if you have access to the online version which I'm
improving on every few months or so.  The following are mainly of
historical interest:

<itemize>
<item> Handbook of Interactive Computer Terminals by Duane E. Sharp;
Reston Publishing Co. 1977. (mostly obsolete)
<item> Communicating with Display Terminals by Roger K. deBry;
McGraw-Hill 1985.  (mostly on IBM synchronous terminals)
</itemize>

The "HANDBOOK ... " presents brief specifications of over 100 different
models of antique terminals made in the early 1970's by over 60
different companies.  It also explains how they work physically but
has a diagram for a CRT which erroneously shows electrostatic
deflection of the electron beam (p. 36).  Terminals actually used
magnetic deflection (even in the 1970's).  This book explains a number
of advanced technical concepts such as "random scan" and "color
penetration principle".

The "COMMUNICATING ... " book in contrast to the "Handbook ... " ignores
the physical and electronic details of terminals.  It has an entire
chapter explaining binary numbers (which is not needed in a book on
terminals since this information is widely available elsewhere).  It
seems to mostly cover old IBM terminals (mainly the 3270) in block and
synchronous modes of operation.  It's of little use for the commonly
used ANSI terminals used today on Unix-like systems.  Although it does
discuss them a little it doesn't show the various wiring schemes used
to connect them to serial ports.

<sect2> Books with chapters on terminals
<p> These chapters cover almost nothing about the terminals themselves
and their capabilities.  Rather, these chapters are mostly about how
to set up the computer (and its terminal driver) to work with
terminals.  Due to the differences of different Unix-like systems,
much of the information does not apply to Linux.

<itemize>
<item> Unix Power Tools by Jerry Peck et. al.  O'Reilly 1998.
Ch. 5 Setting Up Your Terminal, Ch. 41: Terminal and Serial Line
Settings, Ch. 42: Problems With Terminals
<item> Advanced Programming in the Unix Environment by W. Richard Stevens
Addison-Wesley, 1993.  Ch. 11: Terminal I/O, Ch. 19: Pseudo Terminals
<item> Essential System Administration by Aleen Frisch, 2nd ed.
O'Reilly, 1998.  Ch. 11: Terminals and Modems.
</itemize>

The "UNIX POWER TOOLS" book has 3 short chapters on text terminals.
It covers less ground than this HOWTO but gives more examples to help
you.

The "ADVANCED PROGRAMMING ... " Chapter 11 covers only the device driver
included in the operating system to deal with terminals.  It explains
the parameters one gives to the stty command to configure the
terminal.

The "ESSENTIAL SYSTEM ..." book's chapter has more about terminals
than modems.  It seems well written.

<sect1> Non-Linux OSs <label id="non_linux">
<p>Under Microsoft's DOS one may use the DOS command "ctty COM2" so
that the DOS command line will display on a serial terminal (on COM2
in this example).  Unfortunately one can then no longer
use the computer monitor since MS DOS is not a multiuser operating
system.  Nor can more than one terminal be used.  So this capability
is of little (if any) benefit.  If you emulate DOS under Linux with
the free dosemu, it's reported that you can run several terminals
(multiuser).  But it's reported that PCTerm emulation doesn't work
with it (yet ??).

While MS didn't create a "multiuser DOS" OS, others did.  This permits
the use of many terminals on one DOS PC.  It's compatible with most
MS-DOS software.  One multiuser DOS OS is named "REAL/32".  The
terminal's "pcterm" emulation is used here.  There also may be a
"scan" (scancodes) setup mode which needs to be set.  Other OSs such
as PICK, PC-MOS, and Concurrent DOS were/are multiuser and support
terminals.

There are 3 programs for Linux which let you run Windows applications
on a Linux PC: free: Wine, non-free: VMware and NeTraverse.  Can they
use text-terminals under DOS?  Wine can't since it doesn't have a DOS
mode.  The other two require you to run the MS Windows OS software as
a "guest OS".  The guest MS Windows OS has a DOS mode but it's not of
much use for text-terminals since it's not multiuser.

For other unix-like OSs, the configuration of the host computer for
terminals is usually significantly different than for Linux.  Here are
some links to on-line manuals for non-linux systems.

<itemize>
<item> <url url=
"http://docsrv.sco.com:507/en/HANDBOOK/serial_terminal_adding.html"
name="Adding Serial Terminals"> in SCO OpenServer Handbook.
<item> Hewlett-Packard's HP-UX <url 
 url="http://docs.hp.com/en/B2355-90675/ch03.html" name="Configuring 
 Terminals and Modems">
</itemize>

<sect> Appendix B: Escape Sequence Commands Terminology <label
  id="esc" >

<p> These are sometimes called "control sequences".  This section of
Text-Terminal-HOWTO is incomplete (and may never be complete as there
are such a huge number of control sequences).  This section is for
reference and perhaps really belongs in something that would be called
"Text-Terminal-Programming-HOWTO".

An example of an ANSI standard escape sequence is ESC[5B which moves
the cursor down 5 lines.  ESC is the Escape character.  The parameter
5 is included in the sequence.  If it were 7 the cursor would move
down 7 lines, etc.  A listing for this sequence as "move cursor down x
lines: ESC[xB" is easy to understand.  But command jargon such as:
"tertiary device attribute request" is less comprehensible.  This
section will try to explain some of the more arcane jargon used for
escape sequence commands.  A full listing (including the escape
sequence codes for the ANSI standard) is a "wish list" project.  Since
many escape sequences do the same thing as is done when setting up the
terminal with <ref id="set_up_pars" name="Set-Up Options">, such
escape sequences options will not be repeated here.

<sect1> Esc Sequence Lists <label id="esc_seq_lists">
<p>See url url= "http://www.neoware.com/docs/teemtalk/t2k17pro.pdf"
name="TeemTalk.2000 Programmer's Guide v 1.7"> in pdf format.   But
there are some sites that have info for certain terminals.  For VT
terminals see <url url="http://www.vt100.net/" name="VT Manuals">.
Other lists have disappeared from the internet. 

<sect1> 8-bit Control Codes
<p> Table of 8-bit DEC control codes (in hexadecimal).  Work on VT2xx or
later.  CSI is the most common.
<tscreen><verb>
ACRONYM  FULL_NAME	 		HEX	REPLACES
IND Index (down one line)		84	ESC D
NEL Next Line				85	ESC E
RI  Reverse Index (one line up)		8D	ESC M
SS2 Single Shift 2			8E	ESC N
SS3 Single Shift 3			8F	ESC O
DCS Device Control String		90	ESC P
CSI Control Sequence Introducer)	9B	ESC [
ST  String Terminator			9C	ESC \
</verb></tscreen>

<sect1> Printer Esc <label id="printer_esc">
<p> <itemize>
<item> Auto Print on/off: When on, data from the host is also teed
 (sent) to the printer port of the terminal (and also shows on the
 terminal screen).
<item> Print Controller on/off: When on, data from the host is sent
 only to the printer (nothing shows on the terminal screen).
</itemize>

<sect1> Reports
<p> These sequences are usually a request sent from the host to
request a report from the terminal.  The terminal responds by sending
a report (actually another escape sequence) to the host which has
embedded in it certain values telling the host about the current state
of the terminal.  In some cases a report may be sent to the host even
if it wasn't asked for.  This sometimes happens when set-up is exited.
By default no unsolicited reports should be sent.

<itemize>
<item> Request for Status (Report Operating Status):  Meaning of
replies for VT100 is either "I'm OK" or "I'm not OK"
<item> Request for Device Attributes:  The "device" is usually the
 printer.  Is there a printer?  Is it ready?
<item> Reqest for Tertiary Device Attributes (VT):  Reply is report that
 was entered during set-up.  The tertiary device is the 3rd device
 (the printer or auxiliary port device ??).  The 1st device may
 be the host computer and the 2nd device the terminal.
<item> Request for Terminal Parameters:  What is the parity, baud
 rate, byte width, etc.  This request doesn't seem to make much sense,
 since if the host didn't already know this it couldn't communicate
 with the terminal or send a reply.
</itemize>

<sect1> Cursor Movements
<p> The cursor is where the next character received from the host will
be displayed.  Most of the cursor movements are self-explanatory.
"index cursor" means to move the cursor down one line.  Cursor
movements may be relative to the current position such as "move 4
spaces left" or absolute such as "move to row 3, column 39".  Absolute
is called "Direct Cursor Positioning" or "Direct Cursor Addressing".

The home position is row 1 col. 1 (index origin is 1).  But where this
home position is on the physical screen is not completely clear.  If
"Cursor Origin Mode" = "Relative Origin Mode" is set, then home is at
the top of the scrolling region (not necessarily the top of the
screen) at the left edge of the screen.  If "Absolute Origin Mode" is
set (the same as unsetting any of the two modes in the previous
sentence) then home is at the upper left corner of the screen.  On
some old terminals if "Cursor Origin Mode" is set it means that it's
relative.

<sect1> Pages (definition) <label id="pages_def">
<p> See <ref id="pages_" name="Pages"> for an explanation of pages.
There are a number of escape sequences to deal with pages.  Text may
be copied from one page to another and one may move the cursor from
page to page.  Switching pages may or may not be automatic: when the
screen becomes full (page 1) then more data from the host goes to page
2.  The cursor may only be on one page at a time and characters which
are sent to the terminal go there.  If that page is not being
displayed, new text will be received by the terminal and go into
display memory, but you will not see it (until the terminal is
switched to that page).

<sect> Appendix C: Serial Communications on EIA-232 (RS-232)
  <!-- keep block mode sect. -->
<sect1> Intro to Serial Communication
<p> (Much of this section is now found in Serial-HOWTO.)  Text
terminals on Unix-like systems (and on PC's) are usually connected to
an asynchronous 232 serial port of a computer.  It's usually a
RS-232-C, EIA-232-D, or EIA-232-E.  These three are almost the same
thing.  The original RS prefix became EIA (Electronics Industries
Association) and later EIA/TIA after EIA merged with TIA
(Telecommunications Industries Association).  The EIA-232 spec
provides also for synchronous (sync) communication but the hardware to
support sync is almost always missing on PC's.  The RS designation is
obsolete but is still in use.  EIA will be used in this article.

The serial port is more than just a physical connector on the back of
a computer or terminal.  It includes the associated electronics which
must produce signals conforming to the EIA-232 specification.  The
standard connector has 25 pins, most of which are unused.  An
alternative connector has only 9 pins.  One pin is used to send out
data bytes and another to receive data bytes.  Another pin is a common
signal ground.  The other "useful" pins are used mainly for signalling
purposes with a steady negative voltage meaning "off" and a steady
positive voltage meaning "on".

The UART (Universal Asynchronous Receiver-Transmitter) chip does most
of the work.  Today, the functionality of this chip is usually built
into another chip.

<sect1> Voltages
<sect2> Voltage for a bit
<p> At the EIA-232 serial port, voltages are bipolar (positive or
negative with respect to ground) and should be about 12 volts in
magnitude (newer ones are 5 volts but the 12 volt example is given
here).   For the transmit and receive pins +12 volts is a 0-bit
(sometimes called "space") and -12 volts is a 1-bit (sometimes called
"mark").  This is known as inverted logic since normally a 0-bit is
both false and negative while a one is normally both true and
positive.  Although the receive and transmit pins are inverted logic,
other pins (modem control lines) are normal logic with a positive
voltage being true (or "on" or "asserted") and a negative voltage
being false (or "off" or "negated").  Zero voltage has no meaning
(except it usually means that the PC is powered off).

A range of voltages is allowed.  The specs say the magnitude of a
transmitted signal should be between 5 and 15 volts but must never
exceed 25 V.  Any voltage received under 3 V is undefined (but some
terminals will accept a lower voltage as valid).  One sometimes saw
erroneous claims that the voltage is commonly 5 volts (or even 3
volts) but it's usually 11-12 volts on older PCs.  If you are using a
EIA-422 port on a Mac computer as an EIA-232 (requires a special
cable) or EIA-423 then the voltage will actually be only 5 V.  The
discussion here assumes 12 V.  There was much confusion about voltages
on the Internet.

Note that normal computer logic normally is just a few volts (5 volts
was once the standard) so that if you try to use test equipment
designed for testing 3-5 volt computer logic (TTL) on a 12 volt serial
port, it may damage the test equipment.

<sect2> Voltage sequence for a byte <label id="byte_seq">
<p> The transmit pin (TxD) is held at -12 V (mark) at idle when nothing
is being sent.  To start a byte it jumps to +12 V (space) for the
start bit and remains at +12 V for the duration (period) of the start
bit.  Next comes the low-order bit of the data byte.  If it's a 0-bit
nothing changes and the line remains at +12 V for another bit-period.
Then comes the next bit, etc.  Finally, a parity bit may be sent and
then a -12 V (mark) stop bit.  The line remains at -12 V (idle) until
the next start bit.  Note that there is no return to 0 volts and thus
there is no simple way (except by a synchronizing signal) to tell
where one bit ends and the next one begins for the case where 2
consecutive bits are the same polarity (both zero or both one).

A 2nd stop bit would also be -12 V, just the same as the first stop
bit.  Since there is no signal to mark the boundaries between these
bits, the only effect of the 2nd stop bit is that the line must remain
at -12 V idle twice as long.  The receiver has no way of detecting the
difference between a 2nd stop bit and a longer idle time between
bytes.  Thus communications works OK if one end uses one stop bit and
the other end uses 2 stop bits, but using only one stop bit is
obviously faster.  In rare cases 1 1/2 stop bits are used.  This means
that the line is kept at -12 V for 1 1/2 time periods (like a stop bit
50% wider than normal).

<sect1> Parity Explained <label id="parity_def">
<p> Characters are normally transmitted with either 7 or 8 bits (of
data).  An additional parity bit may (or may not) be appended to this
resulting in a byte length of 7, 8 or 9 bits.  Some terminal emulators
and older terminals do not allow 9 bits.  Some prohibit 9 bits if 2
stop bits are used (since this would make the total number of bits too
large: 12 bits total).

The parity may be set to odd, even or none (mark and space parity may
be options on some terminals).  With odd parity, the parity bit is
selected so that the number of 1-bits in a byte, including the parity
bit, is odd.  If a such a byte gets corrupted by a bit being flipped,
the result is an illegal byte of even parity.  This error will be
detected and if it's an incoming byte to the terminal an
error-character symbol will appear on the screen.  Even parity works
in a similar manner with all legal bytes (including the parity bit)
having an even number of 1-bits.  During set-up, the number of bits
per character usually means only the number of data bits per byte (7
for true ASCII and 8 for various ISO character sets).

A "mark" is a 1-bit (or logic 1) and a "space" is a 0-bit (or logic
0).  For mark parity, the parity bit is always a one-bit.  For space
parity it's always a zero-bit.  Mark or space parity only wastes
bandwidth and should be avoided when feasible.  "No parity" means that no
parity bit is added.   For terminals that don't permit 9 bit bytes,
"no parity" must be selected when using 8 bit character sets since
there is no room for a parity bit.

<sect1> Forming a Byte (Framing)
<p> In serial transmission of bytes via EIA-232 ports, the low-order
bit is always sent first.  Serial ports on PC's use asynchronous
communication where there is a start bit and a stop bit to mark the
beginning and end of a byte.  This is called framing and the framed
byte is sometimes called a frame.  As a result a total of 9, 10, or 11
bits are sent per byte with 10 being the most common.   8-N-1 means 8
data bits, No parity, 1 stop bit.  This adds up to 10 bits total when
one counts the start bit.  One stop bit is almost universally used.
At 110 bits/sec (and sometimes at 300 bits/sec) 2 stop bits were once
used but today the 2nd stop bit is used only in very unusual
situations (or by mistake since it seemingly still works OK that way).

<sect1> Limitations of EIA-232
<sect2> Low Speed & Short Distance
<p> The conventional EIA-232 serial port is inherently low speed and
is severely limited in distance.  Ads often read "high speed" but it
can only work at high speed over very short distances such as to a
modem located right next to the computer.  All of the wires use a
common ground return so that twisted-pair technology (needed for high
speeds) can't be used without additional hardware.  However some
computers have more modern interfaces.  See <ref id="non_232"
name="Successors to EIA-232">.

It is somewhat tragic that the RS-232 standard from 1969 did not use
twisted pair technology which could operate about a hundred times
faster.  Twisted pairs have been used in telephone cables since the
late 1800's.  In 1888 (over 110 years ago) the "Cable Conference"
reported its support of twisted-pair (for telephone systems) and
pointed out its advantages.  But over 80 years after this approval by
the "Cable Conference", RS-232 failed to utilize it.   Since RS-232
was originally designed for connecting a terminal to a low speed modem
located nearby, the need for high speed and longer distance
transmission was apparently not recognized.

<sect2> Successors to EIA-232 <label id="non_232">
<p> See the Serial-HOWTO section "Other Serial Devices" for a longer
discussion about non-EIA-232 ports.  A number of EIA standards have
been established for higher speeds and longer distances using
twisted-pair (balanced) technology.  Balanced transmission can
sometimes be a hundred times faster than unbalanced EIA-232.  For a
given speed, the distance (maximum cable length) may be many times
longer with twisted pair.  Few terminals seem to support them.  While
many terminals also support EIA-423 is almost like EIA-232 but is
only 5 volts and somewhat higher speeds (without using twisted pair).
Twisted pair includes EIA-422, EIA-530-A, HSSI (High Speed Serial
Interface), USB (Universal Serial Bus), and of course ethernet.

<sect2> Line Drivers
<p> For a text terminal, the EIA-232 speeds are fast enough but the
usable cable length is often too short.  Balanced technology could
fix this.  The common method of obtaining balanced communication with
a text terminal is to install 2@ line drivers in the serial line to
convert unbalanced to balanced (and conversely).  They are a
specialty item and are expensive if purchased new.

<sect1> Synchronization & Synchronous <label id="sync">
<sect2> How "Asynchronous" is Synchronized

<p> Per EIA-232 there are only two states of the transmit (or receive)
wire: mark (-12 V) or space (+12 V).  There is no state of 0 V.  Thus
a sequence of 1-bits is transmitted by just a steady -12 V with no
markers of any kind between bits.  For the receiver to detect
individual bits it must always have a clock signal which is in
synchronization with the transmitter clock.  Such clocks generate a
"tick" in synchronization with each transmitted (or received) bit.

For asynchronous transmission, synchronization is achieved by framing
each byte with a start bit and a stop bit (done by hardware).  The
receiver listens on the line for a start bit and when it detects one
it starts its clock ticking.  It uses this clock tick to time the
reading of the next 7, 8 or 9 bits.  (It actually is a little more
complex than this since several samples of a bit are often taken and
this requires additional timing ticks.)  Then the stop bit is read, the
clock stops and the receiver waits for the next start bit.  Thus async
is actually synchronized during the reception of a single byte but
there is no synchronization between one byte and the next byte.

<sect2> Defining Asynchronous vs Synchronous

<p> Asynchronous (async) means "not synchronous".  In practice, an
async signal is what the async serial port sends and receives which is
a stream of bytes each delimited by a start and stop bit.  Synchronous
(sync) is most everything else.  But this doesn't explain the basic
concepts.

In theory, synchronous means that bytes are sent out at a constant
rate one after another in step with a clock signal tick.  There is
often a separate wire or channel for sending the clock signal.
Asynchronous bytes may be sent out erratically with various time
intervals between bytes (like someone typing characters at a
keyboard).

There are borderline situations that need to be classified as either
sync or async.  The async serial port often sends out bytes in a
steady stream which would make this a synchronous case but since they
still have the start/stop bits (which makes it possible to send them
out erratically) its called async.  Another case is where data
bytes (without any start-stop bits) are put into packets with possible
erratic spacing between one packet and the next.  This is called sync
since the bytes within each packet must be transmitted synchronously.

<sect2> Synchronous Communication
<p> Did you ever wonder what all the unused pins are for on a 25-pin
connector for the serial port?  Most of them are for use in
synchronous communication which is seldom implemented on PC's.  There
are pins for sync timing signals as well as for a sync reverse
channel.  The EIA-232 spec provides for both sync and async but PC's
use a UART (Universal Asynchronous Receiver/Transmitter) chip such as
a 16450, 16550A, or 16650 and can't deal with sync.  For sync one
needs a USART chip or the equivalent where the "S" stands for
Synchronous.  Since sync is a niche market, a sync serial port is
likely to be quite expensive.

Besides the sync part of the EIA-232, there are various other EIA
synchronous standards.  For EIA-232, 3 pins of the connector are
reserved for clock (or timing) signals.  Sometimes it's a modem's task
to generate some timing signals making it impossible to use
synchronous communications without a synchronous modem (or without a
device called a "synchronous modem eliminator" which provides the
timing signals).

Although few serial ports are sync, synchronous communication
does often take place over telephone lines using modems which use
V.42 error correction.  This strips off the start/stop bits and puts
the date bytes in packets resulting in synchronous operation over the
phone line.

<sect1> Block Mode <label id="block">

<sect2> Introduction to Block Mode
<p> Block mode is seldom used with Linux and is mainly of historical
interest.  In block mode, when one types at a terminal the results are
saved in the terminal memory and are not sent just yet to the host
computer.  Such terminals often have built-in editing capabilities.
When the user presses certain keys (such as the send key) what has
been saved in the terminal memory is sent to the host computer.  Now
the Linux editors vi and emacs, must react instantly to typing certain
keys so block mode isn't feasible.  Such editors and other interactive
programs can't permit the long delay in sending a keystroke to the
computer which is inherent in block mode.  So they can't use block
mode.

The old IBM mainframe interface uses block mode (see <ref id="ibm_"
name="IBM Terminals "> so many IBM terminals are block-mode only and
also synchronous (see Section <ref id="sync" name="Synchronization &
Synchronous">).

<sect2> Types of Block Modes, Forms
<p> Block mode may itself have various sub-modes such as "page" (a
page at a time) and "line" (a line at a time).  Some terminals have
both block transmission modes and conventional character modes and may
be switched from one mode to another.  Async terminals which have
block modes include HP2622A, Wyse60, VT130, VT131, VT330, VT340, and
Visual500.  Many later model terminals can emulate block mode.  But
the Linux console can't.  Block modes may include a forms capability
where the host computer sends a form to the terminal.  Then the user
fills it out and hits the send key which sends only the data in the
form back to the host computer.  The form itself (not the data) is
displayed on the screen in protected fields which don't get
transmitted to the host.

<sect2> Efficiency
<p> Block mode takes load off the host computer, especially if the
host computer's hardware is designed for block modes (as IBM
mainframes were).  In character mode every character typed is sent
immediately to the serial port and usually causes an interrupt at the
host computer.  The host that receives the byte must stop whatever it
is doing and fetch that character from the port hardware.  Even with
UART's that have FIFO hardware buffers, the hardware timeout is
normally only the transmission time of 3 bytes so that an interrupt is
usually issued for every character typed.

In true block mode a long block of characters is received using only
one interrupt.  If block mode is used with conventional async FIFO
serial ports, an interrupt is needed only every 14 bytes since they
have 16-byte hardware buffers.  Thus much of the load and overhead of
interrupt handling is eliminated and the computer has more time to do
other tasks when block mode is used.

A significant savings for block mode occurs if the terminal is
connected to its host via a network.  Without block mode, every
character (byte) typed is sent in its own packet including all the
overhead bytes (40 in a TCP/IP packet as used on the Internet).  With
block mode, a large number of characters are sent in a single packet.

<sect2> Problems with block mode
<p>While block mode is more efficient, it is nearly extinct, and for
good reason.  Faster and cheaper computers made the higher efficiency
less important.  For example, a 56k modem results in hundreds of
interrupts per second (every 14 characters) while typing at a terminal
only causes a few interrupts per second (one for each character
typed).  So the number of interrupts caused by typing at a terminal
is not very significant (unless you have hundred of terminals
connected to the same computer).

Another point is that the efficiency is not of much significance where
the user doesn't type in very much.  Editors are a primary example of
where the user types in a lot.   But if you use block mode for
editing, you must then use the crude editor built into terminal.  Modern
editors like vim and emacs are much better but can't use block mode.
Even in the days of mainframes with terminals, block mode wasn't used
much except by IBM.  A major reason was that software to utilize it
was not widely available (except for IBM).  The terminfo data base
doesn't seem to include it and this would complicate writing software
for it.

<sect1> EIA-232 (RS-232) Books <label id="RS232_books">
<p> (Note: The first book covers much more than just EIA-232.)
<itemize>
<item> Black, Uyless D.: Physical Layer Interfaces & Protocols, IEEE
	Computer Society Press, Los Alamitos, CA, 1996.
<item> Campbell, Joe: The RS-232 Solution, 2nd ed., Sybex, 1982.
<item> Putnam, Byron W.: RS-232 Simplified, Prentice Hall, 1987.
<item> Seyer, Martin D.: RS-232 Made Easy, 2nd ed., Prentice Hall,
	1991.
</itemize>

<sect1> Serial Software
<p> See <url url="ftp://ibiblio.org/pub/Linux/system/serial/"
name="Serial Software"> for Linux software for the serial ports
including getty and port monitors.

<sect> Appendix D: Notes by Brand/Model

<p> Here are notes by brand name that were too specific to a certain
terminal to be put elsewhere in this HOWTO.  If you have some info to
contribute on a certain terminal that is not covered elsewhere, it
could go here.  Various models often have much in common so such
common information need only be written about once.  It would be
nice if for each terminal model, there were a set of links linking to
most of the documentation relevant to that model (including escape
codes).  But it hasn't been done.  Note that some VT (DEC) manuals are
now available on the Internet.  See and <ref id="dec_" name="VT
(DEC)">.  Wyse put the information from its manuals on the
Internet but it can't be readily found now (2013).  

<sect1> Adds
<p>The Adds terminal menu incorrectly used "Xon/Xoff" to mean any kind
of flow control.  True for which models ??

Adds, which made the Adds Viewpoint terminal, was taken over by
Boundless Technologies in 1994 but they continued to use the "Adds"
name.

<sect1> CIT
<p> CIT terminals were made in Japan in the 1980's for CIE Terminals.
They ceased to be imported in the late 1980's.  The company, CIE,
still made CItoh printers (in 1997) but has no parts for its
abandoned terminals.  Ernie at (714) 453-9555 in Irvine CA sold (in
1997) some parts for models 224, 326, etc. but has nothing for the 80
and 101.

To save the Set-Up parameters press ^S when in Set-Up mode.
cit80: Contrast: knob on rear of terminal,
cit101e: Brightness: use up/down arrow keys in Set-Up mode.

<sect1> IBM Terminals <label id="ibm_">

<p> Don't confuse IBM terminals with IBM PC monitors.  Many IBM
terminals don't use ASCII but instead use an 8-bit EBCDIC code.  It's
claimed that in EBCDIC the bit order of transmission is reversed from
normal with the high-order bit going first.  The IBM mainframe
communication standards are a type of synchronous communication in
block mode (sends large packets of characters).  Two standards are
"BISYNC" and "SNA" (which includes networking standards).  Many of
their terminals connect with coax cable (RG62A/U) and naive persons
may think the "BNC" connecter on the terminal is for ethernet (but
it's not).

While this IBM system is actually  more efficient than what is
normally used in Linux, terminals meeting this IBM standard will not
currently work with Linux.  However, some IBM terminals are
asynchronous ASCII terminals and should work with Linux on PC's.  The
numbers 31xx may work with the exception that 317x and 319x are not
ASCII terminals.  Before getting an IBM terminal, make sure there is a
termcap (terminfo) for it.  If their isn't, it likely will not work
with Linux.  Even if there is a terminfo, it may not work.  For
example, there is a termcap for 327x but the 3270 is an EBCDIC
synchronous terminal.

The 3270 series includes the 3278 (late 1970's), 3279 with color and
graphics, and the 3274 terminal controller (something like the 3174).
They may be used for both BISYNC and SNA.  The 3290 has a split screen
(splits into quarters).

The synchronous IBM terminals don't connect directly to the IBM
mainframe, but connect to a "terminal controller" (sometimes called
"cluster controller" or "communication controller").  Some of these
controllers can convert a synchronous signal to asynchronous so that in
this case a synchronous terminal could indirectly connect to a
Unix-like host computer via its serial port.  But there is still a
major problem and that is block transmission.  See section <ref
id="block" name="Block Mode">.

<sect2> IBM 3153
<p> It's claimed that the Aux port is DCE and uses a straight-thru
cable.

<sect1> Teletypes <label id="teletype">
<p> These are antiques and represent the oldest terminals.  They are
like remotely controlled typewriters but are large and noisy.  Made by
the Teletype Corp., the first models were made in the 1920's and
predate the computer by over 30 years.  Early models used
electro-mechanical relays and rotating distributors instead of
electronics.  Their Baudot code was only 5-bits per character as
compared to 7-bit ASCII.  See the book "Small Computer Systems
Handbook" by Sol Libes, Hayden Books, 1978: pp. 138-141 ("Teletypes").

<sect1> VT (originally DEC, now Boundless) <label id="dec_">
<p> Digital Equipment Corporation (DEC) made the famous VT series of
terminals including the commonly emulated VT100.  

In 1995 DEC sold their terminal business to Boundless Technologies.
Boundless went bankrupt in 2003 but emerged from bankruptcy in 2006 as
a division of "Visual Technologies".  Then in 2008 they were acquired
by Video Display Corporation and given to their Z-AXIS subsidiary
located near Rochester, New York.  The <url
url="http://www.boundless.com/terminals.html" name="Boundless"> name
and url have been retained.

Detailed VT terminal information, some manuals, and
history is at <url url="http://www.vt100.net/">.

VT220: Some have a BNC connector for video output (not for input).
Sometimes people erroneously think this is for an ethernet connection.

VT510, 520, 525: Supports full DTR/DSR flow control.  Some are "low
emissions" models. The 520 is multi-session and the 525 has colors for
highlighting.

Dorio is a lower quality model which can emulate many other terminals.
The "sco unix console" is claimed to be a powerful emulation using the
"scoansi" terminfo.

<sect1> Links
<p> The terminal maker Links was taken over by Wyse.

<sect1> Qume
<p> Qume was taken over by Wyse in the early 1990s.

<sect1> Wyse Terminals <label id="wyse_">
<p> detailed manual-like information on old terminals see <url
url="http://www.wyse.com/service/support/kbase/wyseterm.asp">.  This
information includes specs, lists of escape sequences, part lists,
FAQs, setup info, etc.   Thanks to Wyse for providing this even though
as of 2006 they are no longer making text terminals.

Wyse terminals were lower in cost than other brands and they captured
a major share of the market.  There were concerns about the quality of
these terminals, especially the Wyse 50.  But the large number of
failure reports (other than Wyse 50) may be due in part to the large
number of Wyse terminals in use.

See <url url="en.wikipedia.org/wiki/Dell_Wyse"> for a history of Wyse.

<sect2> Wyse 50
<p>Reported not to last very long.

<sect2> Wyse 60
<p> Display adjustments (must remove cover): Brightness VR202, Height
VR302, Width VR101 (also affects height).  If you want to use it in
Native Personality, then the arrow-key codes will conflict with the
codes used in vi (such as ^L).  To fix this set "Application key mode"
with ESC &tilde; 3.  This results in the arrow keys sending 0xd0 - 0xd3.
Due to a bug in the readline interface of the Bash shell, you need to
edit /etc/inputrc so that the arrow keys will work in Bash.  See <ref
id="bash_bug" name="Bugs in Bash">

<sect2> Wyse 85
<p> Can emulate VT52/VT100/VT200.  Press F3 for setup.  After moving
left/right to go a menu "icon", press space to select it.  Scroll
thru setup menus with up/down keys.  Press F3 at any time to reenter
setup (without loosing any settings).

<sect2> Wyse 99-GT
<p> Here is the setup Menus of the Wyse99GT (late 1980's).  Note that
TERM means "termination" (character) and not "terminal".

<tscreen><verb>  WYSE 99-GT Terminal Set-Up as used at the University of CA, Irvine

		by David Lawyer, April 1990

			F1 DISP:
COLUMNS=80		LINES=24		CELL SIZE=10 X 13
STATUS LINE=STANDARD	BACKGROUND=DARK		SCROLL SPEED=JUMP
SCREEN SAVER=OFF	CURSOR=BLINK BLOCK	DISPLAY CURSOR=ON
ATTRIBUTE=CHAR		END OF LINE WRAP=ON	AUTO SCROLL=ON
----------------------------------------------------------------------------
			F2  GENERAL:
PERSONALITY=VT 100	ENHANCE=ON		FONT LOAD=OFF
COMM MODE=FULL DUPLEX	RCVD CR=CR		SEND ACK=ON
RESTORE TABS=ON		ANSWERBACK MODE=OFF	ANSWERBACK CONCEAL=OFF
WIDTH CHANGE CLEAR=OFF	MONITOR=OFF		TEST=OFF
----------------------------------------------------------------------------
			F3 KEYBRD:
KEYCLICK=OFF		KEYLOCK=CAPS		KEY REPEAT=ON
RETURN=CR		ENTER=CR		FUNCT KEY=HOLD
XMT LIMIT=NONE		FKEY XMT LIMIT=NONE	BREAK=170MS
LANGUAGE=US		MARGIN BELL=OFF		PRINTER RCV=OFF
----------------------------------------------------------------------------
			F4 COMM:
DATA/PRINTER=AUX/MODEM	  MDM RCV BAUD RATE=9600  MDM XMT BAUD RATE=9600
MDM DATA/STOP BITS=8/1	  MDM RCV HNDSHAKE=NONE	  MDM XMT HNDSHAKE=NONE
MDM PARITY=NONE		  AUX BAUD RATE=9600	  AUX DATA/STOP BITS=8/1
AUX RCV HNDSHAKE=NONE	  AUX XMT HNDSHAKE=NONE	  AUX PARITY=NONE
(There is a main port (Modem=MDM) and an Auxiliary Port (AUX)
----------------------------------------------------------------------------
			F5 MISC 1:
WARNING BELL=ON		FKEY LOCK=OFF		FEATURE LOCK=ON
KEYPAD=NUMERIC		DEL=DEL/CAN		XFER TERM=EOS
CURSOR KEYS=NORMAL	MARGIN CTRL=0		DEL FOR LOW Y=ON
GIN TERM=CR		CHAR MODE=MULTINATIONAL
----------------------------------------------------------------------------
			F6 MISC 2:
LOCAL=OFF		SEND=ALL		PRINT=NATIONAL
PORT=EIA DATA		SEND AREA=SCREEN	PRINT AREA=SCREEN
DISCONNECT=60 MSEC	SEND TERM=NONE		PRINT TERM=NONE
PRINT MODE=NORMAL	VT100 ID=VT100		POUND=US
----------------------------------------------------------------------------
F7 TABS: You should see several "T" characters spaced 8 dots apart.
    If you don't, hit backspace.
F8 F/KEYS: Normally you will see no definitions for the Function Keys
    here (unless someone has set them up and saved them).  This means that
    they will normally generate their default settings (not displayed here).
    <ctrl><F5> shows the "user defined definition" of the F5 key, etc.
F9 A/BACK: Normally not defined: ANSWERBACK =
F10 EXIT: Selecting "DEFAULT ALL" will make the factory default settings
    the default.
</verb></tscreen>

HINTS on use of WY-99GT User's Guide:
Note that much that is missing from this Guide may be found in the
WY-99GT Programmer's Guide.  The VT100 emulation (personality) is
known as ANSI and uses ANSI key codes per p. A-10+ even though the
keyboard may be ASCII.  A sub-heading on p. A-13 "ASCII Keyboard" also
pertains to VT100 because it has an "ANSI KEY ..." super-heading a few
pages previously.  But not all ASCII keyboard headings pertain to
VT100 since they may fall under a non-ANSI personality super-heading
which may found be a few pages previously.  Appendix H is the "ANSI
Command Guide" except for the VT52 (ANSI) personality which is found
in Appendix G.

<sect2> Wyse 150
<p> When exiting set-up using F12, hitting space changes "no" to "yes"
to save the set-up.  The sentence to the left of this no/yes is about
"vertical alignment" and has nothing to do with this no/yes for saving
the set-up (confusing menu design).

<sect2> Wyse 185
<p>Has 10x20 character cells.  Can emulate DEC VT320.  Uses 45 watts power.
Later models were 185e.

<sect2> Low Emissions: -ES
<p>ES after the model number means low emissions: low magnetic field,
etc.

END OF Text-Terminal-HOWTO
</article>
