690 13128 001_Xenix_Dev_Sys_Prog_Ref_Guide_Jan1983 001 Xenix Dev Sys Prog Ref Guide Jan1983

User Manual: 690-13128-001_Xenix_Dev_Sys_Prog_Ref_Guide_Jan1983

Open the PDF directly: View PDF .
Page Count: 320

Download
Open PDF In Browser	View PDF

I,

.

COMPUTER SYSTEMS

ALTOS
586
Computer System
XENIX Development
System
Programmer's
Reference Guide

(

Part Number: 690-13128-001

January 1983

Altos is a registered trademark of Altos Computer
Systems.
XENIX is a trademark of Microsoft, Incorporated and
is a l6-bi t mi cr ocomputer impl ementa tion of the
UNIX operating system, version 7.
UNIX is a trademark of Bell Laboratories
UNET is a trademark of 3Com Corporation

The information contained herein is subject to change
without notice. Changes will be incorporated in new
editions of the document as they are published.

Copyright (e) 1913.

All right. re.erved.

Altos Co.pater By.te ••

ALTOS 586 COMPUTER SYSTEM

XERIX PROGRAMMER' S REFERERCH GUIDE

TABLE OF CORTER'rS

1.

IRTRODU CT ION

USING THIS MANUAL
1-1
Purpose/Scope
1-1
Organization
1-1
OTHER DOCUMENTATION AVAILABLE
1-4
Altos 586 Operator's Guide
1-4
Altos Introduction to Xenix Manual
1-4
Altos Business Solution
1-4
Bell Laboratories Manuals
1-4
Unix Programmer's Manual
1-4
Unix Reference Card
1-5
Commercially Available Books
1-6
2.

INSTALLIBG XERIX DEVELOPMERT SYSTEM

3.

UTILITY PROGRAMS REFUERCH GUIDE

USEFUL UTILITIES
3-1
UNIX MANUAL CHANGES AND ADDITIONS
BSH(l)
3-6
CSH (1)
3-1121
DIGEST(l)
3-28
EDIT(l)
3-3121
EX(l)
3-33
FCOPY(l)
3-36
FORMAT (1)
3-37
FSCK(l)
3-38
LAYOUT (1)
3-41
LS(l)
3-43
MAIL(l)
3-47
MAP (1)
3-53
MULTIUSER (1)
3-54
PRINTENV(l)
3-55
PS(l)
3-56
RESET(l)
3-59
SIZEFS(l)
3-6121
TAR(l)
3-61
UA(l)
3-64
VI(l)
3-68
LOCKING(2)
3-69
RDCHK (2)
3-71
CURSES(3)
3-72
MENUS (5)
3-74
TERMCAP (5)
3-79
TTYTYPE(5)
3-87

i

2-1

3-3

AL'l'OS 586 COIlPUTER SYSTEM

B.

UNIX PROGRAMMER' S REFERENCE GUIDE

8886 ASSEMBLY LAICOAGE REFERENCE MANUAL

XENIX Software Development Extract from Microsoft Manual
I.

'tUTORIAL AND REFERENCE MATERIAL
(UNIVERSI'l'Y OF CALIFORNIA, BERKELEY MARUALS)

An Introduction to the C Shell
An Introduction to Display Editing with Vi
Quick Reference for Ex,Vi
Ex Reference Manual
Edit: A Tutorial
Ex/Edit Command Summary (Version 2.0)
Mail Reference Manual
-ME Reference Manual
Screen Updating and Cursor Movement Organization
Screen Updating and Cursor Movement Organization:
Package

iii

A Library

ALms 586 COIlPOTER SYSTEM

Appendix B:

UNIX PROGRAJUIER' S REFERENCE GUIDE

Floppy Diskette Organization

A brief reference describing how files are allocated
on floppy diskettes.
Appendix C.

The Serial Line Printer and Spooler

Information regarding the serial line printer and
spooler, such as hardware connections required,
configuring your system wi thout a printer, connecting
more than one printer, and changing/setting band rates.
Appendix D.

List of Terminal Capabilities

A data base listing special capabilities of all
terminals supported by Altos XENIX.
Appendix E.

Numeric Formats, C, and Fortran 77

Reference information on the internal format used
for numerical representation in these languages.
Appendix F.

Sample List of XENIX utilities

A sample list of utilities furnished with your
system.
Appendix G.

Copying files from the Altos 8600 to the
Altos 586 under the XENIX operating
system.

A description on how to transfer files from an Altos
8600 to an Altos 586 computer system under the XENIX
operating system, or between two 586 computer
systems. It discusses the uucp (UNIX-to-UNIX copy)
Facility.
Appendix H.

8086 Assembly Language

A description of the XENIX 8086 Assembly Language.
Appendix I. Tutorial and Reference Material
(University of California, Berkeley Manuals)
Documentation describing UNIX modifications
developed at the University of California,
Berkeley. The material is supplied from the
Regents of the University.

1-2

ALTOS 586 COIlPOTBR SYSTBII

Appendix B:

URIX PROGRAIUIBR' S RBFBRBRCB GOIDB

Floppy Diskette Organization

A brief reference describing how files are allocated
on floppy diskettes.
Appendix C.

The Serial Line Printer and Spooler

Information regarding the serial line printer and
spooler, such as hardware connections required,
configuring your system without a printer, connecting
more than one printer, and changing/setting band rates.
Appendix D.

List of Terminal Capabilities

A da ta base listing special capabil i ti es of all
terminals supported by Altos XENIX.
Appendix E.

Numeric Formats, C, and Fortran 77

Reference information on the internal format used
for numerical representation in these languages.
Appendix F.

Sample List of XENIX utilities

A sample list of utilities furnished with your
system.
Appendix G.

Copying files from the Altos 8600 to the
Altos 586 under the XENIX operating
system.

A description on how to transfer files from an Altos
8600 to an Altos 586 computer system under the XENIX
operating system, or between two 586 computer
systems. It discusses the uucp (UNIX-to-UNIX copy)
Facil i ty.
Appendix H.

8086 Assembly Language

A description of the XENIX 8086 Assembly Language.
Appendix I. Tutorial and Reference Material
(University of California, Berkeley Manuals)
Documentation describing UNIX modifications
developed at the University of California,
Berkeley. The material is supplied from the
Regents of the University.

1-2

ALms 586 COIlPOTER SYSTEM

XERIX PJlOGRAJIUIER' S RBFBRBRCE GOlDE

information on Unix programming (C language).
Volume 2B contains additional reference mater ial, and
includes advanced topics and languages. For example,
this volume includes information or supporting tools
and languages such as~, which is a tool for writing
compilers for other languages.
It also includes
information on system implementation and maintenance.
ORIX Reference card

A 36 page concise reference booklet, loosely bound in
order to lie flat.
It contains information on UNIX
commands, documentation preparation, and C language
functions.
Co. .ercially Available Books

There are numerous commercially available books on UNIX that
explain it and give tutorial material. Two such books are:
A User Guide to the UNIX System, by Thomas and Yates
Using the ORIX System, by Richard Gauthier

Two useful programming books related to UNIX are:
~e C Programming Language, by Kernighan and Ritchie.
This book describes the C programming language, which is the
language that the UNIX operating system is written in.
It
provides tutorials as well as a reference section.

Software Tools, by Kernighan and Plauger.
This books is a guide to good programming techniques and a source
of proven, useful programs written in RatFor (Rational Fortan).
The C language, which is designed for UNIX, provided the model
for Rat For. Many of the tools described in this book are based
on UNIX model s.

1-4

ALTOS 586 COIlPOTBR SYSTEM

UNIX PROGRAIUlBR' S RBFBRBHCE GUIDE

information on Unix programming (C language).
Volume 2B contains additional reference mater ial, and
includes advanced topics and languages. For example,
this volume includes information or supporting tools
and languages such as~, which is a tool for writing
compilers for other languages.
It also includes
information on system implementation and maintenance.
UNIX Reference card

A 36 page concise reference booklet, loosely bound in
order to lie flat.
It contains information on UNIX
commands, documentation preparation, and C language
functions.
Co.mercially Available Books

There are numerous commercially available books on UNIX that
explain it and give tutorial material. Two such books are:
A User Guide to the UNIX System, by Thomas and Yates
Using the UNIX System, by Richard Gauthier

Two useful programming books related to UNIX are:
~e C Programming Language, by Kernighan and Ritchie.
This book describes the C programming language, which is the
language that the UNIX operating system is written in.
It
provides tutorials as well as a reference section.

Software Tools, by Kernighan and Plauger.
This books is a guide to good programming techniques and a source
of proven, useful programs written in Rat For (Rational Fortan).
The C language, which is designed for UNIX, provided the model
for Rat For. Many of the tools described in this book are based
on UNIX models.

1-4

ALms 586 COMPUTER SYSTEM

UNIX PROGR.AMIIER' S REFERENCE GUIDB
Section 2

IRSTALLIBG UNIX DEVELOPMENT SYSTBM

To install the Xenix Development System on your Altos 586
Computer System, you should:
1.

Install the Xenix Run-Time System by following the instructions in the Altos Introduction to Xeniz Manoal.
Do not
shut the system down.
If you interrupt the installation procedure for some reason,
or your system was shut down by a power failure or system
crash, see the Resuming Interrupted Installation section in
the Altos Introduction to XENIX Manual.

2.

Make sure you are logged as super-user (root).

3.

Enter
cd

/



This command causes the system to go to the top directory
(or parent directory) of the XENIX system.
4.

Insert the diskette labeled nXenix Utilities #2 of n,n where
nn n is the total number of utili ty diskettes.
Enter
tar xv



This command causes the directories and files on the utility
diskette to be loaded onto the XENIX system. For information on the ~~~ utility, see the section SAVING AND
RESTORING FILES in the Altos Introduction to XBNIX Manual or
under the entries for Tar(l}, DD(2}, Dump (I) and Restore
(I) in the UNIX Programmer's Manual.
5.

Repeat step 4 for each utility diskette.

6.

When you have loaded all of the utility diskettes, enter
install

7.



To load the C compiler onto the XENIX system, you should:
Insert the diskette labeled nC Compiler. n
Enter
tar xv



Enter
2-1

ALTOS 586 COMPUTER SYSTEM

UNIX PROGRAMMER' S REFERENCE GUIDE

install
You have just loaded the C Compiler.
8.

If you wish to load the UNIX Fortran compiler, you should:
Insert the diskette labeled "F77."
Enter
cd /tap 
Enter
install 
You have just loaded the UNIX Fortran compiler.

9.

If the prior steps were successful,
System is correctly installed.

your XENIX Development

If you purchased Altos communication network services, refer
to the Altos 586 UNET User Guide for information on how to
install the communication network services.
If you purchased the ASS package or other Altos application
packages, refer to the Altos XENIX Application Software User
Guide for information on how to install the ABS-586 Menu
Shell and application programs.
If you wish to start a XENIX up, see the "Start-Up XENIX"
section of the Altos Introduction to XENIX Manual. If the
system has not been shutdown, skip steps 2 and 3.
If you don't plan on using your XENIX system at this time,
you can shut the system down by entering:
# etc/haltsys 

** Normal System Shutdown **

2-2

ALTOS 586 COMPUTER SYSTEM

XDIX PROGRAIIIIER' S REFERENCE GUIDE

Section 3
UTILITY PROGRAMS REFERENCE GUIDE
USEFUL UTILITIES

Table 3-1 lists some useful utilities that are supplied
with the Altos implementation of XENIX. This list is not intended to be complete, but merely a summary of those utilities you
will find useful in getting started with XENIX.
A complete
listing and description for all utilities may be found in the
UNIX Programmer's Manual, Volume 1.
You may list the full set of utilities supplied with any
particular release of XENIX by displaying the contents of the
/bin, /usr/bin, and /etc directories.
Appendix F contains a
sample list of utilities.
The Altos implementation of XENIX provides some utilities
which differ from standard UNIX, and also some new utilities from
various sources. This section documents the changed and new
utilities, as "UNIX Manual Changes and Additions." The material
supplied in this section may be kept in this supplement or
inserted in the UNIX Programmer's Manual, as desired.
In the follow ing pages, "UNIX Manual Changes and Addi tions,"
many useful utilities are documented. See Table 3-2 for a quick
reference to these utilities. Note in particular: format, fcopy,
multiuser, and ~, and the new version of~.
The Business
Shell, ~, has two accompanying utilities, menus and digest.
See also the APPENDIX I for reference and tutorial material
on the University of California, Berkeley utilities, such as the
screen editior ~.

3-1

ALTOS 586 COKPOTER SYSTEII

Table 3-1

XBBIX PROGRAIUIER' S REFERENCE GUIDE

A List of Useful Utilities for Getting Started

UTILITY

DESCRIPTION

ar

Object library manager and archiver

as

XENIX 8086 relocatable assembler

cat

Display a file

cc

"C" compil er

cd

Change directory. Changes your current position
in the File System hierarchy.

chmod

Change mode. Changes file protection attributes

chown

Change file ownership

cmp

Compare two files

cp

Copy a file

diff

Display the differences between two files

ed

The standard UNIX editor

ld

XENIX linkage editor

Is

List. Displays the contents of the current directory

mkdir

Make a new directory

mv

Move. Renames files and directories

od

Displays an octal dump of a file

ps

Display system status

pwd

Print working directory.
Displays current
position in the directory hierarchy

rm

Remove.

rmdir

Delete a directory

stty

Set terminal options, such as baud rate

tar

File system archiver.
dumps and restores

Deletes a file

3-2

May be used for file system

AL'l'OS 586 COIlPU-nR SYSTEM

XBRIX PROGRAIUIER' S REPERENCE GUIDE

UNIX IIAlItJAL CllAlGES ARD ADDITIORS

The material in this section may remain in this supplement
or be inserted in Sections 1 through 5 of Volume 1 of the UNIX
Prograamer's Kanual, as you wish. If you insert these documents
into the manual, place them in the sections corresponding to the
number in parentheses after the utility name. (Entries within
sections are in alphabetic order.)
Some of the utilities are enhancements or variations of
existing Bell Laboratories UNIX utilities. Others are completely
new.
The origin of each utility is specified (in abbreviated
form) in column 2 of Table 3-2.
Utilities labelled "(altos)" are provided by Altos Computer
Systems.
Utilities labelled "(bell)" were developed by Bell
Laboratories after their current manual was published.
Utilities labelled "(msoft)" were developed by Microsoft, Inc.
Utilities labelled "(uofcb)" were developed at the
University of California, Berkeley. They are supplied under
license from the Regents of the University.
Table 3-2.

List of UNIX Kanual Changes and Additions

UTILITY

SOURCE

bsh (1)

(al tos)

Business Shell.
A menu-driven
user
system with special guidance and
convenience features. It enables you to
access the more commonly used UNIX
utilities via menus.

csh

(uofcb)

A shell (command interpreter) with Clike syntax.

digest (1)

(altos)

Create menu systems for the Business
Shell.

edi t

(uofcb)

Text editor (variant of the ex editor
for new or casual users).

ex (1)

(uof cb)

Text editor.

fcopy (1)

(al tos)

Copy a floppy diskette, while in XENIX.

(1)

(1)

DESCRIPTION

3-3

ALTOS 586 COIlPOTER SYSTEM

UNIX PROGRAMMER' S REFERENCE

GUIDE

Table 3-2.

List of UNIX Kanual Changes and Additions (cont.)

UTILITY

SOURCE

format (1)

(altos)

Format a floppy diskette,
XENIX.

fsck (1)

(bell)

File system consistency check and interactive r epai r.

layout (1)

(altos)

Configure a hard disk.

Is (1)

(uofcb)

List contents of directory

(uof cb)

Send and receive mail.
(The U.C.B.
"Mail" utility goes in front of, and
makes use of, the Bell Labs "mail" utility. The names of the two utilities are
distinguished by whether the first letter is capitalized or lower case.)

map (1)

(altos)

Create an alternate sector map for a
hard di sk dr i vee

multiuser(l)

(altos)

Bring the system up multiuser.

pr intenv (1)

(uofcb)

Print out the environment.

ps (1)

(uof cb)

Processor status.

reset(l)

(uofcb)

Reset the terminal
predef ined sta tee

sizefs (1)

(al tos)

Determine the size of a logical device
from the layout informa tion associated
with a hard disk.

tar (1)

(bell)

Tape or floppy archiver.
restores hard disk files.

ua(l)

(altos)

User administration. Adds and deletes
user accounts on the system.

vi (1)

(uofcb)

Screen oriented (visual) display editor.

locking(2)

(msof t)

Lock or unlock a record of a file.

rdchk (2)

(msoft)

Check if there is data to be read.

Mail

(1)

DESCRIPTION

3-4

status

while in

bits

Dumps

to a

and

ALTOS 586 COIlPOTBR SYSTEM

XERIX PllOGR.AMIIBR· S REFERENCE GUIDE

Table 3.2

List of UNIX Manual Changes and Additions (Cont.)

UTILITY

SOURCE

cur ses (3)

(uofcb)

Screen functions with "optional" cursor
motion.
(Has window capability.)

men us (5)

(altos)

Develop menus for Business Shell.

termcap (5)

(uofcb)

Data base which defines cursor-control
sequences for most commonly used CRTs.
It is used by most "screen oriented"
software, such as the Altos shell and
visual screen editor, xi.

ttytype (5)

(altos)

Data base for defining terminal type
associated with each 586 serial port.

DESCRIPTION

3-5

BSB(l)

NAME

UNIX (BSB Version 1.')

8SB(1)

bsh -- Altos Computer Systems Business Shell

SYNOPSIS
~

[

-~

] [ menusystem ]

DESCRIPTION
.aah is a menu-dr i ven command language interpr eter. It may
be installed as the "login shell" in the password file, or
it may be invoked directly by the user.
The command is implemented using the termcap and curses
facilities from UC Berkeley. It must be run from a terminal
which is defined within /etc/termcap.
This command should only be run interactively. A user's
terminal may be left in a very strange state if ~ is run
in the background.
In the options described below, either
"return" performs the newline function.

"line feed" or

Options

-L

Start ~ in "fast" mode. In this mode, a prompt whose
first letter is a lower-case alphabetic or numeric
character is executed immediately when the first letter
is typed. The system does not wait for a terminating
newline. Prompts
whose first letter is upper-case
alphabetic wait for a terminating newline before
executing the requested actions.
Fast mode is the
default initial mode, if not over-ridden by the command
line or the BSHINIT variable (see below). The current
mode may be changed during execution through use of the
"?mode" command (described below).

-h

displays a short help message describing how to invoke
.bRll.

-z.

displays a one-line descriptive summary of the syntax
used to invoke ~.

-~

Start ~ in "slow" mode. In this mode, all prompts
must be terminated by newline before execution occurs.
The current mode may be changed during execution
through use of the -?mode" command (described below).

A menu system may be specified if desired. In this case,
utilizes the designated menu system instead of the
defaul tone (jetc/menusys.bin). Prior to use by .bRh a menu
system must be "digested" using the digest(l) utility. If
the specified menu system does not exist or if it is not
read-accessible, ~ issues an error message and terminates.

~

BSB(l)

UNIX (BSB Version 1.1)

BSB(l)

How to create a new menu system and how to update or modify
an existing menu system is described in menus(S).
Commands
prompts
Typing any of the prompts on the current menu screen
immediately causes the actions associated with the
prompt to be executed. It is the responsibility of the
menu designer to ensure that reasonable actions exist
for each prompt. Selecting a prompt with no associated
action causes an error message to be displayed.
An

action may be anyone of the following:

> Go to a specified menu
> Execute a sh(l) script
> Execute a bsh internal command
(e.

g. chdir (1) )

menuname
Typing the name of a menu causes it to immediately
become the current menu.
If the menuname is
misspelled, or if it does not exist in the current menu
system, an error message is displayed.
newline
Typing a newline causes the immediately preceding menu
to become the current one. If there is no previous
menu, an error message is displayed. ~ does not distinguish between Rline feed R and Rreturn R -- both
generate a newline.
?

Typing a question mark (?) causes the RhelpR menu
associated with the current menu to be displayed. Help
menus are no different from normal menus (except,
perhaps, in the type of information they contain).
When the current menu is named RxyzR, typing a question
mark is entirely equivalent to typing ·xyz?"

??

Typing a pair of question marks (??) causes the ~
system help information to be displayed. It contains
much the same information as is presented here.

menuname?
Typing the name of a menu followed by question mark
causes the designated help menu to become the current
one.
manual page??
Typing the name of an entry in the Unix manual followed
by two question marks causes the designated manual page
to be displayed. Thus, to see the entry for ~ one

ORIX (BSH Version 1.1)

8SH(1)

may type "bsh??"
typing "lman bsh."

BSH(l)

This is precisely equivalent to

1command
The exclamation point (1) allows the user to "escape"
to the standard shell (sh(l». The command must follow
the usual rules as described in the shell documentation. In particular, the command may consist of a
sequence of shell commands separated by semicolons -thus several actions may be invoked. If the command is
absent, shell is invoked as a sub-shell with no arguments. In this case, ~ will be resumed as soon as
the sub-shell terminates. (Usually, this is accomp1 i shed by sending the sub- shell an end-of-f il e.
Endof-file is Control-d on most terminals.)
You may
escape to the Berkeley C shell (csh(l»
by typing
"lcsh."
?index
This special command causes ~ to display its internal
"index" for the current menu system.
The index
contains the names of every accessible menu.
?mode
This special command allows the user to change from
"slow" mode to "fast" mode and vice versa. The user is
asked if he wishes to change to the alternate mode. If
your response begins with "y" or "Y", the change is
made, otherwise the current mode remains in effect.
interrupt

will immediately return to the top-level command
interpreter upon receipt of an interrupt signal. Such
a signal is usually generated via the DEL, RUBOUT or
BREAK key.

li.Q.b

backspace

understands the Backspace function (as obtained
from /etc/termcap).

li.Q.b

CANcel
.a.ab interprets the CANcel key to mean "restart input."
The CANcel key is Control-x on many of the more popular
terminals.
ESCape
Typing an ESCape has the same effect as does typing
CANcel.
DC2

If the screen becomes "dirty" for some reason, you can
force bRh to clear it and redisplay the current
contents by transmitting an ASCII "DC2." This is
Control-r on most of the currently popular terminals.

q

Typing a "q", "0· or ·Ouit" all have the same effect:
3-8

BS8(1)

UNIX (BS8 Version 1.')

BS8(1)

Ub. is terminated. If Ub. is your login shell, "quit"
also results in your being logged out.
Environment
BSHINIT
The BSHINIT environment variable contains the initial
value of the default mode ("fast" or "slow"). If this
variable does not exist in the environment, ~ assumes
"fast" mode. BSHINIT should be set by inserting the
line BSHINIT="fast" or BSHINIT="slow" into your
.prof ile file.
Note that even if bRb is designated as the "login
shell" in /etc/passwd, your .profile file will be
interpreted correctly. (See login(l) and sh(l).) In
particular, any overriding definitions you may have for
the kill and erase characters will be correctly interpreted by .b.Qb.
FILES

-/.profile
/etc/menusys.bin
/etc/passwd
/etc/termcap
/usr/lib/bsh.messages

contains commands to be executed
during login(l)
default menu system used by bsh
used to define a user's login name,
password, horne directory, shell,
etc.
contains terminal attribute descriptions
system warning and error messages

SEE ALSO

digest(IM), login(l), menus(5), sh(l), termcap(5)
DIAGNOSTICS
The diagnostics produced by
explanatory.

~

are intended to be self-

BUGS
probably should never allow itself to be run in the
background.

~

BRb should detect the fact that the current terminal is not
defined in /etc/termcap and abort gracefully.

3-9

CSH(l )

CSH (1)

cm - a shell (command int.arpretar) With C-llke syntax
SYlfePSlS

nh ( -eef1nst.,VzX] [ arl .•. ]
DESClUP'l'ICK

Osh 11 a command la~uaie interpret.er. It belW by execut1nC commands from
the me •.cshM:' ill the Mf7U cUreclory of the invoker, It t.h.t3 11 a 10&11'1 shell then
It also executes commands trom the me ·.login' there, In the normal case. the
shell Will then begin readq commancb trom the terminal. prompt.!ni With "~ "
Process1n& ot ar.uments and the use of tha .hell to process mls contai.nlll.i
command scripts will bl described lataI'.
Tba· shell then repeat.edly performs the tolloW1ni actions: a Une of command
input 18 read and broken int.o UIOnLs. This .equence ot words is placed on the
command hist.ory list and then parsed., Finally each command in the current.
Une 11 Ixecuted.
'
nen a 10l1n Ihell terminat.e.it Ixecutls commands from the me ·.lOl0ut· in the
use" Qoc:.e cUrect.cry.
Lezlcal 8t.:uctmw
The .hell IpUta input Une. 1Dt.c word. at blanks and tabs W'1th the tollo'tt'ini
8xcept.1ons. The charact.e" 'ac'
.<' '>' '(' ')' form .eparat.e words. If lioubled. 1D ·ac.·. ·t I'. '« or '»' these pain form line!e words. These parser cetacharact.ers may be mada part. ot other words, or prevent.ad their 'Pecial meanmal by prececi1na tham wtt.b. ·V. A. new111'1e preceded. by a 'V 1. equiftlent to a
blank.
.
In add.1UoJ:l .tr1n&1 enclosed 1D matchec! pain of quotaUoas, .... , .... or '-1 form
paru ot a word.: met.acharact.e" in these strings. 1DclucUnc blanks and tabs. do
Dot torm leparate words. These quot.aUoc.s have .emanUcs t.o be described sub.equently. Wit.hi:1 pairs ot •• or .- characters a DewUne preceded by a '" gives a
true n8,,111'1e character.
nen the sheU's input 11 Dot a terminal. the character ." introduces & comment
wbic!1 continues t.o the end of the input Une. It. 111 prevented Ws speci4l mee.n.i.l:.i
-heD preceded by'" and in quotaltom usmc .W . . . . . and. '-.

'r ';'

~mman&U

A limple :ommand 11 a sequence ot word.s, the ~st of which spec~es the command to be .xecuteet. A simple comm&1'1d or a sequence of simple comcancis
..paratad by characters torms a pipeline. The ~uti'ut of .ach command in a
pipeUna 111 connected ~ the 1Dput of the next. 'Sequence. of pipeUnes may be
Nparatad by';'. aDd are then executed .equenUaUy. A .equence of pipelines
may be .xecuted Without waitinl ~or 1t to terminate by toUowinC 1t WiCl an . k',
Such a .equance 18 aui.omaUcally prevent.ed from beq terminated by & Qalliup
lienal; the ftOhup command need not be used..
/my of the above may be placac! in '{' .). to torm a s1mple comc&1'1cl (wmcn cay
be a compone%1t of a pipel1ne, etc.) It. 11 &.lso possible t.o separate pipelines Wit!l
'11' or 'ac&' Lndlcat1n&. as 1D the C laZliuaiel that. the .econd 1II'to be executeci
cm1y 11 the &-st tails or .ucce.ds respectively. (See Ezpf-UNft.s.)

'r

~bst1tuUcma

1/11/81
3-l0

1

CSH (l)

CSH (1)

We now describe the vuious transformations the .hell performs on the input in
the order in which they occur.
History subsUtutiol18
Hutory substitutions can be useci to reintrociuce sequences of word3 trom preVl~us comma..tlcis. possibly performing woci~cations on these word3. Thus !:Ustory
Nbstitutions proVide a &eneral.izauon of a " @ tunction.
History substitutions be,in With the character '!' and may begin anywhere ill the
input stream it a history substitution is not alrfJady in prt)gress. This '!' may be
preceded by an '\' to prevent 1t.3 special mean.iJli: a '!' is passed unch.anged.
when it is rollowed by a blank. tab. newline. '=' or '('. Hutory substitutions also
occur when an input line beiins With 'f'. This Ipecial abbreViation will be
described later.
Azly 1nput Une which contains history substitUtion 13 echoed 00 the ter:mc.al
betor. 1t is executed as it. cowd tave been typed Without history substitution.
Commands input tram the t.arminal which conaist of one or mo" wortis are
savel:! on the history Ust. the lize of which is controlled by the h:i:Jtary variable.
The previous command ia always reta.i.c.ed. Commands are numbered .equent1ally trom 1.
For dewten.ss. conaider t.ha tolloW'il1& output trom the history command:
9 write michael
10 ex write.c
11 cat oldwrtta.c
12 cW! -wnta.c
The commands are Ihcwu wtt.h their eveot numben. It ia not usually necessary
to usa ..... nt numben. but the current event. number can be mad.e part ot the
prompt by placill& an '!" in the prompt "~~.
'1fith the c~nt. event 13 we can refer to previOUS events by event number '!l1',
relatively as 11:1 '!-2" (re!err.na to t.he same event). by a predx of a comc"cd
woMi U in '!d' tor event 12 or '!'" tor event 9, or by a rtri%ll containeci in a word
in the command as in '!1mic?" also reterrin& to ..... nt 9. These torms. wtt.hout
. turther mo~catioD. limply reintroduce the words of the Ipec~ed eventa. each
separated by a s1n&le blank. As a special cue 'II" reters to the preVious command: thus '!!' alooe 1a essentially a redo. The torm "I" reterences the C1J1""1~nt
command (the one bein& typed in). It allow, a word to be selected !rom further
lett in the Une. to avoid retypill.i a loCi l:Wlle, u in '!1:1'.
To select words tram an "ent we can foUoW' the eftol fl)ec~cs.tion by a ':' and a
desi&!1Ator tor the desired words. The words of a input Une are numbered ~om
O. the ~t (usually command) word beiC& O. the second word (4rst ari~ent)
betna 1, etc. The basic word desi&!1Aton an:
o
ant (command) word
"
,,'th ar&ument
f
Orst ariument. Le. '1'
I
last ariument
_
~
woMi mat.ched by (immedialaly ?recec:i1nc) 7.? .earch··
:r-y ~,e of worda
-V
abbreviates 'O-Y'
•
abbreViates'
or l1ot.hi%:l.& it only 1. word in rrent.
••
abbre91&tas ':r-I"

'-I"

I

1/18/81

3-11

2

CSH(1)

CSE (!)

aUke '~.' but omit.tin& word'S'
The ":' .eparaUni the event speci~cation t%'1)m the word desianater can be omitt..ed if the argument selector beiins With a ',' 'S', ' .. '-' or ':;'. Att.er the optional
word desianator can be placed a sectuence 01 modi~ers. lach preceded by II. ':'.
The tollOWina modi~erl are de~ed.:
h '. .
Remove a t.raillna patbname component. leaVini the head.
I'
Remove a tra.ilil:1& '.:ax' component. leaV'1n& t.he root name.
s/' /.,. I
Substit.ute I tor .,.
t.
Remove allieadina patbname componenu. leaVina the tail.
Ie
Repeat the preVious substitution.
I
Apply the chanie ilobaUy, predxina the above. e·i, 'i.!t',
p
Print the new command but do not Ixecute it.
q
Quote t.he substit.uted word.s. prevenUni further substit.utions.
x
Like q, but. break int.o word.s at. blanks, tabs and newlines.
Unless preceded by a ',' the mod~cation 15 appUed only to the tlrst mo~ble
word.. In 1ZJ.1 case 11. 1.1 an error tor na word t.o be appUcable.
The lett hand lide of lubstitutions are nat. re,ular expressions in the lense of
the editors. but rat.her It.rin&S. Ar1y charact.er may be used as the delimit.er in
place at '/';
quot.es the delimit.er into the land,. It.rin&S. The character '&'
in the ri&ht. hand lide 1s replaced by t.he text. from the lett.. A'" ctuotes '&' also.
A nullC uses the preVious st.rin& either trom a I or trom a contextual scan Itri1:1g
• in '!?s "!'. The trailln& delimit.er in the substitution may be omitted. if a newline
folloW's immecUat.ely as may the trllilln& '" in a cont.extual ICan.
A history reterence may be linn without an Ivent. Ipec~cation. •. i. '!S'. In this
case the reterence 1.1 to the preVious command \U1less a previous history rete~
ence occurred on the lame line in which case this form repeats the previous
reterence. Thus '!?foo?'t !S' lives the tlrst. md last &ra'lCenU from the command matcl::W:1& '?foo"!'.
A Jl)ecial abbreviation 01 a hist.ory reterence occurs when the tlrst nen-blank
character of IZJ. input. line is a"'. This 15 lquivalent. to '!:s,' providin& a convenient shorthand for substit.utions on the text. ot the preViOUS Une. Thus
"lb1'lib' ~es the speUini at "Ub' in the previous commlZJ.d. F1nally, a history
IUbstitution may be surrounded wtth 't' mel 'I' if necessary t.o insulat.e it. trom
the characters whi.:-:h folloy. Thus, atter "ts -ld -paw' we mi&ht do '!U~a.' to clo
'ts -ld. -paula.' , while 'lla' would look for a comma.nr1 sta.rt1ni 'la'.
QuotaUoa. with • md. •
The quotat.ion of ItrinlS by ,.e and ,- can be uaeel to prevent. all or lome ot the
rema.illinl substitutions. StJ1n&s enclo.eel in ,.. an prevent.ed any further
interpret.ation. St.rin&s Inclo.ed. 1Zl ,- are yet n.riable and. command Ixpanded
as describeel below.
In both case. the nsult1n.l text becomes (all 01' part of) a siD.lie word: only in
one speCial ca.e (lee CommAnd Substililioft. b.loW') doe. a ,- quoled Itrlni lle!d
parU ot more than ODe wor~: ,. quot..d Itrinis never do.
AU•• IUbsUtuUQIl
The shell maint.ains a ll.It. at aliase. winch can be estabUshed. displayed and
mod~ed by U1e ~it:.r and. un.alia.. command•. Atter a command Une is Ica.cne:i.
1t. t. j)&rSed int.o distinct commands and. the ~st word at each command. lett-t.orilht. is checkeel to .e. if it. hu an all... If 1t. 40e.. then the text. wilic!l i. tJ:le
I

a'"

1/18/81
3-ld.

CSE(:)

lJNlX ?rcgrammer's Manual

CSH(:)

alias tor that command i.s reread With tbe history mechanism available as
though that command. were the preVious input line. The ruulting words repiace
the command and ariument list. It no reference 13 mad.e to the history ~t.
then the argument list ls lett unchanged..
Thus it tbe alias tor 'ts' 13 'Is -1' the command 'ts lusr' would map t.o ·ts -1 Ius:,,'.
the argument tist bere being ~ndistur!:)ed. Similarly l! the alias tor 'lookup' was
',rep !, /ete/passwd' then '!OO!Np bill' would map to 'iTsP bill letc/puswc1·.
·It an allas is tound. the word. transtormation of the input. text. is performed and
the aliasill& process begins again on the reformed input line. Looping is
prevented it tbe dnt word of tbe new text is the same as the old. by ~aUing It. t.o
prev~nt further aliasing. Other loops are detect.ed and cause an errer.
Note tbat the mechanism llIows aliases to introduce parser metasyntu. Thus
we can 'alias print 'pr \1- Ilpr'" to make a command whichp""s iU uguments to
th, u.ne printer.
Variable subsUtutioll
The sheU maintaiIW a .et of Variables. each of which has as value a list of zere or
more words. Some of these ftl1ables are .et by the shell or referred to by it.
For instance. the tI2'V'J 98riable is an image at the sheU's ugument. list. and
words ot this vaMabLe', value are referred to 1n special ways.
The values of Variables may be displayea ana chanaea by using the ut and U1l.Tat
commands. or the 98riables reterred to by the shell a number are toggles: the
sheU does not can what their value is. only whether they are .et or not. For
instance. the \/wbos . . .riable t. a t.oggle which causes command input to be
echoed.. The settlni of this variable results tram the ... command Une option.
C+..her operations treat. 'Yariablll numerically. The '0' ~ommand permit.!
numeric calc~ations to be performed and the result assigned to a va.nable.
VariabLe values are. however, always "presented as (zero or more) st.rln.gs. For
the purposes ot numeric operations. the null .trilli 1s conSidered t.o be zero. and
the lecond and lubsequent WOrdl at mulUword values are linored.
AA~ar the input 11ne t. aliased and parsed. and betore each command is executed. variable substitUtion 13 performed keyed by 'S' characters. Tl::Us expanlion can be prevented by precedilli the'S' With a '\' except. within ..... wb.er. it
alw.y. occun. aDd wtt.h.in .... where 1t. l1e".r occurs. Slrill&S quoted by·... are
tntef1lreted later (lee Q)m.m4M $"Ubstitu.ti.tm below) .0 'S- lubstitution does not
occur there until later. II at all. A 'S' t. passed unch&llied i! toUowed by a blank.
tab. or end~t-!ina.
Input/output redirections are reco,lli:ed betore variable expansion. and ue
variable expanded separately. Otherwise. the command name and entire ariument list are expanded to,.ther. It Is thus poslible tor the ~ (command.)
word to this point. to ,enerata more than one WOM!. the drst of which becomes
the command l:1ame. and t.ha rest of wbich become arguments.
Onless enclosed In .- or pen the ":'1' mo~r the result.. of variable substitution may eventually be command and menama subsUt.uted. 1rith1n·- a 98riable
whose ?alue consists of multiple words expands t.o a (portion at) a liJ:I.ile word.
With the words ot Ule 98riables value separated by blanks. When the '::tt' modit:.er
11 ap~!1ed to a substitution the variable wtll expand to multiple wortis wtth eacb.
word .e;>arated by a blank and quoted to prevent latar command or 11lencme
IUbst1tuuon.

1/18/81
3-l~

CSH(1 )

CSH (1)

The followtni metaseq,ulncn ue proVided for introduc~ variable v&lues into
thlr shell input. Except as noted. it. is an error to reference a variable whlc!l lS
net let..
Iname
Ilnamei
Are replaced by the words of the value of Variable fta.m.a. each sepuated by
a blank. Braces insulat.. nama trom folloWilli characten which woula otherwise be part of it.. Sbell varia.bles havI cames consisting of up to 20
letters, diiitS. and und,rlcores.
Il n.tmU Is not a shell variable, but is set 1n the .n~nment. then that value is
returned (but: moclitlers and the other forms .iven below ue not available in
this case).
Iname( selectDr]
Itname (selector] I
liay be used to .elect ocl.y lome of the words tr'tIm the value of ncm.8. The
.elector 11 subjectad tD 'S' lubstitution and may consist of a sillile number
or two cumbers separated by a '-'. The drst word of a variables value is
numbered '1'. Il the drst number ot a r&1l.i1 is omitted it aefaults tD '1'. l!
the last member ot a raJlil 11 omitted it. default5 to ·Slname'. The selecter
' ... elecU all words. It is IlOt an error for a Z"az:l.i8 t.o be empty if the second
argument is emitted or in rallie.
Iiname
Itlnamei
Give. the cumber of word. in. the variable. This 1. u.seful for later use in. Ii
'(.electDr]' .

so

SubstItutes the lWDe of the me from which commanc! input is being raad.
An error occurs if the :!.ame 11 not. known.

Inumber
Ilnumberi
Eq,uivalent t.o 'Iarrtnumber),.
Eq,uiValent to 'Sarr{·]'.
The moditlen ':h', ':t', ':r', ':q' and ':r may be applied to the substitutions above
u may ':,ll', ':gt' and ':&1"'. If braces T T appear in the ccc.:nand form then
the moditlen must appear Within the braces. The CUlT1tDt lmplementatioD
allows oaly one ':' mocw'er em each ',. npanmcm.
Tha follow1n& substitut1oD.l may not. be mod~ed With ':' mo~n.
I?name
I(?namei
Substitute. the .trmc '1' if name is I.t.. '0' if it 11 not.
Sublrtitut•• '1' if the current input dleoame 1Ilclaw. '0' if 1t 1JI net.
IS

Substitute the (decimal) pr'1)cess cumber ot the (parent) shell.
~mmand and mename .ubsUtuUaa.

1/18/81
3-1~

CSH(l)

UNIX Programmer's Ma.nual

CSH (1)

The rema.ulllli substitutions. command and tnename substitution. are applied
lelectively t.o the ariument.! of builtin commands. This means that portions ot
eJq)ressions Which are not. evaluated are not subjected to these expansions. For
commands which are not 1.nt.ernal t.o the shell. t.he command came is substltuted
'separately from the argument. tist. This occurs very late. atter iJlput.-OU~?~t
,redirection is performed. and 1.n a child of the mam sb.ell.
'Command SUbstitution
Command substitution 18 indicated by a command enclosed 1:1 ..... The output
from such a command is normally broken into separate words at blanks. tAbs
and newlines, with null words being discarded. this t.ext then replaciIli the or",lnal st.rilli. Wit.hin ...... oaly newl.1.nes force new words: blanks and tabs are
preserved.
In any case. the siIlile ~al newline does not toree a new word. Note that it is
thus possible tor a command substitution to yield oaly part of a word. even it the
command outputs a complete Una.
nIename substit.ution
If a word contains any of the characters .... '1'. T or T or begins With the character '-', then that. word 13 a candidate for dlename substitution. also mown as
·,lobbilll·. This word. is then regarded as a pattern. an.d. replaced With an alp:abetical!y sorted. list ot ale names which match the pattern. In a Ust of words
specifY'ini aIename substitUtion it is an error for no pattern l:) match an eXistq dle name, but it 1s not. required for each pattern to match. Only t.l::I.e meucharacters 'e', '" an.cl ,(, imply pattern matcl:.ina, the characters '-' and T
beilli :nore akin to abbre11ations.
In matc!m1i aIenames, the character ': at the begiening of a aIename or
immeeliately followin.& a •I'. as well as the character' I' must be :natched explicitly. The character 'e' matches any It.rin.& of characters, includ.1.n.i the null
It.r'illi. '!'he char3.cter '1' matches any ,qle character. The sequence ,[ ... ],
matches anyone of the characters enclosed. Within '[ ... ]'. a pair ot characters
separated by '-' matches any character lexically between the two.
The character ..... at the bea1nefn, of a mename is used to M!fer to home directones. Stand.1ni alona. Le. •...' it expands to th. invokers home directory as
retieetad in. the value ot the Variable hom... When i~llowed. by a name consistilli
ot letters, d.1g1ts and '-' characters the shell learch~s tor a user with that name
and. substitutes their home directcrr. thus '-ken' aught expand. to •lusr Iken'
and '-ken/cbmach' to '/usr/ken/cbmach'. If the character '-' is tollowed by &
character other than a leu..r or' I" or appian not at the be,;nnini of a word. it
t. lett undisturbed.
Th. metanotation '~b,c.d.fe' 1a a shorthand tor 'abe ace ade'. Left to ri&ht order
La preserved, With results of matches beq lorted separately at a low level to
preserre
this
order.
This
construct
may
be
nested.
Thus
'~uree/sl/toldls,ls(.c'
expands
to
'/usrlsouree/sl/01dls.c
lusr/source/sl/la.c' whether or DOt these mes exist Without any chane\! ot
error if tha hom. directory for ',ouree' t. ' lusr Isouree'.: Similariy
' .. /tmemo. ebox(" miCht expand. to •.. /memo ..Ibox ..Imbox'. (Note that ':naco'
was not sorted With the results of matcllillg 'ebox'.) .u a special cue T, T and
'B' are passed undinurbed.

1/18/81
3-15

e

CSH(1 )

UNlX Proirammer' s Manual

CSH (1)

Input/output.
The standan! input and Itandar1'i output of a command may b. redinctad Wit.!:.
the toll Qwil:l& syntax:

 name
>f name
llame

>.

>.'DAme

The tne ft4m. is used as standard output. If the dle does l10t eXist then it i.
created: if the tne exiSts. it.. is truncated. it. preVious cont.ents beirli lost.
If the variable ftOcLabb..,. is set. then the tne must not. exist or be a character special tne (e.i. a terminal or ·/de..,/null') or an error resulu. TIlls
helps pre..,ent accidental destruction of tnes. In this CU8 the '!' forms can
be used. and. suppress un. check.
The torms invol?lni •k' route the diainostic output into the specifted me as
."ell as the standard output. Na.tf'IA is expanded in the same way as <' input
tnenames are.
» name
».llame
»fname
».!name
•
Uses me name as standar.! output Uke '>' bu.t. places output at the end. of
the me. If the variable nDclabbw 1.1 nt. then it is an error tor the me IlOt. to
eX1lt. unlesl one of the '!' torma 1.1 ,1..,.n. Otherwise s1mi1ar to '>'.
If a command ia run detached (foUowed by 'Ie') then the default. standard 1llput
lor the command. 1.1 the empt.y tne '/de..,/null". Otherwise the command recei..,es
the enVirocment. in which the theU was in..,oked u modiAed by the input-output
parameters and the presence of the command in a pipeUne. Thus. unlike some
preViOUS the~. commands run from a me ot sheU commancis b.&ve 110 aceess to
the text. ot the commands by default.; rather they receive the oriiir1al stanciard
1D;>u.t. ot the Ihell. The' <<' meehamsm should be used to present. 1nllne ciata..
This permits shell command scripts to function as component. ot j)ipelines ana
allows the Ihell to block r.ad it. input.
.
Diagnostic; output may be directed t.hrouah a pipe With the Itanda.rd output..
Simply use the form 'Ilk' rather t.!1an Just 'r·
0

1/18/81
~-l(,

7

CSH(l)

UNIX Programmer's Manual

CSH (l)

Expressions
A number ot the outltin commands (to oe descrioed subsequenUy) take expnslions, in which the operators are similar to those ot C, With the same precedence. These expressioDS appear in the 0, .:it, i/, and whi.J.a commands. The
tollowilli operators are available:
HI"

·11 "at I ,. " == != <= >= < > « » + - • / ~ ! - ( )
the precedence increases to the right, '==' and '!=', '<=' '>=' '<'

Uld ':>',
'~ beinl, 1%1 groups. at the same level. The
operators compare their arluments as strings, all others operate

'<<' and '»', '.' and '-', '.' '/' and

.'==' and '1='

on numbers. St.rin&s which oegin With '0' are cODSidered octal numbers. Null or

missini arguments are considered '0'. The result ot all expressions are stnD&s,
wtlich represent decimal numben. It. 11 important to note that no tyO components ot an expression can appear In the same word; except when adjacent to
components ot expressions which are syntactically Sii~cant to the paner (' at'
'<' '>' '(' ')') they should oe surrounded oy spaces.
Also available in expressions as pMm1t1ve operands are command executions
Inclosed in T and 'I' and Cle enquiries ot the torm '-l name' where l 111 one ot:
read access
r
write acclss
Ixecute acce.s
x
I
existence
ownership
0

'r

"
z

zero

liZ.

t
cl

plain me
c!1rICtory
The lPec~ed name is command and Clename expanded and then tested to lee 1!
it has the specit1ld relationship to the real user. It the Cle does not exist or 18
ma.c'Cesstble then all Inquiries return rlLlse, 1.e. '0'. Command executions
succeed. retW"'t2irl& true,!. •. '1', 11 the command eXits with status O. otbe1""W1se
they rail. returninl fILls •• 1. •. '0'. II more detailed status intormation is reqUired
then the command should oe executed outside ot an expression and the variable
ftaZ'U4 examined.

C4Iltz'QI 4GW
The shell cont.a.i.ns a number of commands wbich can be used to regulate the

~O'W

of control in command mes (shell scripts) Uld (in limited out useful ways) trom
terminal Input. These commands all operate by toreini the shell to reread or
skip in its input and. due to the implementation. restrict the placement ot lome
ot the command3.
Tl:w /tn'.o.r:/t.. rtuitch., and 'Whi1A statements. as Yell as the i/-th.rrr.....z... tor.::n at
the if It&t.ment require that the major keY"'ords appear in a sinile simple c=mmand on an 1.npu1 Une as .hoYll oelOY.
If t.ha shell's input is not. •• ekable, the shen o~en up input whenever a loop i.
bema read and performs leek3 in this internal o~er tD accompl.i3h the reread1n& implied. by t.ha loop. (To the extant that t.b.i.s alloW'S. backwutC,oto's will
succeed on notHeekable inputs.)
Bu1ltin COm.tDaD.CD

1/18/81

3-11

8

CSH(l)

'UNIX Proirammer'l1danual

CSH(l)

BWlUn commands u. executed Within the shell. If a bWltin command. occurs as
~y component. of a pipeline except the last then it 1s executed in a lubshell.
allas
allu name
allu name woMWst.
The drst torm prints all aliases. The .econd (orm print.s the allas for name.
The dna! (orm assilns the specitted 1.UarrlZist as the alias of nAma: 1.UoY"ali.st is
command and manam. suDst.1tuteci. Ham.. 1.1 not. allow.d to b. CIli4s or
\&ftGLia6

alloc
Shows the amount of dynamic core in us'. broken down into used and !ree
core. and address of the last location in the heap. With an ar&ument shows
each used and tree block on the int.ernal dynamic memory chain indicating
113 address. liZe. and whether 1t 1.1 used or tree. This il a debUCii%li command and may ~t. work in production versions ot the shell: it reqUires a
modided version ot the syst.am memory allocator.
break
Causes execution to resume atter the end ot t.ha nearest .JlClosing JrrraiJ. or
UllLw.. The "mainin& commands on the current Une are executed. llulti18"el breakl an thus possible by writ1n& th.m all on one Une.
})reanw

Causes a b"u: from a nui.tch.. reSymflli atter tb.a .ftdIow.
cue label:
A label in a S"UAtch. statem.nt as cUscussed below.
ad
cdl1&me

chdlr
chcilrname

Chanc. th••hells warkine direct.ory to directory ftAS'tU. If no ar&ument is
&1"en than ch&Jl&e t.o the home direct.ory ot the Wier.
lf n.am.a 1.1 not. fOW1d u a lubdirectory ot the cW'rent directory (and does net
e • or " •• 1"). then each component ot the variable cdprUh. is
be&in With ",..
checked to .ee if it has a IUb~ctory name. F1na1ly. if all else fails but nmn.e is
a shell variable whose "alue belms With "', then W. lA, tried to lee if it. 1.1 a
.d1rect.ory .
I ./

CODtmue
Cont.1nue execution ot Ule nearest .nclol1Jl& 'WII:ile or /o.,.,a.ch.. The rest ot
t.he commancl. on t.ha current. Un. an execut.d.
d8fau1t:
w.b.1s the default case in a nWcA It&t.ement. The d.fault should come
atter all ca.n tabe1a.
_ho worcll1lt
The Ip.cta.d. ... ord.s ar. written to the Ihells standard output. A "c' causes
the echo t.o complet.e wit.hou.t. print.1n& a ne"line. akin to the ''\c' in n.1"Oll(!).
A '\11' in ...ordUst. caus •• a n ....l1n. t.o b. printed.. Ot.herwia. lhe worda ~
.choed. separated by spa.:e..
.

1/18/81

3 -, i

;

CSH(l )

lJNlX ?roiramz:er's Manual

C~.rl

(: )

else
IIZld

eDdU
endsY

See the description of the /or.~ch., il. nui.tch., and 'WhiLe sta.tements belo""
e%8C command
The spec~ed commae.d is executed in place of the current shell.
ait
~t.(expr)

The shell exits either with the value at the stcUU3 variable
with the value of the specUied .:pr (second form).
tonach name (wordlist)

(~t

!Or.:l) or

met
The variable ~ is successively let to each member of 'Wardlist anci the
.equenc. of comma.e.ds between this command and the matchin& .nd 11.""e
executed. (Both/or.ach and m4 must appear alone on separate lines.)
The builtin commscd conh'nu. may be used to continue the loop precatwoeiy and the builtin commae.d br.aJ: to terminate it. pnmaturely. When.
this command ~ read from the t.erminal. the loop is read up once promptin& With ',. before any ltatements in the loop are executed. It you make a
mistake t.ypilll in a loop at the t.erminal you cae. rub it out.
&lob wordllst
Like .CM but no '" escapes are recognized and words are delimit.ed by null
characters in the output. tJ.etul tor programs which wish to use the sheU to
mename expand • ast of words.

pt.o word
The sp.c~,d wcwd 11 mename and command expanded to yield a string at
the torm 'label'. The Ihell reYic.ds its input as much as panible and
searches tor a line at the torm 'label:' possibly preceded by bla.c.ks or ta.bs.
Execution continues att.er the spec~ed line.
biAorr
Displays the h1st.ory nent a.t.
if (expr) command
If the spec~ed expression evaluates true, then the Iinlle c:Jm.m4n.d wi.th
arguments 11 executed. Variable substitution on cO'"-""'47\d happens early.
at the same ume it does tor the rest of the if commae.d. CQm.m.a.ftd must be
a simple command. not a pipeline, a command. list. or a parent.hesized command list. Inputloutput ret:!irection occurs even if .zpr is talse. when command is not executed (this t. a bue).
If Cexpr) then

me Sf (expr2) then

.....

.L!.

eDdI.f
If the .p.c~.d .:pr t. true then the commae.ds to the Cnt
art! execut.ed.: else if .:prt t. true theD the commana. t42 the •• cond else an

1/18/81

3-1'1

10

CSH (1)

UNlX Prolrammer's Jlanual

CSH (1)

executed. etc. AIly number of ti.se-if pairs e.re possible; only one rnd:i.! is
needed. The .l$. part is Ukewtse optional. (The ",ords .l$e and rnd.i! m~t
appear at the be&innin.& of input lines; the if must. appear alone on1ts input
Une or atter an eLse.)

Iocm

.

Terminate a IOlin shell. rep1acma it With an inst.ance of Ibin/locf.D. 'l"b.i.s is
one way t.o 101 ot!. included tor compatibility With Ibin/sh..

locout
Terminat.e a 101m shell. Especially

~efulif

igno.,... o! is set.

Dice

Dice +number
Dice command
Dice +number command
The ~st torm set.. the nic. tor this shell to 4. The second form sets the
me. to the liven number. The Onal t.wo torms run .... I')mmand at priority 4and numb.,. respectively. The super-user may specify nelative niceness by
usin& 'nice -number ...•. Command 1s always execut.ed in a suD-shell. and
the restrictions place on commands in simple i!stat.ements apply.
Dohup
nohup command
The ~st. torm can be used in shell sCript.s to cause han&ups t.o be 19t\ored
for the remainder of the script. The second torm causes the Ipec~ed command t.o be run with haQiUPS ilnored. On the Computer Center systems at.
UC Berkeley. tb.iI wo ~bmits the process. Unless the shell is running
det.ached. ftOJa:ul' has no e~ect. All processes detached with "a:" an
automatically ftOhup 'eeL (Thus. n.ahup is not really needed.)
oD1Dtr
OD.intr -

onintr label
Control the action of the shell on interrupt.s. The ant. form restores the
detault action of the shell on interrupt.s which 11 t.o t.erminate shell scripts
or to ret.urn to the t.erminal command input IneL The second torm 'onintr
-' causes all int.errupt.. to be linoreeL The anal form causes the shell to
execute a 'Ioto label' when an int.errupt. 11 received or a child pro~eSl terminat.es because it "as interrupteeL
.
In any case, if the shell 11 runnfnl detached and int.errupts are ~eilli
1inored. all torms ot onintr haft no mean.in& and interrupts continue to be
finored by the sh.U and all invoked commands.
rahuh
C&uses the internal hash table of the content.. of the c!1rect.ories in the path
nriable to be recomput.ed. Tbia 11 needed if new commancis are added to
cli.rectories in the pfi.th whil. you an lOl,ed in. This should only be neces.ary if you add commands t.o on. of your OW'll directori .. , or if a Iyst.ems
prolrammer cha.n&es th. contents ot oa.e of the system direct,?ri."
repeat count. command
.
The speci1ied com.m.a.Ni 'Which 1. subject. to the lame restrictions u the
com.m.4fttt in the one lJ.ne \f statAment above. 11 executed count times. 1/0
red.i.recUoJll occurs exacUy once .... n if count 11 O.

1/18/81
~-~O

11

CSH (1)

UNlX Programmer's Manual

CSH (:)

_to
. t name
.t. !lAC e =word.
. t IlACe[illdex]:word.
. t name=(wordlist)
The th-st form ot the command. mows the value ot all shell variables. VariAbles which have other than a sUlile 'Word. as value print as a parentheslzed
'Word. list. The second form lets n.a.me to the null strilli. The third tor:::
sets
to the single ~01"1i The fourth form sets the inda= 'th component
ot name to 'Word.; this component must alrea.dy eXist. The ~al torm sets
to the list ot words in ~o,.dli.st. In all cues the value is command ~d
die.llAme expanded..
These I.riumenu may be repealed. t.o let. multiple values ill a sillile set
command.. Note however. that. variable expansion ha.ppens tor all ariuments before any setting occurs.
_tan~ I1&me value
eversion 7 Iystems only.) Seu the value ot enVironment. variable T\417'U to be
~alue. a single strillg. Useful environment. variables an '1'E1U{' the t.ype of
your terminal and. 'SHEl..L' the shell you are u.silli.

n.am..
n.am..

lbift
lhitt variable

The members ot ~ are lhifted. to the lett. ctiscard.ing ="gov[ 1]. It is an
error for =vv not to be let. or to have less than one 'Word as value. The
lecond. torm performl the same tunction on the specitied Variable.
8DU1'C8 name
The shell reacis comm~d.s troe NZm.•. S~. commands mG.Y be nested.: if
they an nested too deeply the Ihell may run out at ale descnpt:)rs. An
error in a
at any level terminate. all nested .OU7'C' commands.
Input durini sourc. commands il ne-rer placed on the blstm"y list.
1Wit.ch (strin&)
cu. strl:

.oun:.

c:Ialault:

breakrlr

eD"

Each case labelil successively matched. Alainst the spec~ed string wl:Uch
~t command and alename expanded. The &e metacharacters '.'. '~.
&Del '[ ••• ]' may be used in t.he case labels. wbich are Variable expand.ed. If
DOne of the labels match befon a 'default' label is found. then the execution begirlS attAr the default label. Each case label and the d.efault. label
must appear at. the beliDD!n, at a line. The command bna.e.nu causes execution to continue atter the tndorw. Otherwise control may tall throUih case
labels and d.efault labels as in C. If no label matches and there is no d.etault.
execution continues atter the rn4Jow.
time

t.

1/18/81

3-d'

12

CSH(!)

UNIX Pr:lgrammer's Manual

CSH ( : )

Ume c:lmmand
With. no argument. a lummary of time \Ued by this shell and tts child.nn is
printe!1. It aT.uments are .iven the 1'P.c~ed. limple command is timed. and
a time summary u d.escribed under t.he tim.e vanable is printed. It neceslary, an extra Ihell 1.1 created tQ print t.he time stAtistiC when the command
completes.
umask
umask value
The die creation mask 1s displAyed (~'t torm) or set to the spec~ed value
(second. form). The mask is liven in octal. Common values tor the mask
are 002 giVing all access to the group and read and execute access to others or 022 givizli all access except no write access tor users in t.he .roup or
others.
unaliu pattern
All &liases whose Ilames match the sp.c~ed pattern are discarded. Thus all
aliases are removed. by 'unaliu ... It ~ not an error (or not.hinc tQ be
una.lia.sat:L

anhuh
Use of the int.ernal huh. t.&ble to speed. location of executed programs is
disabled..
unset pattern
All va:1a.bles wb.ole names mAt.ch t.be s'Pec~ed pat.tern are removed. Thus
all variables are removed by 'unset .. ; this Ilu noticeably distasteful lide.trICU. It 1.1 not. an error (or notbilli to be ""-ftt.
"ALt.

All child processe, are wait.ed tor. It. t.be shen 1.1 int.eractive, then &%linterrupt. can disrupt. the wait. at. which time the shell prints names and process
numbe" ot &ll children mown to be ouUt.and.1J:1i.
while (expr)

end
'While the spec~ed expression evaluat.es non-zero. the commancU bet"'een
the 'WIt:ila and the mat.chin& Ind are rraluated.. ereal: and. con.nnu. may be
used. to terminate ·or conUnue the loop prematurely. (The whiZe and m.d
must appear alone on their input l1nes.) Prompt1ll& occurs b.ere t.he ~st
lime through the loop al (or tb.e /onaJ!ia. st.atement 1! the input 1.1 a term!-

•

D&L

• name • expr
• name(index] Ixpr
The ~st (orm pr1nU the values of all the .hell variables. The sec:lnd !or.n
•• ta the Ip.c~.d ft4J7U to the value of .:pt". If the expression cont~ '<',
'>', 'k' or 'j then at leut t.his part ot the exprellion must b. placed W'lthln
ttt ')t. The lh1rd form ullinl the ValUI of .=pr t.o the Vld.= 1h. argument ot
nama. Both na.m.a and ita Vv:ta=1h component mUit &lraady .~t.
The operators •••• , '+=', ate are available u in C. The Ipace sepuatiIli the
name from the uSi&nment operator 1.1 option.al. Spaces are. however. mandatory in leparatm& componenta of .zpr which would otheMrile be lmale
war".

~

=

Berkllay D1m1.but1on

. 1118/81
3-~~

13

CS"rl ( 1)

UNIX Proarammer's Manual

CSH ( 1)

Special pos~ ....... ' and ' - ' operators incr.ment and decrement fllUl'\.e
respectively, 1.e. '0 1"'''''.
Pre-me line 1. and
.tAt will print the current Une (the new u.ne 1) se yeu can s.e where you are. In
general. the current l1ne Will always be the last lin. a1!.cted by a cemmand..
Yeu can mak. a chAn&- to seme text Within the current Une by using the IUbstitat. (a) cemmand. Yeu say .ol/old /n.a1IJ/'O where old is replaced by the old
charact.rs yeu want to ,et rid et and fY'W 18 the new characters yeu want to
replace 1~ wtth.
The cemmand me (n Will tell yeu how many lines th.re are in the b~r yeu I1re
ed1t1n& &%ld wtll .ay "(llodidedJ'° if yeu have chanied it. Atter modify1n& a dIe
yeu can put the bw!er text back to replace the dIe by living a write C,,) command. Yeu can then leave the ed1t.:1r by 1ss\1.Uli a qu1~ (q) cemmand.. It you run
.dI.l on a ate. but cien't. ch.ance it. it 18 not necessary (but dees ne harm) to 'ft'1te
the ale back. It you try to qW~ !rom .tAt atter moc:!i!yil:l& the bw!.r Wlthout

4/8179

3-30

1

EDI"!'(UCE)

TJNlX l'roirammer'l Manual

EDIT ( UCD )

'WTiting it out. you wtll be wlU'~ed that there has b.en "~o WTit.e lince last.
change" and tdil Yill s.wait another command. If you 1ri.lh not to WTit.e the
bw!er out then you can issue another ctuit command. The bw!er is then r.~­

tnevably discarded. and you return t.o the shell.
. By using t.he delete and append commands. and giving Une number! t.o see lines
~1n -the ale you can make ar.,y cnAllies you deSire. You should learn at least a tew
; more t.hill.&s. how.v.r, 1! you are to use .dil more than a iew times.
·:Th. cba.n&e (c) command will. change the current line to a sequence of lines you
supply (as in append you give llIles up to a line cOllSistini of only a .. ,"). You can
tall ch&ll&e to change more than one Une by giving the line number! ot the lines
you want to cnAllie. La. ··3.Schange'·. You can print Unes this wa.y too. Thus
"1.23p" prinU the ~t 23 lines of the tn•.
The undo (u) command Yill reveMe the el1ect of the last command you gave
which cl::lAn&ed the butrer. Thus 1! give a substitute command which dcesn't do
whAt. you want.. you can lay undo and. the old. cont.nU ot the lin.e Will be
restored. You cm wo undo an undo command. so that. you cm continue t.o
change your mind. Ed.il will give you a warning message wb.en commands you do
a.11ect. more than one llne of tJ:1e butrer. l! the amount of change •• ems unrea.JOnable. you should consider doing an undo and loolCni to see wb..a.t ~ppened.
If you decide that. the chante is ok. th.n you can und.o &ialn t.o get. it back. Not.e
t.h4t. cOClmand.s such as 'Wf"\ta and pit cannot. be u.ndone.
To look at the next u.ne In the butrer you can Just hit carriage ~tW'U. To look at
a number ot Unes hit -D (control key ar.,d. while it is held down D ~ey. then let up
both) rather than carriAie return. This Will ahow you a h.a.1! .creen ot lines on a
CXI' or 12 Unes on a llAr~copy tarmi%lal. You em look at. the text around wb.ere
you are by givill& the command .. z.... The current line Will then be the last l1lle
pr.nt.ad.: you cm get back to the Una where you 'Were before the ,oz.'. commAnd
by sayill& '''-'. The • comman.d can wo be given other iollowlni character~
"z-" prillU a screen of t.ext. (or 24 Unes) ending where you are; .• %+ .. pnnU the
next IcreentW. If you want less than a IcreenIu.l of lines do. e.i .. "%.12" to get
12 Unes t.otal. This method of iiV'in& counts wcm 1.D. general; thus you can
delete ~ Unas IUrt..1ni With the current line With the command "deleta ~".
To ~ t.hin&s 111 the &e you can use line numbe" 1! you happen to know them;
lince the lin. cumbe" change wb.eno you insert and d.eLete lines this 1s lomeweat
unrella.ble. You can .earl:h backwards and forwards in the Ole for .trings by ii'vI.ni commands of the torm ItIat/ to seareh forward tor t.=t or ?text? t.o sea.r~!l.
backward tor t.:t. If a se~h reaches the e~ ot the ele wtt.hout tUlding the text
it wraps. end ~und. and continues t.o search back to the line wb..ere you ar~. A
useful teature !1ere 1.1 a .eareh of the torm 1-t.e%tJ which .earehes tor ta:: at
the beg;nnin.g of a Une. S1mJ.lariy ltans; searehes for t.:: at the end. of So line.
You can leave o~ tha t.ra1l.1nc I or 1m these commands.
ThII current Une bas a symbolic nama ".": this 11 most. useful In a range ot Unes
as 111 .... Sprint." which priJ::l.t,3 the rest ot the liD.es In the ale. To ,et t.o the last
Une 1.D. the ale you can refer to it by its symbolic name "S··. Thus the commaIld
.. , rieleta" or "Sci" cialetes the wt 11::I.e !:1 the Ole. no matter whic!rUr.e was Ule
current. Une bafon. Arithmetic W'lt!l l.J.ne references is WO ?ossible. Thus ~
1me "S-~' t. the dtth befon the last. and ". +20" is 20 lines alter the ?resent..
You can ~ci out which Una you an at by d.o1n& '0. =". This is usefu11! you wuh to
mo•• or copy a section ot tart wtt.h.1n a Ole or ,O.t..,..•• n &es. 1'1%1cl out. t.!:le ~,t
accllut
!lumbef'l 1"u Y1.Ib. to copy or men (I&Y 10 t.D 20). For a move yOQ

an.

2

tDIT(UCE)

UNIX l'roira.mmer's Manual

EDIT(UCE)

can then lay "10.Z0move "." wbich deletes these Unes trom the me and places
them in a b~.r named ~ Ed.i.t has Z8 luch bW!ers named II throUib. z. You can
later let these lines back by doina ..... move :' to put the content.s ot bW!er II
atter the current Une. It you want to move or copy these lines bet.Yeen mes you
can live an edit. (e) command atter copyina the Unes. tollo1f'ill& it with the name
of. the other ·d1e yO\1 wish to edit. Le. "edit chapterZ". By cb.an&ini m.au. to copy
above you can let • pattern tor copyi.n& lines. It the tan you wisb. to move or
copy is all within one dle then you can Just lay '·10.Z0move S.. tor example. It is
·not necessary to use named b~ers in this cue (but you can if you wisb.).
SEEALSD

ex

(U~). Vi (U~),

'EcUt: A tutorial', by Rick1 Blau and .fame. Joyce

mTHoa
'lrWiam Joy

See

u(U~}.

4/8/79
")

_~

-

-.,

~

00..

3

EX(UCB)

UNIX Prcgrammer' s Manual

EX(UCB)

ex - text editor
S"(NOPSIS

ex ( - ] ( -'" ] ( -t tAi ]( -r H +li:n.a'n.o ] lll1me ...
])£SCRlPTION
E= 1.1 the· ~e·t. of a tamily of ecUter'S: .dit. • : and vi. E: is a supenet of

.d. W'ith

the" mest neubla extension being a display editiIli facility. Display based eclltm.g
tI t.h8 focus of vi..

if yeu bAve c.ct used ,eL or art! a cuual user. you will and that the ed.1tor ,du

is

cenvanient tor yeUo It aveids sema of the cemplexities of ,: used mostly by systems programmen and pen OIlS vary familiar With ,a.
If you have a en term;na l you may Wish te use a display based editor, in this
cue lee vi(UCE). wCich is a cemmand wbich focuses on the display edit.in& pert10n of u.
DOC:nI!NTAIIOK
Fcr .dit .and. U lee the E=/Idf.t cammand ~ - Veni.oft 2. o. 't'he decument Edi.l: A tutari4l pM)V'i.des a ccmprellec.sive i.n.U'1)duction te .dit assuming llO
previous kncwiedie of computen or the t1NlX system.

The E= R.!.ruu:. lla.n:u.al. - ~7'SWn 2. 0 is a cemprellensive and cemplete
manual tor the cemmand mode teatures of I:. but. you can.i:lot. learn to use the
editer by readi.n.& it.. For an introductien to more "dvanced !Or::lS of editm.g
USU:1& the command mode of U" see the editing documents writ.ten by Brian Kerniihan tor the editor ,eL' t.h8 material in the introductory and advanced documents works also With u.

An J"n..tnrtw:titm. ta !X:rpla:y Editi.n.g wi.UL lot introduces the display eclltor vi and
p~vides reference material on vi.. The Vt Quick R.!rrrn.s:e cUfi sw:n.mari%es the
commands of vi in a usetuJ.. tlmctional ....y. and is useful with t.h8 In.t"~t-..an..
FOR !!D OSZliS

If you have ust!d .d you will dnd that .: has a number ot new !eaturt!s useful on
CRT Larm;na l ,. Intelli&ent t.erminal3 and biill speed t.erminals art! very pleasant
t.a use With vi.. Generally. the editor uses tar men ot the- capabillt.:i.es of termiD&ls than .~ does. and uses t.h8 terminal capability data base tarm.c~(UCB) and
the type of t.h8 tarm.inal. you an usin& from the nnable 1'E1W in tbA environment to cleterm.1lle ho" to driTe your terminal emcielltly. 't'he editor makes u.se
of teaturws such as insert. and delete cllaractar and lli:e in lts 'rima! comm&lld
(wmcn can be abbreViated ~) and which is the central mode ot edit1n.e when
1DinI vi(UCl!). Then is WO an interline ed.1Uc.& opeD. (0) cemmand which worles
Oil all term;n all •
E: contains a number of ne" teatures tor easily Vi.-winc the text ot the me. !he
• command liTes easy acc8SS to wtnde'WS of tan. Hittin& - D causes the editor to
1C~1l a half'-willd.ow of text and ls more useful tor quickly ste'PPini ~Uill So me
t.h.an just nitt.iJl& return. Of coune. the acr.en orienteci Yisu.a1 mode .ivas con.unt access to ed1t.1ll& conta:t..
E:;: &ives you more help wnen you make mistakes. 't'he tmdo (u) com.a;s.and a.llows
you to revane any linile cb.a.n&a wCich ioes astray. E= (ives you a let ot teeciback. c.crmally prillt.1nc ch&n&ed lines. and incllcates when more t.h.an a rew I.i:U!S
an urected by a command 10 thAt it 1.s easy to lietect when s comm&lld lla.s
&1!ectad mere Unes tha.n it should haTe.

1

EX(UC3)

UNlX Programmer's Manual

EX(UCE)

The editor also normally prevenu overwritin& existing mes UZlless you edited
them so that you don't accident.a.lly clobber With a 1IJ7"'it. a ale other than the
one you are ed.iti%li. II the system (or editor) crashes. or you accidentally ha.Ili
up the phone. you can use the editor recover command t.o retriev. your "ork.
This Will iet you back to Within a te" lines of when you lett o~.
~ ,!las severaL. features tor dea!in& With more than one ale at a time. You ean
.,v.. it a list of mes on the command. line and. u.s. the next (n) command. to deal
lrtth each in turn. The nen command. ean also b. given a list of dIe names. or a
pattern as used. by the shell to specity a ne" set of ales to b. dealt With. In general. menames i.e. the ed.itor may b. formed. 'With full shell met.asynt.ax. The
metacharacter '';' is also aVailable in tormini menames and. is replaced. by the
name of the current me. For edit.in& IArie groups of related. mes you can use
. : 's ta& command t.o ~Uickly locat.e tunctions and other important. pOUlts in any
of the meso This is usetul when working on a large program when you want to
qUickly ~d. the dednition of a particular function. The eommand cta.gs(UCE)
builds a ta.gs dIe or a &roup of C programs.
For moVin& text bet."••n m.s a.nc! Within a me the eelitor has a &rOup of bUl'!ers.
named a. throuah. S. You can place ten in the .. named bW!ers and. earry it over
when you edit. another dIe.
There is a command. IE in .: which. repe au the last .ubstitute command. In
addition there is a co~med substitute command.. You give a raIlie of substitutions t.o be done and the eelit.or int.eractively uks whether each substitution lS
d.esired.
You ea.n use the I'UbsUtuta command in .: to systematically convert the case ot
letters bet."een upper IUld lower case. It is possible to tinore case ot letters ill
.earcb.es and. .ubstitutions. Ez also allows regulu expressions which mat.ch
words to be constructed.. This is convenient. tor example. in searcb.in& tor the
word "edit." if your document also contains the word "eelitor. ,.
E:: !las a set of O]'Nms which. you can .et to tailor it to your liking. One opt.:.on
which is very u.setul is the =aaLndaftt opUon which. allows the edit.or to automatically supply leadini "hit.. space t.o aliin text.. You can then use the -D key as a.
baclctab and space and. tab !or"'Ward. t.o align new code easily.
KisceUaneous new uaetu1 features includ.e IUl int.eWaent loin 0) command which
IUpplies wbite space bet.ween joined. l1nes automatically. commancis < and >
which. shitt. ,roup' of Unes. and. the abilit.y to dIt.er portions ot the bU1'!er throUih
commands sucb. as nrt.
lusr IUb lez2. Oat.r1=Cs
lusr IUb lex2. Orec~er
1U!lr IUb I ex2. 0pA.ern

letc/tarmcap

-I.exre
Itmp 1EX7U'Lftftft
Itmp IRxnnftftft

sa:

ern»r messqes
recover command.
preserve command
d.escribes capabilities of terminals
editor startup me
editor t.emporary
named b~er temporary
preservation ci1rectory

1u.r/preset'9'e
AI.SO
awk(l). ed.(l). ,"p(l) ••• d.el). eelit(lJO), ,rep(lJO), t.ermcap(lJO} • .t(lJC3)

4/41'79

3-3'1

2

a(OCE)

EX(UCE)

AUT.BCR

YW1Am Joy
The U2'I.da command causes all marla to be lost on lille! challied and then
r.estored. it the marked. lines were cha.nied..
rOAdI:J never clean the bw!er mod.~d c:uldition.
~ • command prinb a number at logical rather than physicallmes. More thAn
&:Icreen tull at. output. may result it 10Zl& 1ic.es are present.
rue input/output erron don't print a name if the command l.1na ,_' option is
usect
The" is co easy way to do a sinale scan ignor'iIli cue.
Because at the implementation ot the ariuments to ft.:t, ocly ~12 bytes ot argument list are allowed there.
The format af /etc/'t~1Zp and the large number ot capabilities ot termicals
Wled by the editor causa tarminal type satup to ba rather slow.
The editor does not warn it text is placad in named bw!en and not used beiore
exit1ni the editor.
Null charactars are discarded in input &es, and C&llllot appear ill resultant dies.

'"

~,,"'," "" ""m",,", "" ~~, .,0"., ,", "'""d, w~."'. "" ".., '" W~,

So Irom the above Ilow Chart, We Can cover ali the lines / edges with two test cases.
For getting the correct answer browse down to the end 01 this page
::<:.:<,;:«
:>;::.»»

~.

48: Use the fOlloWing cOde;

'1

., 2j

It

"liJ nlt:rt~

''';

•• .. , " ' " ,,,'"

PORllAT(l)

NAME

URIX Programmer's Ranual

PORllAT(l)

format - format a floppy disk while running XENIX

SYNOPSIS
format
DESCRIPTION
Format is a menu-driven program for formatting floppy disks.
Diskettes are formatted in Altos 5-1/4 inch format; doubledensity, double-sided.

3-37

LAYOUT(l)

UNIX PJlOGRAIUIER' S IIAIIOAL

LAYOUIJ.'(l)

The options to layout are used to create some very common
layouts.
USAGE

layout /dev/hd0.layout 586
SEE ALSO

map(l), sizefs(l)

3-42

!'SCKCl)

-t

UNIX Programmer's Manual

FSCJt(l)

If ~ cannot obtain enough memory to keep its tables,
it uses a scratch file.
If the -t is specifiea, the
file named in the next argument is used as the scratch
file.
Without the -t option, ~ prompts if it neeas
a scratch file.
The file shoula not be on the file
system being checked, and if it is not a special file
or did not already exist, it is removed when ~
compl etes.

If no filesystems are given to ~ then a default list of
file systems is read from the file /etc/checklist.
Inconsistencies checked are as follows:
1.

Blocks claimed by more than one i-node or the free
list.

2.

Blocks claimed by an i-node or the free list outside
the range of the file system.

3.

Incorrect link counts.

4.

Size checks:
Incorrect number of blocks in file.
Directory size not a multiple of 16 bytes.

5.

Bad i-node format.

6.

Blocks not accounted for anywhere.

7.

Directory checks:
File pointing to unallocated i-node.
I-node number out of range.

8.

Super Block checks:
More than 65536 i-nodes.
More blocks for i-nodes than ,there are in the file
system.

9.
10.

Bad free block list format.
Total free block and/or free i-node count incorrect.

Orphaned files and director ies (allocated but unreferenced)
are, with the operator's concurrence, reconnected by placing
them in the "lost+found" directory. The name assigned is
the i-node number.
The only restriction is that the
directory "lost+found" must preexist in the root of the
filesystem being checkea and must have empty slots in which
entries can be made.
This is accomplished by making
Wlost+found n , copying a number of files to the directory,
and then removing them (before ~ is executed).
3-39

UNIX PROGRAMMER'S MARUAL

LS(I)

LS(I)

-u

Use time of last access instead of last modification
for sorting (-t) or printing (-1).

-c

Use time of file creation for sorting or printing.

-i

Print i-number in first column of the report for each
file listed.

-f

Force each argument to be interpreted as a directory
and list the name found in each slot.
This option
turns off -1, -t, -s, and -r, and turns on -a; the
order is the order in which entries appear in the
directory.

-g

Give group ID instead of owner ID in long listing.

-m

Force stream output format.

-1

Force one entry per line output format,
teletype.

-c

Force multi-column output, e.g. to a file or a pipe.

-q

Force printing of non-graphic characters in file names
as the character '?'; this normally happens only if the
output device is a teletype.

-b

Force printing of non-graphic characters to be in the
'ddd notation in octal.

-x

Force columnar printing to be sorted across rather than
down the page; this is the default if the last
character of the name the program is invoked with is an

e.g.

to a

'x' •
-f

Cause directories to be marked with a trailing '/' and
executable files to be marked with a trailing '*'; this
is the default if the last character of the name the
program is invoked with is a 'fl.

-R

Recursively list subdirectories encountered.

The mode printed under the -1 option contains 11 characters
which are interpreted as follows: the first character is
d
b
c
m

if the
if the
if the
if the
file;
if the

entry
entry
entry
entry

is
is
is
is

a
a
a
a

directory;
block-type special file;
character-type special file;
multiplexor-type character special

entry is a plain file.

3-44

UNIX PROGRAMIlBR' S IIAROAL

LAYOUT(l)

LAYOUT(l)

NAME
layout - configure a hard disk
SYNOPSIS
layout layout-device 586
DESCRIPTION
L~Y~~~

creates a table defining a number of "logical
devices" associated with each physical disk in the XENIX
system.
Layout records this table on cylinder zero of each
disk.
Each entry in the table is in the following format:
struct layout {
daddr_t l_blkoff; /*Block offset to area */
daddr_t l_nblocks; /*Number of blocks in area */
};

Layout defines ten "logical devices" on the hard disk:

o

The whole disk, with the alternate sector
mechanism disabled.

1

The swap area.

2

The root file system.

3-8

Unused.

9

Alternate sector area into which bad disk sectors
are automatically mapped by the XENIX kernel.

The logical device numbers above
numbers in the hard disk driver.

correspond to

device

Other device numbers are pre-defined in the XENIX kernel as
follows:
10

Future expansion.

11

All of track0.

12

Boot program area.

13

Portion of cylinder zero used for
file.

14

Layout information created by this utility.

15

Alternate sector map (see map(l».

3-41

~

temporary

LS(l)

LS(l)

UNIX PROGRAMMER' S MAllUAL

NAME
map - create an alternate sector map for a hard disk drive
SYNOPSIS
map layout mapfile drive
DES CRI PT ION
Map creates a bad sector map, on mapf ile, using the layout
The last
information, in layout, created by layout(l).
argument is the logical device name which references the
whole dr ive.
The standard invocation is:
map /dev/hd0.layout

/dev/hd0.secmap

/dev/hd0

The structure used for the bad sector to alternate sector
mapping is as follows:
struct mapsec {
int
bad_cyl;
char bad_hed;
char bad_sec;
int
bad_good;

/*
/*
/*
/*

Cylinder number of bad sector */
Head number of bad sector */
Sector number of bad sector */
Offset into alternate sector
area */

};

This structure provides a way for the XENIX hard disk driver
to recover from bad sectors it encounters when reading the
h a r d dis k • I f a ba d sec tor i s rea d , a sea r c h 0 f a t a b 1 e 0 f
the above structures is made.
If an exact match of
cylinder, head and sector is found, the corresponding offset
is used as an index into the area reserved on the disk for
alternate sectors.
SEE ALSO
layout (1) , sizefs(l)

3-46

LS(l)

UNIX PROGRAMMER' S MAllUAL

LS(l)

NAME
Is - List contents of directory
SYNOPSIS
Is {-abcdfgilmqrstuxLCFR} name •••
DESCRIPTION
For each directory argument, ~ lists the contents of the
directory; for each file argument, ~ repeats its name and
any other information requested.
The output is sorted
alphabetically by defalt. When no argument is given, the
current directory is listed.
When several arguments are
given, the arguments are first sorted appropriately, but
file arguments appear before directories and their contents.
Th ere are th r e e ma j 0 r 1 i s tin g for mat s. Th e for mat c h 0 sen
depends on whether the output is going to a teletype, and
may also be controlled by option flags.
The default format
for a teletype is to list the contents of directories in
multi-column format, with the entries sorted down the
columns.
(Files which are not the contents of a directory
being interpreted are always sorted across the
page
rather than down the page in columns.
This is because
the individual file names may be arbitrarily long.)
If the
standard output is not a teletype, the default format is to
list one entry per line.
Finally, there is a stream
output format in which files are listed across the page,
separated by'.' characters.
The -m flag enables this
format; when invoked as ~ this format is also used.
There are an unbelievable number of options:
-1
List in long format, giving mode, number of links,
owner, size in bytes, and time of last modification for each
file.
(See below.) If the file is a special file the size
field will instead contain the major and minor device
numbers.
-t

Sor t by ti me modif ied (la test first)
name, as is normal.

instead of by

-a

List all entries; usually'.' and ' •• ' are suppressed.

-s

Give size in blocks, including indirect blocks, for
each entry.

-d

If argument is a directory, list only its name, not its
contents (mostly used with -1 to get status on
directory) •

-r

Reverse the order of sort to get reverse alphabetic or
oldest first as appropriate.

UNIX ?rogracmer's J,IanwU

MAIl ( : )

Ptnon.tJ.L ~d systun'Lllide distribution. !-ists. It is also possible t.o cr~ate a perlonal ciistribution lists so that. for instance, you can send mail to "cohorts" and
have it go to a .roup ot people. Suchlist3 can be dedned by placing a line like
alias cohorts bill ozalp sklower jld mark cory:kridle
.1ll the dIe .mAil~ in your home dir~ctory. The current list of such aliases can be
tcUsplayed by the alias (a) command in m.=iL. System wi.de distribution lists can
.be· created by editing lusr/lib/aliases. see a.lia.ses(5) and daLi~,,"",,,iL(B); these
kept in a slighUy ~erent syntax. In mail you send. persow aliASes will be
:expa.c.ded in mail sent to othe~ so that they ,"U be able to "ply to the ~Cl­
pienU. Syst.em Wide a.lia.ses an not expanded when the mail is sent. but any
reply returned to the machine will have the system Wide alias expanded u ~
ma.U ioes t..brough claLi1Ja""-4iL If you ecUt lusr/Ub/a.liues. you must run the
program 1LrWalWaS ( 1).
Network mail (ARPA. rJrJCP, BlrlcTt.at) Mail to sites on the ARPA net"ork and
lites Wlt.bin Belliabon.tories can be sent using "nameOsite" tor ARPA-net 5ltes
or '"macbine!user'" for Bell labs sites. proVided appropriate gat.eways are Qown
to the system. (Be sure to escape the ! 1ll Bell sites when gi'Vil:1i it on a esh command Une by p"c~dilli it With an \. Mach.ines on an instance ot the Berkeley
net'Work are addressed as '"macbine:user", a.g. "csvax:bW". When addressed
trom the arpa-net, "csvax;blll" illmowu as "csvu.billCberkeley".
Jla:i1. has a number of options which can be let in the .~ dIe to alter its
behaVlor: thus "set uk-cc" enables the "&Skcc" feature. (These options an
tumma.ri%ed below.)

:ar1!

S01IlI.ARr

(Adapted from the 'llail Raeerence Manual°) Each command is t.yped on Il line by
itself. and may take argum.enU foll0wUli the comrneod word.. The ccmmand
need net be typed in its entirety - the dr~t command which matches the typed
p~tlx is used. For the commands which take message lists as argumenu. it no
messqe list is iiven, then the next message forward. which latis~es tbe
commandO s req,uir~ments is used. If there are ne mess8.ies forward ot the
current messqe. the seareh prt)ceeds backwards. and i! there an no icod messages at all. m4'il types UNo applicable mess8.ies" anci aborts the command.
Goes to the preVious message and prinb it out. If given a numeric
arlUlllent fL. loes to lhe fL th. preVious mess8.ie and pnnu it..
Prints a brief summary of commands.
Executes the UNIX shell command which rolloW'S.
!
(a) With no argument.3. print.3 out all currenUy~e~ed alia.ses. With
al1u
one arlUlllent. print.3 out. that &11&5. With :nore than one argument.
adds the users named in the second and lat.r ar.umenb to the ~4!S
named in the drst. arl'l=ent.
(c) C'hanies the user', working dinct.ory to that spec~ed.. 1! iiven. II
no ciirectoQry is iiven. then ch.anges t.o the user's login dinctory.
(cl) iakes a list of messages as argument and mar~3 t.,tlem all as
dalete
cleleted. Delet.ed messqes will :lOt be saved 1ll m.bo: . %lOr will they
be a'V1Lilable for mo~t other commands.
(aLso cit) Deletes the curr~nt messqe and print.3 the next :c.essa,ge.
dp
If then is no next. :nes3qe. m.a:il sa~ .• at. tOY."
ee) iake. a list of messages and points the text editor at each one in

,

•

LS(l)

UNIX PROGRAMMER' S MAJlUAL

LS(l)

The next 9 characters are interpreted as three sets of three
bits each. The first set refers to owner permissions; the
next to permissions to others in the same user-group; and
the last to all others.
Within each set the three
characters indicate permission respectively to read,
to write, or to execute the file as a program.
For a
directory, 'execute' permission is interpreted to mean
permission to search the directory for a specified file.
The permissions are indicated as follows:
r
w
x

if
if
if
if

the
the
the
the

file is readable;
file is writable;
file is executable;
indicated permission is not granted.

The group-execute permission character is given as ~ if the
file has set-group-10 mode; likewise the user-execute
permission character is given as R if the file has set-user10 mode.
The last character of the mode (normally 'x' or I_I) is t if
the 1000 bit of the mode is on.
See .k.b.m~(l) for the
meaning of this mode.
When the sizes of the files in a directory are listed, a
total count of blocks, including indirect blocks is printed.
FILES
/etc/passwd to get user IO's for 'Is-I'
/etc/group to get group IO's for 'ls-g'
BUGS

Newline and tab are considered printing characters in file
names.
The output device is assumed to be 80 columns wide.
The option setting based on whether the output is a teletype
is undesirable as "ls-s" is much different than "ls-s Ilpr".
On the other hand, not doing this setting would make old
shell scripts which used lR almost certain losers.

3-45

UNIX Programmer's Manual

undeleta
unset.

MAll. ( 1 )

'1&llidca.c.ce.
(u) Takes a messqe list and marks e!\ch one I1S n.ot bein.g deleted.
Takes a list of option c.ames and discards their remembered val~s:
the invene ot set. .
(T) Takes a message list and invokes the display editor on each mesIqe.

(y) A synonym for

la~

.

(x) A synonym for extt .

Here 1s a I~ary of the tilde escapes, wllich are used wb.en compoSlng messages ~ perform special tunctiocs. rude esca.pes an only recogruzed at the
beginnilli of lines.· The name .. tilde esca.pe" is somewb.at of a misnomer SUlce
the actual escape charact.er can be set by the option escape.

-fcommana
Executa the Indicated shell command. then retUl"!l to the message.

-c name ...
Add the liven names to the list of carboD. copy reciptent.3.
Read the me "deaci.letter" from yotJr home directory into t.!:.e meslAie.
Invoke the text editor on the messqe collected 10 far. After the
edit.in& sessiCt1 I..s ~hed... you may continue appending text to the
messAie.
EcUt the messqe header aeIds by typi.ng each one in tur:1 and alloW'ina the user to append taxt. to the end or' mocilly the aeld by IlSlng
the currant. t.erminal erue and kill charact.en.
-m messAies
Read the named messqes into the message being sent. siillled ~..g.b.t
one~. If no messages an specified. read the cun-ent messqe.
-p
Print out the messqe colle clad so tar. prefaced by the meslAie
header tlelcis.
"'""I
Abort the message beini sent. copyin& the messa,e to 'Odead.letter"
In your home directQry l! sa~ is set.
-rmename
Read the named me into the message.
-11 st.rin& Cause the named st.rin& to become the current. subject aeld.
-t name .••
Add the liven names to the direct reCipient l1st.
~
Invoke an alternate eci1tor (de~ed by the VISUAL option) on the mesIqe collected 10 tar. Usually. the alternate editor Will be a screen
editor. Atter you quit the editor. you may resume appending text to
the end ot yotJr message .
..."mename
Writ. the mess&.le onto the named dle.

-tcommana
P1.pe t.ba messAie through the command as a alter. If the eemmand
&ins %).0 output Or" t..!"!21inates abnormally. ret.a.m the or-",mal text o!

3-50

lWl.(1)

UNIX Procrammer', Manual

mail- ,end a.nd receive mail
SYNOPSIS

mail [ -l [ Ilame ] ] [ people ... ]
I!f'l'RODUCTION
~.
~

1!a.'iJ. is a I.nlelll,e:t mail processin& system. which has a command synLax reminiacent of It:! With lines replaced by massqes.
Se'ftding m4il. To .end a messqe to one or more other people. m4'iJ. can be
1nvo~ed with ar&wnenu which are the names ot people to send to. You are then
expect.ed to t.ype in your message. followed by an EQT (control-D) at the begmD.ini of a line. The lection below, labeled R,plying la or origin.a.t1:n.g mm:L.
describes some feat.ures of mczil aVailable t.o help you compose your let.ter.
Rea.ding m.=:z. In Ilormal U3qe. m.cil is civen no ar&uments and check3 your
mail out. of the post ot!ice. then print.inC out a one line header of eac!l message
there. The curnnt. meslace 13 initially the ant. meslAle (numbered. 1) and C~
be printed us1n& the print command (which can be abbreViat.ed pl. You can
move among the messa,es much as you move between Unes in It:!. With the command3 '.' and '-' moVini backwards and fonrarUa. and simple Ilumbers typilli
the addressed meslAce.
Dispa&'i:n.g at m.=:z. After exami.n.inC a mess Ale you can delete (d) the messace or
reply (r) to it. Deletion causes the m4il proiram to toriet. about. the mess~e.
This is not irreversible. t.h8 messace can be undelet.acl (u) by &iVinc its number.
or the m.=z lession can be aborted by liVini the ent (%) command. Deleted
messa,es will. hew • .,.r. usually di5appear never to be seen &&s.ill.
Sp.cij'ym.g menag.s. Commands Nch as print. and delete often can be liven a
list ot messace numbers as arlument t.o apply t.o a Ilumber of messages at. once.
Thus "delet.. 1 2" deletes messAIes 1 and 2. while "delete 1-~'" d.eletes me,'Ales 1 t.brouah 5. The special rlame ..... addresses all messages. and "s"
addresses the lut. messAle; thus the command t.op which prints the ~rst !ew
Unes of a messa,e could be used in "t.op ." to print. the arst tew lines of all mes8&&es.
R'1'lyiAg ta Of" or\gVt.i:tiftg m4iZ. You can U3e the reply commane! to set up a
respol1le to a messAie. ,endJ.ni it back to the person who it. was from. Text you
then type in. up to an e~d.-ol-me (or a line consisUn.c only ot a ..... ) de~es the
conterlU of the messqe. 'While you are composinC a message. mlZil treats lines
becinni::li With the charact.er "_" Ipecially. For instance. typinC "-mil (alone on
a line) will place a copy of the current. message into the response right shi!tin& it
by a t.abstop. Other escapes W'ill .et up subject. ~elc:1s. add and delete recipienu
to the me.l&&e and allow you to escape to an editor to rmse the message or to
a Ihell to run lome commands. (These OpUOr1S Will be liven in the summary
below.)
Bndi:n.g a. me'Ll ~c.ui.ng sasrim.. You can end a mczil session with the quit. (q)
command. lless&&es which have been examined 10 to your mba: ale unless they
have been deleted in which case they are discarded. Ullexammed messages go
back to the post. ot!ice. The ~ option CI!1U3es m.aiZ to read in the contents of
your mba= (or the lpec1.ded dle) for processinC: when you quit. m.cil wntes
undeleted messAies back to this dle.

3-'11

1

lUn.(1)

tJNlX

Itmp/R#
/usr IUb/Yail.ilelp·
/U3%' IUb IMail.~
Ibm/mail
I etc / delivermail

SEZALSO

rrogracmer's Mar.u.al

tempora.ry for editor escape
help ~es
system initialization ~e
to do actual mail.in.g
postman

.

ptiunail( 1). fmt(l). lle'Waliases(l). aliases(S). delivermail(B)
"I'he ldail Refennee MAnual'
AC"I"BOR

Kurt. Shoens
BOGS

3-Sc.l

MAll(:)

JWl.(:.)

u1t

from

.-

heaciers

t

help
bold

mail

pnSerTe
print
quit

repl,.

turn. On return from the editor. the messaae is read back ill.
(ex Clr z) ttrecu an immediate return to the Shell Without modifyilli
the user'l system mailbox. l:Us m.be.: tUe. or his edit 41e in -f .
(I) Takes a list of messages A%ld prints lheir messaae headers.
(h) List.s the current. ra.o.e of beaders. "hich is an 18 messllIe group.
It" a"." Ariument is liven. then the next 18 message group i.s
printed.. and if a
Ariument. is liven. the previous 18 message
Iroup is prmtAd..
A synonym tor?
(ho. also prese"e) Tues a message Ust and marla each message
therein to be laved. in the user's system mailbox instead of in mbe.:.
Does not. override the clelete command..
(m) Takes as Argument login names and distribution Iroup names
and sends mail t.o these people.
(D. Uke + or CR) Goes to the next messqe in sequence and. types it.
With an Argument liat.. types the next matchin& messqe.
A synonym for holcL
I
(p) Takes a messaa. l1st and types out each message on the user's
terminal.
(q) Terminates the session. laVing all undeleted. unsaved messages in
the user's NO: Ole in his login ci1rectory, preserTing all messages
marked. with hold. or prese"e Clr never reterenced. in his system mAlIbox. and removing all other messages from bis .ystem mailbox. If
n." mail has arrived dwi..l:1& the session. the messag. "'You bave new
mail" 13 liven. If liven while ed1tin& a mailbox tUe with the -f tiag.
then the ed1t Ole ~ rewritten. A return to the Shell UI etrected. unless
the rewrite of eci1t die tails. 11:1 which case the user can escspe With
the ezit command..
(r) Takes a message list and leneil mail to each messag. author just
11ke the mail command. The default message must not. be deleted.
A synonym for repl,..
(.) Takes a message list and a mename and appends each message in
turn to t.he end of the me. The dleneme m quot.es. followed. by the
line count and character count is echoed. on the user'l t.erminal.
Ylth no Arguments. prints aU variable values. Otherwise. sets
option. Arauments arw of the form "option=v'alue" or "option."
(m) Invokes an interactive .ersion of the shall
Take. a message Ust aDd prina out. the lize in characters ot eaC!l
mesl&le.
•
Takes a message 111t and prints the top fe" Unes of each. The
number ot lines prmt.eci is controlled by the .ari.able t.optiDee a.nd
de!a ult..s to dYe.
el) A 'ynonym for priDt.
Take• • l1st of aames c!edned by all.. commands and. c!1scar~s the
r:emembered Iroup- of u.ers. The &roup oames no 10llier b.ave any

u_..

(_>

top

?S(1)

PS(l)

ps - prt)cess status
SYNOPSIS

t- ( ac&kInt.uTY%# ( core~e ] ( S'Wap~e ] [ Iystem ] ]
DESCRIP'l'ICH

<

-is"'print.3 certain indicia about active processes. To get a complete print:)ut on
the console or Ipr. use "ps axliT' For a q,uick snapshot of system aCUvtty.
'~s au" is recommended. A minus may precede options lfit!l no el!eet. The tollowin, options may be spee~ed.
•
asks for information about all processes lfith lermil:l4ls (ordinarily otlly
one'. own prt)cesse. are displayed.).
c
causes only the com.m. aeld to be displayed instead of the arguments.
(The comm aeld is the tail of the path name ot the me the prt)cess last
exec'ed..) Th1s option speeds up ps lomewhat aJld. reduces the amoWlt ot
output. It iI also more "liable linee the process can't scribble on top of

1t.
I

k

)

1

•

Asks tor all prt)cesses. Without t.h1s option. ps only prinb "interesting"
processes. Processes are deemed to be Wllnt.erestini 1.f they U'1I prt)cess
,rt)up lladers. or if their u.uments belm w1th a '-'. This normally elim-

inal's !bells and ,etty procas.es.
causes the &e A£.I'r /S"!/S /eon 11 used in place of /dJI'V.ll:mAm. and
/!U1i;"'t7um.. ThiJ 11 used (or postmortem Iystem debUii~.
asks tor a 10111 Ust1ni. The short list.1ng eonwns the user name. process
ID. tty. the cumulative Ixecution time ot t.he process and ILIl approx:u:nation lD the command Une.
asb for "raw output". A non-human readable sequence of structures is
output on the Itandard output. There is one structure (or each prt)cess.
the tormat 11 de~ld by 
Print the lize of the kernel ltack ot each process. This may ocly be used
wtth the short l13t.1n&. and is for use by system cllvelopen.

tttyn,ama

u

"

%

,

,

"stricts output. to process.s whose controll.1nl tty 11 the Irec~ed
t1yname (which mould be .pec~ed u prilltad by PS, I.i. tt1;3 tor tty3.
tctm.Sol., (or console. tttydJJ tor ttydO. t1 tor processes With no tty. etc).
ThiJ option must be the lut ona &ivan.
'
A user oriented output 11 produc.cl. 't'b.U lllcludes the name of the owner
at the process. process id. mee Talue. liza. "sidem I.t G%e. tty. c!>u time
used.. and the commancl.
lell3 ps you an 011 I. w1de t.,rminAl (132 colw:::u:u). PI normally assume.
you are on an BO column terminAL 'I'h1s information is u.ed t.D decide how
much ot lonl commands to print. The .. option may be repeated. I.i. "".
and thl Intire command. up to 128 charactan. W1l1 be pr.nta~ Wlt!leut
relard to terminal wtdt.h.
asks ..en about processes w1th no lerminal
A. process number may be ,ivan.. (1l1ci1catad he" by I). in "flicn cue the
output ~ "strict,d to that. proces.. 't'bil option must we be Iut.

1/13/81
-, _ c I

1

UNIX ?rcgra.mmer' s J,1a.c.ual

MAll. ( : )

the message. The command. fm.t(l) is often used as com.m.l:n4 to
rejustity the message.
--strine Insert the strin& of text in the message prefaced by a single -. Ir you
lave chall&ed. the escape character. then you should. double t.llat
character in ortier to send. it.
:OptiollS are con~lled. ViA the let. and. unset. commanc.s. Options may be either
binary. ill which cue it is only signiacant to see whether they are set or not. or
. Ilrin&. in which cue the actual value is of interest. The binary options include
the follo'Win&:
append.
Causes messaaes saved in mba: to be append.ed to the end. rather
than prepend..d.. ('!"his is let. in lusr IUb IMAil.re on version 7 systems.)
Causes m=.l to prompt you for the subject of each message you
send.. If you respond. With limply a nf'w"line. no SUbject ~eld will be
lent.
uk=:
Causes you to be prompted. for additioc.al carbon copy recipients
at. the end ot each mesillie. Respond.ill& With a newline ind.icates
yoW' saUsfaction With the current. u.st.
autopriDt
Causes the delete command. to behave Uke cfp - thus. atter de letin& a m.,sllie, the next one Will.be typed automaticAlly.
Causes int.errupt. st&WS from yoW' termillal to be i&nored and
1&nore
echoed as O' s.
Usually. when a group is expanded. that. contaills the sender. the
sender is removed. from the expansion. Settillg this option causes
the sender to be included in the group.
quiet
Suppresses the print.ing of the venion when 11rst invoiced..
• •e
Causes the message collected prior to a int.errupt to be saved on
the me ··dead..letter" in your nome ciirectory on receipt ot two
~t.rrupts (or att.er a -q.)
The folloWini options hA.... It.rill& ftlu ••:
EDITOR
Patlmame of the text edit.or to use in the edit command. and ~
escape. If net dedned.. then a default editor 1.1 used..
Patbname of the sheU to use fl1 the , command and. the -! escape.
A d.efault shell is used if this option. is net d.edned.
Palhrlame ot the text acUtor to use in the 'risual command. and -v
VISUAL
••cap •.
If d.edned.. the 11m character ot this option. gives the character to
\De in the place of" to d.enote elcap.s.
If d.edned.. liv.s the pathname of the ~e \Hed. to record all out.oin& mail. If 1101. d.e~ed.. then outi0in& mail 1.1 110t so saved.
If d.edaed.. giv•• the l1umber of line. of a messqe t.o, be t'rillted out
1tith the top command; normally. th. ~st av. lines'are printed.

f.

lusr Ilpoollmall/ e

-/mbox
-I.m.ailrc

post ot!1ce
your old. mail
me g1Vin& 1n.it.1al mail command.

. '3 -

s1

-

.....

-~--

..

-.-

PS (1)

UNlX ?roirammer'l Manual

PS (1)

Processes With lUi' ec.Vironmec.tl. which have all QT part Qt the command ~ So
block Qther Ulan Ule top block in memory, are not correctly pr.llted by ps.
which oc.ly looks at Ule top block 1n memory. Thus. users using the TEPJA CAP
enVironmec.t. variable will proba.bly only have their command llAme shown.

1

.'

,
1/13/81

3-5b

3

PRlNTENV' ( UCE )

PRlNTE..W ( DeE )

UNIX Programmer's Manual

printenv - print out the environment
SYNOPSIS

prillt.enT [ name]

l)ESCRlPfiON
.pri:n.te1l:u prints out the values of the variables ill the environment. If

r

It.

n.am.e is

speci!'1ed. only its value iJ printed..
! If It. n.am.. is specitied and it iJ not dedned ill the environment. pnntrn:u ret'W'!ls
~ exit status 1. else i.t "tur:1S stat.us O.

l'

sa .&LSO

mel). environ(S). csb.(UCB)

BOGS

?thEdit1on

._._-----

2/24/79

3-SS

--=~;::::;;;;;;==:;:;:;;;;;;====~~~-;::---.---~.-:=~
".
-:::;.-:;::;--::::---- --

.

PS(l)
•

PS( 1)

UNIX i'roirammer'l Manual

A lecond argument tells ps where to look tar c~. if the c option 1s given. msteali
ot Ivmcare. A t.mrd argument is the name ot a swap me to use instead ot the
default. Idev/drum. U a fourth Uiument is liven. It is taken to be the ale containing the system's namelist. Otherwise. "/vmwUx" is und.
The output is lome! by tty. then by procell m.
The lona llsting II columnar ane! containl
"'1'
Fla,s associated with the process. These are detmee! by Ie!e~e lines in
IUD' l1Dclude I SYl Iproc.h.
: S
The ltate at the process. 0: nonexistent; S: Ileepill&: W: wait.inl: R: run-...
Di.J:lg: I: tnt.ermec1iate: Z: terminated.; T: stoppeci.
The user Ie! at the procesl owner.
t1ID
Pm The procesl ID ot the process; as in certain cul13 1t 11 pOlsible to Idll a
procesl it you kne" 113 true name.
PPID The process m at the parent process.
CPU P!-oC8l10r utilization tor .cheduJ.in&.
Pm 'nle priority of the process: high numbers mean 10" priority.
NICE Usee! in priority computation.
ADDR The memory ae!c:1reu ot the process if resie!ent.. otherwise the disk
adc:1reu.
SZ
The size in blocks of the memory image ot the procesl.

t. ".

YCHAN
The event tor which the process is waitin& or Ileepq: if blank. the procesl is nmnlCi.
TTY The contnlll1n& tt.y tor the process.
TIl4E The cumulative execution time for the process.
COlDrtAND
The commane! ane! 1ts &:'lumen13.
A process that has eXitee! and bas a parent. but h.as Dot yet been waited tor by
the parent is marked . 11 makes an educated luess as to the me
name ane! arluments ,iven when the process was createe! by examlni n , memory
01" the swap anL The methoe! 11 inherently lom."bat unreliable and in any
..,.nt. a proces~ 1s entitled' to destroy t.h1s intormation. so the names cannot be
counted on too Ir.uch.

hmumx
Idev/mem
Idev/drum
l"f'mcol'I
Id . .

system camelist
kernel memory
swap devtce
core ale
.. arched to and swap timce ane! tty names

srs.u.sa

k11l( !), w( 1)
:

Things can change wbJle F is runDi!'ll: the ptcture it iives is only
imaticn to reality.

Sn1 Berkeley DLstr1but1on

--:..-.:.-=-:.:===:.:..... . .
:.

&

close appr-ox-

2

1/1~/el

3-5~1

---===;:.:..~-...;.--------.-'--.

,. -.- -_...__. . . . .

MULTIUSER (I)

UNIX Programmer's Manual

MULTIUSER (I)

NAME

multiuser - bring the system up multiuser
SYNOPSIS

multiuser
DESCRIPTION

Multiuser prompts the user to set the current system date
and time, and then brings the system up multiuser.
First, multiuser displays the current system date and time
and asks the user to confirm or change the date and then the
time. Confirmation is done by entering Return. The format
for entering the date is "yymmdd." Time is entered as a 24hour clock in the form "hhmm."
SEE ALSO

date (1)

3-54

reset - reset troe taltty;>e bits to a se::5ible sUte
~OP5%S

,... .t

OESCR::P"!lCN

). ~u.t lets th. tel.tn>e bits to 'seft-eopy terminal standard mede' Yit.!l tbl I~!e
\ ch.a.r~et.ar set 1.:) cec.t.r:>H:~ &.Cd lbe kill c!laracter 1.:) • 0' .. Flu.t i5 mest us efui
:. w!lan yeu cr~p cut in ra." :::lede.
S!% ALSO

It.ty(l) .•tty(2). ,tty(2)
.xnBOB
KW"t Sheens
BOGS

If you &oM in ~ func.y .tat.e yeu may well have t.e tn- "reset" rollewed by l.i!:.etaed (cec.t..~l-j it the" 11 :10 .uch key.)

•

..

IIZt\!7I
3-S~

__==-::=:=-:_~_:",,!_:-:,.~.. =-- -

---'---''''''-'~----'===r:::-..._~=

- -- _.-

TAR(l)

NAME

UNIX Progra.mer's Ranual

TAR (1)

tar - tape or floppy archiver

SYNOPSIS
tar [ key ] [ name ••• ]
DESCRIPTION
~ saves and restores files on magtape or floppy.
Its
actions are controlled by the ~ argument. The ~ is a
string of characters containing at most one function letter
and possibly one or more function modifiers.
Other
arguments to the command are file or directory names
specifying which files are to be dumped or restored. In all
cases, appearance of a directory name refers to the files
and (recursively) subdirectories of that directory.
Note that XENIX contains a new version of tar, which permits
a file to extend across media boundaries. For compatability
considerations with the previous version of tar, refer to
the BUGS section below.
The function portion of the key is specified by one of the
following letters:
r

The named files are written on the end of the tape.
The c function implies this.

x

The named files are extracted from the tape. If the
named file matches a directory whose contents had been
written onto the tape, this directory is (recursively)
extracted.
The owner and mode are restored (if
possible). If no file argument is given, the entire
content of the tape or floppy is extracted. Note that
if multiple entries specifying the same file are on the
tape, the last version will overwrite all preceeding
versions.

t

The names of the specified files are listed each time
they occur on the tape. If no file argument is given,
all of the names on the tape are listed.

u

The named files are added to the tape if either they
are not already there or have been modified since last
put on the tape.

c

Create a new tape; writing begins on the beginning of
the tape instead of after the last file. This command
implies r.

The following characters may be used in addition to the
letter which selects the function desired.

3-61

UNIX PROGRAMM.ER· S MAIIOAL

MAP(l)

MAP(l)

NAME
map - create an alternate sector map for a hard disk drive
J.

SYNOPSIS
map layout mapfile drive
DESCRIPTION
Map creates a bad sector map, on mapfile, using the layout
The last
information, in layout, created by layout(l).
argument is the logical device name which references the
whole dr ive.
The standard invocation is:
map /dev/hd0.1ayout

/dev/hd0.secmap

/dev/hd0

The structure used for the bad sector to alternate sector
mapping is as follows:
struct mapsec {
int
bao_cyl;
char bad_hed;
char bad_sec;
int
bad_good;

/* Cylinder number of bad sector */
/* Head number of bad sector */
/* Sector number of bad sector */
/* Offset into alternate sector
area */

};

This structure provides a way for the XENIX hard disk driver
to recover from bad sectors it encounters when reading the
hard disk. If a bad sector is read, a search of a table of
the above structures is made.
If an exact match of
cylinder, head and sector is found, the corresponding offset
is used as an index into the area reserved on the disk for
alternate sectors.
SEE ALSO
layout (1) , sizefs(l)

3-53

TAR(l)

UNIX Programmer's Manual

TAR(l)

The b option should not be used with archives that are going
to be updated.
If the archive is on a disk file, the b
option should not be used at all, as updating an archive
stored in this manner can destroy it.
The current limit on file name length is 100 characters.
EXAMPLES
To dump the directory /usr/john to diskette(s), enter the
command
tar cvf /dev/fd0/usr/john
Note that if the device /dev/tar has been configured to
reference the floppy disk drive, as desired, the above
command can be abbreviated to:
tar cv /usr/john

3~63

SIIEFS(l)

UNIX PROGRAMMER' S MAIIOAL

SIZEFS (1)

NAME

sizefs - determine the size of a logical device from the
layout information associated with a hard disk.
SYNOPSIS
sizefs layout-file logical-device-number
DESCRIPI'ION
Sizefs prints on the standard output the size in blocks of
the specified area on the disk. It gets its information out
of the structure created by layout (1). Its most common use
is in shell scripts for creating a file system on the hard
disk, where its output is used as an argument to mkfs(l).
SEE

ALSO
layout (1) , map(l), mkfs(l)

3-60

UA(lM)

UNIX Programmer's Ranual

UA(lM)

exists for a new user, it is not removed. All files under
/etc/newuser are copied to the new directory during the user
installation process.
Typically /etc/newuser will contain
the standard versions of the following files:
.cshrc,
.login, .logout, .prof ile. The ini tial val ue given to a new
user ID is one more than the maximum user ID currently in
use. The same is true for a new group ID.
Delete allows the deletion of an existing user or group.
Deleting a user optionally also deletes his directory and
all files contained within it. Deleting a user will not
cause,gil files throughout the system owned by the user to
be deleted -- only those beneath his directory. Thus, some
files may have an "unknown" owner after a user is deleted.
And, if a user is later added with the same user ID as the
deleted user, these files will suddenly belong to the new
user.
The same problem may arise with the deletion and
later addition of a group •
.s.h.QXl will s h ow an i n d i v i d u a 1 use r 0 r g r 0 u p 0 r all use r s
groups. The word "show" may be omitted if desired.

0

r

Change allows the modification of any existing user or
group. A special display mode is entered with a menu of
fields for selection of the item to be modified. Typing
RETURN or LINE FEED in response to a field change request
will empty the field. Changes to a user or group change the
corresponding entries in the /etc/passwd and /etc/group
files. Changing a user's directory entry will ~ cause a
renaming of the actual directory.
It is the user's responsibility to ensure that the /etc/passwd and /etc/group
files remain consistent.
Help displays a short informative text on the screen. "?"
is equivalent to help. The message is the same one as obtained by invoking ~ with the "-h" option.
1 escapes to the shell (see sh(l)).
If no arguments are
given, a shell is invoked which will continue until it
receives an end-of-file. Then ~ resumes. If arguments are
present, a shell is invoked with the "-c" option and the arguments are passed along. ~ resumes immediately thereafter. If csh(l) is desired rather than sh(l), the command
lcsh should be used.
Qyit

immediately terminates

~

and returns to the system.

Any command which is not understood by ~~ causes an
appropriate message to be displayed. As a side-effect, the
working portion of the screen is cleared.

lla does not distinguish between RETURN and LINE FEED.
may be used interchangably.

They

If the screen becomes "dirty" for some reason, you can force
3-65

UNIX Programmer's Kanual

TAR (I)

TAR (I)

v

Normally.tiu. does its work silently. The v (verbose)
option causes it to type the name of each file it
treats preceded by the function letter. With the t
function, v gives more information about the tape
entries than just the name.

w

Causes ~ to print the action to be taken followed by
file name, then wait for user confirmation.
If a word
beginning with 'y' is given, the action is performed.
Any other input means don't do it.

f

Causes ~ to use the next argument as the name of the
archive instead of /dev/tar. If the name of the file
is I_I, tar writes to standard output or reads from
standard input, whichever is appropriate. Thus, ~
can also be used to move hierarchies with the command
cd fromdir; tar cf - • I (cd todir; tar xf -)

b

Causes ~ to use the next argument as the blocking
factor for tape records. The default is 1, the maximum
is 8.
This option should only be used with raw
magnetic tape archives (see f above). Altos recommends
a blocking factor of 8 when using the cartridge tape.

1

Tells.tH to complain if it cannot resolve all the
links to the files dumped. If this is not specified,
no error messages are printed.

s

Obsolete. No longer supported. (Was size parameter,
used when files did not cross diskette boundar ies.)

FILES
/dev/tar
/tmp/tar*

default input/output device

DIAGNOSTICS
Complains about bad key characters and tape read/write
errors.
Complains if not enough memory is available to hold the link
tables.
Tar will tell you to change volumes when the current volume
(floppy or tape) becomes full. It expects you to type one
or more characters and then return.
BUGS
This version of ~ can read old style tar disks,
old tar program can read new style tar disks, as
they do not extend over mul tiple floppies.
Note that the old version of tar cannot be used
multiple volume archives created by the new version
There is no way to ask for the n-th occurrence of a
Tape errors are handled ungracefully.
The u option can be slow.

3-62

and the
long as
to read
of tar.
file.

UA(lM)

UNIX Programmer's Ranual

DIAGNOSTICS
The diagnostics produced by
explanatory.

~

UA(lM)

are intended to be self-

BUGS
should allow specification of alternate passwd and group
files.

~

Complete consi stency checking between the /etc/passwd and
/etc/group files is not done. In particular, it is possible
to install a user with an unknown group in the passwd file
and it is possible to install a group with an unknown user
in the group file.
The shells and directories specified in
the /etc/passwd file are not checked for existence or
accessibility.
does not check for duplicated user IDs or duplicated
group IDs.

~

Impossible user IDs and group IDs are permitted.
Impossible or non-existent names may be specified for a
user's Directory and Shell fields.
The System 3 commands pwck(IM) and grpck(lm) should be incorporated into ~.
NOTE:
DO NOT USE llA TO SET A USER'S PASSWORD. The
password would be incorrectly encrypted, and
the user would NOT be able to log in successfully. Passwords .ay only be set with the
passwd command, explained in PASSWD (1). ~e
password field displayed by ~ is the
encrypted version contained in /etc/passwde

3-67

NAME

UA(lll)

UNIX programmer's Manual

UA(lll)

ua -- user administration

SYNOPSIS
.wi [

-.b ]

DESCRIPTION
~ is used for the addition, deletion and modification of
users and groups.
It provides an effective means for
maintaining the system password (/etc/passwd) and system
group (/etc/group) files.
The command is implemented using the ~ID~ and cur£e~
facili ties from UC Berkeley.
It must be run interactively
from a terminal which is defined within /etc/termcap.
This command should only be run by Super User -- improper
results may occur if it is run by a normal user.
The following option is interpreted by

-.b

~:

Displays the program's current version and copyright
notice as well as a short description of the program's
functions •

displays its legal commands at the top of the screen.
The "Command?" prompt at the bottom of the screen indicates
that ~ is awaiting input. The command language syntax is:

.llg

[ addldeletelshow I change ] [ user  I group  ]
show [ Users I Groups ]
help I ?
[  0) read(fildes, buffer, nbytes);
SEE ALSO
read(2)
DIAGNOSTICS
Rdchk returns -1 if an error occurs (e.g., EBADF), 0 if the
process will block if it issues a read and 1 if it is okay
to read.
EBADF is returned if a rdchk is done on a
semaphore file or if the file specified doesn't exist.

3-71

ORIX Programmer's Manual

IIBROS(S)

DRUS(S)

for this prompt. These are bsh(l)
commands and/or sh(l) commands.
An example menu for Electronic Mail Services is:
&Mail
\ELECTRONIC-MAIL-SERVICES

Idate

-a - Receive-mail
-b - Send-mail
-c - Return-to-starting-menu
&Actions
-a
0
mail
-b

I
I
l-c

-1

echo
read
echo
echo
mail

-n "To whom do you wish to send mail?"
x
"Now type the message."
"Terminate it by typing a control _d."
$x

11________________________________________________
Start
__

&Menuidentifier must appear beginning in column one.
Nenuidentifier is any string having relevance to the
user. A short descriptive string is usually best. The
string may not contain any blanks or punctuation ana it
must begin with a capital letter. If the string ends
with a question mark ("?"), the menu is called a "help
menu." It will be invoked automatically when bsh is
displaying the base menu and the user types a"?"
command. Thus, the &Admin? menu is invoked when &Admin
is the current menu and "?" is typed. The remainder of
the &Menuidentifier line should be empty.
The body of each menu is composed of text which will be
reproduced on the screen exactly as it appears (with
exceptions as described below).
-~m~ may occur one or more times within the body.
This indicates a prompt for which there will be an
associated action within the &Actions portion of the
menu. Usually there will be a short phrase or sentence
describing the action just to the right of the
-prompt. A prompt may be any letter, numeral or string
of char acter s not containi ng punctua tion.
Usually
shorter (1-2 character) prompts are preferred.
A
prompt must be separated from its surroundings by one

3-75

C1.I'l!SES ( :3 )

tJNDC Programmer's Manual

curses - Icreen tuncUocs With "optimal" curser motion
SYNOPSIS

~s ] mes -Icurse. ~t.enDl1b [ llbranes ]
DESCmP11CN
.

!=c [

~

~ese

reutines Ii.,.. the user a method of updatinc Icreens Yith reasec.abLe
~ptimizatien.. They keep an image of the current screen. and the user lets up an

:smage of a new one. Then the "!f"ulL() t.ells the reutines t.e make the current
°lCreen leek Uke the new one. In order t.e I.nitiall.:e the routines. the routine
Wt.i.l$C1"O must. be called betere any of the other routine. that deal With Windows
and. Icreens are Wlad.
S!:! ALSO
Senm. Clpda.ting ~ ~o,. JlO'Ulf1IJI'fLt Optimization,: A Libf'TV'J PaJ:Jc::.gI. Ken
Arnclcl.
termcap (5). Itt.y (2)... teny (3) •• et.eny (3) •

.wmcm
XenArncld

rmrcnCNS
addch(ch)
addst.r( IU)
bex( win. vert.her)
cnDedeO
clearQ
cl.&n)k(sc:, .beeU)
clrtebetO
c1rt.cael()
cielY1n('WUl)

.cheO

erase 0
,eteh()
,eut.:'( str)
,et.tmedeO
,etYX(W1n.1.%)
1zlch()

tmt.scrO
leavaek(W'in.beeU)
lonaname (t.ermbul.u.me )
meye(y.%)
mvcur(lasty .lutx.nawy.118W%)

D8YWin(11nes.cell.be&in-1.bel~)

DI()
DOcrmedaO
DOechcO
Danl()
DaraYO

a.er1ay(~.wta2)

overwrit.e(1rinl. win.2)
pr1nt.w(fmt..&r&l.. araZ••••'

raw{)

Nfnah()
N.uy()

.

add a charact.er te dt:laf:1"
add a st.rin& to dtbC1"
draw a bex around a W'il:1d.ew
.et. cbrealc mede
clear stUC1"
..t clear ~ fer """
clear to bottem on $ttUC1"
clear to ena of line on $ttbt:r
delet.e uAft
.et eche med.
erase $ttUC1"
let. a char thr0Uib dd.:lC1"
let e strini throUih dtbC1"
let. ltoy mocie.
,et (y .%) co-ordiDat.es
let char at current. (,.%) co-ora!nates
initialize screens
..t leave && ter uM\
,et lena name !rom te"",lru.!
meye t.e (1.X) on dt:l.sf:fo
actually mCYe cursor
create a new Yinciow
..t newline mappini
unset. cbreale mede
unset eche mecie
unset newtina mappinC
unset raw meci.
overlay Wil11 011 W1n2
ovel""'n'ile Yinl on lep of WU12
print! on .Itt:iaC1"
set raw mede
make current. scr.en lock like .IttUC1"
Nsat. It.y &&1 to .~r.d ftlue

1

... ..

~-"l'"

.~-- . - - ~.:..:. -:'.~~"7:::=:-:::.,,:,~.::...::,.·=~_~_=_:::;:o~~==~~-~
.!:-~_
- - - ......_~
.. "' __:!.joa._
. _ •...

•

ORIX Progra.mer's Ranual

IlBIlUS (5)

IIDOS(S)

The tilde a-" is an "escape character,· and may not be
used for any other pur-pose within a menu.
Each of the special escape sequences described above
must be separated from surrounding text by one or more
spaces or tabs.
It is important to know the number of lines and columns
of the terminal(s) to be used with a menu system and to
be certain not to create menus longer or wider than
these values. Their values are specified within the
termcap(5) file for each terminal upon which the
Business Shell may be run.
Actions
&Actions must appear beginning in column one.
must appear, even if there are no actions.

&Actions

Each prompt in the actions section must be reproduced
exactly as it appears in the body of the menu.
It is
the user's responsibility to ensure that the spelling
of prompts in the ~ and actions sections match. The
case of characters is significant; so "A" is not the
same as "a."
Size is optional.
It specifies the length of the
window to be used during execution of the actions.
If
omitted, the default value is 5, and a window 5 rows by
column columns will be reserved at the bottom of the
screen for output. Column is the terminal column width
as obtained from termcap(5).
A ~ of 0 will reserve
the entire screen.
In this case, the screen is blanked
prior to execution of the actions; and a prompt
requesting a return or line feed is issued after
execution.
A negative size will reserve the entire
screen similarly to the zero case, but after execution,
the Business Shell is immediately resumed without
waiting for a return or line feed.
It is the user's
responsibility to ensure that the action window is
large enough.
The actions may be composed of bsh (1) commands or
commands which are executed by the standard shell,
sh(l). The actions should all be indented one tab stop
from the left side of the file.
A bsh(l) command is the instruction to transfer
immediately to a particular menu. This is specified by
writing the name of the destination menu in the
semantics field. Bsh(l) commands must be typed oneper-line.
Sh(l) commands follow the usual rules as described in

Volume 1 of the Progra•• er's Reference KanDal.
3-77

IlENUS(S)

MENUS

menus

UNIX Progra.mer's Manual

IlERUS(S)

format of a Business Shell menu system

DESCRIPTION
A menu system is a collection of menus which has been
processed (digested) by digest(lM).
The Business Shell,
b s h ( I), r e qui res a men u s y s tern up 0 n wh i c h too pe rat e : i t
contains all the menus which are normally displayed to
accomplish some set of functions.
As distributed, the
Business Shell includes the default menu system
(/usr/lib/menusys and /etc/menusys.bin).
A menu source file may contain one or more individual menus.
However, in the interest of maintainability, it is
recommended that each menu source file contain only a single
menu, or only very closely related menus.
It is also
recommended that the name of the menu source file and the
menuidentifier be the same.
A source menu system may be a single menu file (containing
one or more menus) or a directory structure containing menu
files and subordinate directories.
Each menu file is an ASCII file consisting of two logical
parts:
the..bQQy and the actions. A (digested) menu system
contains an addi tional par t, the index. The index appear s
prior to the ~~. It specifies the byte-offset locations
of each of the body and action sections as well as the
associated menuidentifiers.
Users should never attempt to
construct an index by hand -- that is the function of
digest (1M).
Mor eover, users should never attempt to edi t a
digested menu system; rather, the source menu files should
be edited and then the menu system recreated using
digest(lM}.
The precise format of a menu source file is described below:
&Menui dentif i er
The substance of the menu ~epresented
essentially as it is to be displayed.
Within this area there usually will be
one or more occurrences of:
-prompt strings
as well as other special commands as
described below.
&Actions
Zero or more occurrences of:
-prompt
size
The sequence of actions to be taken

3-74

IlBROS(S)

OHIX ProgrUlJller' s Manual

IIBlIUS(S)

or more spaces or tabs. If a menu name and a prompt
both have the same spelling, the prompt is given
preference in all cases.
I~ inserts the current date and time, left-justified
on the "I." The date/time format is "Tue Jul 13 17:10
1982." Idate may appear more than once if desired.

luser inserts the current user id, left-justified on
the "I." luser may appear more than once if desired.
left-justif ied on
I~ inserts the current directory,
the "1."
The full path name is displayed, e.g.
/usr/jones/admin/cur rwor k.
Ipwd may appear more than
once if desired.
I@ indicates where the cursor is to be placed on the
screen. Usually this should be just slightly to the
right of the current prompt. If!@ is omitted, the
cursor will be placed at the bottom left corner of the
screen. At most, one occurrence of !@ should appear in
each menu.
with the exception of !@, the "!" may appear as a
suffix in which case the string will be right-justified
instead of left-justified.
The "!" is an "escape characater", and may not be used
for any other purpose within a menu.
\string denotes a string which is to be "highlighted"
using the terminal's highlighting capabilities (usually
reverse video). The "\" character must be on the left
of the string. It is converted into the appropriate
highlighting information during display. The string
may be of any length up to the width of the display
screen.
'string denotes a string which is to be "underlined"
using the terminal's underlining capabili ties (usually
true underline). The It'" character must be on the left
of the string. It is converted into the appropriate
underlining information during display. The string may
be of any length up to the width of the display screen.
The backslash "\" and backquote ,,'It as the initial
letter of a string are "escape characters" and will
always have the interpretations given above.
In order to create a highlighted or underlined string
containing spaces, "signif icant spaces" may be
repr esented a s til des (n-") within a str ing.
Th us,
\-hi-there- will create a highlighted ten-character
string.

3-76

.
'I'tP.MCAP ( 5 )

UNIX Programmer's lh.nw

TERM CAP ( 5)

ed
ei
eo
tr
:bc

Itr
End delete mode
str
End insert mede: iive ":ei=:'" i! ie
str
Can erase over'trikes With a bl4nk
(1'e) Hardcepy ter:::mnal page eject. (default -1.)
st:'
boe1
Hardcepy ter.nillal
str
Halt-line dewn (!erwarti 112 linefeed)
.lui
It:'
U10
Heme curser (i! 0.0 em)
Itr
.Halt-Une up (nvene 1/2 linefeed)
:bz
st:'
Hazeltine: can't pr.nt ""s
It:'
(1') ~ert character
ie
It:'
if
Name of Ole centAininl t.
bo01
~ert mede (enter); lift ":im=:" 1f Ie
1m
bo01
~ert mede dist.inguishes o.ulls en display
in
(pe)
Itr
Insert
pad atter charact.er illserted
1;1
It:'
is
Terminal initializatien str.l1i
Sent. by to other'· Nnctien keys o-g
kO-k9 .t:'
.t:'
Sent. by backspace key
kb
.t:'
Sent. by t.ermill.al down art'ew key
kd
Out ot ··keypad tra.n.smit'· mode
.t:'
ka
It:'
Sent by Ilome key
1m
It:'
Sent. by t.erminAl left ~ key
ld
Number ot "other" keys
kn
num
Termca.p entries fer other non-functien ke~
It:'
ka
]a
It:'
Sent. by t.erminal rilbt IJ'r1)W luy
Put terminal in "keypad transmit." mede
lcs
It:'
Sent. by terminal up UTeW key
.t:'
ku.
10-19 It:'
Labels on. "'other" !Unction keys
Number of lines on screen or page
num
11
Lut line. Ont. celumn. (it no em)
It:'
U
J.;rrf:Jw
key map. used by Vi versien 2 oely
str
ma
Sate to move wtille in insert mode
bool
mi
Kemory lock on above curser.
It:'
ml
Kemery unlock (turn. oj! memory lock).
mu str
No correcUy work::ini carr1a& e ret1Jr.1 (DM2:S00.H2000)
bool
DC
Non-dest.ructift space (cunor r1iht)
It:'
nd.
(1'e) Newline charact.er (default \11)
nl
It:'
Terminal is II. aT but doesn't .croll.
bo01
ns
TermillaJ. oventrikes
oa
bo01
Pad character (rather than null)
pc
It:'
Has hardwar1l tabs (may c.aed ~'be set with t.)
pt
bo01
End sUnd out mode
It:'
(1') Scroll !orYard3
It:'
.t
Number of blank chan lett by 10 or se
num
II
Be
stand. out mod.e
It:'
10
(i')
Scroll ""ne (backwards)
Ir
It:'
(1') Tab (other than -lor With padd.1.n.i)
bIt:'
Entry ot similar tarm.ina!- must be last
tc
It:'
Strml ~ end. Prolruns tbat us. em
ta
It:'
St.rm.& to oelin programs that WI. em
It:'
t1
'Ond.encor. one :b..ar and. move ?ast it
It:'
1:
Ene! Wlder,coMt mod.e
U8
It:'
Number ot blank chars lett by WI or u.e
:mm
QI

:hu

..

t

..

,m

t

4th Berkeley

~

~/la/8C

_ _ 3-g0

-- .... --.-

2

DRUS(S)

UNIX Programmer's Kanual

IIBRUS(S)

Since a menu file may contain one or more menus or
directories containing menus, the recommended way to create
a menu system is to create a tree of directories containing
the various portions of the system. Each subtree contains
all the menus related to a given subject. Thus, a primary
menu (directory) is created for, say, system management
functions: and subsidiary menus are placed beneath (within)
the directory for each of the individual system management
functions or function areas.
Help menus may be placed
wherever appropriate in the structure.
FILES

/usr/lib/menusys
/etc/menusys.bin

source directory for /etc/menusys.bin
digested default menu system for bsh(l)

SEE ALSO
bsh(l), digest (1M), shell, termcap(5)

3-78

..
'I'ERMCAP(S)

UNlX ?:-ogrammer's Manual

TERM CAP ( 5 )

as '\072. II it is %leesssary to plaee a %lull cbaracter in a st.""ini capability it must
be e%lcQded as '\200. The rQut.i.c.es wbieh deal 'W1t.h t.nn.c:::.p U3e C sirllli', and
strip the biih biu ot the output very late SQ that a '\200 comes out as a '\000
'WOwd.
l'reparini
.
. Description.
'e %lOW' outline hoW' tQ prspars descriptioas ot terminals. The most etreetive way
~ prepare a t.er:ninal descriptio%l is by imitatillg the description ot a similar termic.A1 in tUTI'1.Ct:1l' and. tQ build up a description gradually. U31.c.& partial descr~p­
tiQas with 1% UI cbeek that they are CQrreet. Be aware that. a very unusual ter-minal may ext'ose de~cieneies in. the ability ot the t.nn.t:ap Ole to describe it or
bUi~ in t%. 1'0 easily test a %lew terminal description you can set the e%lvironment Variable 'l'ERMCAP tQ a paUmame ot a Ole cQntainiIli the description you
are woric:in& on and the editor 1rill look there rather than in. /.tc /tr!"'l'7\t::::.p.
'l'DUr{CAP can also be set UI the termcap entry iueU t.c avoid reaciillg the ale
wben starting up the editor. (This only works on version 7 sysbms.)
Buic capabilities
The %lumber ot CQlumns on each Une tor the ter:nil:lAl is given by the co numeric
capability. It the terminal is a C3T. then the number ot u.nes on the screen is
linn by the 11 capability. U the ter:ninal wraps aroWld UI the beginning ot the
next line when it reaches the riiht margin. then it should. have the am capabilit.y. It the terminal can clear iu screen. then this is .lven by the ci st.-illi capability. It the terminal can backspace. then it should have the b. capability.
unless a backspace is acecmplished. by a cbaracter other than "'B (\lib) in whlch
case you should give this character as the be: st.ril:l.& capability. II it overst."1k:es
(rather than clearini a posiliQn wben a cb.cact.er is struck over) then it showd.
have the os capability.
A very important point. !lere is that the local cunor motions encQded ill taTmC:lp
are WlCie4D.ed at the left. and t.cp edges ot a car term..i.tlal. The editor will never
attempt to backspace around. the lett edge. %lOr will It at.tempt to go up locAlly
o~ the Ulp. The editor assumes that teed.ing ol! the bottom ot the screen Will
cause the screen UI scroll \ll). and the am capability tells whether the cursor
lUcks at. the riibt edie at the screen. II the term.il:14l !las S'W1tch seleetable
autQmatic margi.cs. the t~t:1i' Ole usually assumes that t.hi.s is on. 1.e. am.
These capabilities sumce to describe hardcopy and. .. giass-tty'· terminals. Thus
the C1ode133 teletype i. desCribed as

.

t3133 Itty33:col72:cs
Yhile the Lear Siegler A.OlI-3 is deSCribed as
c! Iad.m3131lsi ad.m3:am:bs:cl=-Z:11i24-;coISO
Cunor~

CUnor adciresstn.a U:1 t.he terminal is described by a cm .t.rini capability. Wlth
escapes %x 1.n It. These substitute t.o encod1:c.is ot the ctU":~:lt
Une or column position. wbile other cnaracten an ?A!lsed. t.hr0Uib. WlchAnied.
II the em st.-m.a is thoUiht ot as being a function. then ib argumellts .ar~ the line
and then t.he cclwnn UI which motion t. desir~d. and the :: encQcW:1gs have the
tolloYiJ::li mea.z:W:lis:
:u
as ill f1Nt..tt. 0 oriiU1
~
Uk. ::2d
:3
Uk. ::3d

~!t3s) Uke

,

SI10lSO
==

--.--.

~-.----

.--.

,3-&;" .

TERMCA?(5)

T'ERMCA?(5)

t.armeap - t.erminal capability daU base
SYNOPSIS

lete It.ermeap
DESClUP1"ION
_T~~p is a data base describing t.erminals. used. I.g .• by viO) and C"t.D'U$(:3).
,rerminW are described in t.7""I'7\C~p by living a set ot capabilities w!:lieb. they
~have. and by describing how operations are performed. Paddin& req,uirements
-and initial~zat1on seq,uences are irlcluded ir1 tl1"mC~p.
.
ktries irl t.rm.c~p consist. ot a number of ':' separat.ed delds. The erst entry tor
each t.erminal lives the IlAmes w!:lich are lalOW'll for t.he terminal. separated by
'I' characters. The erst Ilame 1s always 2 charact.en 10Ili and is used by older
version 6 syst.ems which store the t.erminal type in a 16 bit. word in a system'Wld.e
data base. The secolld Ilame liven is the most commoll abbreViatioll tor the termi1' al. and the last Ilame .iven should be a long name tully id.entifying the ter:n.inal. The second name should contain no blanks: the last name may well cont41ll
blanks for readability.

CAPABIIJ'l'IES

(P) indicat.es paddiJ:::.& may be I'pec~ed
(pe) indicates that. paddin& may be based
NAme
I.e
al
am

•i

as
bc
'os
bt
'ow
CC
cd
ca
ch
el

em
co
cr
cs
en'

d.a

dB
cib
ciC
clc
dF
dl

em
aN
cio
ciT

Oil.

no. Unes

~ected

Type Pad? Description
(P)
End alter:l&te character let.
sU'
str (pe) Add new blank Une
'0001
Terminal has automatic margins
sU'
(P) Start alternat.e character set.
IU'
Backspace if not - H
'0001
Terminal can backspace With -H
str (P) Back tAb
'0001
Backspace wraps trom column 0 to last column
Command charact.er in prototype it terminAl lettable
IU'
(pe) Clear t.o end ot d15play
IU'
str (P) Cle ar to enei ot Une
(P) Uke cm but horiZontal moUon omy. !ina stays same
It:'
str (pe) Cle ar Icreen
str (P) Cuner moUon
Number ot columns in a Une
num
(pe) CazTi.qe return. (eietaull -11)
It:'
str (P) Chanae sc~1liIl.& region (vt100), Uke cm
IU'
(P) Uk. ch but vertical only.
Display may be retaineei abaft
bo01
Number ot millisec of '01 delay needed
num
Display may be retaineei below
'0001
Number of mtllisec of C%' delay needed
num
(pe) Delete character
It:'
Nwnber of milllsec of ~ delay ne.eieei
num
(pe) Delete Une
It:'
Delete mode (enter)
str
Nwnber of millisec of n1 delay needeei
num
Down one UDe
str
Nwnber of millisec ot tab eie1ay needed
rwm
o

5/10/SO
.....

- -----_..

3-1~
_-- --------..;...._.
-_._----_. -

_

1

'IDMCAP(S)

UNIX Programmer's Manual

TERM CAP ( 5)

Ther~ ar~

-

-

t"o basic kinds ot 1ntelligent terminals With respect to 1mert/delete
character which can be desc!"'ibed usini tarm.c:p. The most ccmmon
insert/delete character Qpera~O)1lS a1!ect oIlly the characten on the current
Une and shitt characters ot! the end of the line rigidly. Other terminals, IUCb. as
the Concept 100 and the Perkin Elmer OYL make a distinctioQ between typed
and untyped blanks OQ the screen. shifting U.pOQ an insert or delete ocly to an
p.Dtyped b!arik OQ the Icreen wbich is either eliminated. or erpanded to t;wo
~typed blanla. You can o.nd out wbich k:i.z:ld ot terminal ycu have by cleari.t:li
the Icreen and then tYPini text separated by cunor motions. Type" abc det"
UsiIli local cunor motiolU (not spaces) bet."een the "abc" and the "de!". Then
position the cursor betore the "abc'· and put the terminal in insert mode. II
typiIli characters causes the rest of the line to sb.i!t r'iiicily and characters to
tall ot! the end. then your terminal does QOt. dist..iIliw.sc. between blanks and
untyped pOSitions. If the "abc" 1b.i!U over to the "der· wb.ich then move
together &.M)und the end ot the current Une and onto the next as you imert. you
have the secoQd type of terminal. and should give the capability 1n. 'Wbich stands
tor ··insert. QuU··. If your t.erminal does somet.hi.ng cii.1!erent and unusual then
you may have to modi!y the editor t.o get. it to use the insert mode your t.erminal
de~s. We have seen QO terminals wmch ll.ave an insert mode QOt. not ta.l.ling
into one of these two cla.sses.
The editor can hAndle both terminels wbicb. have an insert mode. and terminals
which send a simple sequence to open a blank position OQ t!le current liI:.e. Give
as 1m the sequence t.o let into insert mode. or iive it an empty value it your terminal uses a sequence to insert a blank position. Give as .1 the seq,uence t.o
l.ave insert mode (,ive this. With an empty value also 11 you gave 1m so). Now
live as Ie any lequence needed to be sent Just betore sending the cb.aracter to
be inserted. liost terminals With a true insert mode will not live Ie. terminals
which send. a lequence to open a screen position should give it here. (Insert
mode is preterable to the sequence t.o open a positioQ on the screen i! your tarminAl has bot.h.) l! post insert padding is needed. live this as a number o! mill1s.conds in ip (a striIli option). AJ:J.y other seq,uence which ::nay need to be sent
attar an insert of a single character may alse be liven in Ip.
It is oecuiona.lly necessary to move around while in insert mode to delete charactars on the lam. Une (e.,. 11 there is a tab attar the insertion position). l!
your terminal alloW'S motion while in insert mode ycu can iive the capability mi
to sp.ed. u.p insertil:1i in this case. Omitt.i%li m1 Will a.1!ect only speed. Some terminals (notably Datamedia's) must not have m1 because of the way their insert
mode wora.
rtnally. yeu can specify delete mode by liViIli am and eel to tnt.ar and e%lt
deleta mode. and de to delete a siIl&le cha.ra.cter wh11e in delete mode.
Blchllcht1n&. undarlSnfn&. mel 1Uibl. ben.
If ycur terminal has .equences to ent.er and eXit standout mode these can be
,inn U ID and .. respectively. If the" are .everal daVO" of .tandout mode
(NCh u inven. Video. bUnkj!li. or underlinin.i - b..a1l bri&ht 1s not usually an
acceptAble .. standout" mode untess the terminal is in 1nverse Video mode I:COstantly) the pnterred mode is inverse Video by itself. l! the code to ~ange into
or out of standout mode leaves one or even tyO blank spaces on the scree!l. as
the 1'V1 912 and. releray 1081 do. this is acceptable. and 4lthouah it. mAY ccc.!-..ue
lOm.e p~,rams slilhtly. it can't b. helped.

•
S/10/BO
-

...__ ...3 ~~'j

---_._._._-----_._----

..... _.

s

'I'E.~CAP

...

t1NIX i'roira.mmer's Manual

(5)

bool
Itr

u1
up

-.:..

Itr
Itr

US

..-b

TERM CAP ( 5)

Terminal u:cderlines even tho\lih it. doesn't overstrike
'Upline (cursor up)
Start underscon made
Visible bell (may not move cursor)
Sequence to end open/Visual made
Sequence to .tart open/visual mode
aeehive (fl=escape. t2=ctrl C)
A newlille is linared atter a wrap (Concept.)
Ret.urn acts 11ke c. \r \.a. (Delta Data)
Standout not erued by writini over it (Hi' 2S4~)
Tabs are destructive, maiic so char (Teleray 1061)

Itr
Itt
bool
bool
m
bool
2::
boo!
D
bool
xt
A Sample Entr:r
The following ent.ry, which describes the Concept-100, is amolli the more complex entries in the t'7'mCap m. as at t.his wriUlli. (This particular concept entry
ill outdated, and ill \Ued at an example only.)
ell c 100 ! conceptl OO:is=\E'U'.Et\E7\E~8'-El'-ENH~X'\E'\200\J:o~'200:'
:al=3·\J:-R:a.n:1:bs:cd=lS·\E-C;c.=lS\J:-S;cl=2·-L:cm=~+ :f:+ :coI80:'

'f'I

:dc=lS\J:-A;dl=3·\J:-B:ei=\J:\200:eo:im=\E-P:Ul:1p=lS·:11124:m1;%ld.=~=:\

:•• =\Ed\J:e:so='\ED'-EE:ta=e,t;u1;up=\E;:vb=\Ek'\EX;xn:
Entries may continue onto multiple Unes by iivina a , as the last character ot a
line. and that empty delds may be included tor readability (here between the
last deld on a line and the ~st deld on the next). Capabilities in tenn.c~ are ot
t.b.ree types: Boolean capabilities which indIcate that the t.erminal hu .ome particular feature. numeric capabilities liVini the IU. ot the t.ermil:l.Al or the lize of
particular delays. and strin& capabilities. which live a sequence wblch can be
used t.o perform particular t.ermmal operations.
Types of CapabWU..
All capabilities have t.wo letter codes. For instance. the fact that the Concept
has "automatic marlin," (l.e. an automatic return and linefeed when the end of
a l1lle i.a reached) is indicated by the capability am. Hence the description of
the Concept 1llcludes am. Numeric capabilities are followed by the charact.er ',.
and then the value. Thus co wbicn indicates the number ot columns the ter::n1nal cas lives the valu. '80- for.lha CDncepL
i'1nAUy. st.rm& Yalued capabilities. such as ee (clear to end ot l1lle le~uence) an
liven by the two character code. an 'a', and then a strilli endiJli at. the next tol10Yin& ':'. A delay in mi1l1seconds may appear atter the '=' in such a ca.pability,
Illd pacici1n& characte" are suppUed by the editor attar the r~mainder ot the
t. lent to proVide this d.elay. The delay CaD. be either a inteier .•. ,. '20',
or an intaier followed. by an ' .. , I.e. ·3 e '. A '.' indicates that the padd1n&
re~uired t. proportional to the number of Unes l.1!ected by the operation. and
the amount liven 1.1 the per-a11ected-o,mlt. paddUli req,uired. Yhen a '.' ~
lPec~.d. it. t. 10meUmes useful to I1Y. & delay at the form '3.!\· .pecUy a delay
per unit. to tenths ot mJl.l1aeconds.
A number of escape .eq,uences ar. provided in the .trill& Yalued capabilities for
easy encod1nc ot characters there. A \% maps to an :::SCAlI!: charactei-...% maps
to a control-x for any apprtlpria.te x. and the sequences \D '\r \1 \b \J i1ve a
newline. return. tab, backspact! and formteed. F1nally, characters may be i1ven
u lhr•• octal dl&iU attu a \. and the characters - IJld \ may be liven as \and. ,\. If 11 il neces.ary to place a : in a capabilit.y it must be escaped in octal

nrmc

5/1Q/80

-

.

3 _(''" !
----~~.:::~-~
=-~=============:~~~~~~~-------------.-.-.....--- --_ .. _-..
.
---

..

-.-

....

----

TE?.M CAP ( 5 )

-•

If tabs on the terminal ~qUl1'e padding. or it the t.erminal. uses a character ot!ler
Ulan -1 to tab. then this can be .iven as t.a.
Hazeltine terminals. which don't allow· ... • characters to be printed should inciicate hz. Datamedia t.arminais. which ecb.o carnage-return Unefeed for car:-:age
. retur:l and then ignore a folloW'ini linefeed should indicate nco Early Concept
. terminals. which ignore a lineteed immediately &.iter an am Wl'ap. should indireate %n. II an erase-eol is required to let rid of standout (instead ot merely
wnting on top of it). D should be .iven. Teleray ter.::linals. where tabs turIl all
= characters moved over tQ blanks. should ill die ate :n. OUler spec~c ter~
"pr1:)blems may be corrected by adding more capabilities ot the form %:.
OUler capabilities include is. an initialization st.ri.ng ror the terminal. and if. the
name ot a Ole containing lOIli initialization st.r'inis. These strings ue expected
to properly clear and then set the tabs on the terminal. 1! the terminal has settable labs. II ooth are given. ia lrill be printed betore if. This is usetul where if lS
.I\I..s'7"/tib/tabsat/std. but ia clears the tabs ~
Smilar fermmm
II there ue two very similar terminw. one can be de~ed as beilli just like the
oUler with certain exceptioDS. The stri.n& capability t.c can be Ilven With the
name ot the similar terminal. This capability must be wt and the combined
tellith of the two entries must not exceed 1024. Since trrrm.lib r1:)utines seut:b.
the entry {rem lett tQ riiht. and since Ule tc capability is replaced by t.he
correspondi.n.i entry. the capabilities given at the lett override the ones in the
similar terminal. A capability can be cancelled wiUl %XO where xx i5 t..!le capabH1ty. For example. t.b.e entry
bn 12e21nl:k~O:keO:t.c:2S21:
dl~.s a 2S21:l1 t.b.at does !lot have t.b.e lu or k. capabilities. and hence :'oes not
turn on the function key labels when in T1SUal mode. Tbls is useful (or d~er~nt
modes tel'l. term 1n"!' or for dit!erent user preferences.
letc/termcap

me containing tarminal descriptioDS

sa .lLSC
.x{l). cunls(3). tarmca.p(3). uet(l). vt(l). w(l). mon(1)
m'I'BOR
'It'ill1am Joy
llar~

Horton added underlin1J:li and

~eypad

support

E= alloW'S only 2~S charactan for 1t.ril1i capab1l1tJes. and the ~utine! in
trrm.ca.p(3) do not check tor over'dcW cf this bw!er. The total leIlitb. of a sUliie
entry (excludin& only escaped newlines) may :let exceed 1024.
The ma. ft. and f t entries UI spec~ tQ the vi Pl"1:)&ral=Net I.J.l pl"1:),r~ support all entries. There are entries that ue not supported
by Uly ?~irar::l..

1

S/lO/SO

B

mnx Programmer's lb.nual

TER.\!CAP ( 5 )

x.

TERMCAP(5)

Uke ~c

adds: to value. then ~.
X>xy U value> x adds y. no output.
XI'
reverses order of line and column. 110 output=.
mcrements Une/column (for 1 oriam)
=: lives a 1;"'~le ~
k
exclusiv;;r row and column With 0140 (DM~OO)
D
SCD (11S-(X/l0» • (~10). no output.
XI)
Reverse cod1n& (x-Z·(X::16». 110 output. (Delta Data).
COnsider the HP2645. which. to let to row 3 and column 12. needs to be sent
\E&a12c03Y padded tor S milliseconds. Nole that the order of t.he rows and.
columns is inverted here. and t.hat the row and column are printed as two digits.
Thus its cm capabWty 1s "cm=6\.E&~r~2c;:2r·. 'I'h. Jdicrolerm ACT·rv l1eeds the
current. row and colw::nn sent. preceded by a "T. With the row and column simply
encoded in binary. "cm="~.;C.". Terminals which u.se .. ~.'. l1eed to be able to
backspace the cursor (btl or IM:). and t.o move the cunor up one line on the
ICreel1 (up introduced below). This 1. l1ecessary because it. is 110t always sate to
transmit,t. \D .. ]) and \ro. as t.he system may chanae or discard them.
A anal example 1s the LSI AllIl-3a. wbicD. u.ses row and column o~et by a bla.c.k
character. thus "cm=\E=:;. :;. ".
~.x

t·

o

Cw-wor moUoa.

If the t.erminal can mema the cursor one positiol1 to the ",ht. teaVina the char!.ctar at the current position unchanaed. then this seCluence should be liven as nd
(non-Gestructive space). U 1t can move the curlor up a line on the screen in the
Ame column. t.llis should be liven as up. It the terminal has 110 cursor address1D& capability. but can home the cursor (to very upper lett corner ot screen)
then this can be liven u ho: limilarly a fast way ot letl1n& to the lower lett hand
corner can be liven as U: this may involve lOi%1& up With up trom the home position. but the editor will l1ever do this itself (unless 11 does) becau.se it makes 110
assumption about the et!ect ot moVln& up trom the home position.
Area clean
11 the terminal can clear from U1r. current position to the end of t.he Une. 1eaVil:li
the cursor where 1t 1s. tbis SD.ould ~e liven u ceo If the terminal can clear from
the current posiUon to the end ot ~he display. then this should be liven as cd.
The editor only u.ses cel from the &-st column of a l1ne.
rnsert/delet.e llDe
If the t.erm1Dal can open a ne" 'blank Une betore the line where the cur. or is.
th1I SD.ould be liven as a1: this La done only from the &-st poSiUan of a line. The
cunor must then appear on the ne"ly blank Une. If the terminal can delete the
Une which the cursor 1s on. then this should be liven as dL this is done only trom
the &-st posiUon on the line to be deleted. If the terminal can acrell the screen
backwards. then thia can be liven as ab. but lust a1 .Wfices. If the term.1w can
ret.a1D display memory above then the da capability should be liven: if display
memory can be retained belo" then dI» mould be liven. These let the editor
understand that. deletina a Une on the screen may brma 110n-blank l1lies up trom
below or that. ICrollin& back With ab may brin& doW'll 110n-blank u.n.•.
lIuerV delete charac:t.

lSI 10/80

3-g3
--=:""'::'=-___
., _...
----- ._-_. ____
._ ........ -.----

--=:-~~~~~~~=~~.....---

0,

TERM CAP ( 5 )

Codes to begin under!1.n1Dg and end underlinini can be given as us and ue
respectively. II the terminal has Il code to underline the current character ana
move the cursor one space to the Maht. such as the Microterm Mime. this can ~e
,iven as UC. (If the underline code does not move the cursor to the right. glve
the code followed by a nondestructive space.)
ltthe termin!.! boas a way of Oashi%li the screen to indicate an error quietly (a
b41Lreplaceme.nt) then this can be iiven as Tb; it must not move the cursor. If
tHe 'terminal should be placed in a d~erent mode during open and Visual modes
ot: .:. Ws can be given as n and ft. lent at. the start and end of these modes
respectively. 'I'hese can be u.sed to cha.ngl. I.i .. from a underline to a block curlOr and back.
'

It the terminal needs to be in a special mode when runn.ini a program that
addresses the cursor. the codes to enter and eXit this mode can be iiven as ti
and te. Th1s artses. tor example. trom terminals Uke the Concept with more
than one page of memory. II the terminal has only memory "lative cursor
admssiIli and not Icnen relative curlor addr.ss1n&. a one .creen-sized wmdow
mu.st be ~ed into the tarminal for cursor addrulin& t.o work properiy.
If !our terminal correctly ,enerates underUned charact.en (with no Ipecia!
codes needed) even thoUib. it does not overstrike. then you sb.ould give the capab1l1ty ul. II overstrikes are erasable with a blank. then this sb.ould be lnci1cated
by iiVin& eo.
Xeypacl

If the terminal !:las a keypad that transmiu codes when the keys are pressed.
~ information can be given. Note that 1t is not possible to hancile terminals
where the keypad only works in local (this appUes. tor example. to the U%Uhifted
HP 2S21 keys). II the keypad can be set. to transm1t. or not transmit. ,ive these
codes as ka and n. Otherwise the keypad is assumed to always transmit.. 'I'he
codes sent. by t.he lett arrow. right arrow. up arrow. dowu arrow. and home keys
can be iiven as kl. la. m. kd. and kh respectively. II there are function keys
Nch as to. fl ....• t9. the codes they send can be given as leO. kl •.••• Jd1. If these
keys have label. other than the default to lhrou,h i9. the labels can be liven as
10. 11 ••••• 18. If there are other keys that transmit the lame code as lb.e terminal expect. tor t.h.e correspond..1n& function. IUcb. u clear screen.. the '.rm.cap 2
letter codes can be ,iven 1D the ko capabil1ty. tor example. ":ko=cl.l1 .•f .• b:".
which lays that the terminal h.a.s clear. home down. scroll dowu. and Icroll up
keys that transmit the same t..b.1.lla as the cit U. If. and sb entriel.
The ma entry 11 also used to lrlci1cata arrow keys on t.erminals which have slnile
charact.er arrow keys. It is obsolete but Itill in u.se in "nion 2 of Vi. which must
be run on lome minicomputers due to memory l1m1tatiolU. Th1s d.lei 1. reduneiant with k1. kr. ku. kd. anei kh. It consiSts of ,roups ot two characten. In each
,roup. the Orst charact.er is wnat. an arroW' key lends. the second character is
the correspond1na Vi commanci. 'I'hes. command. are J:L tor Jd. J for kcL k tor ku.
1 for kr. and B for kb.. Tor example. the mime would be :ma=-lQ-Zk-X1: lnci1cat1DC arrow leeys lett (-H). dowu (-!C). up (-Z). and "aht. (-Xi, (There 1a no home
key on th. mime.)
llllceUaneoWi
If the tarminal requires other thAll a :lull (zero) charact.er as a pac1 then t.l:ls
can b. given u pc.

I

5/10/80

.--_ - .... - .. ---.
..

.' -

,3-~~

7

URIX ProgrUlJller' s llanual

!"tiYiPB (5)

"rt'iYiPB (5)

NAME
ttytype

- data base def ining terminal type1 used for
associating terminals with serial ports

DESCRIPTION
The ttytype data base is used to associate a manufacturer's
terminal with the different serial ports on the system.
Each line contains the name of a terminal, a tab character,
and then the XENIX device entry for the serial ports
associated with that terminal.
The terminal name must
correspond to an entry in /etc/termcap.
Making an entry in the ttytype file for your terminals
allows the system to make maximum use of terminal features
for certain system facilities that use full screen
capabili ties. Among these programs are vi (1), bsh (1), and
ua (1) •
FILES
/etc/ttytype
SEE ALSO
vi(l), bsh(l), ua(l), termcap(5)
USAGE
A typical line in the tty type file might look like ndumb
/dev/tty3 n or nwyse /dev/tty5. n The first says that serial
port 3 is connected to a terminal described in /etc/termcap
as having no special characteristics such as cursor movement. The second entry tells XENIX that serial port 5 is
connected to a terminal manufactured by Wyse Technology that
is described in termcap under the name nwyse. n The terminal
name is the name found between the first and second vertical
bars of the appropriate entry in /etc/termcap.

3-87

ALTOS 586 COMPUTER SYSTEM

XBNIX PROGRAMMER' S REFERENCE GUIDE

Appendix A
BARD DISK ORGARIIATIOH
CONFIGURATION

The built-in internal l0-megabyte hard disk on the 586
System is configured as follows:

CYLINDER

o
1-40

Bootstrap program
Swap area

40-41

Alternate-sector area

42-end

XENIX file system

A-l

ALTOS 586 COJIPUTER SYSTEM

UNIX PROGRAMIIBR' S REFERENCE GUIDE

LOGICAL DEVICES

The following logical devices are defined in the Altos
configuration of XENIX.

Logical Devices - Integral Bard Disk

LOGICAL DEVICE

DESCRIPTION

0

hd0

all of hard disk (without sector
mapping).

1

hd0a, swap

swap area.

2

hd0b, root

root file system.

3-8
9

unused.
hd0.spares

10

spare blocks for alternate sector
mapping.
future expansion.

11

hd0. track0

all of track 0.

12

hd0.boot

primary bootstrap on track 0.

13

hd0.roc0

rest of cylinder 0. (Consists of
cylinder 0 except for track 0.)
Used for fsck temporary file.

14

hd0.1ayout

layout information.

(See layout

(1» •

15

hd0.secmap

mapping information for alternate
sectors (See map (1».

A-2

ALms 586 COIlPOTER SYSTEM

UNIX PJlOGRAIUIBR' S REFERENCE GUIDE

Appendix B

FLOPPY DISKETTE ORGARIIATION
CONFIGURATION

The floppy disk organization for a bootable XENIX File
system is as follows:
TRACK

0-54

Xenix file system

55-end

Swap area

LOGICAL DEVICES

The following logical devices are defined in the Altos
configuration of XENIX:
DEFINITION

LOGICAL DEVICE

fd0
fd0.swap

0-end
55-end

"Pseudo-tape" (see below) or
file sy stern
swap area

B-1

ALTOS 586 COIlPOTER SYSTEM

UNIX PROGRAMMER' S REFERENCE GOlDE

BOOTIIJG FROM FLOPPY DISKETTE

XENIX is not setup to be run in multiuser mode after booting
from the floppy diskette. Of course, it is fine to access a file
system on the floppy diskette after booting off hard disk.
DISUTTES AS PSEUDO-TAPE

The floppy disk may be used sequentially as a "pseudo-tape",
for example, by the ~ utility. The command:
tar c filel file2

archives filel and file2 to the device /dev/tar, which is usually
equivalent to the floppy disk device /dev/fd0
These files may be recovered from that diskette with the
command:
tar x

For information on using this utility, see the section,
"Saving and Restoring Files Using ..tll" in the AI tOB Introduction
to XERIX Manual.

B-2

UNIX PROGltAIUIER' S REFERENCE GUIDE

ALTOS 586 COIlPOTER SYSTBJI

RANDOM ACCESS DISUftE PILES
When diskettes are used with the..t..A.1: utility, they are treated as
sequential files.
Files on those diskettes are read from
beginning to end, as with tape files.
It is also possible to have -Random-Access R files on diskette.
XENIX can use random access diskette files in the same way it
uses the hard disk files. You can have additional files that you
load into the system when needed and unload when not.
Initializing Diskettes as

Rando~Access

Piles

To use a diskette in this fashion, you must first initialize it
with an empty file system as follows:
1.

If necessary, format the diskette using the format utility.
After the XENIX prompt, enter format , and follow the
instructions given.

2.

Insert (load) the formatted diskette.

3.

Enter
/etc/akfs'/dev/fd8 1441
Although the newly created file system is physically loaded,
you must "mount" the file system before you can use it.
Mountinc.; gives XENIX the information to link the diskette
with its own file system on your hard disk.
Similarly, you must Rdismount" (or unlink) the file system
on the diskette before physically unloading that diskette.

Mounting a Diskette
Whenever
mounted:

a diskette file system is loaded,

1.

Insert (load) the diskette, if necessary.

2.

Enter

/etc/mount

it must be

/dey/fdl /fd

You may now access the diskette's file system through the
directory Ifd.
You can treat this directory as you would a directory on the
hard disk. You can create files on it, transfer files to
this directory, change or remove these files, etc.

B-3

ALTOS 586 COMPUTER SYSTEM

XDIX PROGRAMMER' S REPEREIICE GUIDE

Dismounting a Diskette
Before removing a mounted diskette, it must be dismounted:
1.

Enter
/etc/uaount /dev/fdl

2.

Remove (unload) the diskette from the drive.

As with .tAr diskettes, these diskette files should be
labeled with a meaningful description and dated, and kept in
a safe location when not being used.

B-4

ALTOS 586 COIlPOTER SYSTEJI

/

UNIX PROGRAIUIER.' S REFERENCE GUIDE

.'

APPENDIX C
SERIAL LIRE PRIIn'ER ABO SPOOLER
STANDARD PRINTER CONFIGURATION

In the Altos implementation of XENIX, serial port 6 is configured
for a serial printer operating at 9600 baud. The logical device
name "/dev/lp" may be used to refer to this port, and the l.J2.I
utility references this device automatically for printing and
spooling.
Th e 1 p rut iIi t y ass u mest hat 0 n 1 yon e p r in t e r , / d e v / 1 p, i s
attached to the system. If you want to connect more than one
printer, refer to the "Connecting More Than One Printer" section
of thi s appendi x.
Printer spooling is a technique that mediates printer activity in
a manner that allows all users of the system to share a printer
without conflict.
Files to be printed are copied to a spool
directory (/usr/spool/lpd) and a background process moves those
copies to the line printer device. This device is found in /dev,
and is called "lp" (lpl, Ip2, etc). Files in /dev are known as
"special files", and are the interface to UNIX I/O.
For an
expanded discussion of special files in specific and I/O in
general, see sections 29-32 of the UNIX Progra • • er's Ranual,
Volume 2B. A great deal of this material is specific to the PDP11, however the mechanisms are the same as those for the Altos
586 computer system.
Any of several programs may be used to copy material to printer
devices. For example:
cat /usr/john/doc

>

/dev/lp

C-l

AL'l'OS 586 COMPUTER SYSTEM

XERIX PROGRAMMER' S REFERENCE GUIDE

This command copies the file "/usr/john/doc" directly to the
def aul t pr inter. If you have mor e than one pr inter, the def aul t
printer is the one that is most used. This has three possibly
undesirable effects:
1.

If /usr/john/doc is a big
take some time to complete.

file,

this

command

may

2.

If another user is copying a file to the printer at the same
time, the result is probably not what anyone intended.

3.

Since the ~ program knows nothing about printers, and
therefore nothing about baud rates, page sizes, margins,
etc., the resul t may not be what is expected.

The ~ utility program is used to control printer requests.
This program knows something about printers, how to set baud
rates, etc.
To invoke the

~

utility, enter:

IprN [file_list]
Where: "Nil is a digit from 0 to 5 and selects one of 6 printers.
Lpr may be invoked without entering a valve for "N" by entering:
lpr [file_list]
This command assumes the default printer, Ip, and has the same
effect as entering:
lprl [file_list]
The ~ program copies the files in [file_list] to a spool
directory and returns immediately to the invoker.
Sometime
later, perhaps up to 10 seconds, a printer (if not already busy)
will begin printing. The printers themselves are physically
connected to serial ports.
B.ARDWARE CONNEC'l'IONS

The connection between the 586 computer system and a printer is a
cable which has 25-pin subminiature D-type connectors.
The
computer's port hardware is "female", which requires that the
computer side of a cable have a "male" connector. Most printers
also have "female" port connectors: a compatible cable should
have a "male" connector on each end. The most commonly used
cables have at least pins 2, 3, and 20 connected from end to end.

C-2

IERIX PROGRAMMER'S REFERENCE GUIDE

ALTOS 586 COIlPUTBR SYSTEII

Printer control of computer output is accomplished by either of
two methods:
1.

The printer should be configured to use the X-ON, X-OFF
protocol, because XENIX uses this protocol to control the
flow of data to the serial printer. This method requires
that the printer send an X-OFF control code to the computer
when overrun is about to occur.
An X-ON control code is
sent when it is safe for output to the printer to continue.

2.

The second method controls the RS232C DTR (signal 2~) signal
to accomplish the same result.
If you wish to use this
method, be sure that the cable which connects the pr inter
and the computer has this conductor.

CORREcrIRG MORE 'l'IIAII ONE PRDlTER
If you want to connect more than one printer, you should:
1.

Log in as super-user (root).

2.

You need to create appropriate device files in /dev. This is
done with the In command. First, select which printer is to
be the default printer. This printer should be the mostused printer in the system.

To make the default printer device available for reassignment,
enter:

mv /dev/lp /dev/olp
Next, select the port to which this printer is to be connected,
by entering:

ln /dev/ttyp /dev/lp
Where: "P" is the port number of the serial port.
Next, configure the system for the additional printers to be
supported, selecting which printer number (1-6) they are to be,
and the number of the serial port which they ae to be connected,
and enter:

ln /dev/ttyp /dev/lpR
Where: "P" is the serial port number, and "N" is the printer
number.
It is suggested that "P" and "N" be the same number to
alleviate the confusion that occurs when printer 5 is connected
to port 3.
.
Next, repeat the above
supported.

~n

command for each printer to be

C-3

ALms

3.

586 COJIPU'l'ER SYS'l'BII

XBBIX PROGRAMMER' S REPBRBRCE GUIDE

You need to make file names for invoking the Ipr program.
For each printer device file made in the previous step,
enter:

In /bin/lpr /bin/lprR
Where: "N" is a printer number.
4.

You need to create spool directories. These directories are
used to hold copies of material to be printed for each
printer. For each printer device file made, enter:
mkdir /usr/spool/lpdN
Where: "N", as above, is a printer number.

NOTE: The default directory is already installed, do not try to
create it. If any of the printers have baud rates other than
9600, refer to the next section "Changing/Setting Baud Rates".
CBAa;IRG/SEftIRG BADD RAIf'ES

If you want to change or set a terminal or printer to a a
different baud rate than 9600, you should perform the following
steps.
The /etc/ttys file contains entries of the form:
l2ttyP
The above line is interpreted by various system programs. The
first digit ("1" in the above example) tells the system to
attempt to log on ttyP ("P" is a serial port number). The second
digit specifies the baud rate for that particular terminal (see
Baud Rate list below or GETTY(8) in volume I of the URIX Programmer's Manual for the baud rates associated with these values.)
For each printer to be supported, type a "disable" command for
the corresponding serial port. This ensures that the system will
not attempt to log on a port which is dedicated to a printer.
For example, if a printer is set up for port 6, enter:
disable tty6
Now, for each printer to be supported,
/etc/ttys that has the following format:

add a line to file

IBlpR
This line may be anywhere in the file. No spaces are permitted
between portions of the line. "B" is a baud rate argument from
the list below. "N" is the printer number.

C-4

AL'l'OS 586 COIlPOTBR SYSTEM

UNIX PROGRAIUIER' S REPDEIICB GUIDE

If the default printer's baud rate is other than 9699, add:

'Blp
NOTE:
Printers whose baud rate is 9699 do not require a corresponding
line in /etc/ttys.
Baud Rates

"B" VALUES
9

1
2

3
5
6
7

BAUD RATE
399
150
9690
1200
300
2400
4800

CONPlGURIIK2 SYSTEM WI'l'BOUT A PRINTER

If you wish to support six terminals
should:

(with no printer),

1.

Log in as super-user (root).

2.

Remove the lp entry in /dev by entering

you

rm /dev/lp
3.

Enable the login and shell on port 6 by editing the line
referencing tty6 in the file /etc/ttys from "02tty6" to
"12tty6", before going multiuser.

C-5

ALTOS 586 COIlPOTBR SYSTEM

UNIX PROGRAMMER' S REFERENCE GUIDE

Appendix D
LIST OF TERMrRAL CAPABILITIES
The basic XENIX system works with nearly all the generally
available terminals, by making use of a standard "lowest common
denominator n of terminal capabilities.
However, some of the
XENIX utilities, including many especially useful utilities, can
make use of special terminal capabilites. A major example is the
Business Shell.
For this reason, the /etc/termcap data base has been
developed to describe terminal capabilities. The following pages
give essential information extracted from /etc/termcap,
in a
form more easily understood that when the file itself is viewed.
The information given describes all terminals currently supported
for special use by the Altos release of the XENIX operating
system.

Custoaizing Your Altos XBNIX systea
The following information explains how to inform XENIX of
the special capabilities of the terminals~you are using with the
system.
The XENIX utilities, such as the Business Shell, that make
use of special terminal capabilities access the file
/etc/ttytype, which defines the type of the terminal attached to
each serial port.
It may be necessary to edit this file to
provide the correct terminal type for each port. Each line in
/etc/ttytype has two fields; the terminal type, and the associated port number.
The "terminal type" used in /etc/ttytype is the second field
of the appropriate terminal entry in the /etc/termcap data base;
that is, it is between the first two vertical bars, "I", in the
entry.
On the following list of "Terminals Supported by the

D-l

AL'l'OS 586 COIlPOTBR SYSTBII

DIUX PROGRAMIIER' S RBFBRBRCB GOlDE

XENIX Opera ting System," the entry called "name of terminal" is
the proper reference. When editing /etc/ttytype, use that name
as the "terminal type." Any editor that is convenient can be
used. Change the terminal type, if necessary, for each active
serial port that your system uses.
(See TTYTYPE(S) in the
utility Reference Section for more information about
/etc/ttytype. )
For example, if you are using a TeleVideo terminal, current
model 92~, when you consult the following list you will find a
group of entries for Televideo. The appropriate entry is "920b."
Editing /etc/ttytype, you find that all ports are associated with
"wyse." Change the port assignments you are using, or all port
assignments, to "92~b" and update the file.
If you do not find a listing for the terminal you are using,
consult your dealer or Altos Customer Support.

D-2

ALTOS 586 COIlPOTBR SYSTEM

UNIX PIlOGRAIUtER' S REFERENCE GUIDE

Terminals Supported by the XBNIX Operating System
The material below is derived from the system
file/etc/termcap.
This file describes terminal capabilities and
characteristics.
The use of this file is to support screenoriented programs, such as vi. The /etc/termcap file is composed
of a description entry for each supported terminal (and sometimes
more than one, if the terminal has options, or is part of a
family of products).
This document cites the name by which a particular terminal
is known to the system, and contains a short description of the
terminal, including the manufacturer's name, and other useful
information. Included are comments relevant to the lIse of the
terminal.
an example:
wyse

WYSE WY-HH'

this entry indicates that the WYSE WY-100 terminal is supported by the system and that its name is 'wyse' (case is
significant) •
The 'name' of a terminal is specified to several system
progr ams. Among them are:
the shell (sh):
% TERH

=

name; export TERM

the C shell (csh):
# setenv TERM name

or, for the default definition of a port.
a typical line in /etc/ttytype:
name

tty5

Please reference the appropriate documentation for an
expanded explanation of the capabilities and uses of the above
programs and structures.
Terminal naming conventions:
Terminal names look like:
(manufacturer>  - 
Certain abreviations (e.g. cl00 for conceptl00) are also
allowed for upward compatibility. The part to the left of the
dash, if a dash is present, describes the particular hardware of
the teminal.
The part to the right is used for flags indicating

ALms 586 COMPOTBR SYSTEII

DNIX PROGRAIUIBR' S RBFBRBBCB GUIDB

special ROM's, extra memory, particular terminal modes, or user
preferences. Names are always in lower case, for consistency in
typing.
The following are conventionally used for flags:
rv
2p
w
pp
na

Terminal in reverse video mode (black and white)
Has two pages of memory. Likewise 4p, 8p, etc.
Wide - in 132 column mode.
Has a printer port which is used.
No arrow keys - termcap ignores arrow keys which are
actually there on the terminal, so the user can use the
arrow keys locally.
Special manufacturer codes:
A:
M:
q:
s:

hardcopy daisy wheel terminals
Misc. (with only a few terminals)
Homemade
special (dialup, etc.)

the terminals:
NAME OF TERMINAL
wyse
du
hp
2621-nl
2621
2621-wl
h19-u
h19-us
h19-bs
h19
cl1313-rvs
c100-s
cl130-rvna
c10C!J-rvpp
cl13 0
cl13C!J-rv
adm3a
adm3
mime
bg
vt52
gigi

DESCRIPTION
WYSE WY-l13 0
dialup
Hewlett-Packard
HP 2621 with no labels
HP 2621
HP 2621 w/labels
Heathkit with underscore cursor
Heathkit w/keypad shifted/underscore
cursor
Heathkit w/keypad shifted
Hea thki t h19
slow reverse Concept 1130
slow Concept 10"
cll313 with no arrows
cll313 with printer port
Concept 11313
cll313 rev video
LSI ADM3A
LSI ADM3
Microterm Himel
BBN BitGraph terminal
DEC VT52
DEC GIGI

D~4

ALms 586 COIlPDTBR SYSTBIl

A:

DRIX PROGRAIUlBR' S RBFBRERCB GUIDE

DAISY WHEEL PRINTERS

The A manufacturer represents Diablo, DTC, Xerox, Qume and
other Daisy wheel terminals.
1620
1620-m8
dtc
dtc300s
gsi
aj830
5520
qume5
x1720

Diablo 1620
Diablo 1620 w/8 column left margin
DTC 382 with VDU
DTC 300s
Anderson Jacobson
NEC Spinwriter 5520
Qume Sprint 5
Xerox 1720 same as the Diablo 1620

C: CONTROL DATA
cdc456
cdc456tst

CDC
CDC

D: DATAMEDIA
dm1520
dm2500
dm3025
3045
dt80
dt8f(Jw

Datamedia
Datamedia
Datamedia
Datamedia
Datamedia
Datamedia

1520
2500
3025a
3045a
dt80/1
dt80/1 in 132 char mode

H: HAZELTINE
h1000
h1552

Hazeltine 1000
Hazel tine 1552
(be sure auto If/cr switch is set to cr)
h1552rv
Hazeltine 1552 reverse video
h1420
Hazeltine 1420
Hazel tine 1500
h1500
h1510
Hazeltine 1510
h1520
Hazel tine 1520
h2000
Hazeltine 2000
I:

IBM, INTERACTIVE SYSTEMS, AND INTECOLOR

8001
ISC8001 Compucolor/Intecolor
compucolor2
CompucolorII
intest
Interactive Systems Corporation
(modif ied PE Owl 12000
ibm
IBf.l 3101-10
M: MISCELLANEOUS TERMINALS
tab132
tab132w
tab132rv
tab132wrv

TAB
TAB
TAB
TAB

132/15
132/15
132/15
132/15
D-5

ALTOS 586 COMPUTER SYSTEM

XBRIX PROGRAMMER' S REPERERCB GUIDB

mw2
trs80
d800

Multiwriter 2
TRS-80 Radio Shack Model I
Direct 800/A

vc404
vc404s
vc404na
vc404sna

Volker-Craig
Volker-Craig
Volker-Craig
Volker-Craig

vc303a
vc303

404
404 w/standout mode
404 wino arrow keys
404 w/standout mode and
no arrow keys
Volker-Craig 303A
Volker-Craig 303

ampex
d132
soroc

Ampex Dialogue 80
Diagraphix 132a
Soroc 120

tec400
tec500
tec

TEC scope
TEC 500

teletec
Teletec Datascreen
Digilog 333
diSilog
ep48
Execuport 4080
terminet1200
GE Terminet 1200
aed512
AED 512
datapoint
Datapoint 3360
falco
Falco TS-l
dg
Data General 6053
cdi
CDI 1203
(AS is an arrow key. not recommended for use)
sol
x183
Cybernex XL-83
Omron 8025AG
omron
plasma
Plasma Panel
swtp
Southwest Technical Products CT82
terak
Terak emulating Datamedia 1520
CB unix virtual terminal
virtual
delta
Delta Data 5000
Cybernex MDL-110
mdll10
zen30
zentec 30
N: ANN ARBOR
aa
aaa-18
aaa-20
aaa-22
aaa-24
aaa-26
aaa-28
aaa-30
aaa-36
aaa-40
aaa-48

Ann
Ann
Ann
Ann
Ann
Ann
Ann
Ann
Ann
Ann
Ann

Arbor
Arbor
Arbor
Arbor
Arbor
Arbor
Arbor
Arbor
Arbor
Arbor
Arbor
D-6

4080
Ambassador/18
Ambassador/20
Ambassador/22
Ambassador/24
Ambassador/26
Ambassador/28
Ambassador/30
Ambassador/36
Ambassador/40
Ambassador/48

lines
lines
lines
lines
lines
lines
lines
lines
lines
lines

ALms 586 COIlPUTER SYSTEM

XENIX PROGRAMMER' S REFERENCE GUIDE

aaa-60
Ann Arbor Ambassador/60 lines
aaa
Ann Arbor Ambassador
aaa-db
Ann Arbor Ambassador 30
(destructive backspace)
T: TELETYPE
33
43
37

Model 33 Teletype
Model 43 Teletype
Model 37 Teletype

V: VISUAL
vi200
vi20111-rvic
vi2111111-f
vi2111111-rv
vi211l0-ic

Visual 2111111 with function keys
Visual 21110 revers video using insert
character
Visual 2111111 no function keys
Visual 2111111 reverse video
Visual 21110 using insert character

X: TEKTRONIX
tek
tek40l3
tek40l4
tek40l5
tek411114-srn
tek40l5-sm
tek411123
411125
411125-17
4025-l7ws
4025ex

Tektronix 411112
Tektronix 4013
Tektronix 4014
Tektronix 4015
Tektronix 411114 in small font
Tektronix 411115 in small font
Tektronix 411123
Tektronix 411124/4025/4027
Tektronix 4025 17 line window
Tektronix 4025 17 line window in
workspace
Tektronix 4025 wi!

a: ADDS
Regent: lowest common denomina tor, wor ks on all regents.
regent

ADDS Regent Series - works on all of
series.
regent100
ADDS Regent 100
regent20
ADDS Regent 20
regent25
ADDS Regent 25
regent40
ADDS Regent 40
regent60
ADDS Regent 60
regent60na
ADDS Regent 60 wino arrow keys
a980
ADDS Consul 980
Note:
If return acts strangely on a980, check internal
switch 2 on the top chip on the Control PC board.
viewpoint
ADDS Consul 980

D-7

AL"l'OS 586 COIlPUTER SYSTBII

UNIX PROGRAMMER' S REFERENCE GUIDE

b: BEEHIVE
sb2
bh3m
superbeeic
microb
sbl

fixed Super Bee
BeehivellIm
Super Bee with insert character
Micro Bee series
Beehive Super Bee - fl=escape, f2=AC.

c: CONCEPT (HUI-IAN DESIGNED SYSTEMS)
There seem to be a number of different versions of the C108
PROMS. The first one that we had would lock out the keyboard if you sent lots of short lines (like /usr/dict/words)
at 9600 baud. Try that on your C108 and see if it sends a
AS when you type it. If so, you h a v e an old v e r s ion 0 f the
PROMs. The old one also messed up vi with a l32-character
line-length. You should configure the C108 to send AS/A Q
before running this.
c108
c108

Concept 108 w/8 pages and AS/A Q
Concept 108 w/4 pages and AS/A Q

Concepts have only window relative cursor addressing, not
s c r e en reI a t i v e.
To get i t t 0 w0 r k, a 0 n e pa 9 e win dow
scheme is used for screen style programs.
d: DEC (DIGITAL EQUIPMENT CORPORATION)
It is assumed that you have smooth scroll off or are at a
slow enough baud rate that it doesn't matter (12007 or
less). Also this assumes that you set auto-nl to on; if you
set it off, use "vt100-nam."
The xon/off switch should be on.
vt100
DEC VT100
vt100
VT100 wino am
gt42
DEC GT42
vt132
VT132
gt40
DEC GT40
vt50
DEC VT50
dwl
Decwriter I
vt50h
DEC VT50h
ovt100
old DEC VT100
vt100-s
DEC VT100 132 cols 14 lines
w/o advanced video option)
vt100-w
DEC VT100 132 cols (w/advanced video)
dw2
Decwriter I I
dw4
Decwr iter IV

D-8

ALTOS 586 COMPUTER SYSTEM

UNIX PROGRAMMER' S REFERENCE GUIDE

h: HEWLETT PACKARD
2621-A
2621 wlnew ROM, strap A set
HP 2621 with 45 keyboard
2621-45
(should be used at 48eleJ baud or less)
hp2645
HP 264x series
hp2626
HP 2626
(should be used at 48eJ0 baud or less)
hp2648
HP 2648a graphics terminal
264el
HP 264eJa
264elb
HP 264x series
2621-48
HP 48 line 2621
2621-nt
HP 2621 wino tabs
(2621 with no labels ever)
i: INFOTON (GENERAL TERMINAL)
ileJel

General Terminal 10eJA
(formerly Inf oton leJ el)
i4el0
Infoton 400
addrinfo
infotonKAS
k: HEATHKIT (ZENITH)
h19-a

Heathkit H19 ANSI mode

1: LEAR SIEGLER (ADM)
If the adm31 gives you trouble with standout mode, check the
DIP switch in position 6, bank @cll, 25% from back end of
pc. Should be OFF. If there is no such switch, you have an
old adm31 and must use oadm31.
adm31
adm2
adm42
adm5
adm3a+
oadm31

LSI adm31
LSI adm2
LSI adm42
LSI adm5
ADM3A PLUS
old ADM31

m: MICRTOTERM
These mimel entries refer to the Microterm Mime I or Mime
II. The default mime is assumed to be in enhanced act iv
mode.

D-9

ALTOS 586 COIlPOTER SYSTEM

~'

UNIX PROGRAIUlBR' S REFERENCE GOlDE

mime3a
Mimel emulating 3a
microterm
Microterm Act IV
microterm5
Microterm Act V
act5s
skinny act5 - Act V in split screen mode
mime-fb
full bright Mimel
mime-hb
half bright Mimel
mime2a-s
Microterm Mime2a
{emulating an enhanced Soroc IQ120)
{but "'X can't be used a a kill character)
mime2a
Microterm Mime2a
(emula ting an enhanced vt52)
mime-3ax
Mimel emulating enhanced 3a
p: PERKIN ELf.1ER
pe550
fox
owl

Perkin-Elmer 550
Perkin-Elmer 1100
Perkin-Elmer 1200

s: SPECIALS
Special "terminals'. These are used to label tty lines when
you don't know what kind of terminal is on it. The characteristics of an unknwn terminal are the lowest common
denominator - they look about like a TI 700.
arpanet
bussiplexer
ethernet
Ipr
dumb
switch

networ k
network
lineprinter
unknown
intelligent switch

t: TEXAS INSTRUMENTS
ti
ti745
ti800

TI Silent 700
TI Silent 745
TI Omni 800

v: TELEVIDEO
Note: The 912 has a  key that's like shift: 8 xmits
n"'A8/r".
The 920 has this plus real function keys that xmit
different things. Termcap makes you use the funct key on the 912
but the real keys on the 920.
tvi912
912b
920b
tvi912-2p
tvi950-ap
tvi950-b
tvi950-ns

TVI920 old TeleVideo
TVI new TeleVideo 912
TVI new TeleVideo 920
TeleVideo w/2 pages
set to page 1 when entering ex or vi.
reset to page 0 when exiting ex or vi.
TV! 950 w/alt pages
bare TVI 950 no is
TVI 950 wino standout
D-10

ALms 586 COJIPOTER SYSTEM

UNIX PROGRAMIlER' S REFERENCE GUIDE

Note: The following TVI descriptions are for all 950's.
the following attributes:

It sets

full duplex
write protect off
conversation mode
graphics mode off
white on black
auto page flip off
turn off status line
clear status line
normal video
monitor mode off
edit mode
load blank character to space
line edit mode
enable buffer control
protect mode off
local edit keys
program unshifted send key to send line all
program shifted send key to send line unprotected
set the following to nulls:
field delimiter
line delimiter
start-protected field delimiter
end-protected field delimiter
set end of text delimiter to carriage return/null clear all
column tabs
tvi950
Note:

TeleVideo 950
tvi950 sets duplicate (send) edit keys (\El) when
entering vi and sets local (no send) edit keys (\EK)
when exiting vi

tvi950-2p
Note:

TeleVideo 950 w/2 pages

tvi950-2p is for 950 with two pages adds the
following:
set 48 line page
place cursor at page 0, line 24, column 1
when entering ex or vi, set 24 line page
when exiting ex or vi, reset 48 line page,
place cursor at 0,24,1

tvi950-4p

TeleVideo 950 w/4 pages

D-ll

ALTOS 586 COMPOi'BR SYSTEM

Note:

UNIX PROGRAMMER' S REFERENCE GUIDE

tvi950-4p is for 950 with four pages adds the
following:
set 96 line page
place cursor at page 0, line 24, column 1
when entering ex or vi, set 24 line page
when exiting ex or vi, reset 96 line page
place cursor at 0,24,1

tvi950-rv
tvi950-rv2p
tvi950-rv4p

TeleVideo 950 rev video
TeleVideo 950 rev video w/2 pages
TeleVideo 950 rev video w/4 pages

y: TELERAY
t3700
t3800
t106l
t106lf

dumb Teleray 3700
Teleray 3800 series
Teleray 1061
Teleray 1061 with fast PROM

D-12

ALTOS 586 COMPOTER SYSTEM

UNIX PJtOGRAIUIER' S REFERENCE GUIDE

Appendix E
HOMERIC FORMATS, C, AIID FORTRAII 77

The following information is for reference only.
This
information on the internal formats used for numeric representation is not necessary for general use of the C language or
Fortran 77.
It can be useful when examining actual memory
contents or doing other specialized system programming work.
The same formats are used by both languages.
INTEGER FORMATS

Integers and "short integers" are 16 bits in length. "Long
integers" are 32 bits.
For both sizes, the leftmost bit is a
sign bit and the other 15 or 31 bits are magnitude. The sign is
zero for pOSitive, one for negative.
Negative numbers are in
twos-compl ement form.
The range of values is as follows:
Signand 15 bits

-32,768 to 32,767

Sign and 31 bits

-2,147,483,648 to 2,147,483,647

FLOATIRG-POIRT FORMATS

Single precision floating point is 32 bits in length, double
is 64.
The leftmost eight bits consist of an exponent in excess
8~ nota tion.
"Excess 8~" means th at th e hexadecimal val ue s from
8~ to FF are positive exponents, corresponding to ~ through 7F.
Values less than 8~ are negative exponents; 7F through ~ correspond to -1 through -7E.

The remaining 24 or 56 bits consist of a leading sign bit
E-l

ALTOS 586 COIlPOTER SYSTEM

XBRIX PROGRAMMER' S REFERENCE GUIDE

and magnitude val ues.
J.lagni tudes are normal ized.
"Normal ized n
means that the representation of magnitude and exponent is
adjusted so that each magnitude value can be thought of as
starting with .lnnn •••
For example, the value of 101, decimal 5, would be .101 with
an exponent of 3. The leftmost digit of magnitude does not need
to be represented, because it is always 1 except for the special
case of a value of zero. Therefore, the leftmost magnitude bit
is not stored but is implied. It is referred to as the "hidden
bit."
Example:
The value 15.25, decimal.

In binary, this is 1111.01

(In binary, .1 = .5 decimal; .01 = .25, etc. Moving to the
right of the point halves the value at each move, just as moving
to the left of the point doubles the base 2 value.)
So, 1111.01 represents 15.25 decimal.
Normalizing our
binary value, we have .111101 with an exponent of 4.
The
exponent becomes 84 in excess 80 notation, or 1000 0100 in
binary. The sign bit is zero (positive), and the magnitude is
11101000 ••• with as many trailing zeros as needed. Notice that
the leading ".1 n has disappeared.
It is the unnecessary "hidden
bit." The binary and hexadecimal values are shown below.
1000 0100 0111 0100 0000 0000 0000 0000
8
4 s 7
4
0
000
The example is single-precision.
Double precision, in this
case, would be the same with eight bytes (32 bits) of trailing
zeros.
other examples:
The fractional decimal value .625.
In binary, this is .101;
that is, .5 plus .125.
The value is normalized as it is, the
exponent is 0, the sign is positive, 0.
1000 0000 0010 0000 •••
80s 2
0 •••
Negative 5. In binary, 5 is 101. Before taking the twoscomplement, we supply a leading zero which will become the
negative sign bit: 0101. The twos-complement is 1011. Removing
the sign bit, 011. Normalizing, .1100 with the exponent -2. In
excess 80, -2 is 7E. Result:
0111 1110 1100 0000 •••
7
Ese
0 •••

E-2

ALTOS 586 COMPUTER SYSTEM

Zero, the exception.

XERIX PROGRAMMER'S REFERERCB GUIDE

This is an all zero value.

0000 0000 0000 0000 •••
o
0
0
0 •••
All zeros can be thought of as zero by convention. Otherwise, it would represent the smallest positive number possible in
the scheme.
VALUES IN IIBIIORY

As with other values in 8086 memory, floating point values
are stored "back-words." The least signficant 16-bit word is
stored first, then the next, and so forth.
If the singleprecision value 84740000 is stored at location x, it will show as
follows when displaying memory contents:
x
x + 2

0000
8474

However, long integers are stored in order.
The long
integer with a hexadecimal value of 128A34BF will show as:
x
x + 2

128A
34BF

E-3

ALTOS 586 COMPUTER SYSTEM

XEHIX PROGRAMMER' S REFERENCE GUIDE

Appendix F
SAMPLE LIST OF UNIX UTILITIES
The following is a sample listing of the
provided in a full Xenix Development System.

typical

utilities

You can obtain a list of your Xenix operating system's
by entering:

utilities

cd / 
Is -FCRllpr
LIST OF XENIX UTILITIES
bin
boot
boot.fd
boot. food

dev
etc
fd
load.hd

install
lib
load. hd
lost+found

priboot
pribootfd
tmp
usr

xenix
xenix.fd

• /bin:
ac
adb
ar
arcv
as
at
awk
basename
bc
bsh
cal
calendar
cat
cb
cc
checkeq
chgrp
chmod
chown
clri
cmp
col
comm
cp
crypt
csh
cu

df
diff
du
dump
dumpdir
echo
ed
edit
esrep
enroll
eqn
ex
expr
f77
false
fgrep
file
find
flagbad
fsck
graph
grep
icheck
join
kill

look
Ipr
Is
m4
mail
make
man
mesg
mkdir
mntchk
multiuser
mv
ncheck
ndump
neqn
newgrp
nice
nm
nroff
od
osh
passwd
pr
prep
prof
ps
ptx
pwd

refer
restor
rev
rm
rmail
rmdi r
sa
sed
sh
size
sleep
sort
sp
spell
spline
split
strip
struct
stty
su
sum
sync
t300
t300s
t450
tabs
tail
tar

test
time
tk
touch
tp
tr
troff
true
tsort
tty
uniq
units
uucp
uulog
uux
v7grep
v710gin
v71s
v7ps
vi
vplot
vpr
who
write
xset
xsend
yacc
yes

date

1

Id

learn

F-l

ALTOS 586 COMPUTER SYSTEM

UNIX PROGRAMMER' S REFERENCE GUIDE

dc
dcheck
dd
deroff

lex
lint
In
login

quot
random
ranlib
ratfor

tbl
tc
tee
tek

./dev:
altosnet
console
eua0
cul0
ether
fd0
fd0. swap
fdl
hd0

hd0.boot
hd0.layout
hd0.roc0
hd0. secmap
hd0.spares
hd0.track0
hd0a
hd0b
kmem

lp
mem
null
rfd0
rfdl
rhd0
rhd0.boot
rhd0.layout
rhd0.roc0

rhd0. secmap
rhd0.spares
rhd0. tr ack0
rhd0a
rhd0b tty4
root tty5
rroot
rswap
swap

tar
tty
tty2
tty3

./etc:
accton
asktime
checklist
cron
ddate

getty
group
hal tsys
inir
init

menusys
mknod
motd
mount
mtab

newuser
rc
shutdown
systemi d
termcap

ttys
umount
update
utmp
wall

dial-login
dmesg

menusys. bin
mkf s

passwd
ttytype

f77cl
f77c2
f77crt0.o
f77passl
libF77.a

libI77.a
libc. a
libcurses.a
libdbm. a
libln.a

libm.a
libmp.a
libplot.a
libt300.a
libt300s.a

• /usr :
adrn
altos
bin

dict
games
include

lib
preserve
spool

src
sys
tmp

./usr/adrn :
acct
messages

mssbuf
savacct

usracct
wtmp

tty6

./etc/newuser:
./fd:
./lib:
c0
cl
c2
cpp
crt0.o

libt40l4.a
libt4S0.a
libterrnlib.
libunet.a
libvt0. a

./lost+found:
./tmp:

./usr/altos:
qa. text
./usr/bin:
F-2

unix
user

ALTOS 586 COMPUTER SYSTEM

XENIX PROGRAMMER' S REFERENCE GUIDE

Mail
apropos
chessclock
chfn
chsh
ckdir
clear
clock
copy
ctags
cxref
daytime
decode
diff3
disest
disable

double
enable
error
expand
fcopy
ffmt
finser
fleece
fmt
fold
format
from
setNAME
sets
head
iul

last
layout
leave
lock
lookbib
lorder
makewhatis
map
mkstr
more
msgs
nohup
num
page
pcc
pconfig

./usr/dict:
hlista
hlistb

hstop
papers

spellhist
words

plot
print
printenv
reset
script
sddate
see
sendnet
set time
sizefs
soelim
ssp
strings
tod
tra
tset

ua
ucp
ul
users
uudecode
uuencode
uusend
uversion
v7wc
w
wc
whatis
whereis
whoami
whon
xstr

./usr/dict/papers:
Ind.ia
Ind.ib

Ind.ic

Rv7man

runinv

./usr/games:
arithmetic
backgammon
banner
craps

master
number
quiz
quiz.k

random
snake
snscor e
ttt

wump

./usr/games/lib:
fortunes
mmhow

snake. log

snaker awscor es

./usr/games/quiz.k:
af rica
chinese
america
collectives
areas
ed
arith
elements
asia
europe
babies
greek
bard
inca

index
latin
locomotive
midearth
morse
murders
poetry

posneg
pres
province
seq-easy
seq-hard
sexes
sov

spell
state
trek
ucc

./usr/include:
a.out.h
ar.h
assert.h
core.h
ctype. h
curses.h
dk.h
dumprestor. h

olda.out.h
olddump.h
pack. h
psout.h
pwd.h
regexp.h
saio.h
setjmp.h

setty. h
signal.h
stddef. h
stdio.h
symbol. h
sys
sys. s
sysexi ts.h

time.h
tp-defs.h
utmp. h
varargs.h
whoami. h
xout86.h

fish
fortune
hangman
lib

errno.h
execargs.h
grp.h
i dent. h
local
rna the h
mp.h
mtab.h

./usr/include/local:
layout.h
sspare.h

uparm.h

F-3

ALms 586 COIlPUTER SYSTEIl

UNIX PROGRAIlIlER' S REFERENCE GUIDE

./usr/includes/sys:
acct.h
file.h
buf. h
f il sy s. h
callo.h
ino.h
chars.h
inode.h
conf.h
ioctl.h
dir.h
locking.h
fblk.h
map.h
./usr/lib:
Mail.help
Mail.help.atrun
bsh
bsh. messages
calendar
cign

mount.h
mpx.h
mx.h
param.h
pk.h
pk.p
prim.h

crontab
crontab.noUNET
diff3
ex2.l3reserve
ex2.l3recover
ex2.l3strings
ffmt

./usr/lib/font:
ftB
ftCE
ftCS
ftBC
ftCl
ftCw
ftC
ftCK
ftG

font
learn
lex
lintl
lint2
llib-lc
llib-lm

ftGl
ftGf.1
ftGR

./usr/lib/learn:
C.a
Xinfo
Linfo
editor.a
READ_ME
eqn.a

ftl
ftL
ftLl

ftPA
ftPB
ftPl

proc.h
res.h
sc.h
sites.h
stat.h
systm. h
text.h

timeb.h
times.h
tty.h
types.h
user.h

llib-port
lpd
me
menusys
more. help
refer
struct

tabset
term
tmac
uucp
yaccpar

ftR
fts
ftSB

ftSl
ftSr.1
ftUD

f tXfwl

files. a
1 count
macros.a

makef ile
morefiles.a
tee

index.me
local.me
nUll.me

rev isions
sh.me
tbl.me

thesis.me

./usr/lib/menusys:
Backup
Dir
Backup?
Dir?
Commands?
Execute

Execute?
Help
Help?

Mail
Mail?
Start

Start?
SysAdmin
SysAdmin:

./usr/lib/refer:
hunt
inv

mkey

./usr/lib/lex:
ncform
./usr/lib/me:
acm.me
chars.me
deltext.me

eqn.me
float.me
footnote.me

./usr/lib/struct:
beautify
structure
./usr/lib/tabset:
beehive
std
diablo
teleray

vt10~

xerox1720

./usr/lib/term:
tab3~~
tab3~~-12

tab37

tab3~~s-12

tab45~-12-8

tab3~~s

tab45~

tabal
tablp

tab832

tabn3~~

tab450-12

F-4

ALTOS 586 COMPUTER SYSTEM

UNIX PROGRAMMER' S REFERENCE GUIDE

./usr/lib/tmac:
tmac.an
tmac.help
tmac.e
tmac.r

tmac.s
tmac.scover

tmac.sdisp
tmac.skeep

./usr/lib/uucp:
L-devices
L.sys
L-dialcodes
USERFILE

uucico
uuclean

uuxqt

tunetmail
unetmail

uucp
uucppublic

./usr/preserve:
./usr/spool:
at
lpd

mail
msgs

./usr/spool/at:
lasttimedone
past
./usr/spool/at/past:
./usr/spool/lpd:
./user/spool/mail:
./usr/spool/msgs:
bounds
./usr/spool/uucp:
./usr/spool/uucppublic:
./usr/src:
cme
./usr/srs/cmd:
decode. c
./usr/sys:
./usr/tmp:
./usr/unix:
./usr/user:

F-5

trnac. sref,

ALTOS 586 COIlPOTER SYSTEM

UNIX PROGRAMMER' S REFERENCE GUIDE

Appendix G
COPYIBG FILES FROM TIlE ALTOS 8688 TO mE
ALTOS 586 UNDER mE XENIX OPERATING SYSTEM

If you want to transfer files from an Altos ACS 8600 to an Altos
586 system, the best method is through a uucp network. Bell Labs
developed the uucp group of programs to facilitate the regular
transfer of files between systems using the UNIX operating
system.
(Uucp stands for llniz~-Unix ~.)
This appendix
describes how to use uucp for a different purpose: The one-time
transfer of a large number of files from an 8600 to a 586. Two
assumptions are made here about your needs:
It's assumed that you don't want to regularly
files.

transfer

It's assumed that the two systems can be placed together so
they can be directly hooked up.
If these assumptions don't match your needs, then you should turn
to the description of uucp networks in the UNIX programmer's
Manual that carne with your XENIX operating system. You can find
complete documenta tion of these networ ks there.
This document
describes only those features of uucp needed for a one-time
transfer.
Both systems must be using the XENIX Development System with the
uucp program installed.
The information in this appendix is organized into four major
sections:

1.

Connecting the 8600 and the 586

2.

Preparing the Configuration Files

3.

Disabling and Enabling the TTY Ports

4.

Testing the Uucp Network

5.

Copying Files Using Uucp

It's assumed that you are familiar with the XENIX operating sytem
and its major features. It's also assumed that you know how to
use at least one of the XENIX editors. If you need more information on either Xenix or its editors, refer to the UNIX
Programmer's Manual for more information.

G-l

ALTOS 586 COMPUTER SYSTEM

UNIX PROGRAMIlER' S REFERENCE GUIDE

CONNECTIBG 'mE ACS 8688 AND mE 586

The 8600 and 586 systems should be placed close enough together
that they can be directly connected by a single null-modem cable.
You can connect the cable to any port on the two systems that
isn't the port used by the system terminal on that system. You
can have any arrangement of peripheral devices attached to either
system so long as both systems at least have a system terminal
connected to the them.
NOTE
The systems must be connected using a nullmodem cable for the procedure to work.
We suggest that you connect the two systems through their tty5
ports. The examples in this document show the systems connected
through these ports. If you connect the systems through other
ports, be sure to modify the examples to reflect your setup.
Also, ensure that both systems are set up for multiple users. If
either system is in a single-user mode, lop in as super-user and
type in
multiuser 
PREPARrRG THE CONFIGURATION FILES

The uucp program comes ready to use.
It does need, however,
certain information to establish the connection between the 586
and 8600 systems. You provide this information by adding entries
to several files on each system. The following table gives the
steps needed for ~ system to prepare the files:

.llI& EFFECTED:

TASK:
Assign a system name
to the system

/etc/sy stemid

Define the communications
line characteristics

/usr/lib/uucp/L-devices

Give information needed
to login to the other
system

/usr/lib/uuCp/L.SYs

Specify file accessibility

/usr/lib/uucp/USERFILE

Unless you have special requirements, you probably can edit the
files on both systems in a few minutes. To make the task simpler,
this section gives recommended entries. Some versions of the
XENIX that comes with the 586 already have the recommended
entries placed in the files.
In this case, you don't have to add
anything to the 586 files, but must still modify the 8600 files.
G-2

ALTOS 586 COIlPOTER SYSTEM

UNIX PROGRAMMER' S REFERENCE GUIDE

You can use the XENIX editor to check the contents of the 586's
f i 1 est 0 see if you mus t mod i f y th ern.
In case you have some special requirements, this document also
describes how to prepare your own entries.
You'll use one of the XENIX editors to add the entries to the
files. To edit the files, you must be a XENIX superuser (root).
You can become a superuser either by logging in as root or by
using the .Q.l.l command.
Recommended Entries
You can use a set of standard entries to set up the 586's files
if your requirements meet these assumptions:
1.

You must assign the system name Altos86 to the 8600 system
and the name Altos586 to the 586 system. If you don't, you
must give different system names in the /usr/lib/uucp/L.sys
and /usr/lib/uucp/USERFILE files.

2.

The line connecting the two systems must connect into port
tty5 on the each system. If it doesn't, you must give
different port names in the /usr/lib/uucp/L-devices and
/ us r /1 i b / u u cp / L. sy s f i 1 e s.

3.

The connection between the two systems must be direct. That
is, it can't go through a telephone system. If it isn't a
direct connection, you must give a different baud rate in
the /usr/lib/uucp/L-devices and /usr/lib/uucp/~sys files.

If your requirements don't meet these assumptions, read the
instructions in the section "If You Have Special Requirements."
They tell you how to tailor the file entries to yor requirements.
If your requirements do match these assumptions, copy these
entries into the files shown if they are not already there:

ENTRY
/etc/systemid

Altos586

/usr/lib/uucp/L-devices

tty5 " 9600

/usr/lib/uucp/L.Sys

Altos86 Any tty5 9600 tty5 ogin:-AMogin:-AM-ogin:uucp

/usr/lib/uucp/USERFILE

root, /
/usr /tmp

The entry for the /usr/lib/uucp/L.sys file must have the carriage
G-3

UNIX PROGRAMMER' S REFERENCE GUIDE

AL'l'OS 586 COMPUTER SYSTEM

returns (~M) embedded as shown. See the UNIX manuals for
information on how to embed carriage returns within a character
string using your editor •

.m.R nE 8688:
£lLE

ENTRY

/etc/systemid

Altos86

/usr/lib/uucp/L-devices

tty5 0 9600

/usr/lib/uucp/L.SYS

Altos586 Never tty5 9600 tty5

/usr/lib/uucp/USERFILE

root, /
, /usr /tmp

If these recommended entries meet your needs, skip the next
section and go to the section nTesting the Uucp Network. n
IF YOU HAVE SPECIAL REQUIREMENTS

If you can't use the suggested entries, the following subsections
give instructions on preparing each file. This section is
organized as follows:
Assigning System Names
Defining the Communications Line Characteristics
Supplying the Login Information
Defining the File Accessibility
Assigning the System Names
Uucp needs a unique name for each system. The names identify each
system in commands and during the login. To assign a system
name, use an editor to add a line to the file /etc/systeDlid.
This line should contain a single word entry that can be any
legal UNIX name. The name cannot be the same name as any other
system name that this system will communicate with through uucp.
The /etc/systemid file can contain more than one system name
each.
Any name in this file can be used with uucp, but we
suggest that you use just one name per system to avoid confusion.
Defining the Communications Line Characteristics
Uucp needs certain information about the communications line it
will use. To provide this information, edit the file
/usr/lib/uucp/L-devices on each system to add a line of this
format:
G-4

ALTOS 586 COMPUTER SYSTEM

UNIX PROGRAMMER' S REFERENCE GUIDE

format for both systems:
port call-unit baud-rate
where:
port

names the port to be used.

call-unit

Enter a ., (zero) for this field.

baud-rate

gives the baud rate of the line. If the
systems are directly connected, the baud rate
is 9600.

This entry:
tty5 0 9600
states that the line connects through port tty5 and has a baud
rate of 9600.
If the communications line can operate at more than one baud
rate, you must include a separate entry for each baud rate as
done here:
tty5 0 300
tty5 " 600
Supplying the Login Information
Uucp needs certain information to establish a connection between
the systems. To provide this information, edit the file
/usr/lib/uucp/L.sys to add a line of this format:
format for the 586 system:
system-name time port baud-rate phone login

\

format for the 8600 system:
system-name time port baud-rate phone
where:
system-name

gives the name assigned to the other system
in ~ /etc/systemid file.

time

gives the times that the uucp program is to
try to login to the other system. For 586
system, state Any. This has uucp establish
the connection any time you call it. For the
8600 system, state Never. This prevents the
8600 from ever making the connection.
G-5

ALms 586 COMPUTER SYSTEM

XERIX PROGRAIUlER' S REFERENCE GUIDE

port

names the port through which the connection
is made to the other system. The port name
must match the port name given in the
system's /usr/lib/uucp/L-devices file.

baud-rate

gives the baud rate that is to be used. The
baud rate must match one of the baud rates
given for the port in the system's
/usr/lib/uucp/L-devices file.

phone

must be the same name given for the port
field of this entry.

login

for the 586 only, consists of a series of
fields telling uucp how to login to the 8600
system. The entry should be:
ogin:-~M-ogin:-~M-ogin:

uucp

The AM characters in the string are carriage
returns (CONTROL-M) embedded with the string.
These carriage returns must appear within the
file as shown. See the UNIX documentation
for information on how to embed control
characters within strings using your editor.
Defining the File Accessibility
Uucp needs permission to access files on either system.
To
provide permission, edit the file /usr/lib/uucp/USERFILE on each
system to lines of this format:
format for both systems:
root,
/
/usr /tmp
where:
root,

,

/

/usr /tmp

gives the superuser on either system access
to any file in any directory through uucp.
gives any non-superuser on either system
access to any file in any daughter directory
of the /usr /tmp directories through uucp.

DISABLIIk; AND ERABLIIk; -mE 'l"'l'Y PORTS

Before testing the uucp network and copying files using uucp,
the following steps must be performed:
1.

On the 586, enter:

disable /dev/tty5
G-6

ALTOS 586 COIlPOTER SYSTEM

XERIX PROGRAMMER' S REFERENCE GUIDE

substitute the name of the pot you're using in this command
if the connection to the 8600 isn't through port tty5.
2.

On the 8600, enter:

enable /dev/ttyS
substitute the name of
command.

the port you're using in this

'l'BSTIRG mE OUCP RETWORK

Before you begin copying files from the 8600 to the 586, you
should test the network by copying a single file.
If the copy
succeeds, you can start copying over the bulk of your files.
If
it doesn't succeed, you must check your connection and your
configuration files.
The test copies the file /etc/passwd from the 586 to the the file
/trnp/passwd on the 8600. To conduct the test, follow these steps:
1.

Boot and become a superuser (root) on both systems.

2.

On the 586, enter:

uucp /etc/passvd

Altos86\I/tap/passvd

substitute the system name you gave the 8600 in this command
if you didn't name it Altos8600 in its /etc/systemid file.
3.

The copy takes about one minute to complete.
time, on the 8600, enter:

After that

cat /tmp/passwd
If cat shows that the file /tmp/passwd contains the contents
of the file /etc/passwd on the 586, then the uucp copy
worked.
If the /tmp/passwd file doesn't exist or is empty,
then the copy didn't work.
If the copy works, then go on to the section "Copying Files Using
Uucp." If the copy didn't work, check the connection between the
two systems.
Once you're sure that the cable is properly
connected (and that nothing is wrong with the cable) try the
steps above again.
If they still don't work, check the contents
of the configuration files you prepared. Once you're sure that
they are correct, again try the copy.
If you still have problems, use the information below to try to
debug your setup. These steps descr ibe what happens when uucp
performs a copy. By looking at the files mentioned, you should
be able to determine where the problem lies. Then turn to the
UNIX Programmer's Manual.
It contains more information on uucp

G-7

ALTOS 586 COMPUTER SYSTEM

XENIX PROGRAMMER' S REFERENCE GUIDE

that should be helpful for solving your problem.
When uucp performs the copy, these steps should occur:
1.

The uucp program creates two files in the 586's
/usr/spool/uucp directory.
The first, D.Altos86eJeJneJeJ0l,
contains a copy of the file /etc/passwd. The second file,
C.Al tos86eJeJneJeJ0l, contains control information.
(The names
of these files will be different if you didn't assign the
name Altos86 to the 8600.)
Uucp also places the message, nQUEUED (C.Altos86130n131313l)" in
the file /usr/spool/uucp/LOGFILE on the 586.
At the end of this step, the program uucp stops execution.
If a file /usr/spool/uucp/STST* exists on the 586, remove it
before retrying the procedure.

2•

Th e pro g ram u u c i cot hen beg ins ex e cut ion. It's fir s t t ask
is to examine the 586 file /usr/lib/uuCp/L.sys. The entry
in the file tells uucico to immediately login to the 861313.
The following steps occur as part of the login:
Uucico sends a carriage return to the 861313, which
should respond with login message. Uucico then logs in
on the 861313.
The uucico program on the 586
program on the 861313.

executes the uucico

The uucico program on the 586 creates two temporary
files in the 586's /usr/spool/uucp directory that are
prefixed with nLCK n•
Uucico on the 586 places the message nSUCCEEDED (call
to Al tos86)" in the 586 file /usr/spool/uucp/LOGFILE.
3.

The uucico program on the 586 checks its spool directory and
learns that it should transfer a file from the 586 to the
861313.
The message nREQUEST (S /etc/passwd /tmp/passwd
user name) is placed in the /usr/spool/uucp/LOGFILE files on
both systems.

4.

Uucico on the 586 transfers the file D.Altos86eJ0n00eJl, which
is a copy of /etc/passwd, from the 586 to the 861313.
The
uucico program on the 86130 places the file in the directory
/usr/spool/uucp. It then moves the file to the file
/tmp/passwd.

5.

The message nREQUEST (SUCCEEDED) n is placed
/usr/spool/uucp/LOGFILE files on both systems.

G-8

in

the

ALms

586

COMPUTER SYSTEM

UNIX PROGRAMMER' S REPERENCE GUIDE

COPYIRG FILES USIRG UUCP

After you've tested the connection and the configuration files,
you can begin copying files from the 86~~ to the 586. Follow
these steps to do the copying:
1.

Turn on and boot both systems.
both systems.

Log in as the superuser on

2.

If any of the 86~~ files you want to copy aren't part of the
86~~ directories,
copy them into a directory.
(These typically would be files that you've copied onto a diskette or
tape using the tar command.)

3.

Use the uucp command on the 586 to copy files from the 8600
to the 586. The last section in this appendix, "Using the
Uucp Command, n gives instructions on using the uucp command.
You can use the uucp command as many times as necessary to
copy files.

USING THE UUCP COMMAND

Once you've enabled and disabled the ports, you can begin using
uucp to copy files. The basic format of the uucp command is:

uucp [-d) 86-system-namelsource-file destination-file
where:
-d

is an optional parameter that has uucp
create,
if necessary, all necessary
directories to place the source file(s) in
the destination file given

8600-system-name
gives the name you assigned to the 8600 in
its /etc/systemid file.
You must follow the
system name with an exclamation mark (1).
source-f ile

gives the name of the source file or files to
be copied from the 86~~.
The name must
include the pathname to the directory that
con t a ins the f i 1 e 0 r f i 1 e s •
Th e n am e can
include the metacharaters ? * [] that the
8600 will expand.
Uucp will copy every file
that whose name fits in the expanded name.

destination-file
gives the name of the file into which uucp
will place the contents of the source file.
If a pathname is given, uucp places the
copied file into the named directory.
G-9

ALTOS 586 COIlPUTER SYSTEM

UNIX PROGRAMMER' S REFERENCE GUIDE

Otherwise, the copied file goes into the
current directory.
If more than one file is
copied, then the copied files are placed into
files of the same name as the files on the
8600 system.
Let's say that you want to copy the entire contents of the
directory /usr/marketing/reports from the 8600 to a directory of
the same name on the 586. You would use this command:
uucp -d Altos861/usr/marketing/reports/* /usr/aarketing/reports

The asterick (*) following the Altos8600 pathnarne has uucp copy all
the files in the directory. The -d has uucp create the directory
/usr/marketing/reports on the 586 if it doesn't already exist.
(Note that in this example, the 8600 has the system name Altos8600.
In your commands, you would substitute the name you assigned the
8600.)
In the next example, let's say that you want to copy the file
y_t_d_sales into the current directory on the 586. You would use
this command:
uucp

Altos861/usr/jane/sales/y_t_~sales

This has uucp place the file into the current directory in a file
of the same name as on the 8600.

G-10

ALTOS 586 COMPOTER SYSTEM

XBRIX PROGRAMMER' S REFERENCE GUIDE

Appendix B
8186 ASSEMBLY LAJlGUAGE REFERERCE IlAllUAL

The following pages represent an 8~86 Assembly Language
Reference Manual extracted with permission from a Microsoft, Inc.
publication.
The section and page numbers of this excerpt
reflect the enumeration and pagination of the original
publi ca ti on.

H-l

XENIX Software Development

2.5

AS: The XENIX Assembler

This document describes the usage and input syncax of
the
XENIX 8086
assembler as.
As is an assembler that produces
an output file
containing
relocation
information and a
complete symbol
table.
The output
is acceptable to the
XEN!X loader ld, which may be used to combine the outputs of
seve::al assembler
runs and- to obtain object programs fr.om
libraries.
The output format has been cesigned so that if a
prog~am
contains no unresolved references
to external
symbols, it is executable without f~rther processing.
2.5.1

Osac:e

As is invoked as follows:
as [ -1 ]

( -0 output ] file

If the optional '_1' argument is givp.n, an assembly listing
is
produced which
includes
the source,
the assembled
(binary) code, and any assembly errors.
The output of the assembler is by default placed on the file
a86.out
in
the current directory~ The ' - 0 ' flag causes the
outP~to be placed on the named file.
2.5.2

Lexical conventions

Assembler
"symbols"

tokens
include
identifiers
(alt=rnatively,
or "names' '), constants, and operators.

2.5.2.1 Identifiers An identifier ·consists of a
sequ~nce
of
alphanumeric
characters
(including period " . ' 'and
underscore "
" as alphanumeric) of which the first may not
be
numeric.Only
the
first
eight characters are
significant.
The case of alphabetics
in
identifiers
is
significant.
2.5.2.2 Constants A hex constant consists of a sequence of
digits and the letters 'a', 'b', 'c', 'd', 'e', ar.d 'f' (anv
of which may be capitaliiedl ,- pre~eede~ by- the chiracte~
'I'. The letters are interpre~ed with the follow;~g values:

2-69

XENIX Software Development

HEX
A

C

DECIMAL
10
11
12

D
E

13
14

F

15

B

octal constant consists of a series of digits, p:~c~ded
by the tilde character " I I
The digits must be in the
range from ~.to 2.

An

A \decimal constant consists simply of a sequence of digits.
The magnitude of the constant should be representable in 15
bi~s: i.e., be less than ~,~.
2.5.2.3 Blanks Blank and tab characters may be freely
interspersed between tokens, but may not be used within
tokens (except in character constants). A blank or tab is
required to separate adjacent identifiers or constants not
otherwise separated.
2.5.2.4 Comments The character "I I I introduces a comment,
which extends through the end of the line on which it
appears. Comments are ignored by the assembler.
2.5.3

Segments

Assembled code and data fall into three segments: the
text
segment,
the data segment, and the bss segment. The text
segment is the one in which the assembly begins, and it is
the one into which instructions are typically ~laced. The
XENIX system will, if desired, enforce the purity of the
text segment of programs by trapping. '~rite operations into
it. Object programs produced by the assembler must be
processed by the link-editor ld (using its '-il flag) if the
text segment is to be write-protected. A single copy of the
text segment is shared among all processes executing such a
program.
The data segment is available for
placing
data
or
instructions
which will be modified during execution.
Anything which may go in the text segment may be put into
the
data
segment.
In programs with write-protected,
sharable text segments,
the data segment contains the
initialized but variable parts of a program.
If the t~xt
segment is not pure, the data segmen~ begins immediately
after the text segment. If the text segment is pure, the

2-70

XENIX Software Development

data segment is in an address space of its own, starting
location zero (0).

at

The bss segment may not contain any explicitly initialized
code or data. The length of the bss segment (like that of
text or data) is determined by the high-water mark of the
location counter within it. The bss segment is actually an
extension· of the data s"egment and begins immediately after
it. At th~ start of execution of a progr·am, the bss segment:
is se~ to O. The advantage in using the bss segment for
storage that starts off empty is that the initialization
information need not be stored in the output file. See also
location counter and assignment statements below.
2.5.4

The location countet

The special symbol, " . " , is the location counter.
Its
value at any time is the offset within the appropriate
segment from the start of the statement in which it appears.
The
location
counter
m~y
be assigned to, with the
restriction that the current segment may not
change;
furthermore, the value of " . ' 1 may not decrease. If the
effect of the assignment is to increase the value of ....... '.',
the required number of null bytes are generated (but see
Segmen ts aboVe).
2.5.5

Statements

A source program is composed of a sequence of statements.
Statements are separated by new-lines. There are four kinds
of statements: null statements, expression
statements,
assig~ment statements, and keyword statements.
The format for most 8086 assembly language source statements
is:
«label field>]
[]

£E.-~

[]

Any kind of statement may be preceded by one or more labels.
2.5.5.1 Labels There are two kinds of labels: name labels
and numeric labels. A name label consists of a identifier
followed by a colon (:). The effect of a name label is to
assign the current value and type of the location counter
to the name. An error is indicated in pass 1 if the
name is alreadY defined; an error is indicated in oass 2 if
t::', ...... I I value- assigned changes the definition· of the
....... ,

I

2-71

XENIX Software Development

label.
A numeric label consists of a string of digits Q to 9 and
dollar-sign (S) followed by a colon (:). Such a label serves
to define local symbols of the form "nS", where n is
the
digit of the label.
The scope of the numeric label is the
labelled block in which it appears.
As
an example,
the
label 9S is defined ~nlv between the lables foobar and foo:

-

-

foobar:
9$:
.byte 0

foo:

.word a

As in the case of name labels, a numeric label
current value and type of "."
to the symbol.

assigns

the

2.5.5.2 Null statements
A null statement is· an empty
statement
(which may, however, have labels and a comment) .
A null statement is
ignored by the assembler.
Common
examples of null statements are empty lines or liries
containing only a-label.
2.5.5.3 EXDression statements
An
expression
statement
consists of an arithmetic expression not beginning with a
keyword.
The assembler computes its value and places it
in
the output stream, together with the appropriate relocation
bits.
2.5.5.4 Assignment statements
An
assignment
statement
consists of an identifier,
an equal sign
(=),
and an
expression.
The value and type of
the expression are
assigned to the identifier.
It is not required that the
type or value be the same in pass 2 as in pass 1, nor is
it
an error to redefine any symbol by assignment.
Any external attribute of the expression is lost across an
assignment. .This means that it is not possible to declare a
global symbol by assigning to it, and that it is
impossible
to define a symbol to be offset from a non-locally defined
global symbol.
As mentioned, it is ?er~issible to assign to
the location
counter " I I
It
is required, however, that the type of
the express ion ass igned be of the same type as ..... I I , and i =.
is forbidden
to decrease the value of , .. I I
In practice,

2-72

XENIX Software Development

the most common assignment t~ "."
has the
form ".=.+n"
for
some number ~; this has the effect of generating ~ nu::
bytes.
2.5.5.5 Keyword statements
Keyword
statements
a=e
numerically
the most common type,
sinc~
most machine
instructions are of :his sort.
A ~eT~crd statement begins
with one of the many p~edefined keywords of the assemble:;
the syntax of the remainde~ depends on the keyword.
All :~e
keywords are lis~e~ below ~ith ~he syntax they require.
2.5.6

Expressions
.

An expression is a sequence of symbols representing a

val~e.

Its constituents are identifiers, constants, and operato:s.
Each expression has a type.
Arithmetic is two's complement.
All operators have equa:
precedence,
and expressions are evaluated strictly left ~=
right.
2.5.6.1

Exoression ooerators
Ooerator
•
(blank)

+

*

/...

,
>
<

The operators are:
Description

same as +
Addition
Subtraction
Multiplication
Division
Log ical OR
Logical AND
Log ical NOT
Right Shift
Left Shift

2.5.6.2 Tyoes The assembler deals with expressions,
each
of which may be of a different~.
Most types are
attached to the keywords and are used to select the routine
which treats
~~at
~eyword.
The
types
likely to be met
explicitly are:
undefined
Upon first encounter, each
It may become undefined
undefined expression.

2-73

symbol
if it

is undefined.
is assigned an

XENIX Software Deve.lopment

undefined external
A symbol which is declared .globl but not defined
in the current assembly is an undefined external.
If such a symbol is declared, the link editor ld
must be used to load the assembler's output wiEn
another routine that
defines
the
undefined
reference.
absolute

An absolute symbol is defined ultimately from a
constant.
Its value is unaffected by any-possible
future applications of the link-edi tor to the
output file.
text
The value of a text symbol is measured with
respect to the beginning of the text segment of
the program.
If the assembler output is linkedited, its text symbols may change in value since
the program need not be the first in the link
editor's output. Most text symbols are defined by
appearing as labels. At the start of an assembly,
the value of " " is text o.
data
The value of a data symbol is measured with
respect to the origin of the data segment of a
program.
Like text symbols, the value of a data
symbol may change during a subsequent link-editor
run sinr.e previously loaded programs may have data
segments.
After ~~e first .data statement, the
value of "."
is data O.
bss
The value. of a bss symbol is measured from the
beginning of the bss segment of a program.
Like
text and data symbols, the value of a bss symbol
may change during a subsequent link-editor run,
since previously loaded programs may have bss
segments.
After the first .bas statement, the
value of "."
is bss o.
external absolute, text, data, or bss
Symbols declared .globl but defined within an
assembly as absolute, text, data, or bss symbols
may be used exactly as if they were not declared
.globl:
however,
their
value and type ar~
avail-able to the link editor so t..'at the program
may be loaded with others t..'at reference these
symbols.

2-74

XENIX Software Development

other types
Each keyword known to the assembler has a type
which
is
used to select the routine which
processes the associated keyword statement.
The
behavior of such symbols when not used as keywords
is the same as if they vere absolute.
2.5.6.3 Tvtle propagation in expressions When operands ar~
combined by expression operators,
the result has a type
which depends on the types of the operands and on the
operator.
The rules involved are ccmplex to state but were
intended to be sensible and predictable.
For purposes of
expression evaluation the important types are
undefined
absolute
text
data
bss
undefined external
other
The combination rules are then: If one of the operands is
undefined,
the result is undefined.
If both operands are
absolu te,
the result is absolute.
If an absolu te is
combined with one of the 'other types'mentioned above, the
result has the other type.
If two operands of 'other
type' are combined,
the result has the numerically larger
type. An 'other type' combined with an explicitly discussed
type other than absolute acts like an absolute.
Further rules applying to ?articular operators are:
+

If one operand is text-,
data-,
or
bss-segment
relocatable,
or is an undefined external, the result
has ~~e postulated type and the other operand must be
absolute.
If the first operand is a relocatable text-, data-,
or
bss-segment symbol, the second operand may be absolute
(in which case the result has the type of the first
operand): or the second operand may have the same type
as t..~e first (in which case the result is absolute).
If the first operand is ~xternal undefined, the second
must be absolute.
All other combinations are illegal.

others
It is illegal to apply
absolute symbols.

these

2-75

operators

to

any

but

XENIX Software Development

2.5.7

Pseudo-ooerations

The keywords listed
influence the later
metanotation

below
introduce
statements
operations of the assembler.

t!.a t
The

( stuff
means that 0 or mo~e instances of the given stuff may
appear..
Also,
boldface tokens are li terals, italic ....ords
are substitutable.
2.5.7.1
.even If the location counter "."
is odd, it is
advanced by one so ~~e next statement will be assembled at a
word boundary.
This is useful
for
forcing
storage
allocation to be on a word boundary after a .byte or .ascii
directive.
2.5.7.2

.float, .double

.float

31459E4

The .float psuedo operation accepts as
its operand an
optional string of tabs and spaces, then an optional sign,
then a string of digits optionally containing a decimal
point,
them
an optional 'e' or 'E',
followed by an
optionally signed integer. The string is interpreted as a
floating point number.
The difference between .float and
.double is in the number of bytes fur
the result:
.float
sets aside four bytes, while .double sets aside eight bytes.
2.5.7.3

.B .alobl

.globl

name

name

This statement makes the names external.
If they are
otherwise defined
(by assignment or appearance as a label)
they act within the assembly exactly as
if the
.globl
statement '~re not given: however, the li~k editor ld may be
used to combine this routine with other routines that refer
to these symbols.
Conversely, if the given symbols are not defined within
the
current assembly, the link editor can combine the output of
this assembly with that of others which define the svmbols.
It is possible to force the assembler to make all other~ise
undefined symbols external.

2-76

XENIX Software Development

2.5.7.4
.text, .data, .bss These
three pseudo-operations
cause the assembler to begin assembling into the t.ext, data,
or bss segment respectively.
Assembly starts in the text
segment.
It is forbidden to assemble any code or data into
the bss segment, but symbols. may be defined and "."
moved
about by assignment.
2.5.7.5

.comm

.comm

The format of the .comm is:
ARRAY

Provided the name is not defined elsewhere,
~~is
statement
is equivalen~o
.globl. That is,
the
type of name is
"undefined external", and its size is expression. rn-tact
the name behaves in the current assembly
just like an
undeflned external. However, the link-editor Id has been
special-cased so that all external symbols which are not
otherwise defined, and which have a non-zero value,
are
defined to lie in the bss segment, and enough space is left
after the symbol to hold expression bytes.
All symbols
which become defined in this way are located before all the
explicitly defined bss-segment locations.

--

2.5.7.6

.insrt

/'.

/

The format of a .insrt is:

.insrt -filename N
where filename is any valid XENIX filename.
Note
file~ must be enclosed within double quotes.

that

the

The assembler will attempt to open this file for input.
If
it succeeds, source lines will be rean from it until the end
of file is reached.
If as was unable to ooen the file,
a
Cannot open insert file error message will-be generated.
This statement is useful for including a standard set of
comments or symbol assignments at the beginning of a
program.
It is also useful for breaking up a large source
program into easily managable pieces.
A maximum depth of 10 (ten)
time.

files may be .insrted at anyone

System call names are not predefined.
the file /usr/include/svs.s.

-

--

2-77

They may be found

in

XENIX

Soft~are

Development

2.5.7.7
.ascii, .asciz
The .ascii directive ·translates
character strings
into their 7-bit ascii (represented as
8-bit bytes) equivalents for ~se in the so~rce program.
The
format of the .ascii directive is as follows:
.ascii

/character string/

where
character string contains anT
character
valid
in
a
character· constant. Obviously,
a  must
not appear within the character string. (It can be
represented by the escape sequence \en) .
/

and

/

are delimiter characters, which may be
character not appearing in character string

any

Several examples follow:

..

Rex
22 68
68 65
77 61
2D 07
61 62

Code Generated:
~ 6C 6C 6F 20 74
72 65 22
72 6E 69 6E 67 20
07 20 OA
/
67
63 64 65 66'
/

.ascii

Statement:
/"hello there" /

.ascii "Warning-\OO7\OO7 \n"
.ascii *abcdefg*

/

The • asciz dir ecti ve is equivalent to the
. aSCll. dir ecti 'Ie
with a zero (null) byte automatically inserted as the final
character of the string. ThUS, when a list or text string is
to be printed, a search ,for the null character can terminate
the string. Nul: terminated strings are ~sed as arguments to
some XENIX system calls.
2.5.7.8
.list, .nlist These pseudo-directives control the
assembler output listing. These,
in .effect, temporarily
override the '-1' switch to the assembler.
Thi~
is ~sef~l
when
certain portions of the assembly output is not
necessarily desired on a printed listing.
.list
.nlist

turns the listing on
turns the listing off

2-78

XENIX Software Development

2.5.7.9 .blkb, .blkw The .blkb and .blkw directives are
used to reserve blOCKS of storage: .blkb reserves bytes,
.blkw reserves words.
The format is:
.blkb
.blkw

[expressionJ
[expressionJ

where.exoression is the number of bytes or words to reserve.
If no argument is given a value of 1 is assumed. The
expression m~~t be absolute, and defined during pass 1.
This is equivalent to the statement
has a much more transparent meaning.

".~.+ex~ression",

but

2.5.7.10 .byte, .word The .bvte and .word directives are
used to reserve bytes and woras-and to initialize them with
certain values.
The format is:
.byte
.word

[express ion J
[express ion J

The .byte directive reserves one byte for each expression in
the operand field and initializes the value of the byte to
be the low-order byte of the corresponding expression.
For example,
.byte 0
s;ate: .byte

a

reserves an byte, with a value
of zero.
reserves a byte with
value called state.

The semantics for .word are identical,
words are reserved and initialized.

except

2.5.7.11 .end The .end directive indicates
end of the-sQUrce program. The for~at is:
.end

a

zero
that

the

l6-bit

physical

[exoressionJ

where eXDression is an optional argument which, if present,
indicates the entry point of the program, i.e. the starting
point for execution. If the entry point of a program is not
specified during assembly, it defaults to zero.

XENIX Software Development

.end
Every source program must be terminated with a
files which contain a .end statement
statement.
:~serted
will terminate assembly of the entire program, not just the
inserted po=~ion.
2.S.~

Machine

The 8086 ins~:~ctions treat different types of operands
uniformly. ~early every instruction can operate on either
byte or word =ata. In the table that follows, with some
notable ex:~aptions, an instruction that operates on a byte
operand wil: ~ave a b suffix on the opcode.
The 8086 ins~~~ction mnemonics which follow are implemented
by the Mic=~sc:t 8086 assembler desribed in this document.
Some of the ~;c:des are not found in any other 8086 manual.
For example, :~:3 document describes branch instructions not
found in ar.: 9086 manual. The branch instructions expand
into a jump on ~e inverse of the condition specified,
followed by an an unconditional intra-segment jump. The
operand field format for the branch opcodes is the same as
the operand field for the jump long opcodes. The opcodes
which are implemented only in this assembler will be
annotated by an asterisk, and will be fully defined and
described in this document.

2-80

XENIX Software Development

8086 Assembler Opcodes

Opcode
aaa
aad

Description

aas
adc
adcb
add
addb
and
andb
*beq
*bge
*bgt
*bhi
*bhis
*ble
*blo
*blos
*blt
*bne
*br
call
calli
cbw
clc
cld
cli
cmc
cmp
cmpb
cmps
cmpsb
cwd
daa
das
dec
decb
div
divb
hlt
idiv
idivb
imul
imulb
in
inc

ascii adjust for addition
ascii adjust for division
ascii adjust for multiply
aSCll adjust for subt~action
add wi th carry
add with carry
add
add
log ical AND
logical AND
long branch equql
long branch grt or equal
long branch grt
long branch on high
long branch high or same
long branch les or equal
long branch on low
long branch low or same
long branch less than
long branch not equal
long branch
intra segment call
inter segment call
convert byte to word
clear carry flag
clear direction flag
clear interrupt flag
complement carry flag
compare
compare
compare string
compare string
covert word to double word
decimal adjust for addition
decimal adjust for subtraction
decrement by one
decrement by one
divison unsigned
divison unsigned
halt
integer division
integer division
integer multiplication
integer multiplication
input byte
increment by one

int

interrupt

aam

incb

increment

by

one

2-81

XENIX Software Development

into
inw
iret
j
ja
jae
jb
jbe
jcxz
je
jg
jge
jl
j Ie
jmp
jmpi
jna
jnae
jnb
jnbe
jne
jng
jnge
jnl
jnle
jno
jnp
jns
jnz
jo
jp
jpe
jpo
js
jz
lahf
Ids
lea
les
lock
lodb
lodw
loop
loope
loopne
loopnz
loopz
mov
movb
movs
movsb

interrupt if overflow
input word
interrupt return
short jump
short jump if above
short jump if above or equal
short jump if be-low
short jump if below or equal
short jump i f ex is zero
short jump on equal
short jump on greater than
short jump greater than or equal
short jump on less than
short jump on less than or equal
jump
inter segment jump
short jump not above
short jump not above or equal
short jump not below
short jump not below or equal
short jump not equal
short jump not greater
short jump not greater or equal
short jump not less
short jump not less or equal
short jump not overflow
short jump not parity
short ju:np not sign
short jump not zero
short jump on overflow
short jump if parity
short jump 1 ... parity even
short jump 1'Ii:... parity odd
short jump if signed
short Jump if zero
load AS from flags
load poin ter using OS
load effective address
load pointer using ES
lock bus
load stri:"c';; byte
load stri:lg word
loop sho:t label
loop if <2qual
loop if o:ot equal
loop is .lot zero
loop if zero
move
move byte
move strinq
move stri:--;: byte
'~

2-82

XENIX Software Development

mul
mulb
neg
negb
nop
not
notb
or
orb
out
outw
pop
popf
push
pushf
rcl
rclb
rcr
rcrb
rep
repnz
repz
ret
reti
rol
rolb
ror
rorb
sahf
sal
salb
sar
sarb
sbb
sbbb
scab
shl
shlb
shr
shrb
stc
std
sti
stob
stow
sub
subb
test
testb
wait
xchg

multipication unsigned
multipication unsigned
negate
negate
no op
log ical NOT
logical NOT
log.ical OR
logical OR
output byte
output: word
pop from stack
pop flag from stack
push onto stack
push flags onto stack
rotate left through carry
rotate left through carry
rotate right throuch carry
rotate ri~ht ~rouch carry
repeat string operation
repeat string operation not zero
repeat string operation while zero
return from procedure
return from intersegment procedure
rotate left
rotate left
rotate right
rotate right
store AR into flagsno operands
shift arithmetic left
shift arithmetic left
shift arithmetic right
shift arithmetic right
subtract with borrow
subtract with borrow
scan string
shift logical left
shift logical left
shidr logical right
shidr logical right
set carry flag
set direction flag
set interrupt enable flag
store byte string
store word string
subtraction
subtraction
test
test
wait while TEST pin
exchange

2-83

XENIX Software Development

)(chgb
)(lat
)(or
)(orb

exchange
translate
)(clusive OR
)(clusive OR

Addressino

2.5.9

~odes

The 8086 assembler provides many different ways to access
instruction
operand~.
Operands
may
be contained in
reg is ter s, wi th in- the ins truction itself, in memo ry, or in
I/O ports.
In addition,
the addresses of memory and I/O
port operands can be calculated in several different ways.
Reoister O~erands Instructions that specify only
register operands are generally the most compact and fastest
executing of all the instruction forms. This is because the
register 'addresses' are encoded in the instructions with
ju.st a few bits, and because these operations are performed
entirely within the C?J. Registers may serve as source
operands, destination operands, or both.
2.5.9.1

EXAMPLES OF REGISTER ADDRESSING

sub
mv
mv
mov

cx, di
ax,/3*4
/3*4/,ax
ax, 2' 1

2.5.9.2 Immediate Onerands
Immediate operands are constant
data contained in an instru=tion. The data may be either 8
or 16 bits in length. Immediat~ operands can be accessed
quickly
because ~,ey are available directly from the
instruction que~e: it is possible that no bus cycles will be
needed to obtain an immediate operand. An immediate operand
is always a constant value and can only be used as a source
operand.

The assembler can accept both 8 and 16 bit operands. It does
not perform any checking on the operand size, but determines
the size of the operand by the following symbols:
*expt
4expr

an 8 bit immediate
a 16 bit immediate

2-84

XENIX Software Development

EXAMPLES OF
mov

ADDRESSING

cx,*PAGSIZ/2
cx,tPAGSIZ/2
map,tPAGSIZ/2
map,*PAGSIZ/2

MOV

mov
mov
2.5.10

~IATE

Memory Addressing Modes

When reading or writing a memory operand, a value called the
offset is required. This offset value,
also called the
effective address is the operand's distance in bytes from
the beginning of the segment in which it resides.
2.5.10.1 Direct Addressing
Direct
addressing
is
the
simplest memory addressinq mode since no registers are
involved. The effective address is taken directly from the
displacement field of the instruction •. It is typically used
to access simple (scalar) variables.
.
EXAMPLES OF DIRECT ADDRESSING
push
mov
add

*6(bp)
cx,,256
si,*4

2.5.10.2 Register Indirect Addressing
The
effective
address of a memory operand may be taken from a base or
index register. One instruction can operate
on
many
different memory locations if the value in the base or index
register is updated appropriately.
Indirect addressing is
denoted by an ampersand @ preceding the operand.
EXAMPLES OF INDIRECT ADDRESSING
popl
calli

rrO,@rlS
@moncall

2.S.10.3 Based Addressing
In
based
addressing,
the
effective address is the sum of a displacement value and the
content of register bx or bp. Based addressing also provides
a straightforward way to address structures which may be
located in different places in memory. A base register can
be pointed at ~~e base of the structure and elements of the
structure addressed by their displacements from the base.
Different copies of the same structure can be accessed by
simply changing the base register.

XENIX Software Development

EXAMPLE OF BASED ADDRESSING
mov

-2 (si) ,#/1000

2.5.10.4 Indexed Addressing
In
indexed addressing,
the
effective
address
is
calculated from
the sum of a
displacement. plus the content of an index reg ister.
Indexed
addressing often is used to access elements in an array. The
displacement locates the beginnning of the array,
and
the
value of the index register select3 one element. Since all
array elements are the same length, simple arithmetic on the
index register will select any element.
EXAMPLE OF INDEXED ADDRESSING
mov

i_cat, (bx)

2.5.10.5 Based Indexed Addressing Based indexed addressing
generates an effective address
that is the sum of a base
register, an index register,
and a displacement.
8ased
indexed addr~ssing
is a very flexible mode because two
address comP9rients can be varied at execution time.

/

Based indexed addressing provides a convenient way for
a
procedure to address an array allocated on a stack. Register
bp can contain the offset of a reference point on the stack,
typically the top of the stack after the procedure has saved
registers and allocated local storage.
The offset of
the
beginning of
the array from
the
reference point can be
expressed by a displacement value, and an index register can
be used to access individual array elements.
EXAMPLES OF BASED INDEXED ADDRESSING
mov
mov
mov
2.5.11

(bx) (dx), sym
-2(bx) (dx), sym
t2(bx) (dx) ,:sym
Diagnostics

When syntactic errors occur, the line number and the file in
which
~,ey
occur
is displayed.
Errors
in pass 1 cause
cancellation of pass 2.
---ERROR--- syntax error, line xx
file: vv errors

-

2-86

XENIX Software Development

where xx represents the line number(s)
represents the total number of errors.

2-87

in

error,

and

-

YV

ALms 586 COIlPOTER SYSTBIl

DRIX PROGRAIUlBR' S REPERBRCB GUIDE

Appendix I
'.ftJ'lORIAL AlII> REPBRBRCB IlATERIAL
(DRIVERSlft OP CALIFORNIA, BERKELEY, BERKELEY IlARUALS)

On the following pages is informational material developed
at the University of California, Berkeley.
The material is
supplied under license from the Regents of the University.
An

Introduction to the C Shell

An Introduction to Display Editing with Vi
Quick Reference for Ex, Vi
Ex Reference Manual
Edit: A Tutorial
Ex/Edit Ca.mand Su.mary
Mail Reference Manual
-ME Reference Manual
Screen Updating and Cursor Roveaent Optimization:
A Library package

1-1

An introduction to the C shell
(Revised jor (he T!,ird Berkeley Distribution)
Wi/liam Joy

Computer Science Division
.
Department of Electrical Engineering and Computer Science
University of Califomi~ Berkeley
Berkeley, California 94720

ABSTRACT

em is a new command language interpreter for UNIXt systems. It incorporates good features of other shells and a history mechanism similar to the redo
of INTERLlSP. While incorporating many features of other sheils which make
writing sheil programs (shell scripts) easier, most of the features unique to csh
are designed more for the interactive UNIX user.
UNIX users who have read a general introduction to the system will find a
valuable basic explanation of tbe sbell here. Simple terminal interaction with
air is possible after reading just tbe first section of this document. The second
section describes the shells capabilities which you can explore after you have
begun to become acquainted with the shell. Later sections introduce features
which are useful, but not necessary for all users of the shell.
Back matter includes an appendix listing special characters of the shell ano
a glossary of terms and commands introduced in this manual.
December 2u, 1979

tUNIX is

il

Trademark of Bell uOoralories.

An 'Introduction to Display Editing with Vi
William Joy
Rniad 1M

IIfJ'S,IDIIS

J.SI2.JJ by

Mark Horton
Computer Science Division
Department of Electrical Engineering and Computer Science
University of California. Berkeley
Berkeley, Ca. 94720

AllSTlUCT
Vi (visual) is a display oriented interactive text editor. When using vi the
screen of your terminal acts as a window into the file which you are editing.
Changes which you make to the file are reflected in what you see.
Using vi you can insert new text any place in the file quite easily. Most of
tbe commands to vi move the cursor around in the file. There are commands
to move tbe cursor forward and baclcward in units of characters. words. sentences and paragraphs. A small set of operators, like d for delete and c for
change. are combined with the motion commands to form operations such as
delete word or change paragraph, in a simple and natural way. This regularity
and the mnemonic assignment of commands to keys makes the editor command set easy to remember and to use.
Vi will work on a large number of display terminals. and new terminals
are easily driven after editing a terminal description file. While it is advantageous to have an intelligent terminal which can locally insert and delete lines
and characters from the display. the editor will function quite well on dumb terminals over slow pbone lines. The editor makes allowance for tbe low
bandwidtb in these situations and uses smaller window sizes and different
display updating algorithms to make best use of the limited speed available.
It is also possible to use the command set of vi on bardcopy terminals.
storage tubes and "&lass tty's" using a one line editing window~ thus vi's command set is available on all terminals. The full command set of the more traditional, line oriented editor ex is available within vi; it is quite simple to switch
between the two modes of editing.

September 16, 1980

An Introduction to Display Editing with Vi
William Joy
Rniad 1M 1IfP'SI01IS J.JI21J by

Mark Horton
Computer Science Division
Department of Electric:al Engineering and Olmputer Science
University of California, Berkeley
Berkeley. Ca. 94120

1. Gettinl started
This document provides a quick introduction to vi. (Pronounced~) You should be
runninl vi on a file you are familiar with while you are reading this. The first part of this document (sections 1 through 5) desc:ribes the basics of usml vi. Some topics of Sl'ecial interest are
presented in section 6. and some nitty-gritty details of bow the editor functions are saved for
section 7 to avoid ciutterinl the presentation berea
There is also a short appe:ldix bere. which gives for each character the special meanings
which this character has in vi. Attached to this document should be a quick reference card.
This card summarizes the commands of vi in a very compact format. You should bave the card
handy while you are leaminl vi.

1.1. SpeclfyinC terminal tnw
Before you can start vi you must tell the system what kind of terminal you are using.
Here is a (necessarily incomplete) list of terminai type codes. If your terminal does nOl appear
here. you should consult with one of the staff members on your system to find out the code for
your termina1. If your terminal does not have a code. one can be assigned and a description for
the terminal can be created.
Code

Fun Dame

TYlM!

2621
2645
1C14

Hewlett-Pac:Jcard 2621 AlP
Hewlett-Packard 264x
Mic:roterm ACT·IV
Microterm ACT-V
Lear Sie;ler ADM-3a
Lear Sie;ler ADM-31
Human Design Concept 100
Datamedia 1520
Datamedia 2500
Datamedia 3025
Perkin-Elmer Fox
Hazeltine 1500
HeathJcit b19
Infoton 100
!mitatinl a smart act4

Intelligent
Intelligent
Dumb
Dumb
Dumb
Intelligent
Intelligent
Dumb
Intelligent
Intelligent
Dumb
In tellilent
Intellilent
Intelligent
InteUilent

ICS
adm.3a
1dm31
cl00
dmlS20

dmlSoo
dm3025
fox
b1500
b19

ilOO
mime
The lin.neal

su~

MCS7~76044-A03 IIId

o( III ... G..-Iuale Feilowsfti~ and the
MCSis-a7l91 is pte{Wly ldaulwledpd.

~.tionat

Science Foundation under innIS

·2·
tl061

Teleray 1061

Intelligent

vtS2

Dec 'IT-52

Dumb

Suppose for example that you have a Hewlett-Packard HP2621A terminal. The code used
by the system for this terminal is '2621', In this case you can use one of the following com-

mands to teU the system the type of your terminal:
% setan TElL.,. 2621

This command wories with the shell csh on both version 6 and 7 systems. If you are using the
standard version 7 sheU then you should give the commands

S TERM-2621
S export TElL"d
If you want to arrange to have your terminal type set up automatically when you log in,
you can use the tSlt program. If you dial in on a mim~, but often use hardwired ports, a typical
line for your .Iogin file (if you use csh) would be
5eWIT

TERM 'tset - -d mime'

or for your .projiil! file (if you use $h)

TERM-'tset - -d mime'
T~ knows which terminals, are hardwired to each port and needs only to be told that when you
dial in you are probably on a mim~. TSlt is usually used to change the erase and kill characters,
too.

,~

1.2. IdltiDI. 81e
After telling the system which kind of terminal you have, you should make a copy of a
file you are familiar with. and run II; on this file, giving the command
%

replacing

n

name

nam~

with the name of the copy file you just created. The screen should clear' and the
If something else happens refer to the footnote.;

text of your file should appear on the screen.

1.3. The editor's copy: the buffer
The editor does not directly modify the file which you are editing. Rather, the editor
makes a copy of this file. in a place called the lJuffer. and remembers the file's name. You do
Dot atrect the contents of the file unless and until you write the changes you mue back into the
original file.

,-'

• If' 70U pw !be system ID iDc:orrecl terminaf type code lbcn tbe editor rnay bave just INde I mas out of
7OUI' SCI"aft. TbiI ~ ..,nen it seftds control c:odes for one kind of termina.l to some other kind of termi·
aaL 111 this cue bit the keys :q (colon aDd the q key) and then bit !be uruaN key. This should let you baa
10 tbe command level ia&erpreter, Fiaure out ..,hat you did wrona (uK someone dse if nea=ssary) and try
apia.
ADolber tbiac wftidl I2D 10 wrona is that 70U tYJ*i !be WTOCII file name and !be editor just printed an
error c1iap!OSllc. 111 UUS cae you sboWd faDo.., tbe lbow procedure for seuinl out 0( IDe editor. aDd try
apia Ibis lime $CII!iliDa tbe file nam. c:orTedJY,
If' !be editor doesn't seem to respond to lbe commanc1s ..,bidl you type bere. try sendinl aD InterTUl'l to it
bJ biaiaa tbe DEL or au. key aa your termina.l. aDd tbeD IliUina tbe :at command apia roUowed by I c:am.qe
*WIL

• 3•
1.... Notational conTentions

In our examples, input which must be typed as is will be presented in boJd face. Text
which should be replaced with appropriate input wiJi be given in italics. We will represent special characters in SMALL CAPTTALS.
.
1.5. Arrow keys
The editor command set is independent of the terminal you are using. On most terminals
with cursor positioning keys, these keys will also work within the editor. If you don't have cursor positioning keys, or even if you do, you can use the h j k and I keys as cursor positioning
keys (these are labelled with arrows on an adm3a). •
(Particular note for the HP2621: on this terminal the function keys must be shifted (ick)
to send to the machine, otherwise they only act locally. Unshifted use will leave the cursor
positioned incorrectly,)

1.6. Special chancters: ESC. ell ad DEL
Several of these special characters are very important, so be sure to find them right now.
Look on your keyboard for a key labelled ESC or ALT. It should be near the upper left corner of
your terminal. Try hitting this key I few times. The editor will ring the bell to indicate that it
is in a quiescent state.* Partially formed commands are canceJled by ESC, and when you insert
text in the file you end the text insertion with ESC. This key is a fairly harmless one to hit, so
you can just hit it if you dan't know what is I~ing on until the editor rings the bell.
The CR or IlE'TURN key is important because it is used to terminate certain commands. It
is usually a1 the richt side of the keyboard, and is the same command used at the end of each
shell command.
Another very useful key is the DEL or RUB key, which generates an interrupt, telling the
editor to stop what it is doing. It is a forceful way of making the editor listen to you, or to
return it to the quiescent state if you don't know or don't like what is going on. Try hitting the
'I' key on your terminal. This key is used when you want to specify a string to be searched for.
The cursor should now be positioned at the bottom line of the terminal after a 'I' printed as a
prompt. You can get the cursor back to the current position by hitting the DEL or RUB key~ try
this now.- From now on we will simply refer to hitting the DEL or RUB key as "sending an
interrupt... The editor often echoes your commands on the last line of the terminal. If the cursor is
on the first position of this last line, then the editor is performing a comput.1tion, such as computing I new .,osition in the file after a search or running a command to reformat part of the
bu1fer. When ~is is bappeninS you can stop the editor by sending an interrupt.

1.7. GettfDI oat of the editor
After you have worked with this introduction for a while, and you wish to do something
else, you can give the command ZZ to the editor. This will write the contents of the editor's
bu1fer back into the file you are editing. if you made any changes, and then quit from the editor. You can also end an editor session by givins the command :q!CR;t this is a dangerous but
occasionally essential command which ends the editor session and discards aU your changes.
You need to know about this command in case you change the editor's copy of a file you wish
- As we wiD see Later, " moves bKt to me left Oike control-I! wftidl is • bac:SsyJec:e), j moves down (in the
arne column), k moves ~ (in the same column), aDd {moves to tbe ript.
• On sman terminals where it is possible. tbe editor will quietly t1ub the saeeD ralber tban rinpnl tbe beil.
• ~nl OYer me .,. wiD aJso cancel tbe search.
- On some systemS, Ibis int~bilily comes a' a price: you c:anDOC tY)'e abead when !be editor is com""tiDa wilb the cursor on me bcnom !iDe.
t AD c:ommaDds wtsid2 rll8d from the 1ul _lay line can aJso be terminated with • ESC U -n .. III C1.

- 4only to look 11. Be very careful Dot to Jive this command wben you really want to save the
chanles you have made.
...4

""'.

%. MO'fiDI arouDd ill the flle
%,1. ScroIliDI aad padDI
The editor bas a Dum~ of commands for movinl around in the file. The most useful of
these is lenerated by hitlinl the control and D keys at the same time. a control-D or ·-D'. We
wiD use this two character Dotation for referrinl to these control keys from DOW on. You may
have a key labelled .- on your terminal. This key wiD be represented as '1' in this document;
,., is exclusively used as part of the 'AX' DOtation for control characters.*

M you know now if you tried hillinl AD. this command scrolls down in the file. The D
thus stands for down. Many editor commands are mnemonic and this makes them much easier
to remember. For insunce the command to scroll up is -U. Many dumb terminals can't scroll
up at aU, in which case hitting AU dears the screen and refreshes it with a line which is farther
back in the file at the top.
Ir you want to see more of the file below wbere you are, you can hit '"E to expose one
more Une at the bouom of the screen, leavinl the cursor wbere it is. ~ The command -y
(which is hopelessly non-mnemonic, but Dext to -U on the keyboard) exposes one more line at
the top of the screen.
There are other ways to move around in the fil~ the keys "'F and AB move forward and
backward a page, keepinl a couple of lines of continuity between screens so that it is possible to
read throu&h a file usml these rather than AD and -U if you wish.
Notice thedi6erence between scrolling and pacing. If you are tryinl to read the text in a
file, hitlinl 'T to move forward a pqe will leave you only a little context to look back at.
Scrollinl on the other hand leaves more context, and happens more smoothly. You can con.. ___ tinue to read the text as_scrolling is takiDl plac:.

*

__

l.l. SeudliDl. loto, ud prenoas coatest
Another way to position yourself iD the file is by pving the editor a string to search for.
Type the charaI:ter / followed by a string of c:haractc:rs terminated by CR. The editor will position the cursor at the Dext occurrence of this string. Try hitting D to then 10 to the next
occurTeDCe of this string. The cbaracter ! will search backwards from where you are, and is
otherwise like /. t
-.
It the search strinl you pve the editor is not present in the file the editor will print a diqDOStie on the last line of the screen. and the cursor wiD be returned to its initial positiOD.
If' you wish the search to match only at the belinning of a line. belin the search string
with an T. To match only at the end of a line. end the search strine with a S. Thus IT searcheR
will search for the word 'search' at the bqinDine of a lin~ and Ilastb searches for the word
'last· at the end of aline.·

• Irl'OU daD', !law ••~

kay 011 10Ut tenDiaa1 tbeD lIIIn is proOallly • key IaOeJIed 'T'~

iD lIlY

C2Se

tbae

an 0-. .ad tJIe . . . .

.. Venioa J 0IlIy.
• Mot i\'Uablc ill aD y 1 adi&on due 10 memory c:DIIIlniD&s.
, ne.
wiD aomWIy
around the end 0( tile me. and tJnas lind tbe suiftl eYeD if il is DOl on a
!iDe ill tile dirediaa ,.,.. ..reD provided il is anywben die ill tile fUc. You caa disatM IJIis wraperound in
DIll by IMftI tbe commaad :se aown~ or more briedy :Ie ...a.
-AcnIaiIy. tile SIriDI ,.,.. sift 10 ..reD far ben caa be. ,..,., ~ ill tile sen. at the edi&on t:r

- 5The command G. when preceded by a number will position the cursor at that line in the
file. Thus IG will move the cursor to the first line of the file. If you give G no count. then it
moves to the end of the file.
If you are near the end of the file. and the last line is not at the bottom of the screen. the
editor will place only the character .... on each remaininl line. This indicates that the last line
in the file is on the sa~ that is. the .... lines are past the end of the file.
You can find out the state of the file you are editinl by typinl a AG. The editor will show
you the name of the file you are editinl. the number of the current line. the number of lines in
the buifer. and the percentale of the way throu&h the buirer which you are. Try dOinl this
now. and remember the number of the line you are on. Give a G command to let to the end
and then another G command to let back where you were.
You can also let back to a previous position by usinl the command •• (two back quotes).
This is often more convenient than G beause it requires no advance preparation. Try giving a
G or a sean:h with I or ! and then a .. to get back to where you were. If you acedentally hit D
or any command which moves you rar away rrom a context of interest. you can quickly get
back by llittinl ".

%.3. MOTtDI arouDd OD the

screeD

Now try just movinl the cursor around OD the saeen. If your terminal has arrow keys (4
or 5 keys with arrows loing in each direction) try them and convince yourself that they work.
(On certain terminals using v2 editors. they won't.) If you don't have working arrow keys. you
can aJways use b. J, k., and 1. Experienced users of '11; prefer these keys to arrow keys. because
they are usually ri&ht underneath their finlers.
Hit the + key. Each time you do. notice that the cursor advances to the next line in the
file. at the first Don-white position on the line. The - key is like + but goes the other way.
These are very common keys ror moving up and down lines in the file. Notice that if you
10 off the bottom or top with these keys then the saeen will saoU down (and up if possible) to
brinl a line at a time into view. The R.ETtJRN key has the same efi'ect as the + key.
Vi also has commands to take you to the toP. middle and bottom of the screen. H will
take you to the top (home) line on the scre:n. Try preceding it with a Dumber as in 3H. This
will take you to the third line on the saeen. Many vi commands take preceding numbers and
do interestil'!1 thinCS with them. Try M. which takes you to the middle line on the screen. and
L. which takes you to the last line on the screen. L also takes counts. thus SL will take you to
the fifth line rrom the bottom.

1....

MOTiDI withiD • BDe
Now try pickinl a word on some line on the screen. Dot the first word on the line. move
the cursor usinl REn11l.'" and - to be on the line where the word is. Try hiuinl the w key.
This will advance the CW"SOr to the next word on the line. Try bitlinl the 11 key to back up
words in the line. Also try the e key which advances you to the end of the current word rather
than to the bqinninl of the next word. Also try SPACE (the space bar) which moves right one
d1aracter and the as (backspace or AH) key which moves left one character. The key b works
IS AH does and is useful if' you don't have I as key. (Also. IS Doted just above. I will move to
the ri&hL)
If the line had punctuation in it you may have noticed that that the w and 11 keys stopped
at each IfOUP of punctuation. You can also 10 back and forwards words without stopping at
punctuation by usinl W and B rather than the lower case equivalents. Think of these as bigger
words. Try these on a few lines with punctuation to see bow they differ from the lower case w
and 11.
The word keys wrap around the end of line. nlther than stoppinl at the end. Try moving
to a word on a line below where you are by f'el)eateci1y hillinl w.

·61.5. Summary
SPACE

-B

-n
-E
'"}"

-G

-H
-N

-p

-U
-y

+
I

.,.

B

G
H
M
L
W

b

e
D

w

advance the cursor one position
backwards to previous page
scrolls down in the file
exposes another line at the bottom (v3)
forward to next page
teU what is loing on
backspace the cursor
next line, same column
previous line, same column
scrolls up in the file
exposes another line at the top (v3)
next line, at the beginning
previous line, at the beginning
scan for a fonowing string forwards
scan backwards
back a word, icnoring punctuation
10 to specified line, last default
home saeen line
middle saeen line
last screen line
forward a word.. ignoring punctuation
back a word
end of current word
scan for next instance of I or '! pattern
word after this word

1.6. View i
If you want to use the editor to look at a file, rather than to make changes. invoke it as
instead of vi. This will set the rmdonly option which will prevent you from acOdently
overwriting the file.

V"

3. Makinc simple chances

1.

3.1. IDsertiDc
One of the most useful commands is the i (insert) command. After you type i. everything you type until you hit ESC is inserted into the file. Try this now~ position yourself to
some word in the file and try inserting text before this word. If you are on an dumb terminal it
will seem. for a minute. that some of the characters in your line have been overwritten. but
they will reappear when you bit ESC.
Now try finding a word which can. but does not. end in an ·s'. Position yourself at this
word and type e (move to end of word), then a for append and then 'SESC' to terminate the
textual insert. This sequence of commands can be used to easily pluralize a word.
Try inserting and appending a few times to m.a.k.e sure you understand how this worlts~ i
placing text to the left of the cursor. a to the ri&ht.
II is oflen the case that you want to add new lines to the file you are editing. before or
after some Sl'ecific line in the file. F11ld a line where this makes sense and then give tbe command C) to create a new line after the line you are on. or the command 0 to create a new line
before tbe line you are on. After you create a new line in this way. text you type up to an ESC

*Not available in UI vI edilGrS _

10 memory coastraiDu.

- 7is inserted on the new line.

Many reJated editor commands are invoked by the same letter Ieey and differ only in that
one is liven by a lower case key and the other is gjven by an upper case key. In these cases,
the upper case Ieey often differs from the lower case Ieey in its sense of direction. with :he
upper case key working backward and/or uP. while the lower case key moves forward and/or
down.

Whenever you are typing in text., you can give many lines of input or just a few charac·
ters. To type in more than one line of text., hit a IlETtJRN at the middle of your input. A new
line will be created for text. and you can continue to type. If you are on a slow and dumb ter·
minal the editor may choose to wait to redraw the tail of the screen. and will let you type over
the existing screen lines. This avoids the lengthy deJay which would occur if the editor
attempted to keep the tail of the screen always up to date. The tail of the screen will be fixed
uP. and the missing lines will reappear. when you hit ESC.
While you are inserting new text. you can use the characters you normally use at the system command level (usually -H or #) to backspace over the last character which you typed.
and the character whicll you use to kill input lines (usually @ ... X. or ·U) to erase the input
you have typed on the QUTent line. t The character -W will erase a whole word and leave you
atler the space after the previous word.; it is useful for quickly backing up in
insert.
Notice that when you backspace during an insertion the characters you backspace over are
not ~ the cursor moves backwards. and the characters remain on the display. This is
often useful if you are piannin, to type in something similar. In any case the characters disappear when when you hit ESC; if you want to get rid of them immediately. hit an ESC and then a
apin.
Notice also thal you can't erase characters which you didn't insert. and that you can't
backspace around the end of a line. If you need to back up to the previous line to make a
correction. just hit ESC and move the cursor back to the previous line. After making the
correction you can return to where you were and use the insert or append command again.

-an

3.2. Makinc small COrrectiODS
You can make small corrections in eXlSung text quite easily. Find a single character
which is wrong or just pick any character. Use the arrow keys to find the character. or get near
the character with the word motion keys and then either backspace (hit the BS key or "H or
even just h) or SJlACE (using the space bar) until the cursor is on the character which is wrong.
If the character is nOl needed then hit the % keT, this deletes the character from the file. It is
analogous to the way you % out characters when you make mistakes 00 I typewriter (except it's
not as messy).

It the character is incorrect. you can replace it with the correct character by giving the
command rc. where c is replaced by the correct character. Finally if the character which is
incorrect should be replaced by more than one character. gjve the command s which substitutes
I striog of characters. ending with ESC. for iL It then: are a small cumber of characters which
are wrong you can precede s with I count of the number of characters to be replaced. Counts
are also useful with % to specify the number of characters to be deleted.

3.3. More

COrrediODS:

opentors

You already know almost enough to make changes at I higher level. All you need to
know now is that the cl key acts IS a dejete operator. Try the command ell' to delete a word.
Try hitting. a few times. Notic:: that this repeats the effect of the ell'. The command. repeaLS
the last command which made a chanle. You can remember it by analogy with an eHipsis ......

t

Ia (act. me dwaclcr "H (bac:XsTJ!ace) liways worts to erue the Iul inCNl dlanc:er !tere. rqardlcss

'f'NZ

erase c:nancser is.

0(

_hal

·8-.
Now try db. This deletes a word backwards, namely the preceding word. Try dsPACE.
This deletes a single character, and is equivalent to the x command.
Another very useful operator is c or change. The command c:w thus changes the text of a
single word. You follow it by the replacement text ending with an ESC. Find a word which you
can change to another, and try this now. Notice that the end of the text to be changed was
marked with the character'S' so that you can see this as you are typing in the new material.

3.4. OpenriDI OD llDes
It is often the case that you want to operate on lines. Find a line which you want to
delete. and type dd. the d operator twice. This will delete the line. If you are on a dumb terminal. the editor may just erase the line on the screen. replacing it with a line with only an @
on it. This line does not correspond to any line in your file, but only acts as a place holder. It
helps to avoid a lengthy redraw of the rest of the screen which would be necessary to close up
the hole created by the deletion on a tennina.l without a delete line capability.
Try repeating the c operator twice; this will change a whole line, erasing its previous contents and replacng them with text you type up to an ESC. t
You .;;m delete or change more tiw1 one line by preceding the dd or cc with a count, i.e.
Sdd deletes 5 lines. You can also give a command like dL to delete all the lines up to and
including the last line on the screen. or d.3L to delete through the third from the bottom line.
Try some commands like this now.- Notice that the editor lets you know when you change a
larJe number of lines so that you can see the extent of the change. The editor will also always
tell you when a change you make aifects text which you cannot see.
3.5. UDdoiDc
NoW' suppose that the last change which you made was incorrect~ you could use the insert.
delete and append commands to put the correct material back. However, since it is often the
case that we re&ret a change or make a change incorrectly, the editor provides a u (undo) command to reverse the last change which you made. Try this a few times, and give it twice in a
row to notice that an u also undoes a u.
The undo command lets you reverse only a single change. After you make a number of
changes to a line. you may decide that you would rather have the original state of the line back.
The U command restores the current line 10 the state before you started changing it.
OD

You can recover text which you delete. even if undo will not bring it bac:k~ see the section
recoverinllost text below.

3.6. Summary
SPACE

'"H
-W

erase
kill

o
U

•

c

advance the Cltt!or one position
backspace the cursor
erase a word during an insert
your erase (usually -H or #), erases a character during an insert
your Irill (usually @, -x, or -U), kills the insert on this line
repeats the changing command
opens and inputs new lines. above the current
undoes the changes you made to the current line
appends text after the cursor
changes the object you specify to the following text

t The command S is I Cl)ftvenicnl synoaym (or (or CIC. by IIWoU ";Us s. l'hin& 01 SIS. subsUtute on
1iDes, ..hile tis. substitUle Oft c:banders.
• ODe subUe point here involves
tile I sean:D after I Ii. Tbis wiD normany delete chanc:ten (rom tbe
curTaIl positioD to the point 01 !be matdl. If ..tal is ~ is 10 dejele wbole lines indUdiI1l the two pouus.

usin,

Ii". tile paaem as I,.,., +t•• Iiae addna.

- 9deletes the object you Sl)ecify
inserts text before the cursor
opens and inputs new lines, below the current
undoes the last change

Ii
1
o
11

4_ MOYiDC about; resn'2DgiDI and dupUC3dnc tut

".1. LDw IenJ character motioDs
Now move the cursor to I line where there is a punctuation or a bracketing character such
u a parenthesis or a comma or period. Try the command Cx where z is this character. This
command finds the next z character to the right of the cursor in the current line. Try then hitting a ;, which finds the next instance of the same character. By using the r command and then
a sequence of ;'5 you can often get to a particular plac:: in a line much raster than with a
sequence of word motions or SPACEs. There is also a F comman~ which is like C, but searcbes
backward. The; command repeats F also.
When you are operating on the text in a line it is often desirable to deal with the characters up to, but not including. the first instance of a character. Try cU'.x ror some z now and
notice that the z character is deleted. Undo this with 11 and then try d~ the t here stands for
fD, Le. delete up to the next X. but not the.x. The command T is the reverse of t.
When worltine with the text of a single line, an T moves the cursor to the first non-white
position on the line, and a $ moves it to the end of the line. Thus Sa will append new text at
the end of the current line.
Your file may have tab (AI) characters in it. These c:ha.racters are re;»resented as a number
of Sl)aces expanding to a tab stop, where tab stops are every 8 positions.· When the cursor is at
a tab, it sits on the last of the several Sl)KeS which represent that tab. Try moving the cursor
back and rorth over tabs so you understand how this works.
On rare occasions, your file may have nonprinting characters in it. These characters are
displayed in the same way they are represented in this document, that is with a two character
code. the first character of which is .-'. On the screen non-printing characters resemble a ,-,
character adjacent to another, but spacing or backspacing over the character will reveal that the
two characters are, like the spaces representing a tab character. a single character.
The editor sometimes discards control characters. depending on the character and the settine of the bmutifY option. if you attempt to insert them in your file. You can get a control
character in the DIe by beginniDl an insert and then typing a -V before the control character.
The -V quotes the followiDl character, causing it to be inserted directJy into the file:.

".l.

Hlcher Ie1'el

tut objects

In woronl with a document it is often advantageous to work in terms of sentences. para&nphs, and sections. The operations ( and ) move to the beginning of the previous and next
sentenc:e:5 respectively. Thus the command ei> ";11 delete the rest of the current sentence~ likewise Ii( will delete the previous sentence if you are at the beginninl of the current sentence. or
the current sentence up to where you U'e if you are not at the beginning of the current sentence.
A sentence is defined to end It I '.', '!' or '1' which is rollowed by either the end of a
line. or by two spaces. Any number of closinl ')" 'J\ ••, and ". characters may IPPe3I aiter
the '.'. '!' or '1' before the spaces or end of line.
The operations ( and J move over paraaraphs and the operations II and move over sec·
tions. t

n

command al tile rorm :se ts-lC1. ~ z is 4 to set tabstoCII every (our c:ojumn.s.
[be editor.
oc-atians require 1lIe ~lion cnar.cer to be doubled because tbey can move !be cunor far

• This is sellel. b7

This bas

I

esfCCl OD the

t ne II aDd 11

screen teFeseftlation wimm

• 10·
A paraaraph begins after each empty line. and also at each of a set of paragraph macros.
specified by the pairs of characters in the definition of the string valued option ptUagrapns. The
default seEting for this option defines the paragraph macros of the -ms and -mm macro packages. i.e. the '.lP'. •.LP', '.PP' and '.QP'. '.P' and '.U' macros.* Each paragraph boundary is
also a sentence boundary. The sentence and paragraph commands can be &iven counts to
operate over groups of sentences and paragraphs.
Sections in the editor begin after each macro in the S«tions option, normally '.NH'. •.SH' .
•.H' and '.HU'. and each line with a fonnfeed '"L in the first column. Section boundaries are
always line and paragraph boundaries also.
Try experimenting with the sentence and paragraph commands until you are sure bow
they work. If you have a Iatle document, try looking through it using the section commands.
The section commands interpret a preceding count as a different window size in which to
redraw the screen at the new location. and this window size is the base size for newly drawn
windows until another size is specified. This is very useful if you are on a slow terminal and
are looking for a particular section. You can give the first section command a small count to
then see each sucx:ssive section heading in a small window.

".3.

lleurandnc and du;!'catfDI tal

The editor has a sin&le unnamed buffer where the last deleted or changed away text is
saved. and a set of named buffers a-z which you can use to save copies of text and to move
text around in your file and ~tween files.
The operator '1 yanks a copy of the object which fonows into the unnamed buffer. If preceded by a buffer name, -XY. where x here is replaced by a letter a-z. it places the text in the
named buffer. The text can then be put bade in the file with the commands p and P; p puts
the text after or below the cursor, while P puts the text before or above the cursor.
If the text which you yank forms a part of a line. or is an object such as a sentence which
partially spans more than one line. then when you put the text back. it will be placed after the
cursor (or before if you use P). If the yanked text forms whole lines. they will be put back as
whole lines. without changing the current line. In this case. the put acts much like a 0 or 0
comman~
.
Try the command YP. This makes a copy of the current line and leaves you on this copy.
which is placed before the current line. The command Y is a convenient abbreviation for rJ.
The command Yp will also make a copy of the current line. and place it after the current line.
You em Jive Y a count of lines to yank, and thus duplicate several lines; try 3YP.
To move text within the buffer. you need to delete it in one place. and put it bade in
mother. You can precede a delete operation by the name of a buffer in which the text is to be
stored as in -a5dd deleting S lines into the named buffer a. You can then move the cursor to
the eventual resting place of the these lines and do a -ap or -aP to put them back. In fact. you
can switch and edit another file before you put the lines back. by &iving I command of the form
:. flGmeo.. where ntlm~ is the name of the other file you want to edit. You wiIl have to write
back the contentS of the current editor buffer (or discard them) if you have made changes
before the editor will let you switch to the other file. An ordinary delete command saves the
text in the unnamed buffer. so that an ordinary put can move it elsewhere. However. the
unnamed buffer is lost when you change files, so to move text from one tile to another you
should use an unnamed buffer.

'**

from wDere it aarrmlJy is. While it is easy 10 pl
widI the command -. tbese cammmds would sliD be
frusvalinl if tbey were easy to hit acCdeftWly.
You can easily d'I.Inp or extend tJsjs set of m.c:ras by usill'lina • dift'erent sviDl to tbe ~ ~n
in YOIII' EXINlT. See sedioa 6.2 for deWlI. Tbe' .•• directive is aJso considc:ed to SWt • pan.,."il..

*

- 11 ~ ....

Summary.
T

first non-white on line

$
)
}

end of line
forward sentence
forward paragraph
forward section
baeXward sentence
backward paragraph
backward .section
find :r forward in line
put text back, after cursor or below current line
yank operator, for copies and moves
up to :r forward. for operators
f backward in line
put text back, before cursor or above current line
t baaward in line

JI
(

(

II
.fx
p
"1

tx
F,X
P

T,X

S. HIgh lenI commands
S.l. Writinl. quittiDI. editiDI Dew tiles
So far we have seen how to enter vi and to write out our file using either ZZ or :wc::t.
The first exits from tbe editor, (writing if changes were made), the second writes and stays in
the editor.
If you have changed the editor's copy of the file but do not wish to save your changes.
either bec3use you messed up the file or decided that the changes are not an improvement to
the file, then you can &ive the command :q!CR to quit from the editor without writing the
changes. You can also reedit the same file (starting over) by &iving the command :e!CR. These
commands should be used only rarely, and with caution, as it is not possible to recover the
changes you have made after you discard them in this manner.
You can edit a difi"erent file without leaving the editor by &iving the command :e namt'CR.
try to do ~ then the editor will tell you this.
and delay editing the other file. You can then &ive the command :wCR to save your worle and
then the :e nam«:R command again. or carefully &ive the command :e! MmeO.. which editS
the other file discarding the changes you have made to the current file. To Dave the editor
automatically save chang~ maude SIt autowri~ in ~r EXINlT. and use :n instead of ~.

If you have not written out your file before you

S.l. EscapiDI to

shell
You can ,et to a sheil to execute a single command by &iving a vi command of the fonn
:!anti:ll. The system will run the single command cmd and when the command finishes. the
editor will ask you to hit a RETURN to continue. When you have finished looking at the out~ut
on the screen. you should llit RETURN and the editor will c1ear the saeen and redraw it. You
c:an then continue editing. You can also &ive another : command when it asks you for a
RETURN~ in this case the saeen will not be redrawn.
I

It you wish to execute more tban one command in the sheil. then you can give the com·
mand :shCll. This will give you a new sheil. and when you finish with the sheil. ending :t by
typing a AD. the editor will clear the saeen and continue.
On systems which support it. AZ will suspend the editor and return to the (top levei)
sheil. When the editor is resumed. the screen will be redrawn.

- 12 -

5.3. Markinl and returninl
The command ,. returned to the previous place after a motion of the cursor by a command such as I. '! or G. You can atso mark lines in the file with single letter tags and return to
.these marks later by naming the tags. Try marking the current line with the command mx..
where you should pick some letter for .r. say 'a'. Then move the cursor to a different line (any
way you like) and hit '.. The cursor will return to the place which you marked. Marks last
only until you edit another file.
When using operators such as cI and referring to marked lines. it is often desirable to
delete whole lines rather than deleting to the exact position in the line marked by m. In this
case you can use the form '::c rather than 'x. Used without an operator. '::c will move to the first
oon-white character of the marked line~ similarly" moves to the first non-white character of
the line containing the previous context mark ".

5.4. Adjustinl the screeD
If the saeen image is messed up because of a transmission error to your terminal. or
because some program other than the editor wrote output to your terminal. you can hit a -L.
the ASClI form-feed character, to cause the saeen to be refreshed.
On a dumb terminal, if there are @ lines in the middle of the screen as a result of line
deletion, you may let rid or these lines by typing -1l to cause the editor to retype the screen.
dosing up these holes.
.
Finally. if you wish to 'place a certain line on the screen at the top middle or bottom of
the !Creen, you can position the cursor to that line. and then give a z command. You should
follow the z command with a RETURN if you .want the line to appear at the top of the window, a
• if you want it at the center, or a - if you want it at the bottom. (L, Z-. and z+ are not available on all v2 editors.)

•

,. Special topics
'.1. Editio, on slow terminals
When you are on a slow terminal. it is important to limit the amount of output which is
generated to your sc:reen so that you will not suffer long delays, waiting for the screen to be
refreshed. We have already pointed out how the editor optimizes the updating of the screen
during insertions on dumb terminals to limit the delays, and how the editor erases lines to @
w~en they are deleted on dumb terminals.
The use of the slow terminal insertion mode is controlled by the sJowo~n option. You
can foi'O: the editor to use this mode even on faster terminals by givinl the command :se
slowcR. If your system is sluggish this helps lessen the amount of output coming to your terminal. You can disable this option by :se aoslowcll.
The editor can simulate an intelligent terminal on a .dumb one. Try &iving the command
:se rednwCll. This simulation generates a great deal of output and is lenerally tolerable only
on lightly loaded systems and fast terminaLs. You can disabJe this by &iving the command
:se aorednWCR.
The editor also makes editing more pleasant at low speed by starting editing in a small
window, and lenin, the window expand as you ediL This works particularly well on inteiligent
terminals. The editor can expand the window easily when you insert in the middle of the
screen on these terminals. If possible, try the editor on an intelligent terminal to see how thiS
works..
You can control the size of the window whicb is redrawn e3ch time the screen is cleared
by livinl window sizes as argument to the commands which cause large screen motions:

t

:/!((I)"
'Plus if you are searchina for a particular instance of a common string in a file you can precede

• 13 the first search command by a smail number, say 3, and the editor will draw three line windows
around each instance of the string which it locates.
You caD easily expand or contract tbe window, placing tbe current line as you choose, by
Jiving a number on a z command, after tbe z and before the following RETURN •• or -. Thus
the command 15. redraws the screen witb the current line in tbe center of a five line window. r

If the editor is redrawing or otherwise updating large portions of the display. you can
interrupt this updating by hitting a DEL or RUB as usuaL If· you do this you may partially confuse the editor about what is displayed on tbe screen. You can still edit the text on the screen
if you wish; clear up the confusion by hitting a ·L~ or move or search apia, ignoring the
current state of the display,
See section 7.8 on open mode for another way to use the vi command set on slow lenni-

aa1s.

6.1. OptioDS, set, IDd editor startup files
The editor has a set of options, some of which have been mentioned above. The most
useful options are given in the following table.
Name
autoindent
autowrite
iJllorecase
lisp
list
magic
number
paragraphs
redraw
sections
shiftwidth
showmatch
siowopen
term

Delallit
noai
noaw
noi.:
nolisp
nolist
nOmaglc
nonu
para-IPLPPPQPbpP LI
nore
sect -

NHSHH HU

sw-8
nosm
siow
dumb

DescriptioD
Supply indentation automatically
Automatic write before :D, :ta, AT, !
IlDore case in searching
( I ) I commands deal with S-expressions
Tabs print as AI; end of lines marlced with S
The characters . ( and • are spedal in scans
Lines are displayed prefixed with line numbe:-s
Macro names which start paragraphs
Simulate a smart terminal .on a dumb one
Macro names which start new sections
Shift distance for <, > and input AD and -r
Show matcfling ( or I as ) or } is typed
Postpone display updates during inserts
The kind of terminal you are using.

The options are of three kinds: numeric options, string options, and toggle options. You

can set numeric and string options by a statement of the form
set opr- WI/
and toggle options

caD

be set or unset by statements of one of the forms

set opt
set DOOpl
These statements can be placed in your EXINIT in your environment. or given while you are
running vi by preceding them with a : and following them with a CR.
You caD get a list of all options which you have changed by the command :setC~, or the
value of a single option by the command :set Opl?CR. A list of all possible options and thelr
values is generated by :set alleR. Set caD be abbreviated se. Multiple options can be placed on
one line. e." :se ai .,. DIIOt.
Options set by tbe set command only last while you stay in the editor. It is common to
want to have certain options set whenever you use the editor. This can be aa:ompiished by
creatine a list of ex commandst 'which are to be run every time you start up ex. tOil, or VI. A

t
t

Note IDa, the ~mmlPd 51. baa aD -=ntirdy ditfetent e6ec. piKlnl line 5 La the center
All commands -hidl start witll : Ire er commaads.

o( • Dew

window.

• 14 typical list includes a set command. and possibly a few map commands (on v3 editors). Sine:
it is advisable to get these commands on one line. they can be separated with the I character. for
example:

set ai aVi terse:Psap

@

ddjmap # x

which sets the options autoindent, aulowrile. terse. (the set command). makes @ delete a line.
(the first map), and makes # delete a character. (the second map). (See section 6.9 for a
description of the map command, which only works in version 3.) This string should be placed
in the variable EXINIT in your environment. If you use alt. put this line in the tile .Jogln in
your home directory:
setenv EXIN1T 'set ai aVi ters~ap

@ d~ap

# x'

If you use the standard v7 shell. put these lines in the tile .profile in your home directory:

EXlNlT-'set ai aw terselmap
export EXIN1T

@ d~ap

# x'

On a version 6 system. the concept of environments is not present. In this case. put the line in
the tile .IXTC in your bome directory.
set ai aVi ~p @ ddlmap # x

Of course. the particulars of the line would depend on which options you wanted to set.

6.3. Reconrinc lost lines

.

You might have a serious problem if yoU' delete a number of lines and then regret that
they were deleted. Despair not. the editor saves the last 9 deleted blocks of text in a set of
numbered registers 1-9. You can get the n'th previous deleted text back in your file by the
command e np. The· here says that a buffer name is to follow. n is the number of the buffer
you wish to try (use the number 1 for now). and p is the put command, which puts text in the
butrer after the cursor. If this doesn't bring back the text you wanted., hit 11 to undo this and
then. (period) to repeat the put command. In general the. command will repeat the last
change you made. As a special case. when the last command refers to a numbered text buffer.
the . command increments the number of the butrer before repeating the command. Thus a
sequence of the form
'pu.II.II.

will. if repeated long enough. show you all the deleted text wbich has been saved for you. You
can omit the 11 commands bere to gaLber up all this text in the buffer. or stop after any . com·
mand to keep just the then recovered i.:~t. The command P can also be used rather than p to
put the recovered text before rather than after the cursor.

6.4. Reconrinl lost tlles
If the system crashes. you can recover the worle you were doing to within a few chanses.
You will normally receive mail when you next login giving you the name of the file which has
been saved for you. You should then chanae to the directory where you were when the system
crashed and pve a command of the form:

% Ti - r

fllUlfe

replacing fUZm~ with the name of the file which you were editing. This will recover your worlc
a point near wbere you left off. t

to

1

t In rare cases.. 3Qme of the lines of the file may be 1ost. The edilOr wiD live you the nwnbCS's of these lines
IIId the text of the !ina wiD be ~ by tbe SU'iftl 'LOST. These Iincs will almost a./ways be amon, ttle:
IaI& few wbid2 you dlanpd. You can ~thc:r cboose 10 discard the dlanaa whidl you made (j{ they arc: easy
10 temUeJ or 10 ~ t.be few 1011 lines by baDd.

- IS You can Ie:t

I

listing of the files which are saved for you by giving the command:

%" -r
If there is more than one: instance of a particuiar file saved. the editor gives you the newest
instance each time you recover iL You can thus Ie:t an older saved copy back by first recover·
ina the: cewe:r copies.
For this feature to work. vi must be: correctly installed by a super user on your system.
and the mall program must exist to receive maiL Theinvocation .. vi -I· will not always list all
saved files, but they can be: recovered even if they are not listed.

,.5.

CoatiDllous text iaput
When you are typing in large amounts of text it is convenient to have lines broken near
the: right margin automatically. You can cause this to bappen by giving the command :se
WID-IOcR. This causes all lines to be: broken at a space at least 10 columns from the right
band edge of the screen.·
If the editor breaks an input line and you wish to put it back together you can tell it to
join the lines witb J. You can Jive: J I count of the cumber of lines to be joined as in 3J to
join 3 lines. The iditor supplies white space, if appropriate••t the juncture of the joined lines,
and leaves the cursor at this white space. You can kill the white space with x if you don't want
it.

'.6. Futures for edUiDa procrsms
The editor has a number of commands for editing programs. The thing that most distinJUishes editing of prosrams from editing of text is the desirability of maintaining an indented
structure to the: body of the program. The editor bas a autoind~nt fadlity for helping you generate correctly indented procrams.
To enable this facility you can give the command :se aiCR. Now try opening a new line
with 0 and t}'l)e some char~.ers on the line after a few tabs. If you now start another line.
notice that the ediLOr supplies white: sp3Ce at the beginning of the line to line it up with the pre·
vious line. You cannot bac~ace over this indentation, but you can use
key to baclctab
over the supplied indentation.

-n

Each time you type AD you back up one position, normally to an 8 column boundary.
settabl~ the editor has an option called shiftwldth which you can set to change
this value. Try givine the command :se SW-4CR and then experimenting with autoindent

This amount is

aaam.

For shifting lines in the program left and right. there are operators < and >. These shift
the lines you specify right or left by one shiftwldth. Try < < and > > which shift one line left
or richt. and < L and > L shifting the rest of the display left and right.

If you have a complicated expression and wish to see how the parentheses match. put the
cursor It I left or right parenthesis and bit~. This will show you the matching parenthesis.
This works also for braces { and I. and brackets ( and ].
If you are editing C programs. you can use the II and II keys to advance or retreat to a
line starting with a {. Le. I function deciaration at a time. When IJ is used with an operator it
SlOps after • line which starts with I; this is sometimes useful with 111.

• nns realure is DO' available on some v2 editors.

In v2 editors where i' is availabfe. Lbe breai: can oftiy ex·
car to llle ri&Dt 0( tb& S1*i6ed boundary insaead of to lbe left.

- 16 6.7. FilteriDC portions of the buffer
You can run system commands over ponioO! of the buffer using the operator!. You can
use this to sort lines in the buffer, or to reformat portions of the buffer with a pretty-printer.
Try typing in a list of random words, one per line and ending them with a blank line. Back up
to the beginning of the list., and then give the command !\sortCR. This says to sort the next
paragraph of material, and the blank line ends a paragraph.

LISn

6.8. Commands (or editinl
If you are editing a LISP program you should set the option lisp by doing :se liSpCR. This
changes the ( and ) commands to move backward and forward over s-expressions. The ( and J
commands are like ( and ) but don't stop at aloms. These can be used to skip to the next list.
er through a comment quickly.
The autoindent option works di1ferently for USP. supplying indent to align at the first argument to the last open list. If there is no such argument then the indent is two spaces more
than the last level.
There is another option which is useful for typing in usP, the snowmatc1t option. Try setting it with :se sma and then try typing a '(' some words and then.:. ')'. Notice Illat the cursor shows the position of the '(9 which matches the ')' briefly. This happens only if the matching •(' is on the screen, and the cursor stays there for at most one second.
The editor also. has an operator to realign existing lines as though they had been typed in
with lisp and autoindent seL This is the - operator. Try the command -'II at the beginning of
a function. This will realign all the lines of the function dedaration.
When you are editing USP .. the ([ and 11 advance and retreat to lines beginning with a (.
and are useful for dealing with entire function definitions.
6.9. Macros;
Vi has a parameteness macro facility. which lets you set it up so that when you hit a single
keystroke, the editor will act as though you had rut some longer sequence of keys. You can set
this up if you find yourself typing the same sequence of commands repeatedly.
Briefly, there are two flavors of macros:
a)
Ones where you put the macro body in a buffer register, say.x. You can then type @x to
invoke the macro. The @ may be roHowed by another @ to repeat the last macro.
b)
You can use the mtZp command from iii (typically in your EXlJv!n with a command of the
form:
:map Ihs ,hS;R
mapping Ihs into drs. There are restrictions: Ihs should be one keystroke (either 1 charac·
ter or one function key) since it must be entered within one second (unless nOllmeout is
set., in which case you can type it as slowly as you wish, and v; will wait for you to finish it
before it echoes anything). The /hs can be no longer than 10 cnaracters. the ,hs no longer
than 100. To get a space, tab or newline into /Ju or ,Iu you should escape them with a ·V.
(It may be necessary to double the -V if the map command is given inside VI, rather than
in ex.) Spaces and tabs inside the ,Iu need not be escaped.
Thus to make the q key write and exit the editor, you can give the com.nund

;map q ;wq-V-va ell
which means tllat whenever you type q, it win be as though you had typed the four characte~
:-wqa. A -V's is needed becluse without it the at would end the : command, rather than

\

t The USP features are 001 available Otl some v2 editors due to memory CDnSZniDlS.

*The macro feature is availaOia 0Diy ill versioa 3 editaa.

• 17 •
becoming part of the map definition. There are two -V's because from within vi. two ·Y·s must
be typed to get one. The first ~ is part of the rhs. the second terminates the : command.
Macros can be deleted with
unmap lhs

If the Ihs of a macro is "#0" through" #J", this maps the particular function key instead
of the 2 character "#" sequence. So that terminals without function keys can access such
definitions. the form "#X" will mean function key x on all terminals (and need Dot be typed
within one second.) The character "#" can be changed by using a macro in the usual way:
:map -V-V-I #
to use tab. for example.  You can always maximize
the information on the saeen by &iving the "1t command.
If you wish. you can have the editor place line numbers before each line on the display.
Give the- command :se naa to enable this. and the command :se Bonaa to tum it off. You
can have tabs represented as , and the ends of lines indicated with 'S' by &ivinl the command
:se llstCll~ :se BoUsta turns this 06.
FmaUy. lines consisting of only the character .- are disiJlayed when the last line in the file
is in the middle of the saee1l. These represent physical lines which are past the 10gjc:aJ end of
die.

1.1. Counts
Most vi commands will use a preceding count to a1rect their behavior in some way. The
following table gives the common ways in which the counts are used:
new window size
SC'OU ..amount
line/column number
repeat effect

:/!(l1I
-n'\]
zGI
most of the rest

The editor maintains a notion of the CUtTent default window size. On terminals which run
at speeds greater than 1200 baud the editor uses the full terminal saeen. On terminals which
are slower than 1200 baud (most dialup lines are in this group) the editor uses 8 lines as the
default window size. At 1200 baud the default is 16 lines.
Th.is size is the size used when the editor dears and refills the saeen after a search or
other motion moves far from the edge of the current window. The commands which take a
new window size as count aU often cause the saeen to be redrawn. If you anticpate this. but
c10 not need as lalle a window as you are currently using. you may wish to change the saeen
size by specifying the Dew size before these commands. In any case. the number of lines used
on the saeen will expand if you move 06 the top with a - or similar command or off the bottom with a command such as ltETUJlN or -D. The window will revert to the last specified size
the next time it is cleared and refilled. t
The scroll commands -n and -U likewise remember the amount of saoll last specified.
using half the basic: window size initially. The simple insert commands use a count to specify a
repetition of the inserted text. Thus 10. + - - - - ESC will insert a &rid-like string of text. A
few commands also use a preceding count as a line or column Dumber.
Except for a few commands which ignore any counts (such as -'R.), the rest of the ~itor
commands use a count to indicate a simple repetition of their etfect. Thus Sw advances five
words on the current line. wttile SREnJJlN advances five lines. A very useful instance of a
count as a repetition is a count liven to the • command. which repeats the last changing command. If you do dw and then 3•• you will delete first one and then three words. You can then
deiete two more words with 2..

.

1.3. More file manipaiatfoD commaads
The following table lists the file manipulation commands which you c:an use when you are
in vi. All of these commands are followed by a at or ESC. The most basic: commands are :w
and :e. A normal editing session on a single file will end with a ZZ command. If you are editing for a long period of time you can pve :w commands oa:asionalJy after major amounts of
editing. and then finish with a ZZ. When you edit more than one file. you can finish with one

,

t

•

SUI DOl by •

"1. _hidl just reGraWi

u. s:r.a .. it is.

• 19 -

:wq
:%

:a fUlm~
:a!

:. +

na~

:e +n
:. #
:w!

nam~

:.x.Y"

:r

nam~

fUlm~

:r !and
:n
:D!

:nargs
:tatag

write back changes
write and quit
write (if necessary) and quit (same as ZZ).
edit file nam~
reedit. discarding changes
edit. starting at end
edit, starting at line n
edi t al temate file
write file nam~
overwrite file nam~
write lines x through >' to fUlm~
read file nam~ into buifer
read output of cmd into buffer
edit next file in argument list
edit next file, discarding changes to current
specify new argument list
edit
containinl tal tag. at tag

me

with a :w and start editinl a new file by living a :e command, or set aUlowrll~ and use :n
.
If you make changes to the editor's copy of a file, but do not wish to write them back.
then you must give an ! after the command you would otherwise use~ this forces the editor to
discard any changes you have made. Use this carefully.
The :e command can be given a + argument to start at the end of the file. or a +" argument to start at line n. In actuality, n may be any editor command not containing a space. use·
fully a scan like +I pal or +? pal. In forming new names to the e command. you can use the
character % which is replaced by the current file name, or the character # which is replaced by
the alternate file name. The alternate file name is generally the last name you typed other than
the current file. Thus if you try to do a :e and get a diagnostic that you baven't written the tile.
you can give a :w command and then a :e # command to redo the previous :e.
You can write part of the buifer to a file by finding out the lines that bound the range to
be written using -G, and giving these numbers after the : and before the w, separated by ,'s.
You can also mark these lines with III and then use an address of the form .x.'y on the w com·
mand here.
You can read another file into the b\l1J'er after the current line by using the :r command.
You can similarly read in the output from a command, just use !cmd instead of a file name.
If you wish to edit a set of files in succ:ssion. you can give all the names on the command
line. and then edit each one in turn using the command :n. It is also possible to respecify the
list of files to be edited by living the :D command a list of file names. or a pattern to be
expanded as you would have given it on the initial vi command.

If you are editing large prov.uns. you will find the :t. command very useful. It utilizes a
data base of function names and their locations. which can be created by programs such as
czars. to quickly find a function whose name you give. If the :1. command will require the edi·
tor to switch files. then you must :w or abandon any changes before switching. You can repeat
the :t. command without any aI'luments to look for the same tag again. (The tag feature is not
available in some v2 editors.)

1.4. More about seardlinc for strinp
When you are searching for strings in the file with / and ? the editor normally places you
It the next or previous OCCUITence of the string. If you are using an operator such as d. c: or y,
then you may well wish to aired lines up to the line before the line containing the pattern.

- 20 You can pve a se3tcll of the form I patl- n to refer to the ,,'th line before the next line containing par.. or you can use + instead of - to refer to the lines after the one containing par. If
you don't pve a line offset. then the editor will atrect characters up to the match place. rather
than whole lines~ thus use .. +0" to airect to the line which matches.
You can have the editor illlore the case of words in the searches it does by giving the
command :se iCCJl. The command :se DoiCCR tums this ofr.
Strines given to searches may actually be regular expressions. If you do not want or need
this facility, you should
set nomasic

in your EXINlT. In this case. only the characters f and S are special in patterns. The character
.\ is also then special (as it is most everywhere in the system), and may be used to get at the an
extended pattern matching facility. It is also necessary to use a \ before a I in a forward scm
or a 1 in a backward scan.. in any case. The foUowing table gives the extended forms when
mqie is set.
T
S

.

\<
\>
[szri

fTmi
[x-yJ
•

at beginning of pattern. matches beginning of line
at end of pattern.. matches end of line

matches
matches
matches
matches
matches
matches
matches

any character
the beginning of a word
the end of a word
any single character in SIT
any sin&le character not in stT
any character between x and y
any number of the precedin& pattern

If you use Dom_lie mode. then the • I and • primitives are liven with a preeding \.

1.5. More about input mode
There are a number of characters which you can use to make corrections during input
mode. These are summarized in the foUowing table.

'it
-W

erase
kill
\
ESC
DEL

a
'"D
O-D

T""D
-V

deletes the last input character
deletes the last input word. defined as by b
your erase character. same as -H
your kill character, deletes the input on this line
escapes a following ~ and your erase and !till
ends an insertion
interrupts an insertion. terminating it abnormally
starts a new line
backtabs over autoitrdent
kills all the autointknt
same as O-D, but restores indent next line
quotes the next non-printing character into the file

The most usual way of making corrections to input is by typing ~ to correct a single
char3cter. or by typing one or more -W's to back over incorrect words. If you use # as your
erase character in the normal system. it will work like -H.
Your system kill character. normally @. -X or ·U. will erase all the input y"u have liven
on the :urrent line. In general. you can neither erase input back around a line boundary nor
can you e.'"a5e characters which you did not insert with this insertion command. To make
corrections on the previous line after a new line has been started you can hit ESC to end the
insertion., move over and mUc the correction. and then return to where you were to continue.

- 21 •
The command A wbich appends at tbe end of the CUm:nI line is often useful for continuing.
If you wish to type in your erase or Idll c.~arac-.er (say # or @) then you must precede it
with a \. just as you would do at the normal system command level. A more general way of
typing nan-printing characters into tbe file is to precede tbem with a -V. The -V echoes as a i
character on whjch the cursor restS. This indicates that tbe editor expectS you to type a control
charac:te1'. In fact you may type any character and it will be inserted into the file at that point.·
If you are using aUloindent you can bacJctab over the indent which it supplies by typing a
"D. Thjs bada up to a sJriftwidth boundary. This onJy worb immediately after the supplied
flUtointilnL

When you are using autoindent you may wish to place a label at the left margin of a line.
The way to do tbis easily is to type r and tben "D. The editor will move the cursor to the left
margin for one line, and restore the previous indent on the next. You can also type. a 0 followed immediately by a "D if you wish to Icill all the indent and not have it come back on the
next line.

1.6. Upper case only terminals
If your terminal has Guly upper case, you can stiU use vi by using the normal system convention for typinl on such I terminal. Characters wbich you normally type are converted to
lower case, and you can type upper case letters by preceding them with a \. The characters ( - )
but you can escape them as \ ( \
\! \'. These cbaracten are represented o.n the display in the same way tbey are typed.: ;

I . are nat available on such terminals,

r \)

1.7. VI aDd ex
Vi is adually one mode of editing within the editor a. When you are runnin, vi you can
escape to the line oriented editor of c:c by giving the command Q. All of the : commands
which were introduced above are available in a. Likewise. most ex commands can be invoked
from vi using:. Just give them without the : and fallow them with a CR..
In rare instances. an internal error may occur in v;. In this case you will get a diagnostic
and be left in the command mode of a. You can then save your work and quit if you wish by
Jivina a command x after the : which IX prompts you with, or you can reenter vi by givin, a a
v; command.

There are a number of things wbich you can do more easily in a than in vi. Systematic
chanaes in line oriented material are particularly easy. You can read the advanced editing doC".Jments for the editor !d to find out I lot more about this style of editinJ. El:perienced use:-s
often mix their use of a command mode and vi command mode to speOld tbe work: they are
doina.

1.8. Open mode: Ti on bardcopy terminals aDd "&Jus tty's'· :
If you are on a hardcopy terminal or a terminal wbich does not have a cursor whidl can
move off the bottom line. you can still use the command set of v;, but in a different mode.
When you give a v; command, the editor will teU you that it is usina open mode. This name
comes from the open command in ex. which is used to act into the same mode.
The onJy dilference between visutZl mode and open mode is tbe way in whicn tbe text is
• This is lICK quite true. The implementation o( tbe editor does not aBa- tile NUU. (• • ) dlancter to a~r
ia dJes. Also tbe LF (Jinefe.t Of - J) cnancter is used '" the editor to ~te lines ill tile tile. so II cannot
~ ill tbe middle of a line. You can insen any alher chanete:'. ttowner. if you wail ror the editor to
ec:Do Ibe t before you tn- tbe dIancter. la (ad. the edilor wiU treal a (ollo";nl letter • a requesl (or the
C:OUe5POndint contrOl c:harac:ter. This is the only . .y to tVl'e OS Of .Q, since tbe sys&em nonnally uses tbem
to ~d and resume ou,"", and never lives tbem to the editor to pr'OCIeIS.
The , dwac:ter you live will nor edIo IUltil you tVl'e IaOther ley.
Noc availab6e ill aB y2 editors due 10 memory CCIIIIIniDu..

*
*

·22·
displayed.

In o~n mode tbe editor uses a single line window into the file. and movinl backward and
forward in the file causes new lines to be displayed. always- below the current line. Two commands of vi work di1ferentJy in op'n: z and All. The z command does not take parameters, but
rather draws a window of context around the current line and tben returns you to the current
line.
If' you are on a hardcopy tenninal. the ~ command will retype the current line. On such
terminals, the editor normaUy uses two lines to represent tbe current line. The first line is a
copy of the line as you started to edit i~ and you work on the line below this line. When you
delete characters. the editor types a number of \ 's to show you tbe characters which are deleted.
The editor also reprints the c:wTent line soon after such chanles so thal you can see what the
line looks like apin.
It is sometimes useful to use this mode on very slow terminals which can support vi in the
full screen mode. You can do this by enterinl ex and usinl an op'n command.
AcknowledlemeDts
Bruce Englar encourqed the early development of this display editor. Peter Kessler
helped brinl sanity to version 29 s command layouL Bill loy wrote versions 1 and 2.0 throulh
2. 7. and created the framework that users see in the present editor. Mark Horton added macros
and other features and made the editor work on a larae number of terminals and Unix systems.

.

t

- 23 Appendix: chanctu fanctioDS
This appendix gives the uses the editor makes of each character. The characters are
presented in their order in the ASCII character set: Control characters come first., then most
special c~aract~ then the digits. upper and then lower case characters.
For each character we teU I meaning it has as a command and any meaning it has dunng
an insert. If it has only meaning as a command. then only this is discussed. Section numbers
in parentheses indicate where the character is discussed; a 'f" after the section number means
that the charader is mentioned in a footnote.
...
Not a command character. If typed as the first character of an insertion it is
\.
replaced with the last text ~ and the insert terminates. Only 128 char\
lCterS are saved from the lat insert; if more characters were inserted the
mecbanism is not available. A·@ cannot be part of the file due to the editor
implementation (7.50.

·A

Un~

,.

Backward window. A count specifies repetition. Two lines of continuity are
2pt if possible (2.1, 6.1. 7.2).

"c

Unus.L
M • c:ommand. scrolls down a ba1f-window of text. A count gives the number
of (logical) lines to scron. and is remembered for future aD and "'U commands
<2.1. 7.2). During an insert. backtabs over QUloindenl white spac:: at the beginaiDg of I line (6.6, 7.5); this white space cannot be backspaced over.
~ses one more line below the current screen in the file. leaving the cursor
where it is if possible. (Version 3 only.)

Forward window. A c:ount specifies repetition. Two lines of continuity are
kept if possible (2.1, 6.1. 7.2>Equivalent to :fa. printing the current file. whether it aa been modified. the
current line number and the number of lines in the file. and the percentage of
the way throush the file that you are.
Same as left arrow. (See h). During an insert. eliminates the last input charKter. backinl over it but not erasing it; it remains so you can see wbat you
typed if you wish to type something only s1iahtly different (3.1. 7.5),
Not I c:ommand character. When inserted it prints as some number of spaces.
When the cursor is at • tab character it rests It the last of the spaces which
represent the tab. The spacing of tabstops is controUed by the tlZbS10P option
(4.1. 6.6>Same as dOWD arrow (see j).

Unusec1.. .
The ASCII formfeed character. this causes the saeeD to be deared and redrawn.
This is useful after I transmission error. if characters typed by a proaram other
than the editor scramble the screen. or after output is stopped by an interrupt
(5.4. 7.2f).
A c:arriace return advances to the next line. It the first non-white position in
the line. Given a count., it advances that many lines (2.3). Durinl an insert. a
Cl causes the insert to continue onto another line (3.1).
Same as doWD arrow (see J).
Un~

·24·

.,.

Same as up arrow (see k).
Not a command character. In input mode, '"Q quotes the next character. the
same as ·V, except that some teletype drivers will eat the .Q so that the editor
never sees it.
Redraws the current screen, e1iminatin& logical lines not corre5l)Onding to physical lines (lines with only a single @ character on them). On hardcopy terminals in open mode. retypes the current line (5.4, 7.2. 7.S).
Unused. Some teletype drivers use .oS to suspend output until ·Qis
Not a command character. During an insert, with autoindent set and at the
bqinnin& of the line, inserts shiftwidth white space.

Scrolls the screen up, inverting ·D which scrolls down. Counts work as they
do for '"D, and the previous scroll amount is common to both. On a dumb terminal, '"U will often nec:ssitate clearin& and recirawin& the saeen further back
in the file (2.1, 7.2).
Not a command character. In input mode, quotes the next character so that it
is possible to insert non-printinl and special characters into the file (4.2, 7.S)'

.

NOli command character. Durin& an insert, backs up as b would in command
mode~ the deleted characters remain on the display (see '"H) (7.5).

Unused.
Exposes one' more line above the current screen, leaving the cursor where it is
if possible. (No mnemonic value for this key~ however, it is next to -1) which
scrolls up a bunch.) (Version 3 only.}

If supported by the Unix system. stops the editor, exiting to the top level shell.
Same as :stopClt. Otherwise, unused.
Cancels a partially formed command, such as a z when no following character
has yet been given~ terminates inputs on the last line (read by commands such
IS : I and ?)~ ends insertions of new text into the buffer. If an ESC is given
when quiescent in command state, the editor rings the bell or flashes the
sc:r=n.. You can thus hit ESC if you don't know what is happenin& till the editor rinas the bell. If you don '( know if you are in insert mode you can type
ESCa. and then material to be input~ the material will be inserted corr~tly
whether or not you were in insert mode when you started (1.5, 3.1, 7.5),

"'.

Unused.

Searches for the word which is alter the cursor as a tag. Equivalent to typing
:tao this word, and then a CR.. Mnemonically. this command is "go right to"
(7.3).

Equivalent to :e #CR. returning to the previous position in the last edited file.
I file which you specified if you got I 'No write since last change
diqnostic' and do not want to have to type the file name apin (7.3), (You
have to do a :w before ·T will work in this case. If you do not wish to write
the file you should do :e! #CR instead.)

or editing

SPACE

t

Unused. Reserved as the command character for the Tektronix 4025 and 402'7
termina1.
Same as riCht arrow (see 1).
An operator, which processes lines from the buffer with reformatting commands. Follow! with the object to be processed. and then the command name
terminated by Cll. Doubling! and precedinl it by a count causes count lines to
be filtered; otherwise the count is passed on to the object after the !. Thus
l!t/ma reformats the next two paragraphs by running them through the proaram /mL If you are workina on USP, the command !~gr;ntt:R,· given at the

-tIolb /mI UX1 l"ffIi are Bertdey 'PfOIfUDS aad may IIOl be present a' aJJ iftstaJIatioas.

- 2S bqinning of a function. will run the text of the function through the USP
pinder (6.1, 1.3). To read a file or the output of a command into the buffer
use :r (7.3), To simply execute a command use :! (7.3).

•

Precedes a named bu1fer specification. There are named bu1fers 1-9 us~ for
savina deieted text a!!d named buifers &-1 into which you can plaa: text (4.3.

6.3)
#

The macro character which. when followed by a number, will substitute for a
function key on terminals without function keys (6.9), In input mode, if this
is your erase character, it will delete the last character you typed in input
mode. and must be preceded with a \ to insert it. since it normally backs over
the last input ch~r you pve.

S

Moves to the end of the current line. If you :se UsteR, then the end of each
line will be shown by printing a S after the end of the display~ text in the
line. Given a count, advances to the count'th following end of line~ thus 2S
advances to the end of the following line.
Moves to the parenthesis or brace { } which balances the parenthesis or brae:
11 the current cursor position.

a"

A synonym for :.ta. by analOlY with the
command.
When followed by a • returns to the previous context at the beginning of a
line. The previous context is set whenever the current line is moved in a
non-reiative way. When followed by a letter 1-1, returns to the line which
was marked with this letter with a ED command. at the first non-white charac:er
in the line. (2.2. 5.3). When used with an operator such as d, the operation
takes place over complete lin~ if you use '. the operation taXes place from the
exact marked place to the current cursor position within the line.
(

Retreats to the bqinnin, of a sentence. or to the beginning of a USP sexpression if the lisp option is set. A sentence ends at a . ! or ? which is followed by either the end of a line or by two spaces. Any number of closing) J
• and • characters may appe3J' after the • ! or ? and before the spaces or end of
line. Sentences wo begin at paragraph and section boundaries (see ( and II
below). A count advances that many sentences (4.2. 6.8).

)

Advances to the beginning of a sentence. A count repeats the effect. See (
above for the definition of a sentence (4.2. 6.8).

•

Unused.
Same as a when used as a command.

+

r

Reverse of the last f
t or T command, looking the other way in the current
line. Especially useful after hitting too many ; cl1aracters. A count repeaLS the

search.
Retreats to the previous line at the first non-white character. This is the
inverse of + and RETURN. If the line moved to is not on the screen. the
screen is scrolled. or cleared and redrawn if this is not possible. If a large
unount of scrolling would be required the screen is aJso cieared and redrawn.
with the current line at the center (2.3>Repeats the last command which changed the buifer. Especially useful when
deleting words or lin~ you can delete some wordsllines and then !lit . to
delete more and :nore wordsllines. Given a count, it passes it on to the command being repeated. Thus after a 2dw, 3. deletes three words (3 ..3, 6..3, 7.:.
1.4).

·26 •

1

Reads a string from the last line on the screen, and scans forward for the next
OCCUITence of this string. The normal input editing sequences may be used
during the input on the bottom line~ an returns to command state without ever
searching. The search begins when you hit CIt to terminate the pattern~ the
cursor moves to the beginning of the last line to indicate that the search is in
progress; the search may then be terminated with a DEL or RUB, or by backspacing when at the beginning of the bottom line. returning the cursor to its
initial position. Searches normally wrap end-around to find a string anywhere
in the buffer.
When used with an operator the enclosed region is normally affeaed. By mentioning an offset from the line matched by the pattern you can· force whole
lines to be atrected.. To do this give a pattern with a dosing a ciosing / and
then an offset + n or - n.
.
To indude the character 1 in the search ~~~ you must escape it with a
preceding \. A T at the beginning of the pattern forces the mau:h to occur at
the beginning of a line onlr, this speeds the search. A S at the end of the pattern forces the match to occur at the end of a line only. More extended pattern matching is availabl~ see section 7.4; unless you set nomalic in your
.e:ae file you wtll have to preceed the characters . ( • and - in the search pattern with a \ to let them to work as you wou1d naively expect (1..5. 2.2. 6.1.

7.2, 7.4>.

o

Moves to tJie first cllarader on the current line.
numbers., after an initial 1-9.

1-9

Used to form numeric arguments to commands (2.3, 7.2>A prefix to a set of commands for tile and option manipu1ation and escapes to

,

the system. Input is given on the bottom line and terminated with an CR, and
the command then executed. You can return to where you were by hitting
DEl. or RUB if you hit : acddentally (see primarily 6.2 and 7.3).
RepeatS the tast single character find which used
the basic scm (4.1).

<

>

A

B
C

D
I

Also used. in forming

rF

t or T. A count iterates

An operator which shifts lines left one sltiftwidth., normally 8 spaces. Like all
operators., atrects lines when repeated. as in < <. Counts are passed through
to the basic objea. thus J< < shifts three lines (6.6, 7.2>.

Reindents line for LISP, as though they were typed in with lisp and

aUloin""~nl

Jet (6.8).

An operator which shifls lines right one sltiftwidth. normally 8 spaces. Affects
lines when repeated as in > >. Counts repeat the basic object (6.6. 7.1),

Scans backwards, the opposite of I. See the 1 description above for details on
Jeannin& (2.2., 6.1, 7.4).
A macro charade%' (6.9). If this is your kill character. you must escape it with
• \ to type it in during input mode. as it normally backs over the input you
have given on the current line (3.1.3.4. 7.S).
Appends at the end of line. a synonym for Sa (7.2>.
Baas up a word, where words are composed of non-blank sequences, pl30ng
the cur.sor at the beginning of the 'Nord. A count repeats the effect (1.4).
Chan~

the rest of the text on the current line; a synonym for c:$.
DeJetes the rest of the text on the current tine; a synonym for dS.

- 21 [

F
G

H

I
J

Moves forward to the enci of a word.. definea as blanks and non-blanks, like B
and W. A count repeats the effect.
Finds I smile following character. backwards in the current line. A count
repeats this searcll that many times (4.1).
Goes to the line number liven as preceding argument. or t!le end of the file if
no preceding count is given. The saeen is redrawn with the new current line
in the center if necessary (7.2).
Home arrow. Homes the cu~or to the top line on the saeen. If a coun t is
giv~ then the cursor is moved to the count'th line on the screen. In any case
the cursor is moved to the first non-white character on the line. If used as tile
tarlet of an operator. full lines are afi'ectea (2..3. 3.2L
Inserts at the beginning of a line; a synonym for Tl.
Joins together lin~ supplying appropriate white space: one spac: between
words. two spaces after a '0 and no spaces at all if the first character of the
joined on line is ). A count causes that many lines to be joined rather than the
default two (6.S. 7.ln.

X

Unused..

L

Moves the cursor to the first non-white character of the Jast line on the screen.
With a count. to the first non-white of the count'th line from the bottom.
Operators afi'ec1 whole lines when used with L (2.3>Moves the cursor to the middle line on the screen. at the first non-white position on the line (2.3).
Scans for the next match of the last pattern liven to / or '!, but in the reverse
direetion; this is the reverse of D.
Opens a new line above the current line and inputs text there up to an ESC. A
count can be used on dumb terminals to specify a number of lines to be
opened; this is generaUy obsolete, as the s/owopen option works better (3.1).
Puts the last deleted text back before/above the cursor. The text goes back as
whole lines above the cursor if it was deietea as whole lines. Otherwise the
text is insertea between the characters before and at the cursor. May be preceded by a named butrer specification ·x to retrieve the contents of the buffer:
bu1fers 1-9 contain deJetea material. buifers a-z are available for general use

M

N

o
p

(6..3).

Q
R

s
T

u
V

Quits from .,; to a command mode. In this mode, whole lines form commands. ending with a RETURN. You can live all the : commands~ the editor
supplies the : as a prompt (7.7).
Replaces characters on the screen with characters you type (overlay fashion).
Terminates with an ESC.
Changes whole lines. I synonym for cc. A count substitutes for that many
lines. The lines are saved in the Dumeric bu.1fers. and erased on the screen
before the substitution bqins.
Takes a single foUowing character. loates the character before the cursor in
the current line. and places the cursor just after that character. A count
repeats the effect. Most useful with operato~ such as d (4.1).
Restores the current line to its state before you started changing it (3.5).
Unused.

- 28 -

w

Moves forward to the beginning of a word in the current line. where words are
defined as sequences of blank/non-blank characters. A count repeats the eff'ett

(2.4).

x
y

Deletes the character before the cursor. A count repeats the effect, but only
characte1'3 on the current line are deleted.
Yanks a copy of the current line into the unnamed buffer. to be put back by a
later p or P; a very useful synonym for rJ. A count yanks that many lines.
May be preceded by a butrer name to put lines in that buffer (7.4).

zz

Exits the editor. (Same as :%0.) If any changes have been made, the buffer is

n

written out to the CUITent file. Then the editor quits.
Backs up to the previous section boundary. A section begins at each macro in
the S«tiOIU option~ normally I • .NH~ or •.sH· and also at lines which which
Slart with a formfeed". Lines bqinning with ( also stop n~ this makes it
useful for looking bacJcwards., I function It I time, in C pf'OlJ'3lTlS. If the
option lisp is set, stops at each ( at the bqinning of a line., and is thus useful
for moving backwards at the top level USP objects. (4.2, 6.1, 6.6, 7.2>.

\

Unused.

])

Forward to a section boundary, see II for a definition (4.2. 6.1, 6.6. 7.2"
Moves to the first non-white position on the CUITent line (4.4).

T

Unused.

-...

When followed by a • returns to the previous context. The previous context is
set whenever the CUITent line is moved in a non-relative way. When followed
by I letter .-~ returns to the position which was marked with this letter with
I ID command. When used with an operator such as cl, the operation takes
place from the exact marked place to the CUITent position within the line~ if
you use " the operation takes place over complete lines (2.2, 5.3).

•

Appends arbitrary text after the current cursor position~ the insert can continue
ODto multiple lines by using R.En1RN within the insert. A count causes the
inserted text to be replicat~ but only if the inserted text is allan one line.
The in.sertion terminates with an ESC (3.1. 7.2"

It

Backs up to the beginning of a word in the current line. A word is a sequence
of alphanumerics. or a sequence of special characters. A count repeats the
eifed (2.4).

c

AD operator which changes the following object, replacing it with the following
input text up to an ESC. If more than part of a sinlie line is affected. the text
which is changed away is saved in the numeric named butfers. If only part of
the current line is a1fected, then the last character to be changed away is
marked with a S. A count causes that many objects to be a1fec1ed. thus both
Jc) andc5) cb.ange the followinl three sentences (7.4).

cl

AD operator which deletes the (ollowing object. If more than part of a line is
arect~ the text is saved in the numeric buffers. A count causes that many
objects to be a1fected~ thus Jdw is the same as clJw (3.3, 3.4, 4.1, 7.4).

e

Advances to the end of the next word., defined as for It and w. A count
the effect (2.4, 3.1).

repeatS

f

Fmds the first instance of the next character following the cursor on the
c:un-ent line. A count repeats the find (4.1).

I

Unused.
Arrow keys h .. J.

k.

~ aDd H.

·29 •
h

i
j

k

Left arrow. Moves the cursor one character to the left. Like the other arrow
keys. either h. the left arrow key, or one of the synonyms rH) has the same
effect. On v2 editors. arrow keys on certain kinds of terminals (those WilIC;'
send escape sequences, such as vtS2. cl00. or IIp) cannot be used. A count
repeats the en~t (3.1. 7.S).
Inserts text before the cursor. otherwise like a (i ..2L
Down arrow. Moves the cursor one line down in the same column. If the
position does Dot exist, vi comes as close as possible to the same column.
Synonyms include -J (linefeed) and -N.

Up arrow. Moves the cursor one line up. •p is a synonym.
IUpt arrow.
synonym.

Moves the cursor one character to the right. SPACE is a

m

Marks the current position of the cursor in the mark re3ister which is specified
by the Dext char:u::ter a-I. Return to this position or use with an operator
using' or • (5.3).

•o

Repeats the last / or ? scanning commands (2•.2) .
Opens Dew lines below the current line; otherwise like 0 (3.1).
Puts text after/below the cursor. otherwise like P (6.3).

p
q

r

s

Unused..
Replaces the single character at the cursor with a single character you type.
The Dew character may be a RETURN~ this is the easiest way to Sl'iit lines. A
count repl:u::es each of the following count characters with the single cnar:u::te:
Jiven; see R above whicl1 is the more usually useful iteration of r (3.1).
Changes the single character under the cursor to the text which follows up to
an ESC~ given a count. that many characters from the current line are changed.
The last char:u::ter to be changed is marked with $ as in c (3.2L
.~dvances the cursor upto the character before the next character typed. ~ost
useful with operators such as d and c to delete the characters up to a following
character. You can use . to delete more if this doesn't delete enough the first
time (4.1).
Undoes the last change made to the current buffer. If repealed. will alternate
between these two states, thus is its own i:werse. When used after an inser!
which inserted text OD more than ODe line. ~e lines are saved in the numeric
named bufi'ers (3.S).

T

w

z

Unused.
Advances to the bqinning of the next word. as defined by b (2.4L
De!etes the single character under the cursor. With a count deletes deletes
that many characters forward frem the cursor position. but only on the C'.lrrent
line (6.S).
An operator. yanks the following object into the unnamed temporary buffer. If
preceded by a named buffer Sl'ecifiC3tion. -x, the text is placed in that buffer
also. Text can be recovered by a later p or P (7.4).
Redraws the screen with the current line placed as specified by the following
character. RETUR!'f Sl'ecifies the top of the screen •. the center of the scre=~.
and - at the bottom of the screen. A count may be given after the I ll1d
before the following character to spec".fy the new saeen size for the redraw A
count before the z gives the number of the line to place in the center of the
screen instead of the default current line. (5.4)

·30·
Retreats to the beginning of the be3inning of tbe preceding paragraph. A para·
&1"llph begins at each macro in the paragraphs option, normally •.IP'. •.LP· .
'.Pp·. '.QP· and '.bp'. A paragraph also begins after a completely empty line.
and at each section boundary (see II above) (4.2, 6.8, 7.6L
Places the cursor on the character in the column specified by the count (7.1.

7.2).
Advances to the bqinning of the next paragraph. See { for the definition of
parqrapb (4.2, 6.8, 7.6).

Unused.
Interrupts the editor, returning it to command accepting state 0.5. 7.5)

Ex Quid, Itcfcrcncc
1~lIlerlll~/le;n In~ l'I
edil 1It/ll/.·. slarl "I cnd
... al lillc 1/
slllri III
lisl silved files
recllver lile lit/IIII'
edil firsl; resl viu :n
read only mllde
exil. saving (hangcs
uil, dis(ilrdinl (hanges

% e I "11/111'
% t:.
111/11/('
% n ~. lal:
% t'I -r

+"

'''1:

% el - r "01111'
% e I"""/(, ...
% el - R ""1111'
: I

: ql

It:. slales
Nurmal anti inilial slille. IIIIHlI
\lwmpletl fllr by:. Your kill dlluarler nlll(els Ilarlial wlllmand.
I;nlered by • I and c. Arbilrury
led Ihen Icrminules wilh line havillg ollly. (huracler on il or .bnormally wilh inleffulll.
bllered by open Of ,I, lerlllinilies
wilh ., Of '\.

Insell

()llCnl visuill

It:. conllnands
.11
I
Ir

lUllS

change
W\lY
deletc
edil
lile
J!luhal
insert
jllill
lisl
milll
fIIark
muve

c

co

..
e

nexl
lIumber
"lIen
I"eserve
I" inl
IHII
'Illit
reiltl
leCllve.
rewind
set
shell
source

II

IIU
0

lI· e
p
pu

III.

51011

q
.e
.ec
rew
lie
sll
so
51

III

subslilule

5

I

I

J
I

ullllbbrev
undo
unlllap
versitln
visllal
write
xit
yallk

111111

Ir",dfllV

I

1'1('0f/1'

I

M,II

u
unm
.e

.1
w
I

lille "
cUllenl

S

liI~t

+

IlC

+"
%

KI
!,IcvillllS
" 'OIWilll1
I.S

<

fI' ""

,

n"/It

>
'U

1/1'-"
f/'j/lbu

uwl/

Cit

11,,/1
'! 1''''

lIexl with lour
!,revious wilh 1101
"hdllle ..

'. f'

( Ihwllllh .'
lIIalkell wilh
p/eviolls COli It: x I

,-"

.

YI

It:. com lila lid addresses

"

1/1

in Versilln 1

tlwl
dw2
gl40
IIt42
hi SOO

hll}
110(1
mime
owl

JOOs

14S

JJ
11

ad4
a(IS
admJ

4014

11061

hlSlO

vtS2

% .Iew

.:XINI1'
se' .Ir
sci 1I0X
sci x- 1001
sci
sci .l?

IIdmJI
allmJa
clOO
dml520
dm1S00
dmJU1S

.i
aw

Iglloncase
lisp
lis.
... lllc
nllUlllu
p.uI.:raphs
rcdraw

Ie

nil
Ilara

5c.oll
sections
shlflwldlh
ShOWllliidl
slowopclI
window
wrapscall
wraplII"I"1

sect
sw
sm
slow
ws
Win

sUllllly indent
wrile before (hllnging liles
in scali nina
C » II .re s-exp's
prilll "I for tab, S at end
. I • special in Ilallerns
number lilies
macro nallles whkh starl ...
simulille smarl lerminal
C11l11l11antl mode lines
lIIacro nllllles .".
for < >. anti illI'ul "I)
10 »and I IS t Ylled
choke ulldaies during inserl
visual mode lines
alOund end of bulTer?
IU lomat ic line sillilling

Scanning .taUem rormallon
bellinnilll of lille
I
$

\<
\>
III,'
IIIIfI
I {-Ji

•

7.1-

eml uf line
811 Y dlar acter
bellinllilll of wmd
elld (lr wmll
allY dlln ill
.. 11111 in 11,
.. hel weell x allcl J'
IIny IIlIlIIher oll'lccecling

1"

linc "
... at elltl
list sayecl lill's
recuver lile /I"I/Ic'
edil lilsl; rest viII :11
slart lit ItlK
search fur 1'111
reatl uilly mmle
exil fllllll vi. sOIvillg dlanges
stilI' vi fur Iiller resllllllililln

The display
tasl linc

@ lines

Ox

lu'oilidell'

III"

IIIIIt/"

- lines

Userul opllons

II,IIIIC' OIl 11111

.. OIl

"Z

Illnce sel's here in enviwnlllent vur.
enable "Iltion
disable olltion
live vulue I'td
show challgcd options
show value of oplion x

1 .. low.lle

l"clit

III"""

Sume lermilial IYlles
4J
1J)

It:nlerint:lll'llwinR fl
% .1 III111/C'
% t I + II IImll"
'II t I +
% .1 -r
% ,I - rIll"",'
% ,I IIalll.· •••
I~ ,I -. 10K
% ,I +IIltll I/a

InllialiLing opUons

( :ollllllund

Ilbhrev
"Ililend

1'1" und ull versiun (I

St:e also u.·/( I)

2ft21
2M S

"

Itcrcn~lIfc

Vi Quid,

S.tecUyiliG tenninal type
% sdel..... U, .... In'.·
S ....·:H .... = 11'1'('; npo •• n:"1\1

tabs

Error messages, edlllilla illilut III : I 1
IlIti I, feetllllIck II hOIl I illl und lurllC
dlllllges.
Ofl scrcen ollly, 1101 ill lile.
Lines Pilst Clld of lile.
Conlrol characters, "1 is deletc.
Expand 10 SllllCCS, cursur OIl lilsl.

VI slales
COlllmund

Inserl

tust line

Normal olld initial slllie.
Othels
return here. ESC (cscape) ClllIl'elS
Ilarlial commund.
Enlered by • I " I 0 () c (: 5 S ".
Arbitrary texl IhclI tc/millules wilh
ESC charader, or ahllllllllully with
ifllelfullt.
Itcading input for: I ? or I; terlllillale
wilh ESC or Cit til execule, intellllpi
10 cancel"

Counts berore "I commands
line/collllllll nllmber
scroll amounl
.elllicale insert
rcpeat eH'eel

I

(;

0"

I

I
"U

I "

I

1II0Si resl

Simple conllnands
dw
de
del
.lelel
I',",II'S( .
cw II,""t"se
u)ES( "

.p

,lelel c a wllr tI
. !cIlVillll !'unell/ulillll
,Idel e a line
J lines
inserl lexl
challge WI/Ill III
phil illite wtllll
"all~I'''sc dli.. adcl S

II""

""II'

I ... e rru

...
,.11118;. ... ....

.:S(:
"1

-I.

.

ct.'lIl n t:

elld inscrl or im:ulllilicic cllld
Idclele ClI' ruboult illleuullls
rClllill1 ScrcCII if"1 scramhles il

IIU
,J

.... Ie ....... ,ml •• lull
:"

:".
;,
:,1
:t

11,.11/4'

:tl

:t ... "'.",..
:e ... "
:e II

"I

"""...

:"
:" 1 111111/1'
:1iI1

:1..,111/
:11
:II OIl'S

:1
of;

-,

:1.

'''I'

..

wrilc back chilllies
WI ih: 111111 Cluil
'Illil
Cluil, disnrd dlllllles
edil IiIc 1/""/1'
Icc,lil, dislilid challies
edil, slarlilllill clld
edit Slilflilll III Ii lie "
cdil allernlile lile
S)'IICIII)'111 fm :e II
wrile file IIa",c'
overwrile liIe "alll,'
rull shell, Ihcn relurn
run ..,,,d, Ihell relllrn
ed.. IIC III liIe in III glisl
Sllccilr IICW arKlbl
show CUll CIII file IIl1d line
syllulI)'m fur :1
III lat! lilc clllr), 't'l:
:11, fulluwill, WOH' is 'OK

l'uslllolllul: wllhlll flIc
-.-

-II

"n
-U
Ci

11''''
1/11"
II

N

1'1("1 ... ,,
1,,,,,1 -"

II
II
"I.

AdJus.llIg .he
'I,
It
,('I{

,-

,
1""", ,

III,

I

('unccllous durill'; illwr'

Marking IIl1d re.un .... '

II
IM

...

eR
I or J
Inrll

I""

$
h or ....

..

•" or --

splice

Ix

.'x

'h

·

I

%

dcar ,III1IICI!r;IW
lelyl'C, clilllillaic @ lillcs
I elh ;1I~, nil. (III HI Wlllllllw hIlI
;11 ""IIUIII
alll:lIl1'l
I"" IIlIe ,.1 hullulII
,. " hilL \\ IIl1luw

.11 "" .. I,,w .1"wlI I lilli'

home window linc
lasl window linc
middle window line
nexl line, III firsl non-while
Ilrevious line, II firsl lion-while
rclurn, same IS +
ncal line, slime cnlunm
flrevious line, SlIlIle column

belinllinl of line
end of lille
forward
bllckwllrtls
same as ~
Sllllle liS ....
filld x forwllrd
1 backward
ufllo -' for",'ard
back uplo x
repcal lasl 1 .. 1 or
inverse nf i
10 sllCcified COIUIIIII
find IIIlIlchinl f I ) or

"

II
e

W
II
.:

a
C

I

r

a-u
"V

CIOISC laSI ,h;lIi1dcr
CIiISCS 1i,,1 wlIlIl
)'1I1If cr OISC, SillIIC ilS -II
rour kill, crOlsc illllill Ihis lillc
eSClIllCS ".. , r"ur ClOlse OIlId lIill
ell,ls inscllioll, 1111(11 10 l'IllIIlIlallll
illlerrulll, IClillillalcs illsCl1
ba(klab OVCI allltllll'/,''''
kill 1/1,'/1111//,'11', save fur IIcIII
bul II lIIilf,ill IIcal also
quole nOil-llrilllill, dlllflicier

.. '

Inser....d rCI.lace
•

I
A
I

r"
R

1IIIIICnd ..rler cursor
hlserl bdure
1I111'end al cntl of lille
inserl beforc lilsl 1I0n-IIhlllk
OIICII lillc helow
opell IIbove
rellillce sillgle char wilh "
reillace chllracler5

Oper •• ors (duuble ... Il.reel IIncs)

•
c

<

>

,I

-r

I

word forward
back wllld
clld of word
10 ncal senlence
10 ncal paralra .. h
bad. SClllclllC
hal'k Iluragiallh
hl,lIIlI dclimilcd word
halk W
III Clld III' W

CUIIIIIIlIllds ror USI'

I

"U
It

•
()

Words, seu.enccs. luulIgral)hs

I'"'

SfH~l'1I

"1

Cilluacier posl.lcUllnl
firs I 11011 white
I

•

"..
"W
CI lISC
kill
,

tSc

I.Il1e l)osllluIIIIII:

II

furwufll ScrCCllf1i1l
balk"'iud slicellfull
scroll duwlI hulf sueen
scwll UI' half sueell
11110 lille felld dd aullt
IIC III Ii lie lIIall'hilll
Ilrev lille mallhinl pOI'
reilCitI lasl I III 1
rcverse lasl 1111 !
II'lh lille ancr 1m'
1I'lh lille hefore
IIcal scclilln/fullliion
IIIC VilillS ~el'1 illlllf unclilln
lilllJ mallhing f t I '" I

Ilreviou, cOlllcal
," III lirsl lion-while ill'lille
lIIark posilion wilh Ieller x
Itl miuk ,J
..' III lirsl lion-while in linc

I'urwartl S'CIII"cssioll
hili tllIlI'l slclll III IIlom';
Ihrk S'ClIl'ccs~illll
hili ,lilli'
,,. al alums

delele
chllnle
Idl shirl
righl shirl
lillcr Ihmulh clllllmllnd
indenl for I lSI'
rallk lilies 10 hllll'er

Miscellaneous opcullulls
(:

I)
Ii

S
J

•X
Y

V.uk and
P
I'
II'
• A}

·Id

chanlC resl of line
dcklere~ oflille
Sllhslilule lhllrs
suhslilulc lilies
jilin lincs
dclcle dmraders
.. ' befllfe curs",
)'illlk lilies

,m.

1",1 bill'lI lincs
11111 helm e
11111 fllllll hillier "
)'illIlI III hullCI ,
,Icicle illlu blillcr ,

1I11do, rcd ... rchlne

..

II

11111111 lasl lh;lIIgc
IC"IIIIC IIlIlCIiI lillc

Ex Reference Manual
Version 3.S/2.13 - September, 1980
William Joy
R__ for

IIfI'SIOIU

J. Jl2. JJ by

Mark Horton

Computer Science Division
Department of Electrical Engineering and Computer Science
University of California. Berkeley
Berkeley. Ca. 94720

ABSTJUCT

Ex a line oriented text editor. which supports both command and display
oriented editing. This reference manual describes the command oriented part
of ex: the display editing features of ex are described in An Introduction to
D;splay Editing With Vi. Other documents about the editor include the introduction Edit: A tutorial. the Exledit Command Summary. and a Vi Quick Reference
card.

September 16. 1980

Ex Reference Manual
Version 3.5/2.13 - September, 1980
William Joy
RnrsN/o,

~'o"s

l.S/l.ll Oy

lv/ark Harron

Computer Science Division
Department of Electrical Engineering. and Computer Science
University of California. Berkeley
Berkeley. Ca. 94720

1. 5tartine es
Each instance of the editor has a set of options. which can be set to tailor it to your liking.
The command tdit invokes a version of ex designed for more casual or beginning users by
changing the default settings of some of these options. To simplify the description which follows we assume the default settings of the options.
When invoked. ex determines the terminal type from the TERM variable in the environment. It there is a TERMCAP variable in the environment. and the type of tbe terminal
described there matches the TERM variable. then that description is used. Also if the TERMCAP
variable contains a pathname (beginning with a /) then the editor will seek the desciption of
the terminal in that file (rather than the default letc/termcap.) If there is a variable EXINTT in
the environment. tben the editor will execute tbe commands in that variable. otherwise if there
is a file .eXTC in your HOME directory ex reads commands from that file. simulating a sourCt ~om­
mand. Option setting commands placed in EXINIT or .exTC will be executed before each editor
session.
A command to enter ex has tbe following prototype:t

ex [ - ] [ -T

] [

- t lIZg] [ -r] [

-1] [ -wn] [ -s ] [ -1\1 [ + command 1 name ...

The most common case edits a single file with

DO

opLions. Le.;

es name

The - command line option option suppresses all interactive-user feedback and is useful in
processing editor scripts in command files. The - T option is equivalent to using VI rather than
ex. The - t option is equivalent to an initial tag command. editing the file containing the lag
and positioning the editor at its definition. The -r option is used in rea)vering after an editor
or system crash. retrievinl the last saved version of the named file or, if no file is specified.
typing a list of saved files. The -I option setS up for editing LISP. setting the showmatch md
lisp options. The -w option sets the default window size to fl. and is usefui on diaJups to start
in small windows. The -% option causes t!X to prompt for a key. which is used to encrypt md
decrypt the contents of the file. which should already be encrypted using the same key, s~
crypt(1). The - R option sets the r~adonly option at the start.
Nam~ argumentS indicate fijes
to be edited. An argument of the form + command indicates that the editor should begm by

*

The finanoaJ su!)pOn 0( III lltoe Graduate Feliowship and the Nauonal Saence Foundation under p-aJ1u
MCS74-(J7~AOJ and MCS78-Q7291 is sn1efully Icltnowledsed.
t Brackeu '!' 'I' surround o~lonal parameters here.
1'0101 available In all v2 edilOrs due to memory ccnstraints.

*

•2•
executing the specified command. If command is omitted. then it defaults to "s". positioning
the editor at the last line of the first file initially. Other useful commands here are scanning
patterns of the form "/pat" or line numbers. e.g... + 100" starting at line 100.

2. FUe manipulation
2.1. ClU'J'ent file
Ex is normally editing the contents of a single tile. whose name is recorded in the curr~nt
IDe name. Ex performs all editing actions in a buffer (actually a temporary tile) into which the
text of the file is initially read. Changes made to the buffer have DO effect on the file being
edited unless and until the buffer contents are written out to tbe tile witb a wrlle command.
After the buffer contents are written, tbe previous contents of the written file are no longer
accessible. When a file is edited. its Dame becomes tbe current tile name. and its contents are
read into the buffer.
The current file is almost always considered to be edited. This means that the contents of
the buffer are logically connected witb the current file name. so tbat writing the current buffer
~ntents onto that file. even if it exists, is a reasonable action. If the current file is Dot edlled
then ex will Dot normally write on it if it already exists.·

2.1. Alternate file
Each time a new value is given to the current tile name. the previous current file name is
saved as the alternate tile name. Similarly if a file is mentioned but does not become the
current file. it is saved as the alternate tile name.

2.3. Filename expansion

•

Filenames within the editor may be specified using tbe normal shell expansion convene
tions. In addition. the character '%' in filenames is replaced by the curr~nr file name and the
character •#' by tbe alternate file name. t

2.4. Multiple flies and Damed buffers
If more than one file is given on the command line. then the first file is edited as
described above. The remaining aJ'IUments are placed with the first file in the argument list.
The current aJ'IUment.list may be displayed witb the args command. The next file in the argue
ment list may be edited with the nat command. The argument list may also be respecified by
specifying a list of names to tbe .W%I command. These names are expanded, the resuJting list
of names becomes tbe new argumeut list. and ex edits the first file on the list.
For saving blocks of text while ~ting. and especially when editing more than one file. ex
bas a group of named buffers. These are similar to the Dormal buffer. except that only a lim·
ited number of operations are available on them. The buffers bave names a through ;,,;

2.5. Read only
It is possible to use ex in rmd only mode to look at files tbat you have no intention of
modifying. This mode protects you from accidentJy overwriting tbe file. Read only mode is on
wben the rmdonly option is set. It can be turned on with tbe - R command line option. by the
vi~ command line invocation. or by setting the r~donly option. It can be cleared by setting
nor«Uionly. It is possible to write. even while in read only mode. by indicating that you really
• The fi~ command will say "(Not ec1ited'" if !be c:um:nt file is not considered ec1ited.
t This maJtes it easy to deal allCmalCly with two files ana elimnlllCS the need for retyplnl tbe name su""hed
on aD ~/' command after a No ",",r sma iIul 'h~ diaanosuc IS r=ved.
t It is aJso possible to refer to A throuct! Z: the upper case bu1fen are Ute same u the lower bUI commandos
a~ to named bulfers raIDer tban rt:l)laanl if u~ cue names are used.

t

•3•
.--

know what you are doing. You can write to a different file. or can use the! form of write. even
while in read only mode.

3. Exceptional Conditions
3.1. Errors and interrupts
When errors occur ex (optionally) rings the terminal bell and, in any case, prints an error
diagnostic. If the primary input is from a file. editor processing will terminate. If an Interrupt
signal is receiVed. ex- prints "Interrupt" and returns to its command level. If the primary Input
is a file. then ex- will exit when this occurs.
3.2. Recovering from haniUPs and crashes
If a hangul' signal is received and the buffer has been modified since it was last written
out. or if the system crashes. either the editor (in the first case) or the system (after it reboots
in the second) will attempt to preserve the buffer. The next time you log in you should be able
to recover the work you were doing. losing at most a few lines of changes from the last point
before the hangul' or editor c::'lU'I,. To recover a file you can use the -r option. If you were
eciiting the file resum~. then you should change to the directory where you were when the crash
occurred. giving the command

ex -r

,num~

After checking that the retrieved file is indeed Ok. you can wrIte it over the previous contents of
that file.
You will normally get mail from the system temng you when a file has been saved after a
crash. The command

ex -r
will print a list of the files which have been saved for you. (In the case of a hangul', the file
will not appear in the list. although it can be recovered.)

4. Editing modes
Ex bas five distinct modes. The primary mode is command mode. Commands are entered
in command mode when a ':' prompt is present. and are executed each time a complete line is
sent. In Cext inpvt mode ex gathers input lines and places them in the file. The appt!nd. Insert.
and dlanr~ commands use text input mode. No prompt is printed when you are in t~xt input
mode. This mode is left by typing a '.' alone at the beginning of a line. and comman(.' mode
resumes.
The last three modes are OfWn and VIsual modes. entered by the commands of the same
name. and. wlthin open and visual modes tat ins~rrlon mode. O~n and VIsual modes allow
loc:aJ editing operations to be performed on the lext in the file. The o~n command displays
one line at a time on any lerminal while VIsual works on CRT terminals wlth random positioning
cursors. using the scree..n as a (single) wlndow for file editing changes. These modes are
described (only) in An Introduction 10 Display Editing WIth Vi.
5. Command structure
Most command names are English words. and initial prefixes of the words are acce?table
abbreviations. The ambiguity of abbreviations is resolved in favor of the more commonly used
commands.- AJ an examl'ie. the commanc1 ~"SllfIJ" C2fI be ;abbreVIated '5' _hile the snonest ;avaiiaOie ;aobreviauon for

the lrt commaDd

IS '51:'.

·4·

5.1. CommaDd parameters
Most commands accept prefix addresses specifying the lines in the file upon which they
are to bave effect. The forms of these addresses will be discussed below. A number of com·
mands also may take a trailing count specifying the number of lines to be involved in the com·
mand. t Thus the command 00101''' will print the tenth line in the buffer while "delete 5" will
delete five lines from the bu1fer. starting with the current line.
Some commands take other information or parameters. this information always being
given after the command name.*

5.1. CommaDd ,.uiants
A number of commands have two distinct variants. The variant form of the command is
by placiDa an '!' immediately after the command name. Some of the default variants
may be controlled by options~ in this case, the '!' serves to toglle the default.
invo~

5.3. FJacs after commands
The characters '#', 'p' and 'I' may be placed after many commands.·· In this case, the
command ar"revia1ed by these characters is executed after the command completes. Since ex
normally priDts the new current line after each change, 'I" is rarely necessary. Any number of
'+' or '-' characters may also be given with these Oags. If they appear. the specified offset is
applied to the current line value before the printinl command is executed.
5.4. CommeDts
It is possible to Jive editor commands which are ignored. This is useful when making
complex editor saipts for which comments are desired. The comment character is the double
quote: •. Any command line beginning with • is ignored. Comments beginning with • may also
be placed at the ends of commands. except in cases where they could be confused as part oi
text (shell escapes and the substitute and map commands).

5.5. MuJtiple commands per liDe
More than one command may be placed on a line by separating each pair of commands by
a l' character. However the global commands. comments, and the shell escape '!' must be the
last command on a line, as they are not terminated by a 1'.
5.6. ReportiDC IUle chances
Most commands which change the contents of the editor bu1fer ~ve feedback if the scope
of the change exceeds a thresbold given by the ~port option. This feedback helps to detect
undesirably larae changes so tbat tbey may be quickly and easily revers~ with an undo. After
commands witb more aloba! effect sucb as global or IIiSuoJ, you will be informed if the net
change in the number of lines in the bu1fer during this command exceeds this threshold.
6. CommaDd addressiDC
6.1. AddressiDC priDLitiYes
The current line. Most commands leave tbe current line as the last line
which they a1fect. The defauJt address for most commands is the current
line. thus '.' is rareJy used alone as an address.

t Counts are rounded clown if necISIUT·

*

Examples would be ol'lion names iD a SIf CXlmmand Le. "ses number", I file name iD an ~, cornmaad.
felUW expression in • S1IiJsIlllltr command. or I LlI'pI address (or I CDfIY command. i.e. ".1..5 COllY 25··.
- A 'I" or 'I' must be preceded by • blank or LIb cxCC1l' In the sincJe SI'IICW cue 'lip'.

,

I

·: .
The nth line in the editor's buffer, lines being numbered sequenllail:,
from l.
The last line in ~he buffe:.
An abbreviation for "l,S", the entire buffer.

n

s
0/0
-n -n

An offset relative to the current buffer line. t
Scan forward and backward respectively for a line containing par. a reg.:·
lar expression (as defined below). The scans normally wrap around :ne
end of the buffer. If all that is desired is to print the next line contaInmg
pot, then the trailing / or ? may be omitted. If par is omitted or expil'
citty empty, then the last regular expression specified is located.;

/pat/ ?por?

•. ·x

Before each non-relative motion of the current line '.', the previous
current line is marked with a tag. subsequently referred to as •..•. This
makes it e2sy to refer or return to tbis previous context. Marks may
also be established by tbe mark command, using single lower ase
letters x and the marked lines referred to as "x'.

6.2. Combining aCi~:essin& primitives
Addresses to commands consist of a series of addressing primitives. separated by ': or ':'.
Such address listS are evaluated left-le-right. When addresses are separaled by':' the current
line'.' is set to the value of the previous addressing expression before the next address is inter·
preted. If more addresses are given than the command requires. then all but the last one or
two are ignored. If the command takes two addresses. the first addressed line must precede the
second in the buffer. t
7. Command descriptions
The following fonn is a prototype for all ex commands:
aridrt!SS command .' parameters count flags
All parts are optional: the degenerate case is the empty command which printS the next line in
the file. For sanity with use from within VIsual mode. ex ignores a ":" preceding any command.
In the following command descriptions. the default addresses are shown in parentheses.
which are not, however. part of the command.

abbreTiate word rlu
abbr: ab
Add the named abbreviation to the current list. When in input mode in visual. if word is
typed as a complete word. it will be changed to rhl.
( . ) append
rat

abbr: a

Reads the input text and places it after the specified line. After the command. '.'
addresses the last line input or the specified line if no lines were input. If address '0' is
given. text is placed at the beginning of the buffer.
t The forms '.+3' · ... 3· IDd '+++' are all equIvalent: if the current line IS line 100 !.hey aJJ address llne

103.

.

used In a SCln: after a SUDsUlUle / / and ~ ..
would SCln USlne the SUDslJIULe'S !'eIuiar ex"ressJon.
, ~ulI address Sl)eCJticauons are permmed In a lisl of addresses. the deiault In thIS case IS the currenl line' '.
thus' .100' IS equlvaienl to ..• 100'. 11 IS an error to lIve a pret'U address to a c:cmmand .... rueD ex!)eCtS none.

t The forms

\I and \! scan USlnl the last reluJar expression

-6a!
le::rt

The variant

tla&

to ap/Wnd toggles the setting for the autoindenloption during the input of

tal.

The members of the argument list are printed. with the current argument delimited by • rand 'J',
( • , . ) chance count

abbr: c

tea
Replaces the specified lines with the input teet. The current line becomes the last line
if no lines were input it is left as for a .~te.

input~

c!
ID:t

The variant toales autoindent during the dJan~.
( • • • ) copy addr flags
abbr: co
A copy of the specified lines is placed after addr. which may be '0'. The current line'.'
addresses the last line of the copy. The command I is a synonym for copy.

( • , • ) deletel:1uffer count flags

abbr: d

Removes the specified lines from the buffer. The line after the last line deleted becomes
the current tine~ if the lines deleted were originally at the end. the new last line becomes
the current line. If a named buffer is specified by giving a letter. then the specified lines
are saved in that bu1fer, or appended to it if an upper case letter is used.
edit file

abbr: e

ex file
Used to begin an editing session on a new fiJe. The editor first checks to see if tbe buffer
has been modified since the last write command was issued. If it bas been. a warning is
issued and the command is aboned. The command otherwise deJetes the entire contents
of the editor buffer. makes the named fiJe the current file and prints the new filename.
After insuring thai. this file is sensiblet the editor reads the fiJe into its buffer.

If the read of the file completes without error. the number of lines and characters read is
typed. If there were any non-ASCIJ characters in the file they are stripped of their nonASCD high bits. and any null characters in the file are discarded. If none of these errors
occurred. the file is considered edited. If the last line of the input fiJe is missing the trailing newline character. it will be supplied and a complaint will be issued. This command
leaves the current line •.' at the last line read.*

t I.e..

thai il is nOi a binary file such u a direcIory, • blodt or dlanC1el' $lIeCiaJ ftIe otber than Idrvirr)· . • ter·
mlnai. or • binary or execulable file (u indicaled by the finl word).
, /[ ellecuted from wilbin opnr or IIISIIIIi. !.be cunem IiDe is imlWly !.be first line of the me.

I

•

I

•

e! file
The variant fonn suppresses the complaint about modifications having be:n made and :1ot
written from the editor buffer, thus discarding all changes which have been made before
editing the new file.

e

+ ff file
Causes the editor to begin at line ff rather than at the last
command containing no spaces, e.g.: "+/pat".

file

line~

ff

may also be an editor

abbr: r
Prints tbe current file name, whetber it has been '(Modified]' since the last H.'me command, whether it is read only, the current line. the number of lines in the buffer. and the
percentage of the way through the buffer of the current line.·

file file
The current file name is cbanged to file which is considered' [Not edited)',
abbr: ,
First marks each line among those specified which matches the given regular expression.
Then the given command list is executed with'.' initially set to each marked line.
The command list consists of the remaining commands on the current input line and may
continue to multiple lines by ending all but the last such line with a '\'. If cmds (and possibly the trailing / delimiter) is omitted, each line matching par is printed. Ap~nd. Iffserr.
and change commands and associated input are pemtitted~ the'.' terminating input may
be omitted if it would be on the last line of tbe command list. O~ff and Visual commands
are permitted in the command list and take input from tbe terminal.
The global command itself may not appear in cmtis. The undo command is also not permitted there, as undo instead can be used to reverse the entire global command. The
options auroprinr and auroindenr are inhibited during a giobal. (and possibly the trailing I
delimiter> and the value of the report option is temporarily infinite, in deferenc: to a
report for the entire gJobal. Finally, the context mark •••• is set to tbe value of '.' before
the sJoba1 command begins and is not changed during a gJobaJ command. except perhaps
by an o~" or !llsual within the globaL

( 1 • S) dobal /JKlt/ cmds

abbr:

y

The ,'Viant fonn of global runs cmas at each line not matching pal.

( . ) iDsen
lea

abbr:

j

Plac::s the liven text before the specified line. The current line is left at the last line
input; if there were none input it is left at the line before the addressed line. This command differs from append only in the placement of text .

• In the ran cue thai the cur-rent file is '(Not ediledl' this is nOled also; in this cue you !\ave 10 use the

rorm

.! to wrile 10 the file. S1nce the edilor IS not sure that a write .....11 not destroy a file unrelated to the

current COnleftlS of the oll6er.

·8·

i!
text

The variant toggles auto;ndent during the insert.

( . , .+ 1 ) jom

count flags

abbr: j

Places the text from a specified range of lines together on one line. White space is
adjusted at each junction to provide at 1east one blank character, two if there was a '.' at
the end of the line, or none if the first following character is a ')'. If there is already
white space at the end of the line, then the white space at the start of the next line will be
discarded.
j!

The variant causes a simpler join with no white space
lines are simply concatenated.

processin~

the characters in the

(•) k x
The k command is a synonym for IffIlric. It does not require a blank or tab before the following letter.

( • , • ) list count flags
Prints the spec::ified lines in a more unambiguous way: tabs are printed as '-YO and the end
of each line is marked with a trailing'S'. The current line is left at the last line printed.

map Ihs rhs
The IffIlP command is used to define macros for use in visual mode. Lhs should be a sinlie character, or the sequence "#n", for n a digit. referring to function key n. When this
character or function key is typed in visual mode. it will be as though the corresponding
rhs bad been typed. On terminals without function keys. you can type .. #n .. . See section
6.9 of the "Introduction to Display Editing with Vi" for more details.

(. ) mark x
Gives the specified line mark x, a single lower case letter. The x must be preceded by a
blank or a tab. The addressing form "x' then addresses this line. The current line is nol
aft'ected by this command.
( • • • ) moYe addr

abbr:m

The mo~ command repositions the specified lines to be after addr. The first of the
moved lines becomes the current line.
abbr:

Dext

D

The next file from the command line argument list is edited.

D!
The variant suppresses warnings about the modifications to the buffer not having been
written out. discarding (irretrievably) any changes which may have been made.

a jileliSl
a + command jileiiSl
1

-9The specified filelisT is expanded and the ;esulting list replaces the current argument list;
the first file in the new list is then edited. If command is given (it must contain no
spaces), then it is executed after editing the first such file.
abbr: # or nu
Prints each specified line preceded by its buffer line number. The current line is left at
the last line printed.

( • , • ) Dumber count flags

flags
( . ) open / pat / flags

( • ) OpeD

abbr:

0

Enters intra1ine editing open mode at eac.i addressed line. If pat is given. then the cursor
will be placed initially at the beginning of the string matched by the pattern. To exit thiS
mode use Q. See An Introduction to Display Editing with Vi for more details.

*
prese"e
The current editor buffer is saved as though the system had just crashed. This command
is for use only in emergencies when a write command has resulted in an error and you
don't know how to save your work. After a preserve you should seek help.

( • , . ) print count
abbr: p or P
Prints the specified lines with non-printing characters printed as control characters '-x';
delete (octal 177) is represented as '·7'. The current line is left at the last line printed.
( • ) put ln4f~

abbr: pu

Puts back previously deleted or yank~ lines. NormaUy used with fkiele to effect movement of lines. or with yank to effect duplication of lines. If no buffer is specified, then the
last de/et~ or yanked text is restored.· By using a named buffer, text may be restored that
was saved there at any previous time.

quit

abbr: q
Causes ex to terminate. No automatic write of the editor buffer to a file is performed.
However. ex issues a warning message if the file has changed since the last wme command
was issued, and does not qUit. t Normally, you will wish to save your changes. and you
should give a 'Write command; if you wish to discard them, use the q! command variant.

q!
Quits from the editor, discarding changes to the buffer without complaint.
( • ) read fiie

abbr: r
Places a copy of the text of the given file in the editing buffer after the specified line. If
no fiie is given the current file name is used. The current file name is not changed unless
there is none in which case fiie becomes the current name. The sensibility restrictions for
the edit command apply here also. If the file buffer is empty and there is no current name
then e::r treats this as an ~dit command.

, Not Iwilabie in ail v2 editors due to memory constraintS.
• But :'10 moclifyinl commands may InLervene between tbe ~rtr or )lfZnlc and the (Nt. nor may tines be
moved between iHcs WIthout USlnl a named tnurer.
, Ex will also ISSUe a diacnoslic if tbere are more tiles in the 3rwument tist.

- 10 -

Address '0' is legal for this command and causes the file to be read at the beginning of
the buffer. Statistics are given as for the edit command wben the rtad successfully terminates. After a read the current line is the last line read.;
( • ) read !command
Reads the output of the command command into the buffer after the specified line. This
is not a variant form of the command. rather a read specifying a command rather than a
filename: a blank or tab before the ! is mandatory.
reaJyer

file

Recovers file from the system save area. Used after a accidental hangup of the phone·"
or a system crash·· or pns~ command. Except wben you use ",e~ you will be
notified by mail when a file is saved.
rewiDd
abbr: rew
The argument list is rewound, and the first file in the list is edited.

rew!
Rewinds the argument list discarding any changes made to the current buffer.

set

parame~

With no arzuments. prints those options whose values have been changed from their
with parameter all it prints all of the option values.

defaults~

Giving an option name followed by a '?' causes the current value of that option to be
printed. The '?' is wmecessary unless the option is Boolean valued. Boolean options are
given values either by the form 'set option' to tum them on or 'set no option' to tum them
otf~ string and numeric options are assigned via the form 'set option-value'.
More than ODe parameter may be given to

ser~

they are interpreted left-to-right.
abbr: sh

shell

A new shell is created. When it terminates, editing resumes.

soan:efi/e

abbr: so

Reads and executes commands from the specified file. Soul'Ce commands may be nested.

( • , • ) substitute I pat / rep/ / options count ./fags
abbr: s
On each specified line. the first instance of pattern pal is replaced by replacement pattern
rq/. If the global indicator option character 'g' appears. then aU instances are substituted;
if the confirm indication character 'c' appears. then before each substitution the line to be
substituted is typed with the string to be substituted marked with 'T' characters. By typing
an 'y' ODe can cause the substitution to be performed. any other input causes no change
to take place. After a substitute the current line is the last line substituted.
Lines may be split by substituting new-line characters into them. The newline in repl
must be escaped by preceding it with a '\'. Other metacharacters available in par and repl
are described below.

t Wjt=

0"" IUd

_ I the current line is set 10 (be tint line read rather :ban tbe 1uL

- The system saves a co'" of tbe tile you were editin& ol1ly if you !lave made cftanlCS

to tbe

file.

- 11 stop
,Suspends the editor. returning control to the top level shell. If autowme is set and there
are unsaved changes. a write is done first unless the form stop! is used. ThIs commands
is only available where supported by the teletype driver and operating system.
abbr: s
( .•. ) substitute options count flags
If pat and rep/ are omitted. then the last substitution is repeated. This is a synonym for
the & command.
( • • • ) t addr flags

The

t

command is a synonym for copy.

ta liZg
The focus of editing switches to the location of tag. switching to a different line in the
current file where it is defined. or if necessary to another file. i
The tags file is normally created by a program such as czags. and consists oi a number of
lines with three fields separated by blanks or tabs. The first field gives the name of the
tag. the second the name of the file where the tag resides. and the third gives an addressing form which can be used by the editor to find the tag~ this field is usually a contextual
scan using •/ pall' to be immune to minor changes in the file. Such sc:a.ns are always performed as if ffOmagTC was set.
The tag names in the tags file must be sorted alphabetically. i
unabbreTiate word
Delete word from the list of abbreviations.
undo

abbr: una

abbr: u
Reverses the changes made in the buffer by the last buffer editing command. NOle thal
global commands are considered a single command for the purpose of undo (as are open
and visual.) Also. the commands write and edit which interact with the file system cannot
be undone. Undo is its own inverse.
Undo always marks the previous value of the current line •.' as ••••. After an undo the
current line is the first line restored or the line before the first line deleted if no lines
were restored. For commands with more global effect such as glo!xzi and VIsual the
current line repins it's pre-a>mmand value after an undo.

unmap lhs
The macro expansion associated by map for lhs is removed.

( 1•S)

T /

pat / cmds

A synonym for the global command variant I!. running the specified cmds on each line
which does not match paL
nrsion
abbr: Ye
Prints the current version number of the editor as well as the dale the editor was !ast
cb.anged.
: If you Ilave modified tbe currenl file before &ivinc I lDr command. you must wme
I4f command. spec{Yln! no lDr will reuse the prevIous las.
: NOl available In aU v2 eGIlOf"S due to memory construnts.

It

out: ;tYIng another

- 12 ( • ) yisual ry~ count fiags
abbr: yj
Enters visual mode at the specified line. Ty~ is optional and may be •- ' , 'T' or •.' as in
the z command to specify the placement of the specified line on the screen. By default, if
~ is omitted, the specified line is placed as the first on the screen. A count specfies an
initial window size~ the default is the value of the option window. See the document An
introduaion to Display Editing with Vi for more details. To exit this mode, type Q.
Tisual tile
Yisual + n tile

From visual mode, this command is the same as edit.
( 1 $ ) write fik

abbr: w

t

Writes changes made back to fik, printing the number of lines and characters written.
Normally fik is omitted and the text goes back where it came from. If a file is specified,
then text will be written to that tile.· If the file does not exist it is created. The current
tile name is changed only if there is no current file name~ the current line is never
changed.
If an error occurs while writing the current aDd tdittd file, the editor considers that there
bas been "No write since last change" even if the buffer had not previously been
modified.

( 1 $ ) write> > fik

abbr:

t

w> >

Writes the buffer contents at the end of an existing file.

w!

fIIl~

Overrides the checking of the normal write command, and will write to any file which the
_system permits.

( 1 $ ) w !commtlnd
t

Writes the specified lines into command. Note the difference between w! which overrides
checks and w ! which writes to a·command.
wq fIIlme

Like

I wri~

and then

I

quit command.

wq! fIIlme
The variant overrides checking on the sensibility of the wrIte command, as w! does.

xU fIIlme
If any changes have been made and not wrinen, writes the buffer out. Then, in any case,
quits.
(

•

t

•

yuk INffer count
abbr: ya
Places the specified lines in the named buffer. for later retrieval via put. If no buffer name
is specified, the lines go to a more volatile place~ see the put command description.
)

I file OIliy if it is tbe c:urrent file and is ftiilrd.. if tbe tile does nol exist. or if the tile is
te1etYJ)C, Idnfrry. IdnfffIIiJ.. Olberwise., you must Jive tbe vanant form w! to force the wnte.

• The editor wntes to
ICNaJ)y

t

I

- 13 ..

( .+ 1 ) z count
Print the next count lines. default wmdo ....·.

( . ) z rype count
Prints a window of text with the specified line at the top. If rype is '-' the line is ~lacec
at the bottom; a '.' causes the line to be placed in the center.· A count gives the number
of lines to be displayed rather than double the number specified by the scroil option. On a
CRT the screen is cleared before display begins unless a count which is less than the
screen size is given. The current line is left at the last line printed.
! command
The remainder of tbe line after the '!' character is sent to a shell to be executed. Within
tbe text of command the characters '%' and '#' are expanded as in filenames and the character '!' is replaced with the text of the previous command. Thus, in particular. '~!'
repeats the last such shell escape. If any such expansion is performed. the expanded line
will be echoed. The current line is unchanged by this command.
If there has been "(No write]." of tbe buffer contents since the last change to tbe editing
buffer, then a diagnostic will be printed before the command is executed as a warning. A
single '!' is printed when the command completes.
( addr • addr) ! command
Takes the specified address range and supplies it as standard input to command; the resulting output then replaces the input lines.

(S) Prints tbe line number of the addressed line. The current line is unchanged.

(.,.) >
(.,. ) <

count flags
count flags

Perform intelligent shifting on the specified lines; < shifts left and > shift right. The
quantity of shift is determined by the shi/twldth option and the repetition of the
specification character, Only white space (blanks and tabs) is shifted; no non-white characters are discarded in a left-shift. The CUrTent line becomes the last line which changed
due to tbe shifting.

"n
An end-of-file from a terminal input scrolls through the file. The scroll option speCifies
the size of the scroll. normally a half screen of text.

(.+1 .. +1)
(.+1,.+1>1
An address alone causes the addressed lines to be printed. A blanK line prinLS the next
line in the file .

• Forms 'z.' and 'zT' aiso eXISt; ·z·' places the current line in the center, surrounds It with lines of '-'
characters and leaves the culTent line at this line, The (orm 'z r pnnlS the wtndow before 'z -' would. The
charaaers '+', T and • - ' may be reJ)eateO for cumWau\le etfect. On some \12 ec1IlOrs. no ryrw may be
lIVen.

• 14 -

-

( • • • ) " options count ./lags
RepealS the previous substitute command.
( • • • ) - options count ./lags
Replaces the previous regular expression with the previous replacement pattern from a
substitution.

8. Reaular expressions and substitute replacement patterns
8.1. Replar expressions
A regular expression specifies a set of strings of characters. A member of this set of
strings is said to be matchfti by the regular expression. Ex remembers two previous regular
expressions: the previous regular expression used in a substitute command and the previous regular expression used elsewhere (referred to as the previous scanning regular expression.) The
previous regular expression can always be referred to by a null re, e.g. 'I/' or '??'.
8.2. Malic and Domalic
The regular expressions allowed by a are constructed in one of two ways depending on
the setting of the magic option. The a and vi default setting of magic gives quick access to a
powerful set of regular expression metacharacters. The disadvantage of magic is that the user
must remember that these metacharacters are magic and precede tbem with the character '\' to
use them as "ordinary" characters. With nomagic. the default for edit. regular expressions are
much simpler, there being only two metacharacters. The power of the other metacharacters is
still available by preceding the (now) ordinary character with a '\'. Note that '\' is thus always
a metacharacter.
The remainder of the discussion of regular expressions assumes that that the setting of
this option is magic. t

8.3. Basic re:ular expression summa".
The foUowing basic constructs are used to construct magic mode regular expressions.
char
An ordinary character matches itself. The characters T at the beginning of a
line, 'S' at the end of line, '.- as any character other than the first. ' .•• '\', 'I',
and ,-, are not ordinary characters and must be escaped (preceded) by '\' to be
treated as such.
T
At the beginning of a pattern forces the match to succeed only at the be:;}nning of a line.
At the end of a regular expression forces the match to succeed only at the end
S
of the line.
Matches any single character except the new-line character.
Forces the match to occur onJy at the beginning of a "variable" or "word";
\<
that is, either a1 the beginning of a line. or just before a letter, digit, or underline and after a character not one of these.
Similar to "<', but matching the end of a "variable" or "word", i.e. either
\>
the end of the line or before character which is neither a letter, nor a digit, nor
the underline character.

t To d.iJa:m wnat is ltUe witb - r c it su1!'.ces to remember that the only J1)eCiaJ charal::len in this cue will
be 'T' al the Oe&inulftl of • l'eIular eltl'f'eS$iou. 'S' .. the end of I I'elWar Ul)I"eSSIon. and '\'. With ""~II:
the dIaraclen ,-, and 'a;' aIIo lose tbeu J1)eCiaJ mearunp reiIIled to the ~ent panem oi. suDsulule.

- 15 IstmrgJ

Matches any (single) character in the class defined by string. Most charac:ers
in string define themselves. A pair of characters separated by . -' in slrIng
defines the set of characters collating between the specified lower and upper
bounds. thus '[a-z]' ~ a regular expression matches any (single) lower-case
letter. If the first character of string is an T then the construct matches those
characters which it otherwise would not; thus . [y a - zj' matches anything bu t a
lower-case letter (and of course a newline). To place any of the characters 'T'.
'[', or '-' in string you must escape them with a preceding '\'.

8.4. Combinin& rqular expression primitives
The concatenation of two regular expressions matches the leftmost and then longest string
which can be divided with the first piece matching the first regular expression and the second
piece matching the second. Any of the (single character matching) regular expressions mentioned above may be followed by the character ,.' to form a regular expression which matches
any number of adjacent occurrences (including 0) of characters matched by the regular expression it follows.
The character ,-, may be used in a regular expression, and matches the text which defined
the replacement part of the last suost/lUle command. A regular expression may be enclosed
between the sequences '\ (' and '\)' with side effects in the subsltture replacement patterns.

8.5. Substitute replacement patterns
The basic metacharacters for the replacement pattern are '&' and '-'; these are given as
'\&. and '\ -, when nomagfc is set. Each instance of '&' is replaced by the characters which the
regular expression matched. The metacharacter ,-, stands, in the replacement pattern. for the
defining text of the previous replacement pattern.
Other metasequences possible in the replacement pattern are always introduced by the
escaping character '\'. The sequence '\n' is replaced by the text matched by the "..th regular
subexpression enclosed between '\{' and '\)'.t The sequences '\u' and '\1' cause the immediately following character in the replacement to be converted to upper- or lower-case respectlveiy
if this character is a letter. The sequences '\U' and '\L' turn such conversion on. either until
'\E' or '\e' is encountered. or until the end of the replacement pattern.
9. Option descriptions
autoindeat. al
default: noai
Can be used to ease the preparation of structured program text. At the beginning of each
appen~ change or i1UB1 command or when a new line is opened or created by an append.
change. Insert. or SUDstilUre operation within open or visual mode. ex looks at the line bemg
appended after. the first line changed or the line inserted before and calculates the
amount of white space at the start of the line. It then aligns the cursor at the level of
indentation so determined.
If the user then types lines of text in. they will continue to be justified at the displayed
indenting level. If more white space is typed at the beginning of a line. the following line
will start alig."led with the first non-white character of the previous line. To back the cursor up to the preceding tab stop one can hit -D. The tab stops going backwards are
defined at multiples of the shift'",,,drh option. You CDnnot backspace over the Indent.
except by sending an end-of-file with a -D.

,. When nested. j)arenthesized subexpressions ue prexnt. n is determined by c:oununl OCXUl'Tences of .\ ("
SlartJnI (rom tDe left.

- 16 Specially processed in this mode is a line with no characters added to it, which turns into a
completely blank line (the white space provided for the autoindent is discarded.) Also specially processed in this mode are lines beginning with an 'T' and immediately followed by
a AD. This causes the input to be repositioned at the beginning of the line, but retaining
the previous inaent for the next line. Similarly. a '0' followed by a An repositions at the
beginning but without retaining the previous indent.
AUloindent doesn't happen in global commands or when the input is not a terminal.
autopriDt, ap

default: ap
Causes the current line to be printed after each delete, copy. join, mo~. substitute, t. undo
'or shift command. This has the same effect as supplying a trailing 'p' to each such command. AUloprint is suppressed in globals. and only applies to the last of many commands
on a line.

autoWTite, aw
default: noaw
Causes the contents of the buffer 10 be written 10 the current file if you have modified it
and give a nat. rnvind, SlOp, IIlg, or ! command, or a AT (switch files) or -J (tag golO)
command in y;suaL Note, that the «iit and ex commands do Dot aUlOwrite. In each case.
there is an equivalent way of switching when autowrite is set to avoid the autowrtte (edit
for n~ rnv;nd! for.l rewind. SlOp! for SlOp. IIlg! for tag, shell for .I, and :e # and a :ta!
command from within Yisua/).
beautify. bf'
default: nobeautify
Causes all control characters except tab. newline and form-feed to be discarded from the
input. A complaint is registered the first time a backspace character is discarded. Beauttjy
does not apply 10 command input.

directory, clir
default: dir- Itmp
Specifies the directory in wbich ex places its buffer file. If this directory in not writable,
then the editor will exit abruptly when it fails 10 be able to create its buffer there.
edcompatible

default: noedcompatible
Causes the presence of absence of I and c: suffixes on substitute commands to be remembered. and 10 be lOggJed by repeating the suffices. The suffix r makes the substitution be
IS in the - command, instead of like ct.. ~

errorbells. eb
default: noeb
Error messages are preceded by a bell.· If possible the editor always places the error message in a standout mode of the terminal (such as inverse video) instead of ringing the
bell.
hardtabs, bt
default: ht-8
Gives the boundaries on which terminal hardware tabs are set (or on which the system
expands tabs).
iporec:ase, Ie:

default: noic

u Version J only.

• BetI nnsm& ill

0"."

and WSJIIIi on errors is nOI suppressed by setlinl fftIftI.

- 17 -

All upper case characters in the text are mapped to lower case in regular ~xor:SSlon
matching. In addition, all upper case characters in regular expressions are mapped to
lower case except in character class specifications.
lisp

default: nolisp
AUIOtndent indents appropriately for lisp code, and the ( ) { }
and VIsual are modified to have meaning for lisp.

list

II and II commands in

ooe"

default: nolist
All printed lines will be displayed (more) unambiguously, showing tabs and end-of-lines
as in the list command.
default: magic for ex and vrt
If ffomagic is set, the number of regular expression metacharacters is greatly reduced. with
only T and'S' having special effects. In addition the metacharacters ,-. and '&' of :he
replacement pattern are treated as normal characters. All the normal metacharacters may
be made magic when ffomaglc is set by preceding them with a '\'.

malic:

mesg

default: mesg
Causes write permission to be turned off to the terminal while you are in visual mode. if
ffomesg is set. U

Dumber. nu
default: nonumber
Causes all output lines to be printed with their line numbers. In addition each input line
will be prompted for by supplying the line number it will have.
open

default: open
If ffoo~n. the commands open and visual are not permitted. This is set for edit to prevent
confusion resulting from accidental entry to open or visual mode.

optimize. opt
default: optimize
Throughput of text is expedited by setting the terminal to not do automatic carriage
returns when printing more than one (logical) line of output. greatly speeding output on
terminals without addressable cursors when text with leading white space is printed.
panlraphs. pan
default: para-IPLPPPQPP LIbp
Specifies the paragraphs for the { and J operations in open and VIsual. The pairs of characters in the option's value are the names of the macros which stan paragraphs.
prompt
default: prompt
Command mode input is prompted for with a':'.
redraw
default: no redraw
The editor simulates (using great amounts of output). an intelligent terminal on a dum b
terminal (e.g. during insertions in Visual the characters to the right of the cursor pOSitIon
are refreshed as each input character is typed.) Useful only at very high speed.

t

,VOlfllZflC

for

~IL

U versIon J only.

- 18 -

remap
default: remap
If on. macros are repeatedly tried until they are unchanged. ii For example. if 0 is
mapped to 0, and 0 is mapped to I, then if remDp is set. 0 will map to I, but if noremap IS
set, it will map to O.
report

default: report-St
Specifies a threshold for feedback from commands. Any command which modifies more
than the specified number of lines will provide feedback as to the scope of its changes.
For commands such as global. o~n., undo, and "isual which bave potentially more far
reaching scope, the net change in the number of lines in the buffer is presented at the end
of the command. subject to this same threshold. Thus notification is suppressed during a
global command on the individual commands performed.
default: scroll- Ih window

scroll

Determines the number of logical lines scrolled when an end-of-file is received from a
terminal input in command mode, and the number of lines printed by a command mode :
command (double the value of saoJ/).
default: sections-SHNHH HU
Specifies the section macros for the II and II operations in o~n and ",suaL The pairs of
characters in the options's value are the names of the macros which start paragraphs.

sectioas

default: sh -/bin/sh
Gives the path name of the shell forked for the shell escape command '!', and by the shell
command. The default is taken from SHELL in the environment, if present.

shell. sh

.,

shiftwidth. sw

default: sw-8
Gives the width a software tab stop, used in reverse tabbing with
tknl to append text, and by the shift commands.

-n when

using autom-

showmatch. SID .
default: nosm
In o~n and ",sual mode, when a ) or } is typed. move the cursor to the matching ( or {
for one second if this matching character is on the screen. Extremely useful with lisp.
slowopell, l10w

terminal dependent

A1fea..~ the display algorithm used in W$UI1/ mode. bolding off display updating during
input of new text to improve throughput when the terminal in use is both slow and uninte1ligc:nL See An Introduction 10 D,spilly Ediling With Vi for more details.

tabstop, 15

default: IS-8
The editor expands tabs in the input file to be on UZDS10P boundaries for the purposes of
display.

taclealth, tl

default: tJ-O
Tags are not significant beyond this many characters. A value of zero (the default) means
that all characters are significant.

n Version 3 only.

f 2 for filii.

- 19 -

tags
I

default: tags - tags lusr Ilib/tags
A path of files to be used as tag files for the rag command. ~:: A requested lag is searched
for in the spec:fied files. sequentially. By default (even in version 2> files called tags are
searched for in the current directory and in lusrllib (a master file for the entire syste:rl.)
from environment TERM

term
The terminal type of the output device.
terse

default: no terse
Shorter error diagnostics are produced for the experienced user.

warn

default: warn
Warn if there has been '[No write since last change]' before a '!' command escape.

window
default: window - speed dependent
The number of lines in a text window in the Visual command. The default is 8 at slow
speeds (600 baud or less), 16 at medium speed (1200 baud), and the full screen '.."inus
one line) at higher speeds.
w300, w1200, w9600
These are not true options but set window only if the speed is slow (300). medium
(1200), or high (9600). respectively. They are suitable for an EXINIT and make it easy
to change the S/16/full screen rule.
default: ws
Searches using the regular expressions in addressing will wrap around past the end of the

wnPSc:tD, ws

file.
default: wm-O
wrapmUliD, wm
Defines a margin for automatic wrapovcr of text during input in
See An IntroductIon TO Text Editing WIth Vi for det.3ils.

o~"

and VIsual modes.

writnny. wa
default: now a
Inhibit the checks normally made before wrll~ commat:ds, allowing a write to any file
which the system protection mechanism will allow.
10. Limitations
Editor limits that the user is likely to encounter are as follows: 1024 characters pe:- line.
256 characters per global command list, 128 characters per tile name, 128 characters in the pre·
vious insened and deleted text in o~n or VIsual. 100 characters in a shell escape command. 63
characters in a string valued option. and 30 characters in a tag name. and a limit of 250000 lines
in the tiJe is silently enforced.
The vrsual implementation limits the number of macros defined with map to 32. and the
total number of characters in macros to be less than 512.
A.cknowi~dgm~nlS.

Chuck Haley contributed greatly to the early development of ex. Bruc:
Englar encouraged the redesign which led to ex version 1. Bill Joy wrote versions I and :.0
through 2.7. and created the framework that users see in the present editor. Mark Horton
added macros and other features and made the editor work on a large number of terminals md
U nix systems.
;: Verston J aaly.

Edit: A Tutorial
Rickl 8/aLi

James Joyce

Computing Services
University of California
Berkeley. Caiifornia 947:0

A.BSTRA.CT
This narrative introduction to the use of the :e:<, editor edj( assumes no
prior familiarity with computers or with te:. to change each final "ing" to "ed" and pnnt the changed lines.
The symbol .•••• indicates the beginning of a line. Thus.

:sr II. I
instructs the editor to insen "1." and a space al the beginning of the current line.
The characters "S" and ..... have speciai meanings only in the context or" searching. At
other times. they are ordinary characters. [f you ever need to search for a character that ha!i ~
special me:uting, you must indicate that the character is to temporarily lose its speCIal
siillificance by tYl'ing another special character. the bacleswh (\). before it.
: 5/\ $I dollar/
looks for the character "S" in the current line and replaces it by the word "dollar" W~re:l
not for the baclestash. the "S" would have represented "the end or the line" in your se:lrC:1.
r:llher than the ~h:lr:lcter "S" Tne backsiash retains ils special sl~nlficance unless II IS pre·
.:..:~eu by .lnother backsla.sh.

• 18 •

IS5uinl

t.:~l:,{ c:ornmancis"Jrom

[he editor
I-\fte: cre:lting several :lles ...vith the editor. you may want to de!ete tiles no longer useful
to you or ask for a li5t of your rues. Removing and listing file:s are :lOt funC!ions oi :he ~Cltcr,
and so they reqwre the ~e of UNIX system comm3Ilds (:liso refe:T~ ,0 lS "sheil" commanos.
as "sheW' IS the 'name oi the program that processes Li:"lIX commands), You Jo not ne:e:J :0
quit the et1itor to e:t~:.1te a t:~IX commanc1 lS long as you indicte that it is to be sent to ,:1e
sheil for execution. To use the ~tx command I'm to ,emove the :lle rlame~ "junk" type:

:!rm junk

The excamation mark (!) indic:ues that the rest of the line is to be proc:sscO as a U~lX com·
mand. II the buffer contentS have not been written sinc: the last change. a wamIng ',a,il! be
printcO before the command is e:t~.lteO. Tne editor printS i .• ~ •• when the command is .:om·
p'eteO. The tutorial "Communicating with UNIX" c1escribes useful features of the system. of
which the editor is only one part.

Filenames lnd file manipulation
Throughout each et1iting session. edit keeps tr:lCk of the name of the file being eeite:J .lS
the I.·U"tnt /i'enam~. Edit remembers as the current filename the name given when you ~ntere:J
the et1itor. The C'.lrrent filename changes whe!'1ever the et1it (e) command is used to specify do
new file. Once edit has r~ort1ed a current tilename. it inserts th:u name inLo any command
where a filename has been omitted. If J. write command does not spedfy a rue. edit. a.s we
have seen. suppiies the current tile!'1ame. You en have the editor write onto a different :1le by
inc udin~ itS name: in the write commmd:
: ,.. l:hap'erJ
"cll~ter3" 23~

lines. 8698 cnancters

The ~urrent filename ~-emembered by the editor w,II !lOf b~ changed as IJ muir of the wf'llt com·
mand unless If IS th~ fiTSt filename g7vf!n Iff th~ edirmg session. Thus. In the rle:tt wnte command
which does not specify a name. edit will write onto the C'.lrrenc file and not onto the nie
"cnapterJ".
The file ([) c:ornm2nci
To ask for the C'.lrT'e:1t filename. tJ1'e file (or n. [n response. the editor prOVIdes current
information about the buffer. inci.:ding the filename. your curre!'1t positlon. and the numbe:- of
lines in the buffer:

:!
·text" (Modified I line 3 oi -+ - i 5'%-

If the contentS of the butrer have cl'lanied sine: the last time the rue was wntten. the ~ilor
'NtH teil you that the aIe has be-..n "(Modifiedl", After you save to,e ci'langes ~y 'Nrmng onto l
disk file. the outfer Will no longer be considered modified:
:w

"te:tt" -+ lines. 88 charac:e:-s
:(

-te:tt" line J of

~

-75%--

Re-.Jciinl lciditional tiles (r1

The rnci (r) I:ommand ..ulows :/OU to Jdd ~he contents of l tile ~o ~he ,uner without ..:e!:itrOYl"i the :~:tt ..ure:l.Ciy there. To ~~ It. sD~:iy :he line .lfter wn,,:, ,he new text wlil j~

- 19 placed. the command r, and then the name of the file.

: Sr bibliogr2phy
·'oibliography· 18 lines. 473 characters
This command reads in the file bibliography and adds it to the buffer lfter the last line. T.1e
current filename is not changed by the read command unless it is tbe first filename given in the
editing session.
WritiDl pans of the butfer
The write (,,) command can write all or part of the buffer to a file you specify. We are
already familiar with writing the entire contents of the buffer to a di.sk file. To write only part
of the buffer onto a file. indicate the bqinning and ending lines before the write command. for
example

: 45,S" endiDl
Here all lin~ from 4S throuih the end of the buffer are written onto the tile named ending.
The lines remain in the buffer as part of the document you are editing. and you may continue
to edit the entire buifer.

Recoverinl files
Under most circumstances. edit's crash recovery mechanism is able to save work to within
a few lines of changes after a crash or if the phone is hung up accidently. If you lose the contents of an editing buffer in a system crash. you will normally receive mail when you login
which gives the name of the recovered file. To recover the tile. enter the editor and type the
command r!COyer (ree), followed by the name of the lost tile.
: recoYer chapa

Recover is sometimes unable to save the entire buffer successfully, so always check the contents of the saved buffer carefully before writing it back onto the origina! file.
Other recovery techniques

If something goes wrong when you are using the editor. it may be possible to save your
work by using the command prese"e (pre). which saves the buffer as if the system had
crashed. If you are writing a tile and you get the messase "Quota exceeded". you ha·.. e tried to
use more disk storage than is allotted to your account. Proceed with caUllon because it is likely
that only a part of the editor's buffer is now present in the tile you tried to write. In this case
you should use the shell escape from the editor (!) to remove some files you don't need and try
to write the tile again. If this is not possible and you cannot find someone to heip you, enter
the command

: prese"e
and then seek heip. Do not simply leave the editor. If you do, the buffer will be lost. and you
may not be able to save your tile. After a preserve. you can use the recover command once the
.problem has been corrected.

If you make an undesirable change to tbe buffer and issue a write command before discovering your mistake. the modified version will replace any previous version of the rue.
Should you ever lose a good version of a dOC'.lment in ,his way, do not panic and leave the editor. As long as you stay in the editor. the contents of the buffer remain accessible. Depending
on the nature of the problem. it may be possible to restore the buffer to a more complete staLe
with the undo command. After fixing the damaged buffer. you can again wnte the :lie to diSk.

o

20

0

Funher re::uiinl ~d other information
,-Edt is an editor designed for be~lng and casual users. It is ac:ually a Ve:-Slon of . 20

Ex Reference Manual. 20
file. 1
file r=:overy, 19
filename. 1
Interrupt (message), 6
line numbers, see also current line
dollar sign (S), 7, 14
dot (.). 8. 14
relative (+ and -), 14
louing out. 5
login procedure. 2
non-printing characters. 7
"not found" (message). J
program. 1
r=:overy see file recovery
shell. 18
shell escape (!). 18
special characters (.. S. \). 17
text input mode. 4

UNIX. 1

Ex/Edit Command Summary (Version 2.0)
Ex and rriit are text editors. used for creating
and modifying files of text on the UNIX computer
system. Edit is a variant of u with features
designed to malee it less complicated to learn and
use. In terms of command syntax and etrect the
editors are essentiaJly identical. and this command summary applies to both.
The summary is meant as a quick reference
for users aJready acquainted with ~it or ex:
Fuller explanations of the editors m:ay be found
in the documents Edit: .... Tutorial (a self·teaching
introduction) and the Ex R,/,nnr:r Mallual (the
comprehensive reference source for both ~it and
0-). Both of these writeup! are available in the
Computing Services Library.
In the examples included with the summary.
commands and texl entered by the user are
printed in boldfam to distinguish them from
responses printed by the computer.
The Editor Buft'er
In order to perform its tasks the editor sets
aside a temporary work space. called a buffv.
separate from the user's permanent file. Before
starting to wor1c on an existing file the editor
maKes a copy of it in the buifer. lavinl the oripn.. uncouched. All editing changes are made
to the buifer copy. which must then be written
back to the permanent file in order to update the
old version. The butTer disappears at the end of
the editing session.
Editing: Command and Text Input Modes
Durin" an editing session there are two usual
nlo::es nf' opera,i"n: COIffIIWII"1 ",ode and 1m
inflllt mode. (This disreprds. for Ihe moment.
a"" and visual modes. discussed below.) In command mode. the editor issues a colon prompt (:)
10 show that it is ready 10 accept and execute a
command. In tut input mode. on the other
band. there is no prompt md the editor mereiy
accepts te:olt to be added to Ihe butTer. Text
input mode is initiated by the· commands apfWnd.
i".,.,. and r:itGIIfr. . It is terminated by typing a
period as the first charac:ler on a line. followed
immediate.y by a curiaae reIW11.

Line Numbers and Com. . . . Syntas:
The edilor keeps lrac:k 01 lines of lext in Ihe
butrer by Ilumbering them consecutively startinl
wilh 1 and renumberinl as lines are added or
defeted. At any given lime the edilor is positioned alone of these lines: this position is ailed
the nI'~nt lin,. QeneraUy. commands that
change the conlents of the buifer print the new
c:utrent line at the end of tbeir execulion.

Most commands can be preceded b) one or
two line-number addresses which indiQte the
lines to be aifected. If one number is given the
command operates on that line only~ if two, on
an inclusive range of lines. Commands that can
take line-number prefixes also assume default
prefixes if none arc given. The default assumed
by each command is designed 10 make it convenient to use in many instances without any
line-number prefix. For the most part. a command used without a prefix operates on the
current line. though exceptions 10 this rule
should be noted. The print command by itself.
for instance. causes one line. the current line. to
be prinled at the terminal.
The summary shows the u~mber of line
addresses that can be prefixed to each command
as weJl as the defaults assumed if they are omitted. For example. f. •. ) means thaI up to 2 linenumbers may be given. and that if none is gjven
the command operates on the current line. (In
Ihe address prefix notation. ".u stands for the
current line and "s" stands for the last line of
the buffer.) If no such notation appears. no
line-number prefix may be used.
Some commands talee trailing intonnation;
only the more important instances of this are
mentioned in Ihe summary.
Open and Visual Modes
Besides command and text inpul modes. u
and ~it provide on some lerminais other modes
of editing, a".n and VIsual In these modes the
cursor can be moved to individual words or chara.cte:s in a line. TI. I. a. :nr.lat.·:.s the:: giver wi':
very different from the standard editor commands; most do not appear on the screen when
typed. An Introdu~ion to Display Editlnr Mltlh Vi
provides a full discussion.
SpKial Characters
Some chara~ take on special meanings
when used in context searches and in patterns
liven to the SUlnlllUll command. For ~it. these
are .. -.. and "S", meaning the beginning and
end of a line. respectively. Ex has the following
additional special characters:

"

•

I

To use one of the speeia' characters as it! simple
graphic representation rather than with its special
meaning. precede it by a ~cJcslash (\). The
badtSlllSh always has a special meaning. Consult
the more complete wrileups on edit and ex for
details on the use of special characters.

• .. _ .. _• .,n In,,,,"

I
I
I
I
I
I
I
I

I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I

I
I
I
I
I
I
I
I
I
I
I
I
I

I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I

Name

Begins text input mode. adding lines to the buffer
after the line spec;fied. Appending continues until
..... is typed alone al the beginning of a new line.
followed by a carriage return. Oa places lines at the
beginning of the buffer.

Uappend

Deletes indicated line

An address alone followed by a carriage return
causes the line to be printed. A carriage return by
i~elr prints the line following the currenl line.

: 
the line after the current line

.;urches for tile fte.U line in whicn
and prints it.

:fIhis partemJ
This pattern next occurs here.

/I

ptln"."

oa:urs

:11

RCl'e3ts the most recent search.

This pattern also occurs here.

!parrmr?

Se:arches in the reverse direction for

??

Repeats the most recent search. moving in the
reverse direction throup the buffer.

ptlnr",.

MAIL

REFERE~CE

MA.NUAL

Kurt Shoens

Version 1.3
December 2. 1979

1. Introduction
Mail provides a friendly environment for sending and receiving mail by dividing incoming
mail into its constituent messages and allowing the user to deal with them in any order. It provides a set of ed-like commands for manipulating messages and sending mail.
This document describes the Mail command at an introductory level appropriate for the
casual user as well as a more detailed level appropriate for those whose usage of Mail is
sufficiently frequent to justify such familiarity. The reader is assumed to be familiar with the
UNIX' Shell. the text editor, and some of the common UNIX commands. If you are a neophyte
Mail user, section two of this document should provide enough information to allow you to
effectivelY use Mail. The balance of this document describes more advanced features, which
are useful to those commonly barraged with a large volume of mail.
2. Common usage
The Mail command has two distinct usages, according to whether one wants to send or
receive mail. Sending mail is simple: to send a m~age to a user whose login name is, say,
"root," use the Shell command:
% Mail root
then type your message. When you reach the end of the message, type an EOT (control-d) at
the beginning of a line, which will cause Mail to echo "EDT" and return you to the Sheil.
When the user you sent mail to next logs in, he will receive the message:
You have mail.
to alert him to the existence of your message. Incidentally. once you have sent mail to someone. there is no way to undo the act. so be careful. The message your recipient reads will consist of the message you typed, preceded by a line telling who sent the message (your login
name), the teletype from which the message was sent, and the date and time it was sent.
If you want to send the same message to several other people, you can list ail of their
login names on the command line. Thus,
% Mail sam bob john
Tuition fees are due next Friday. Don't forget!!
1 UNIX IS a trademark of Bell uboralOnes.

Mail Reference

~1anuai

12121'79

2



EOT
%
will send the reminder to sam. bob. and john.

If, when you log in, you see the message,
You have mail.
you can read the mail by typing simply:
% Mail

Mail willl'eSl'ond by typing its version number and date and then listing the messages you have
waiting. Then it will type an underscore and await your command. Tne messages are assIgned
numbers starting with 1 - you can refer to the messages with these numbers.
To look at a Sl'ecific message. use the tYl'e command, which may be a.bbreviated to simply
t. For e:wnple. if you had the foilowing messages:
1 root
Wed Sep 21 09:21 "Tuition fees
2 sam
Tue Sep 20 22:55
you could examine the first message by giving the command:
type 1
which might cause Mail to respond with, for example:
Message 1:
From root tty8 Wed Sep 21 09:21:45 1978
Subj: Tuition fees
N

Tuition fees are due aext Wednesday. Don't forget!!
Normally, each message you receive is saved in the file mbo::c in your login directory at the
time you leave Mail. Often, however, you will not want to save a particular message you have
received because it is only of passing interest. To avoid saving a message in mbo::c you c:m
deiete it using the delete command. In our example,
delete 1
will prevent Mail from saving message 1 (from root) in mbo::c. In addition to not saving deleted
messages, Mail will not let you ty-oe them. either. The effect is to make the message disappear
aitogether, aiong with its number. The delete command can be abbreviated to simply d.
When you have perused all of the messages of interest. you can leave Mail with the quit
command, which saves ail of the messages you have typed but not deleted in the 51e mbo::c in
your login directory. Deleted messages are disC3I'ded irretrievably. and messages left untouched
are preserved in your system mailbox so that you will see them the next time you type:
%

~ail

The quit command can be abbreviated to simply q.

If you wisb for some re:sson to leave Mail quickly without altering either your system
mailbox or mbox. you can type the x command (sbort for exit). which will immediatelY return
you to the Shell without changing anything.
II. instead. you want to exet:".lte a Shell command without leaving ~ail. you can type
command prec::ded by an exdamatlon ;:loint. just as in the text ~tor. Thus. for instanc::
!date
wdl print the C'.lITent date without le:lving

1.

~he

~ail.

FnaHy. the help command is available to ;Jrint out a brief summary of the ~faJi com-

mands. usini on1y tne single c:uracter command lobrevialions.

~ai1

Reference

~aDual

1212/79

3

3. Tilde escapes
While typing in a message to be sent to others. it is often useful to be able to invoke the
text editor on the partial message. print the message. execute a shell command. or perform
some other auxiliary function. Mail provides these capabilities through tilde escapes, which consist of a tilde n at the beginning of a line. foHowed by a single character which indicates the
function to be performed. For example. to print the text of the message so far, use:
-p
which will print a line of dashes, the recipientS of your message, and the text of the message so
far. If you are dissatisfied with the message as it stands. you can invoke the text editor on it
using the escape

-e
which causes the message to be copied into a temporary file and an instance of the editor to be
spawned. After modifying the message to your satisfaction. write it out and quit the editor.
Mail will respond by typing
(continue)
aiter which you may continue typing text which will be appended to your message. or type
 to end the message.
It is often useful to be able to include the contentS of some file in your message: the
escape
-r filename
is provided for this purpose. and causes the named file to be appended to your current message.
Mail complains if the file doesn't exist or can't be read. If the read is successful. the number
of lines and characters appended to your message is printed. after which you may continue
appending text.
As a special case of -r, the escape

-d
reads in the file "dead.letter" in your home directory. This is often useful since Mail copies
the text of your message there when you abort a message with RUBOUT.
In order to save the current text of your message on a file you may use the
-w filename
escape. Mail will print out the number of lines and characters written to the file. after which
you may continue appending text to your message.
If you are sending mail from within Mairs command mode (read about the reply and
mail commands, section six). you can read a message sent to you into the message you are
constructing with the escape:
-m 4which will read message 4 into the current message. shifted right by one tab stop. You can
name any non-deleted message, or list of messages. This is the usual way to forward a message.
If. in the process of composing a message. you decide to add additional people to the list
of message recipients. you can do so with the escape
-t name I namel ...
You may name as few or many additional recipientS as you wish. Note that the users origmally
on the recipient list will still receive the message: in fact. you cannot remove someone from the
recipient list with -t.
If you wish. you can associate a subject with your message by using the escape
-s Arbitrary string of text

~aiI

Referenc:e :'Ybnuai

12/2/79

whicn replaces any previous subject with "Arbitrary string of text." The subject. if given. is
sent neu tile top of the message prefixed with "Subj:" You can see what the message will look
like by using • p.
For politic:ai reasons. one oc:3SionaUy prefers to list c:rtain people as recipients oi carbon
copies of a message rath-er than direct reepientS. The escape
-c namel came2 .•.
adcis the camed people to the "0::" list. similar to -to Again. you can exec-olte .p to see what
the message will look like.
The recipients of the message together constitute the "To:" field. the subject the "Sub;:"
field. and the carbon copies the "Cc" field. If you wish to edit these in ways impossible with
the -l, -s. and -c escapes. you can use the escape

il
which prints "To:" followed by the current list of recipients and leaves the cursor (or printhead) at the end of the line. If you type in ordinary c.~aracters. they are appended to the end
of the current list of recipients. You can also use your erase character to erase back into the
list of recipients. or your lcill character to erase them altogether. Thus. for example. if your
erase and lcill characters are the sundard # and @ symbols.
il
To: root Icurt####bill
would change the initial recipients "root leun" to "root bill." When you type a newline. Mail
advances to the "Subj:" field. where the same rules apply. Another newline brings you to the
"C:." field. which may be edited in the same fashion. Another newline leaves you appending
tc."Ct to the end of your message. You can use -p to print the current text oi tbe header fieicis
and the body of the messqe.
To eif=:t a temporary escape to the sheil. tbe escape
-!command
-is used. which exec-oltes command and returns you to mailing mode without altering the text of
your message. If you wish. instead. to filter the body of your message through a sheil command. then you can use
1:ommand
which pipes your message through the command and uses the output as the new text of your
message. If the command produces no output. Mail assumes that something is amiss and
retains the old version of your message.. A frequently-used filter ;., the command Imr whicn is
designed to format outgoing mail.
If you wish (for some reason) to send a message which contains a line beginning with a
tilde. you must double it. Thus. for example.
-"This line begins with a tilde.
sencis the line
-nis line bqins wi th a tilde.
Finally. the esape

-.,

prints out a brief summary of the available tilde escapes.
4.

~essqe

lists
. The tnJe and deiere commands described in section two take a list of messalJes as argument. 3.S do many of the commands described in se:::ion six. This sec:ion desC10es the construction oi message listS in general.

Mail Reference Manual

1212/79

5

A message /iSl consists of a list of message numbers, ranges, and names, separated by
spaces or tabs. Message numbers may be either decimal numbers, which directly specify messages. or one of the special characters "r" "." or "$" to specify the first relevant, current, or
last relevant message, respectively. Relevant here means, for most commands "not deleted"
and "deleted" for the undelete command.
A range of messages consists of two message numbers (of the form described in the previous paragraph) separated by a dash. Thus, to print the first four messages, use
type 1-4
and to print all the messages from the current message to the last message, use
type .-$
A name is a user name. All of the user names given in the message list are collected
together and each message selected by other means is checked to make sure it was sent by one
of the named users. If the message consists entirely of user names, then every message sent by
one those users which is relevant (in the sense described earlier) is selected. Thus, to print
every message sent to you by "root," do
type root
As a shorthand notation, you can specify simply .. ·.. to get every relevant (same sense)
message. Thus,
type •
prints all undeleted messages.

delete •
deletes all undeleted messages, and
undelete •
undeletes all deleted messages.
S. Command line options
This section describes the alternate usages of Mail from the shell.
As you continue to receive system mail. you will most likely accumulate a large collection
of messages in the file mbox. In order to help you deal with this. Mail allows you to edit files
of messages by using the ·f flag. Specifically,
Mail - f filename
causes Mail to edit "filename" and
Mail-f
causes Mail to read "mbox" in your home directory. All of the Mail commands except
preserve are available to edit the messages. When you type the quit command. Mail will write
the updated file back.
Since you will usuaHy have a large number of messages stored in mbox. Mail will only
print out the first 18 message headers when editing more than 18 messages. To display the
other message headers, the he2ders command takes as an optional argument either + or - :0
move forward or back to the next or previous 18 message &rOUp.
If you send mail over a noisy phone line. you will notice that many of the garbage characters tum out to be the RUBOUT character, which causes Mail to abort the message. To deal with
this annoyance. you can invoke Mail with the ·i option to causes these garbage characters to be
ignored. Unfortunately. as you are typing in a line of text to a program. the little gnome which
gathers up the characters is instructed to throw them all away when a RL:BOUT is seen, For thiS
reason. Mail indicates that a RUBOUT has been received by echoing an @ to tell you that everything you had typed on that line has been thrown away.

~ail

Reference

~anual

12/Z/i9

6

6. Additional curnmands
This seaion describes additional Yfail commands available when receivini mail.
The next command goes to the next message and types it. If given a messaie list. next
goes to the first such message and types it. Thus.
type root
goes to tile next messaie sent by "root" and types it. The next command c:m be abbreviated
to simply a newline. which means that one can go to and type a messaie by simply givini its
message n~mber or one of tile magic characters
or "S". Thus.

"r" "."

prints tile current message and
4

prints message 4.
The - command goes to tile previous message and prints it. The - command may be
given a decimal ..lumber n as an argument. in which C3Se the nth previous message is gone to
and printed.
The saTe command alloW! you to save messagc:5 received from others on a file other than
mbox. Its syntax varies somewhat from tile other commands which accept a message list in that
the final word on the command line is taken to be the file on which to save the messages. The
namet1 messaies are appended to the file (which is created if it did not already exist) and are
marked as saved. Saved messages are not automaticaily saved in mbox at quit time. nor are
they seleaed by the next command described above. uniess explicitly specified. The save command providc:5 a facility for saving messages pertaining to a particujar subjea or from a panicular person in a special place.
The undelete command causes a message which had been deieted previously to re32in its
initial status. Only messa&es which are already deleted may be undeleted. This command may
be abbreviated to lJ.
The prese"e command takes a message list and maries each message therein so that it will
be saved in your system mailbox instead of being deleted or saved in mbox when you quit.
This is useful for saving messages of importance that you want to see again. or messages not
intended for you if you are sharing a login name.
Often. one wants to deal with a message by responding to its author right then and there.
The repJy command is usefuj for this PUl1'ose: it takes a message list and sends mail to the
authors of those messages. The message is cotlet::ed in the usual fashion by reading up ~o an
EOT. All of the tilde escapes described in seaion three will worle in reply. Additional1y. if
there are beader fieids in the message being replied to. this information is copied into the new
message. The reply command can be abbreviated to f.
In order to simply mail to a user inside of Mail.· the mail command is provided. This
sends mail in the manner descibed for the reply command above. except that the user supplies
a list of recipient togin names and distribution groups. All of the tilde escapes desc:ioet1 in section three will worle in mail. The mail command may be abbreviated to m.
In order to e&t individual messages using the text editor. the edit command is provided.
The edit command takes a list of message as described under the type command l11d processes
e.ac."l by writing it into the file Messagex '",here x is the message number being ~dited and !xe·
cuting the text e&tor on it. When you bave edited the message to your satjsfac:ion. write :he
message out and quit. upon ...,hic!l Yfail will iead the message bacx lnd iemove the fiie. Edit
may oe abbreviated to e.
It ls often useful to be able to invoice one of two editors. based on the type of terminai
~in~. To invoke a display oric:net1 :ditor. you on use the visual command. T:,e
ope:'3.tion of the visual command is otherwise identic::lJ to that of the edit command.

one is

Mail Reference Manual

1212/79

i

When ~aiJ is invoked to receive mail. it prints out the message header for each message.
In order to re~~lnt the headers for remaining messages (those which haven't been deleted), you
may type the headers command. Deleted messages do not appear in the listing, saved messages are flagged with a ... ., and preserved messages are flagged with a ··P."
The from command takes a list of messages and prints out the header lines for each one:
hence
from joe
is the easy way to display all the message headers from "joe."
The top command takes a message list and prints the first five lines of each addressed
message. It may be abbreviated to to.
The dt command deletes the current message and prints the next message. It is useful for
quickly reading and disposing of mail.

7. Summary of commands. e5apes, and options
This sections describes tersely all of the Mail c:"mmands. escapes. and options. For each
command. its most abbreviated form (in brackets) and a short description of the command is
given below.
First, message lists are computed by determining the set M which consists of all message
referenced explicitly or through ranges. Then, the set U is computed, which consists of all
messages sent by any of the user names specified. Finally, the message list is calculated by
finding the intersection of sets M and U.
Each Mail command is typed on a line by itself, and may take arguments following the
command word. The command need not be typed in its entirety - the first command which
matches the typed prefix is used. If the argument begins with a digit or special character, then
no space is required following the command letter, but otherwise the space is required. If a
Mail command does not take arguments, they may be specified. even though they are ignored.
For the commands which talee message lists as arguments. if no message list is given. then the
next message forward which satisfies the command's requirements is used. If there are no
messages forward of the current message, the search proceeds backwards, and if there are no
good messages at all. Mail types "No applicable messages" and aborts the command.
[-] Goes to the previous message and prints it out. If given a numeric argument
n, goes to the nth previous message and prints it. If there is no previous message.
it prints "Nonzero address required."
[-] Prints out the current message number. Takes no arguments.
?
[?] Prints out the file /usr/lib/Mail.help, which contains a brief summary of the
commands. Takes no arguments.
[!] Executes the UNIX Shell command which follows. Unlike other commands.
there does not need to be a space after the exclamation point.
raj With no arguments, prints out all currently-defined aliases. With one argualias
ment, prints out that alias. With more than one argument, adds the users named
in the second and later arguments to the alias named in the first argument.
[cl Changes the user's working directory to that specified, if given. If no directory
chdir
is given. then changes to the user's login directory.
[d] Takes a list of messages as argument and marks them all as deleted. Deleted
delete
messages will not be saved in mbox, nor will they be available for most other commands. Default messages may not be deleted already.
dp
[dp] Deletes the current message and prints the next message. If there is no next
message. types out .• At EOF."

-

Mail ReierenC!! Manual

8

dt

[dt] Same as tip.

edit

[e1 Takes a list of messages and points the text editor at each one in tum. On
return from the editor. tile message is re3d back in. The default message for edit
may not be saved or de!etea.
[ex1 Eff~.s an immediate rerum to the Sheil without modifying the user's system
mailbox. his mbox file. or his edit file in - C.
(f} Takes a list of messages and prints their message beaders. The default message is neither saved nor deleted.
[h] ListS the current range of headers, which is an 18 message group. If the" -+- ~,
argument is giv~ then the next 18 message group is printed. and if the .. - "
argument is given. the previous 18 message group is printed.

exit
from
haders

help

(heil A synonym for?

hoLd

(ho1 Takes a message list an~ marks each message therein to be saved in the
user's system mailbox instead of in moox. Does not override the delete command. The default message must not be deleted.

list

(l] The list command listS all of the availabLe user commands in the order that the
command proc::ssor sees them. It takes no arguments.

mail

(m1 Takes as argument login names and distribution group names and sends mail
to those people. TUde escapes work in mail.

next

(n] Goes to the next message in sequence and types it. If a message list is given.
then next goes to the first message in the message list.

preserve

(prel A synonym for hold.

print

(p1 Takes a message list and tn'es out each message on the user's terminaL The
default message must not be de!eted.

quit

(q] Terminates the Mail session. saving all undeleted. unsaved messages in the
user's mbox file in his login direaory, preserving all messages marlced with hold or
prese"e in his system mailbox. and removing all other messages from his system
mailbox. If mail bas arrived during the Mail session. the message "You have new
mail" is typed. If eXel:".lting while editing a mailbox file with the -f flag. then the
edit file is rewritten. A return to the Sheil is effec:ed. unless the rewrite of edit
file fails. in which case the user can escape wtth the exit command.

reply

(rl Takes a message list and sends mail to each message author just like the mail
command. The default message must oot be deleted.
(rl A synonym for reply.

respond

\

12/Z/79

save

(sI TaJces a message list and a filename and appends each message in tum to the
end of the file. The filename in quotes, foLlowed by the line count and charac~er
count is echoed on the user's terminaL The default message for saTe may not be
saved or deleted.

set

[seI With no arguments, prints all variable values. Otherwise. sets option. Arguments are of the form "option-value" or "option."

sheil

[shI Invoices an interactive version of the shell.

size

(sil TaJces a message list and prints out the size in charac:ers of each message.
The default message for size must not be deleted.

top

[toI TaJces a message list and pnntS the top so many lines. The number of iines
printed is controiled by the variable "toplines" and defaults to five.

type

[tl A synonym for print.

unalias

(unaI Takes 1 list of names defined by llias commands and disCJ.tds the remem·
bered groups of users. The group names no longer have any signulcnce.

~ai1

Reference

~anual

12/2179

9

[u] Takes a message list and marks each one as not being deleted. Each message
in the list must already be deleted. The default message must be deleted.
runs] Takes a list of option names and discards their remembered values; opposite
unset
of set.
[v J Takes a message list and invokes tbe display editor on each one.
visual
[wl A synonym for save.
write
[XJ A synonym for exit.
xit
Recall that tilde escapes are used when composing messages to perform special functions.
Tilde escapes are only recognized at the beginning of lines. The name "tilde escape" is some·
what of a misnomer since the actual escape character can be set by the option "escape."
Here is a summary of the tilde escapes:
-!command
Execute the indicated shell command, then return to the message.
-c name ...
Add the given names to the list of carbon copy recipients.
Read the file "dead.letter" from your home direc!ory into the message.
Invoke the text editor on the message collected so far. After the editing session is finished, you may continue appending text to the message.
Edit the message header fields by typing each one in tum and allowing the
user to append text to the end or modify the field by using the current terminal erase and kill characters.
-m' messages
Read the named messages into the message being sent. shifted right one tab.
If no messages are specified. read the current message.
Print out tbe message collected so far. prefaced by the message header fields.
Abort the message being sent, copying the message to "dead.letter" in your
home directory if "save" is set.
-r filename
Read the named file into the message.
-s string
Cause the named string to become the current subject field.
-t name ...
Add the given names to the direct recipient list.
Invoke an alternate editor (defined by the VISUAL option) on the message
collected so far. Usually. the alternate editor will be a visual editor. After
you quit the editor, you may resume appending text to the end of your message.
-w filename
Write the message onto the nained file.
~command
Pipe the message through the command as a filter. If the command gives no
output or terminates abnormally, retain the original text of the message.
-string
Insert the string of text in the message prefaced by a single -. If you have
changed the escape character. then you should double (hal character 10 order
to send it.
Options are controlled via the set and unset commands. Options may be either binary, in
which case it is only significant to see whether they are set or not, or string. in which case it's
actual value is of interest.
The binary options include the following:
undelete

append
ask

Causes messages saved in mbox to ,e appended to the end rather than
prepended.
Causes Mail to prompt you for the subject of each message you send. If you
respond with simply a newline. no subject field will be sent.

~ail Re!eren~

askcc
autoprint
ignore
metoo

quiet
save

The

EDITOR

SHELL
V1SUAL

record
top lines

Manual

1212179

10

Causes you to be prompted for additional C3I'bon copy recipients at the end of
each message. Responding with a newline indicates your satisfaction with the
current list.
Causes the delete command to behave like dp - thus, after deleting ames·
sage. the next one will be typed automatically.
Causes interrupt signals from your terminal to be ignored and echoed as @'s.
Usually, when a IfOUP is expanded that contains the sender. the sender is
removed from the expansion. Setting this option causes the sender to be
included in the group.
Suppresses the printing of the version when Mail is first invoked.
Causes the message coHected prior to a RUBOUT to be saved on the file
"dead.letter'9 in your home direaory on ree:ipt of the RUBOUT. Also causes
the message to be so saved in the same fashion for -q.
foHowing options have string values:
Pathname of the text editor to use in the edit command and -e escape. If not
defined.. then a default editor is used.
Pathname of the shell to use in the! command and the -! escape. A default
shell is used if this option is not defined.
Pathname of the text editor to use in the visual command and -v escape.
If defuled.. the first character of this option gives the C!laracter to use in the
place of - to denote esapes.
If defined. gives the pathname of the file used to r~ord aU outgoing mail. If
not defined. then outgoing mail is not so saved.
If defined. gives the number of lines of a message to be printed out with the
top command; nonnally, the first five lines are printed.

8. Conclusion
I would like to acknowledge the suggestions and criticisms of Eric Allman. Ken Arnold.
Bob Fabry, Richard Fateman, Bob KricUe. Doug Merritt. David Mosher, Eric Schmidt. Polly
Siegel. Michael Ubell. and especially Bill Joy, who sneezed nearby~ I caught the bug.

Re'ftZS~

1.1/20

Erir:P.A./JmQn
Eecronic:s Researe!'1 I..lbor.uory
University of CJJ.jfomia. Bericeiey
Berlceiey. California 94i20

This document describes in extremely terse form the futures oi the - me r!".ac:-o .,ac:Jcaie
for version seven !'4ROFr/TllOFr. Some familiarity is wumet1 with those proirarr...s.
5;le:ifially. the reader sbould understand breaks. fonts. pointSiz=s. tbe use and definition of
numoer ~ters and SuUles. how to define ml1C'05. and sc::tiini factors for ens. points. T' s
(vertic.! line s;ac:s). etC.
ror a more asuaJ introduc:tion :0 te:ct proc:ssinl using NROFF. refer to tile doc:-..unent
Writi", Pa~n WIth ."fRO" lain, -",~.
There are a llumber of macro parameters that
be adjustet1, rontS:nay be set to 3.
font rtumber only. La NROFF font 8 is unaerlined. and is set in bold font in neFF (although
font J. bold in nOFF. is net underiinet1 in NROFF). Font 0 is no font change: the font oi ttle
surrounding text is usett instead. ~otic:= that fonts 0 and 3 ue ";lSeudo-fontS"; that is. they
are simulalet1 by the mac::'0S- This me:ms that althougn it is l~ to set a font r~ister :0 zero
or eiant. it is !lot lep! to use tbe esa~e c!lancter form.. suc±1 as:

may

\f8
All distanc:= are in basic: units. so it is ne:1tiy always necessary to use
exam;le. the requCSl to set the ?ata~n indent to elant one~n S;lac::s is:

3.

salin, fac:tor. For

.m' pi 8n

and not
.M

pi 8

wltic:.~

would set the parail'3;Q indent to eight basic: unItS. or about 0.02 inc:!'1. Default .,anmeter values ~e given in braclcets in the remainder of tll1s doc'.lment.

Re~te~ and strin~ oi the form Sx may be used in ex;ressions but should' not ,e
c..,anieQ. ~ac::'Os of the form Sz.,erform some rune-jon (as desC:"lbed) lnd :nay oe redennea :0
c."tanie this fune-jon. This may ~ a sensItive o~eration; iOOK .1t the boay of ~ne angInal mac:-o
before chanlinl it.
AU names in -me: foilow a rilid namin, convention. The user :nay de:lne :lumoer rei1s• te:"S. Strin15. and maC'os• .,rovidet1 that slhe uses sinlie d'l:lr.1c::er u1)"er QSe :lames or aouole
c:ha.rac::er names consisting oi Iette~ and digitS. with at le:J.St one u;lper ::3.Se ~etler. In no c:1Se
should S;leci:lJ ;narac::::s be us~ in user~enned names.

On daisy whe:i ty;e I'rinlC~ in tweLve I'itc:."l. the -r.d flai :m ~ statet1 to make lines
de!':lull to one ~itltn inc!'1 (the normal spac::ni for a newline in tweive-pltc::'). This is normally

1

..,
teo mw.l rOt =sy r=Qcilicy. so ~: ~e£~t :s :0 !;ace oae sir..:. ~c:.
'!'his :.oc-~==taUCU ~ nO" =1 :a Iw:: ~. L9i9 mc1 a;~ii= to vnoa 1.1I:0 of

:~e

- 'l1e :nac:::lS.

1.

l'~;Ji:til2c

7he:sa ~ in used to o!l1in ~~~ The SWlc.art1 ~a a:%3C'O :s .;9: :.::a
om= are ail variantS tQ be USed tor 5;eCa1 i'~QSes..
The ant =:i1 to oae ot tile ~;lCinI ::w::cs ~en:= ia ~ sccn or t:e ..sh ~
(cie::ed. in che ~ex: session) i"mali:D tile :m.c:o ;=rec:::sscr. ....fxe: inic:i~oa ic :s :lot ;:CS3icle
to :J» m., ot:!Xe roUowin3 ~ .JC. .l4. .m.. or..:co Also.. Qe ~!l'== oi Qan~1 ~~
te:: '.hie w;ll ~"e 1 Jiocal d'ec 011 tile to~ ot tile ~e (c.ota.i2iy ;ale 1=it:1 U1c1 :'=c:.::
ana toote: ~J are :lC' -.ve'J aennec1 ma sZ1CWc1 be avoid=.
J;a
Be3in !e{~~umned ~il'Z;li1. C=:ue:inc ana ~ceriinil:c an au::ec1
it tileT ~ 011. tile roat is set te \4{~1 (11 :':e r~e si:: i.s set :c \n('P9
[lO~i. cc1 , \ra(QS ~ is U:1ser-.=1 o~-ore tile ~a (0":5" [:
nOF? Lv or OJv in :'(itOr::' c1e;ea~ oa :.evic:: r=ciutioul. T"..::
inae:u is r=et to \ra(Sl (01 ~ias \4(pa (01 imless tile ~a is imic::
,~Lay. (-=.al. At!aft tne a::n ~c lia= of ::e ~;lil ar=

oa

k~

cae Ice

=a

~

Uke J~ =X=~C ~ it

.;9

j:luts \4(~

(SuI 1JZ1ia

Q{

inc1e::t. "n:is is tJle san-

aarct~il~.

Inc1e:t=:1 ~b. ,..;r.n ~I ~ The ~0c1'1 of the toao..,;al ~.
~a is inc1e"!x.= I ~ (or \A

at the top of the program source 1• Also, compilations should bave the following
form:
cc [ flags] tne ..• -lcurses -itermlib
able~

1.3. Screen Updating
In order to update the screen optimally, it is necessary for the routines to
knoW' what the screen currently looks Wee and what the programmer wants it to
look Uke next. For this purpose, a data type (structure) named WINDOW is
detlned which describes a window image to the routines, including its starting
position on the screen (the (y, x) co-ordinates of the upper left hand corner) and
its size. One of these (called cu.rscr for c:u.rrrm.t screen) is a screen image or
what the terminal currenUy looks like. Another screen (called stclscr, tor sta.ndard screen) is proVided by default to make changes on.

-1-

-

".-·,ii~··~:...:

Screen Package

1

A Window is a pureLy inte~al representation. It is used to build and store a
potential image ot a portion of tb.e termjnal It doesn't bear any necessary relation to what is really on tb.e terminal screen. It is more like an array ot characten on which to make cha.c.ges.
When one has a window which describes what some part the terminal should
look like, the routine refnsh{} (or wrefrash() if the window is not stdsc:-r) is
called. RSfrash{} makes the terminal. in the area covered by the windoW', look
like that wiIldow. Note. there tore. that chaniiIlg somet.bing on a window does not
eha:n.gfltha t8'7"T71.inaL. Actual updates to the term;na l screen are made oo1y by
call.i.n.g Nfresh() or wnfrash(). This allows the programmer to maintain several
di!!erent ideas ot what a portion ot the terminal screen should look like. Also,
changes can be made to windoW'S in any order, Without regard to motion
emciency. Then. at Will, the programmer can etfectively say "make it look like
this." a.n.ci let the package worry about the best way to do this.
1.4. N<:Imjng CollYentions
As hinted above, the routines can u.se several windows. but two are automat·
ically given: ~C'T', which knows wbat the terminal looks like, and std.sc:-r, wbich
13 what the pr::lgrammer want.! the terminal to look like next. The u.ser should
never really access ~cr directly. Changes should be made to the appropriate
screen, and then the routine rafresh() (or wrefrflsh()) should be called.
:Many tunctio~ are set up to deal with std:ser as a detault screen. For e:-

ample, to add a character to stdser, one ca.l.ls ad.dJ::h.() With the desired character. I! a ciitferent Window is to be u:sed, the rtlutine 'Wa.ddt:h.() (for lfindowSl'eci.fi.c a.d.d.t!hQ) is provided2 • 'I'hi:s convention of prepend.in.g tunction names
ytth a "Y' when they are to be applied to specidc windows is con.s:istent. The
only r~utines which do n.ot do tbi,s are those to which a window must always be
specided.
In order to Clove the ourrent (y, x) co-ordinates rr~m oc.e point to another,
theroutin.es maveO and 'W'I'1'UnJe() are provided. However, it is otten deSirable to
~t move and then perform some 110 operatiOn. In order to avoid ciumsyc.ess.
most I/O routines can bo preceded by the pretbc "my" and the desired (y, x)
oo-ordinates then can be added to the argument.! to the function. For exampie.
the calli.
move(y, x):
addch(ch);
can be replaced by
mvaddch{y, x. ch):
and.

Ytnove(Yin. y, x}:
waddch(wt::I.. ell);
can be replaced by
mvwaddch.(win. y, x. ch):
Nota that the windoW' deSCription pointer ('UI'i7t) comes betore the added (y. x)
co-ordinat.es. It such. pOinten are need, they ~ always the ~st paraceters
passed.
c:bad. <.stdio-h> in it. !t ~ t.:1e:-e!are :-edu:da:at (bu~ ~e:IS) tar' '"..!2e ,l"Ogrammer ~o do it. too.
• Ac:tually, ~) is ~ally & "id.~·· :n&c::z"Q wi~ argume::u. u are m~ ot~. "!".cc:::'czu'"

wme.: d.al with ~ sa & detault.

"-2-

Screen Package
2. Variables

Many variables which are used to describe the terminal environment are
available to the programmer. They are:
type
name
description
current version of the screen (terminal
curser
WINDOW •
screen).
standard screen. Most updates are usually
stdscr
WINDOW •
done hero.
default terminal type if type cannot be deterDef_term
char •
mined
bool
use the terminal specification in De!_term. as
terminal, irrelevant ot real terminal type
ttytype
full
nnmc of the current terminal.
char •
int
number ot lines on the terminal
LINES
eOLS
number of columns on the terminal
int
int
ERR
error dag returned by routines on a fall.
error dag returned by routines when things go
OK
int
right.
o

There are also several "#cletlne" constants and types which are of general
usetulness:
reg
bool
TRUE

FALSE

storage class "register" (e.g., reg i:n.t i:)
boolean type, actually a "char'· (e.g., boot dDneit;)
boolean "true" dag (1).
boolean "false" t1ag (0).

3. Usqe

This is a description of how to actually use the screen package. In it. we assume all updatmg. reading. etc. is applied to stdsC'l'. All instructions will work
on any window, with changing the Nnction name and parameters as mentioned
above.
3.1. Sb·rtirg:&p

In order to u:Je the screen package, the routines must know about terminal
characteristics, and the space fCi~ cunC'l" and stdsC'l' must be allocated. These
functions are performed by i:n:i.tsC'l'(). Since it must allocate space for the windows, it can ov8~ow core when attempting to do so. On this rather rare occaSion. 'i:n:i.lscT'(} returm ERR. InitsC1"(} must tlJ:wcp be called before any of the
routines which atfect windows are used. If it is not, the program will core dump
as soon as either c:u:rsC1" or stdsC'l' are referenced. However, it is usually best to
wait to call it untU atter you are sure you will need it, like after checkini tor
startup errors. Terminal status changing routines like nJ.() and crmode() should
also be called atter Vt:itSC1"().
Now that the screen windows bave been allocated, you can set them up tor
the run. If you want to, say, allow the Window to scroll, use scrollo1c(). If you
'Want the cursor to be lett atter the last change, use lIIaveolc(). If this isn't done.
refrash() will move the cursor to the window's current (y, x) co-ordinates after
updating it. New windows of your own can be created, too, by using the functions 1I.fMJJ'tIJ'iz1() and sub1ui:n.(). Delwi:n.() will allow you to get rid of old windows.
If you wish to change the otncial size of the terminal by hand, just set the variables LINES and COLS to be what you want, and then call in:i.lsC1"(). This is best
done betore, but can be done either before or atter, the first call to i:n:itsC'l"(), as
it will. always delete any existing stdscr and/or cu.rscr before creating llew oc.es._

.- s- ; -

°

;.~~:.2--~:.~ :~~1X};:{~~

Screen Package
3.2. The Nitty'-Gritty
3.2.1. Output.
Now that we have set tb.iJ:::lgs up. we will ''''ant to actually update the ter:ni~
o.a.l. The basic fw:::.c tioIlS used to cl:a.Ili e -",hat will goon a wiIldow are a.dd.: h () an::.
maue (). ~lt() adds a character at t.b.e current (y. x) cO-Qr-dlnates. ret'..l.~g
ER.~ it it would cause the wiIlc.ow to illegally scroll. Le .. prin~ a character L=.
the lower ng.b.t-hand corner ot a te.r:o.inal wbic!:l automatically scrolls L! scr:iliI:.g
is not allowed. lJerue(} ch.a.nges the curTeIlt (y. x) c~rdinates to whatever you
want them to be. It returns ERR it you try to move o~ the window when scroUiI:..g
is IlOt allowed. As mentioned above. you can combine the t.."o into m.va~h() to
do both thiJ::lis ill one teU swoop.
The other output tlmctioc.s. such as a.dd.sf:7-() and. pri:rttwO. all call a.d.dl:l1.()
to add characters t() the wtnciow.
Attar you !lave put on the wi.ndow what you want. ther-e. when you want t!::le
porJ.on ot the terminal covered by the window to be made to look 11ke It. you
must call "!resh(). In order to optil::li%e ~d.ing cb.a..Ilges. re!'r-esh() assum.es
that any part ot the WindoW' not cbanged since the last reJresh() ot that window
~ not been cb.a.D.ged on the term;nal. i.e .. that you have not refreshed a por:ioc.
ot the ter.:c.inal With an overlapping iVindow. It ~ is not the case. the routine
to"U.J:hwi:n.() is prOVided to make it look like the eIltire 'I'rtIldow ha:! been c~ged.
thus ma.ki.Ilg refresh() check the ·..hole subsection ot the terminal (or- cbanges.
3.2.2. Input.
Input is esseIltially a mirror image ot output. The complementary !uz:.ctioc.
to o.dd.t:h() 13 g~tt:!t() whicll. it echo i~ set. will call a.ti.d.t:h() to echo the character.
SInce the sc:oeen package need~ to bew what is on the ter.ninal at all times. it
characters are to be echoed. the tty must be in raw or cbreak mode. U it Ls not.
g8tt:h() sets it to be r-aw. and then M!ads ill thc character.
3.2.3. lliscellimeou:s
All sort3 ot tun tunctiOIl3 emb tor maintai.D..i.D.g and chaogillg il::.!or::le.ticc.
about the windows. F~r the most part. the descMptioc.s in secti.on 5.4. should
sutnce.
3. 3. F!n.i:dting up
In order to do certain optiI::li2atioIlS. a.D.d. on some terminals. to •... ork at all.
some tb.iIl.g3 Clust be done betore the SCM!en routi.D.es start up. These f-cct:'or-..2
are pertor:::led in gdttmtJd.a() and SQtt:rrm.(). wb..i.cb. are called by i:nitsc7'(). I=.
order to clean up atter the routi:les. the routine rnd:wi:n.() is pr-ovtded. :t restores tty modes to .,.,bat they ""e~ when 'i:1:i.tscr() was first called. Tht.:.S. a:..y. time atter the call to i.lli.tscr. rru:i:wi'n.O should be called betore exiti.og.
~

Canor Motion Optimization: Standing Alone
It is possible t,Q use the cursor- optimi%ation (unctiOll.! ot tbi~ sc:oeec. package Yithout the overhead and additional si%e of the sc:o~et1. updat~ ~UI:.c':.:Cc.s.
The sc:oeea updating runctioml are designed for uses whe:oe parts ot the 9c:'eec.
are c!:lar..ged. but tlle overall i:clage ~r:laiIlS t!::le same. This includes 3\:.C:::' ?r~ira.I:O.S as eye and Vi~. Cer-tai.D. ot.!:ler pr-ograms will One:. it coc.side:oaoiy ~~c~~
to use these tUllctiollS in this manner wi.thout considerable 1.ln!'!ecessar:.r pr:-

.--. ".-:-..
•. _ . -

. ' •• _ .

.'

...
J.

I

Screen Package
gram overhead. For such applications. such as some "CTt hacks .. 4 and optimizing cat(1)-type programs. all that is needed is the motion optimizations. This.
therefore. is a description ot what some ot what goes on at the lower levels of
this screen package. The descriptions assume a certain amount ot familiarity
with programming problems and some ftner pnints or C. None ot it is terrlbiy
dit!icult. but you should be forewarned.
4.1. Terminal In!ormatioD.
In order to usc a terminal's features to the best of a program's abilities, it
must drst know what they ares. The letc/termcap database describes these.
but a certain amount ot decoding is necessary. and there are. of course, both
e1!lcient and inetficient ways ot reading them in. The algorithm that the use:;: is
taken from vi and is hideously emcient. It reads them in a tight loop into a set
of variables whose names are two uppercase letters with some mnemonic value.
For example. HO isa string which moves the cursor to the "home" positione. As
there are two types of variables involving ttys. there are two routines. The first.
gettmod.sz(), sets some variables based upon the tty modes accessed by gtty(2)
and stty(2}. The second. setterm.(), a larger task by reading in the descriptions
trom the letc/termcnp database. This is the way these :'outines are used by -£n.-

iUc-r():
it (isatty(O» t
gettmodeO:
it (sp=getenv("TER.\{"»
setterm(sp);

J

else

setterm(Def _ term);
~uts(n):
~uts(VS);

IsaityO checks to see it file deSCriptor 0 is a terminal? If it is. gettmod£ ()
sets the terminal description modes from a gtty(2}. Geten.v() is then cz.lled to
get the oa.-c.r c~ the terminnl, and tha ... valu~ (if there is I'n",) ;.s passed ~" s,.tterm.(). which reads in the variables trom letc/termcap associated With that
terminal. (Gfltlln.V() returns a pointer to a string containing ".he name of the terminal. which we save in the character pOinter .!p.) If isaity() returns ralse. the
default terminal De/_term. is used. The TI and VS sequences initialize the terminal (..pu.ts() is a macro which uses tputs() (see termcap(3}) to put out a string).
4.2. Movement Optimi2a.tions, or, Getting Over Yonder
Now that we have all this useful information. it would be nice to do seme4 Graphics prosrams desi&ned to run em charac:+-er-oriemed terminals. I could :wne :n.a:ry. but
they come and go, so the llst would be quickly out of dat.e. Recently. there have been progra.ms suc.il
as racket. and CUJL
5 If this comes as any surprise to you, there's this tower' in Paris they're +b;nking of junki.,g ~!lar.
I CaD let. you haye tar a sonl.

e These names are identical to those variables used in the letc/termcap
database to describe each capability. See Appendix A tor a complete list of
those read. and termcap(5) for a run deSCription.
, Isa#rl() is de1!ned in the default. C llbrary tunctiOD rout.:ines. It. does a &ttJ(2) on the de3c~pr.or
and chec.k:l the retun1 YIIlu••
~-.

.'
•

-5-

_

:

~

_.

~.
J

I

..

...~. '.
.......
'" ....-' - .....

;. ~;

...

"!4

~..

;..~
'

't...

.'

:-

....

'.
-

Screen Package

r

thilli wi.t.b. its. r=-e mo:::t d.i.Ocult t""jl"'g to do proper-Iy is ::lotioc. ~?t=-=i.zat:o::..
When you coo.side:- boow ::la.ny ciiee:-~nt !eat:.l.r~s di~er~::.t ter-:n.l!:.al.s =.ave (ta:=s.
ba.cktabs. l:.On-~~st:"".lctive space, ,b.ot:J.e sec..ue!:lces, absolute tabs ...... ) yolo! ca=.
see that deci~g how to get from b.e!"e to t!:.ere can be a dec~c.ec.ly ncc.-tr-:V'1.al
task. The edit::r vi uses many ot these features. a..r:.c. the routi!:.es it uses ~:: :ic
tms take up ::la.ny pages ot code. Fortw::.ately, I was abLe to liberate t!:.e= wlt!:.
the author-'s per-::UssioD.. a.nd use them he:-e.
AIter using gettm..tJde() a.nd setterm.() to get the ter=.itlal descript:o::.s. t=.e
function Tff.7JC"..J:!"() deals W1tll. this task. It usage is simple: you simply teil :t wi:.e!"e
you are noW' and where you wa.nt to iO. For example
mvcur(O, 0. UNES/2. COLS/2)
would move the cursor ~m the home positioc. (0, 0) to the t:liddle ot the scree::..
If you wish to !oree absolu.te a.d~ssiD.g. you can use the functioc. tgoto (; tr~~
the termlib(7) routines. or you can tell Tff.1JC'W"() that you are impossl'::Ly ~a:
a.way, like Cleveland. For exa!:lole. to absolutely address the lowe:- Left ::'a=.d
corner ot the screen from aIlJi"here just claim that you are in the upper r-.g::.t
band cor:le r:
mvcur(O, COLS-l. LlNES-l. 0)
5. The Functions
In the !cllcwU::l.g detmiticc.:s. "t'. meaIl!S that the "rw::.cticn" is really a
"#defule" mac:"o wtt.ll arguce!lts. This means that it will !lot show 'J.p i:. stack
traces in the debugger. cr. in the case of such h:..tlctioc.s as a.::idcJt(). it ;vi.2.l sh.ow
up as it's "".' counterpart. The arguments are give!l to show the ot"cie:- a::..c. type
ct eac::" Their c..a.cles are Coct manc.atory. just suggestive.
5.1. Output functioc.:J
a.ddt:h( ch) l'
char

ch;

'\ri.dde !l(lriI.. ~h)
WINDOW ~;
c h.t::r:r

cli.o'

Add the character ch CIl the wtIldow at t:'e c,;~re!lt (y. x) co-or~:~z :es. T:::.ls
r9tur:l.S ERR 11 it would cause the scree::. to sc:"oll illegally.
add.str{:str) r
~tr;

cJu:zr

wadr:Utr(win. str}
WINDOW ~;
~tr;

cha:r

Add the sL........... g poiIlted to by str co. the Wi..tldcw at the cur."e::.~ Cy x) ==ordinates. !=.is ret'..lr~S ERR it It ·,.,ocid cause t!le sc:-ee!l to sc!"oU ilega..:.:::
I.e. tb.i3 case. it '.-rill put on as :nuch ~ it can.

• AA::-.wly. ~~ ::~ ':e ~=oconaUy :"~~ iu.3t ~o let ~. =or:::u~on. :-=~:.:s '..:NAl.::r :I~:' ·':-.le.
:! you ~.ye ~e ,oc:~~ ~. of 4 r.:::.:r..at.

~cweve:".

-s-

:

Screen Package

box(win.. vert, hor}
WINDOW ~;
char
vert, hor,'
Draws a box around the Window using vert as the character for drawing the
vertical sides, and Mr for drawing the horizontal lines. If scrolling is not allowed, and the window encompasses the lower right-hand corner of the terminal, the corners are lett blank to avoid a scroll.
clearO f
yclenr(win)
WINDOW -win;
Resets the entire window to blanks. It 'Win is a screen, this sets the clear
dag, which. Will cause a clear-screen sequence to be sent OD. the next r?.fresh() call.
clenrok(scr, booU) f
WINDOW ~r:
boot
boot/:
Sets the clear dag ~or the screen scr. If boolf is TRUE, this will. force a
clear-!creen to be printed on the next "fresn(} or wrefresh{}, or stop it
trom doing so 11 booLf is FALSE. This only works on screens, and. unlike
claa.r(}, docs not alter the contents ot the screen. It sr::r is CUTSr::r, the n.ext
refresh() call will cause a clear-screen, even if the Window passed to refresh(} is not a screen.

clrt.obotO f
'W'clrtobot(mn)
WINDOW "tum:
Wipes the window clear (rom the current (y, x) co-ordinates tc the bottom,
This does not torce a clear-screen sequence OD. the next refresh under any
cir~ums~i'r,ces. 'l'h.: 'j h1.S ~n as!lociat:.e-i ,. ~.,.' '!ommao'="..
• . clrtoeolO f

...

yc!.rtoeol( win)
WINDOW ~,'
Wipes the window clear from the current (Y', x) co-ordinates to the en.d or
the line. This has no associated u mv" commend.

..

-- .

ereeOf
werue(win)
WINDOW -r.um. ..
Er~es the Window to blanks without setting the clear ftag. This is analagous
to c laa:r 0, except that it never causes a clear-screen sequence to oe generated on a refresh(). This h.as no associated 'Omv'· command.

..... -

-7-

.. . ..

........ ......-.
,

.

Screen Package
move(y. x) t
1/.::

W

wmove(win. y. %)
WINDOW ewin.:
W
1/.::
Cb..ange the cur:-erlt (y. x) co-ordinates of t!:le wi.ndow to (Y. =). T'-wis !"etu:-...s
ERR i1 it would cause the screerl to scroll illegally.

overlay(mnl. mn.2}
WINDOW -win 1. ewin2;
Overlay 1.U'i:nl OIl tui.n2. The cOIlterlts of wi:n.1. insofar as they dt, are pLaced
OIl wi'n.2 at. their starting (y. x) co-ordinates. This is done non-destr".J.ctlvely.
i.e., blaI:lks OIl wi:n.1 leave the conterlts of the space on tJJi:t.2 untouched.
overwrite(winl. win2}
.,,1N DO W -win 1. er.ui:n.2;
Ovenrrite 1.U'i:nl OIl. u.i.1t2. The COrlterlts of 'tui:n.l. insofar as they ftt. are
placed OIl 1.Ui3t.2 at their start1Ilg (y. x) co-ordinates. This is dOrle dest:--..:.ctively. Le .• blank.3 OIl uri:n.l become blank 00. wi:n.2.
priIltw(!mt. argl. arg2•.•• )
c~
~t; .
Yprintw(win. fin t. argl. arg2•..• )

WINDOW

~n.;

chr:::r

~t:

Performs a pri:n.t!() on the wi.ndow starting at the current (y. x) coordinates. It uses a.::J.d.srr() to add the string on the w1rldow. It is otten
adVisabLe to use the deld. Width optiOo.s ot pri:n.tl() to avoid. leaVin.g things on
th.e Wi.nd.ow trom earlier calls. This returns ERR Lt it would cause the sc:ee:l
to scrt)ll illegally.
re!reshO t

wretresh(win)
WIN DO '1f -win;
Syncbroc.i2e the termitl.al screen With the desired ·o'riD.dow. II the Wi.l:c.ow ~s
not a screet:l. ool.y tllat part covered by it is updat.ed. This ret:.J.r!lS ERR i! it
would cau:se the screen to scroll illegally. In tb.i..s case. it will update wi:.atever it can Withou.t caWling the scroll.
standoutO l'
lr.Ibndout(win)
iY!N DO W "'tL.'i.7t;
standendO t
lr.Itandend(win )

if IN DO W -.uin.;

-a-

Screen Package
Start and stop puttillg characters in standout mode sta:n.d.01d 0 causes any
characters added to the window to be put in standout mode OIl. the terrr.J.nal
(if it has that capability). sta:nd.end.(} stops this. The sequences SO and SE
(or US and UE if they are not dedned) are used (see Appendix A).
5.2. Input Functions

crmodeO t
nocrmodeO t
Set or unset the terminal to/from cbreak mode.
echoOt
n08choO t
Sets the terminal to echo or not echo characters.
get.ch.() t

wgetch(win)
WINDOW -win.:
Gets a character from the terminal and (if necessary) echos it on the window. This returns ERR if it would cause the screen to scroll illegally. Otherwise. the character gotten is returned. If no.eha has been set. then the
window is lett unaltered. In order to retain control of the terminal, it is
necessary to have ono of noflCha, cbreak, or rrrwm.ad.e set. If you do Ilot set
one. whatever routine you call to read characten will set cbreaJ: tor you,
and then reset to the original mode when dnished.
getstr(str) t
~:

eha:r

''I ctsll (wiD• .J;"r)

WINDOW
char

-wi:rt.;
"!str,.

Get a string through the window and put it in the location pointed to by str,
which is assumed to be large enough to handle it. It sets tty modes it
necessary. and then calls getch.{} (or wgeteh('U1i:n)) to get the characters
needed to tlll. in the string until a newline or EOF is encountered. This returns ERR if it would cause the screen to scroll illegally.

rawOt
norawO t
Set or unset the terminal to/from raW' mode. On version 7 tnf1XI' this also
turns of newline mapping (see nl(}).

·'D'Jm[is. trademark at Sell Laboratories.

...

-9-

'

. ......,:..
~

. . . 't

.. ..... ";.' ..:...

.'

"':

',

.

'

., ..
....- .. -e.~.- -,

_..............

:.~

~.

•• " •

.,'

~

.

'.
-":

...-.:-

Screen Package
scan'W(!m t. arg 1. arg2. ••• )
cha:r
~::
1'r'SeaIlw("frill.

tm t.

WINDOW

eu.-in:

ch.trr

~t:

a.rg 1. arg ~ .•• )

Pedor::n a sc::n./() tJ:.reugh the windoW' us~ 1m!. It does tbis usi..Il..g cct:.secutive gQtchO's Cor 'W;lltch("W'i.71.)'s). Tbis retur..s ERR i! it would ca~e :::'e
screen to scroll illegally.

5.3. lliscellClIllCoWl Functions
dehrin(win)
WINDOW "Win;
Deletes tb.e wtlldow from emtee.ce. All resources ~ !reed for tut"~e use
by caJlacO. cfrnO. etc. I! a window 1:.a.s a S'Ub~O allocated Window j..r::.!uc.e
ot it. deleting the outer window the subwindow is !lot ~ected. eve!l tb.c~'::'
tl::Ws doe~ invalidate it. Therefore. subwindow~ should be deleted. ~e!ore
their outer '1'Ii:l.dows are.
ench:i.nO
FUlish up wi..ndo'W routines before exit. Tbi:J ~stores the ter ....lmal ~o the
state it was before in.:i.t.se-rO (or gllt!m.od2() aIld set:e-r-mO) 'Was called. It
should always be called before eXiting. It does o.ot eXit. This is espec:al1:r
usetul for resetting tty stats whee. trapping r"'..lbouts V1a rignoJ.().

letyx{Yin. y, %) l'
WIN DO ;Y -u.in.;
W

y.=:
Puts t.b.e cur:-ee.t (y. x) co-ordinates ot ~ ill ~b.e variables 11 and:. 5i..::::e it
is a cacro. not a Nnction. you do o.ot pass the address o~ y and :.

illchO r
winch ("frill) l'

WINDOW "Win;
Retllr'nS tb.e character at the current (y. x) co-;:,rdinates on the give=. Wi:::.doW'. '!'his does not make a.c.y cb.anges to the Window. TIll..5 has e.o assoc~a:ed
"mv" command.

imucrQ
Initialize the screee. routines. ~ must be called before any of t::'e 3c!"e~::.
routines are used. It initializes. t!le ter:mnal-type data and sue::'" a::.c.
Wlthout it. lloe.e of tb.e routines call operate. It stanc.a!"d mput ~s ilot a::::
it sets tb.e soecukatioc.s to the tel"=llnai wnose ila..r:J.e is '::)omte::' := ": ...
Del _tn-m. (iIlit!aly "c.umo"). It ~h.e booLean .TJy_!a-rm. ~s trJ.e-. E-ef _:ern
alway~ used.

.s

leave1:)k(win. bool1) t
WINDOW -..z..-i:1t,.
booL

bool/,'

-10-

Screen Package
Sets the boolean ftag tor leaving the cursor after the last change. It bool! is
TRUE, the cursor will be left after the last update on the terminal. and the
current (y, x) co-ordinates for 'U.Iin. Will be changed accordingly. I1 it is
FALSE, it will be moved to the current (y, x) co-ordinates. This ftag (initialy
FALSE) retains its value until changed by the user.
longname(termbuf. name}

ch.a:r

-name;
Fills in nama with the long (!ull) name ot the terminal described by the
termcap entry in term.buf. It is generally ot little use. but is nice for telling
~he user in a readable format what terminal we think he has. This is available in the global Variable ttytype. Term.buf is usually set via the termlib
routine tgetsnt (J.
~erm.bu.f,

mvwin(win, y, x)
WINDOW -win;
y,

i:nt

=:

Move the position ot the window win from its current starting coordinates
to (y, z(J). It it does not dt at that position, mvwi:n(J returns ERR and does
not change anytb.i.ng

WINDOW "tle1n'1in(lines, eols. ~ginJ. be!gin_x)
lins:r, c:oi.s, begin_y, bagin_=:
Create a new window with linas lines and c:oi.s columns starting at position
(bag-m._y, bagi11._=). If either lines or cols is 0 (zero). that dimensioIl will be
set to (LINES - beg7:n._y) or (COLS - bagin_z) respectively. Thu.s. to get a
new window of dimensions LINES x COLS, use nB1JJ'UJin(O, 0, 0, 0).

int

DIOt
nonlO t
Set or UllSf!t the te~itl.al t"lfrom nl mode. i.e., start/stop the system from
mapping <.mrrt1RN> to . If the mapping is Ilot dune. refresh()
can do more optil:l:ili:ation. so it is recommeuded. but not requir~d. to turn.
it of!.
scroll(lrin)
WINDOW -win;
Scroll the window upward one line. This is normally not used by the user .
.

- -...

scrollok(win, boaU) t
WINDOW -wi:n;
booL
ooolf;
Set the scroll ftag for the given Window. If boolf is FALSE, scrolling is not allowed. This is its default setting.
touchlrin(win}
WINDOW -win;
Make it appear that the every location on the window has been changed.
This is only needed tor refreshes with overlapping Windows.

.,'.

-11-

,,':'.

....

-

,.
-:.... :-..
.....
- ,- -....
.........
'

..........

-~

•••: •• , ...

~

:

.....

-'

\#

-....

~."

'

• •

Screen Package

I.

WIN DO W -SUbwin(-wi.n. line:s. ctlls. beginJ. begin_x)
WINDOW ~.

w

Li:n.as. coLs. begi'n.-,/, bfZg-tn_=:

Create a new wi..Il.do'W with linas Unes an:' eols coiumns starti::.g at ?osi.~~on
(bQgi:n.-,/, beg-m._=) i1z. thQ m:~ of tJtQ 'Window win.. 1'b.i.s means :hat. any
cl:l.ange made to either Window in the arsa coversci by the subw'indow ''''1ll ':le
made on both. Windows. begirt_yo OQg-tn_= aZ"1! spec~ed relative to the
overall screeo.. not the relative (0. 0) of 'Win.. It either lmes or eoLs is a
(zero). that dimeosion will be set to (UNES - oegt.1t_y) or (COLS - OQg-in_=)
respectively.

unctri( c:h} l'
eha:t-

eh.;
~ is actually a debug tunction for the llbI"ary. but it is of general usefulness. It ret~ a strilli which is a representation of eh.. ControL characten become their lower-case equivalents preceded by a "_". Other letters
stay just as they are. To use 'U.7tCtT!O. you must ha''-e #include 
in your die.

5.4. Det.ail3

gettmodeO
gets the tty stats. TIlis is nOI"mally called by i7t:i.tse'1"().

-

mvC":ll'(wty. last:x. newy, lleW%}
i.n.t

wt=.

1't.a'W'!l. 1't.nu%.Moves the terminal's cunOI" frcm (l.a.sty, ltlSt.:) to (ne"ll.J'!{, new:) in an. appI"oximation ot optimal tashion. This routine uses the [unctions berrowed
trom e% ver3ion 2.6. It is possible to use this optimization without the
benefit of the screen routines. With the screen routin~!. this should a.ot ~e
called by the user. matJe () and refresh.O should be used to move the ~ursor
position. so that. the routines lalow what' 3 going OIl.
ltJsty,

savettyQ1'
~etty() l'

Sa:uett:y() saves the current tty characteristic aags. Resetty() restores
them to wl:lat strJJetty() stored. These mnctioc.s are ?e!'for:ned automaucaJ.ly by 'i.ni.ts::-r-O and m.d:wi:rr.O.

setterm(name)
chtrr

~,'

Set the terminal characteristics to be these ot the ter.:linal caned 1UJ.me.
'!"l:lis is called by i:n:i.tsC7"(), so the user usually need not botller W1tb. ~t. u:tie5s
they i"Iish to use just the cunor motioo optimizat:oIl!!.

-.
-12-

- -. ".

.

",

--:

....

AppendizA
1. Capabilities from termcap
1.1. Disclaimer
The description of terminals is a dU!icult business, and we only atte::::.pt to
summarize thp capabilities here: for a full description see the paper descr:bing
termcap.
1.2. Overview
Capabilities trom termcap are ot three kinds: string valued options, numeric valued options. and boolean options. The string valued options are the most
complicated. since they may include padding information. which we describe
new.
Intelligent terminals otten require padding on intelligent operations at high
(and sometimes even low) speed. This is specified by a number before the string
in the capability, and has meaning for the capabilities which have a P at the
front ot their comment. This normally is a number ot milliseconds to pad the
operation. In the current system which has no true programmable delays. we do
this by sending a sequence of pad characters (normally nulls, but can be
changed (specified by PC». In some cases, the pad is better computed as some
number ot milllseconds times the number ot atrected lines (to the bottom ot the
screen usually, except when terminals have insert modes which will shift several
Unes.) This is specified as. e.g .• 12·. betore the capability, to say 12 milliseconds
per atrected whatever (currenUy always Une). Capabilities where this makes
sense say p •.

1.3. Variables Set By settermO
variables set by setterm()
Type
char
bool
char
bo"l
char
bool
char
char
char
char
char
char
char
char
char
bool
char
char
bool
char
bool
char

Name
•

AL

Pad

p.

•

AM
BC
BS

•

BT

P

CA
CD

p.

•
•
•
•
•
•
•
•
•
•
•
•
•

cllar •

CE

CL
CM
DC
DL
DM
DO
ED
EO
EI
HO
HZ
IC
IN

1M
IP

P

p.

P

p.
p.

P

p.

Description
Add new blank Line
Automatic Margins
Back Cursor movement
Back:Space works
Back Tab
Cursor Addressable
Clear to end ot Displ.ay
Clear to End ot line
CLear screen
Cursor Motion
Delete Character
Delete Line sequence.
Delete Mode (enter)
DOwn line sequence
End Delete mode
can Erase Overstrikes With • •
End Insert mode
HOme cursor
HaZeltiIle ... braindamage
Insert Character
Insert-Null blessing
enter Insert Mode (IC usually set. too)
Pad alter char lruserted using IM+IE

-13-

AppendU:A
variables set by settsrm.()
Type

char •
char •
bool
bool
char •
bool
char
char •
char •
char •
char •
char •
char •
char •
char •
bool
char •
char •
char •
char •
char •
bool
Names

pescription
LL
quick to Last Line, colw:::m a
MA
ctrl character MAp for cmd mode
can 1{ove in Insert mode
.
Ml
NC
No Cr: '\r sends \r\Il theo. eats \n
ND
Non-Destructive spa.ce
OS
OverStrike works
PC
Pa.d Character
Standout End (may leave space)
SE
p
SF
ScroU Forwards
SO
Stand Out begin (may leave space)
p
SR
ScRoU backwards
p
TA
TAb (IlQt "'I or with paddil:lg)
Terminal address ec.able Ending sequeo.ce
TE
Terminal address enable lIlitiali%atlon
TI
Underline Eo.~ sequence
UE
Uo.derLi.nio.g works eveo. though !OS
UL
UPline
UP
Underline Starting sequence 10
US
VB
Visible EeU
Visual End sequec.ce
"IE
'IS
Visual Start sequence
a Newline gets eate:. after wra.p
XN
starting with X are reserved for severely nauseous glitches

1.4. Variables. Set By gettmodeO
Variables set by gettmade ()
type
bool
bool
bool

NONL
GT
U?P:'RC" ASE

description
Term can't hack linelceds doing a CR
Gtty indicates Tabs
T-rmi.J:lrU ,;enerates ('"-'y upre!-Ca~e lettl!M

"
-l~-

Appendix B

1.
The wmDOlV structure

The 'flNDOW structure is defined as follows:
# define
WINDOW struct _ win_st
struct _win_st 1
short

_maxy, _maxx:

short

_begy, _begx:
_flags;
_clear:
_leave:
_scroll;
•• J:
• firstcb.;
• -lastch'

short
bool
bool
bool
char

J:

short
short

-

.

# define
# define

_SUBWIN
_ENDLINE

# define

_SCROU.WIN
_STANDOUT

/I define
# define

)

_cury,_curx:

short

01
02
04
010
0200

_Ft1LL'W1N

_C1J.ry and _C1J.r: are the current (y, x) co-or-dinates for- the window. New characters added to the screen are added at this point. _mazy and _ma.:z::: ar-e the
maximum values allowed for (_C1J.ry, _C1J.r:). _begy and _beg;:; ar-e the starting
(y, x) co-ordinates on the ter-minal for- the window, i.e .• the window's home.
_cv:ry, _eur:. _m.tJ....-y. and _m.a= are measured r-elative to (_begy. _beg;:;), not
the terminal's home.
_clear tells it a clear-scr-een sequence is to be generated on the next Tefresh{} call. This is ocly meaningful for screens. The initi.al clear·screen for the
first refresh.{} call is generated by initially setting clear to be true tor C1J.rSCT,
whi·:b. dwayr ,T~nerates a de~r-3crt!en if i.£~, ·.rre~evant cf +.hf' d·.m·~nsioJ'l.,! ot t': a
window involved. _leaua is TRUE it the current (y. x) co-ordinates and the cursor- are to be left after the last character changed on the terminal. or not movetf
it there is no change. _SC1"oU is TRUE it scrolling is allowed.
_y is a pOinter to ail array of lines which describe the terminal.. Thus:
_y(i]

•

is a pOinter to the ith line, and

J(i][j]
is the ith character on the ith line.
Jl.agsO can have one or more values or-'d into it. _S'UBlrIN means that the
window is a subwindow, which indicates to d.aLwi:n.{} that the space tor the lines ~s
not to be freed. _ENDLINE says that the end of the line for this window is also
the end ot a screen.
F'ULL7JN says that this window is a screen.
SCROLLlrlN
indicates that the last character of this screen is at the lower right:-hand corne!"
ot the termjnal: i.e .• it a character was put there. the terminal would scroll.
_S'rANDOUT says that all characters added to the screen are in standout mode.
)

11 Allvviabl" not. :»rmally. ac::cesaed
ccmmc:ts with the user's Yariabla.

m~y

by the ~cr an D4aled with

aD

imtW .. _" to 5void

.-. - .... ~ .

'-15~

..~t-··

'

.it'

. -;.
• ','

:'.;...:. - ";-~·~I..

•

...

':.,'
,j'

Appendix C
1. Exam pie:s
Here we presen.t a few exac.ples of hoW' to use the
to be representative. though !lot compreheIlsive.

~acka~e.

They

atte=.~c.

2. Screen Updating
The folloWing examptes are intended to demonstrate the basic st:-"J.cture ot
a program using the screen updating sectioIlS of the package. Several of t..':.e
programs require calculation.al. sectioIlS which. are irrelevant of to the exampLe,
and are therefore usually not included.. It is hoped that the data structure :iefini.tioIlS give enough of an idea to alloW' -understanding ot what the reLevant ~or­
t1o~ do. The rest is left ~ an exercise to the reader. anci will not be OIl the fi-

nal.
2.1. Twinlde
This is a moderately simpie program which prints pretty pattertlS OIl ';.b.e
screec. that might eveIl hold your interest for 30 secoc.d.s or more. It alte~ates
betweeIl raJlciom patterns of asterisks. putting them OIl OIle by OIle, and the=.
taking them of! in the same lashioc.. It. is more eificie!lt USlng only the motior:.
optU:tizatioIl. as ~ democ.strated below.
, include
<.curses.b.>
I include
<,signal.b.>
/.

• en.. ide~ Jar

th:i.s ~g-ra:m. 'Was

1%

'[J'1""Jc!u.ct oj tha i.ma.gin.a.ti.an of

- Kurt SCftDrrt:l. Not raspO'7'l.S"i.bla Jar m:i:z.cls lost ar stol2T'..

...

•

-/

I derme

NeoLS
80
NUNES 24
MAXi' AITE.~NS

, define
# de!me

struct locs

~

char

y. r.

typedel st:ruct locs

LOes

Layout(NCOLS

tnt

Pattern.
Numsta.n:

mainO

4

LOCS:
e

Ntrm:S]:
/- c-u::-r-rnJ:

pa.::27-n. 1tumoe-r e /

/- -n'Umoe'" of stars i.-.o:. pa.tte-rn

~

char

egetec.v():

iDt

dieO:

srand(~etpidO):

initscrO:
signal(SlG!Nr. die):
!lcec!:100:
leaveok(std.scr. TRL'"E):
scrollo~stc!scr, FALSE):
-1R_

e/

Appendix C

for (;;)

~

/* make the board. se t:u.p • /
/* put on '*'s e/
/* C01Jer up 1JJith' 's e /

make boardO;
puton('*'):
puton(' '):

/*

* On. progra:m 8:it, m01Je thtl cursor to ths lower ZeIt corner by
* d:i:re e t a.d.d.re ssin.g, sine s curt'em Za c a.ti.lJn is no t gu.a:ra.nt e e d..
e

We lis a:n.d.say 'We used to bcr a.t ths

* absoLuia

UppflT

right

Corn.eT'

to gua.ra:n.tee

ad.dressin.g.

*/

dieO ~
signal(SlGINT. SIG_IGN}:
mvcur(O, eOLS-l. UNES-l. 0);
endwin():
exit(O);

/.

* Malee the

c:u.rr&-n.t bocrrci setup. It piclcs Cl ra:n.ciom. pattern. ct1'tCl
cicrtsrm:i:n.s if the cha:ra.r::ter is on. that pattern.

* calls 1.son.() to
* or not.

*/

makeboardO

f
y. x:
*lp:

reg iDt
reg Loes

Pattern = randO ~ MAXPATTERNS;
Ip = Layout:
10r (y = tJ; )' < i\LiNE3: y++ j
for (x = 0; x < NeOLS: x++)
if (ison(y.
~
lp->y = To
Ip++->x = x:

x»

Numstars

J
= Ip - Layout:

/.

* Raru:m. TRUE if (y. =) 'is 07'l tIt.

c:u.rren.t

pattcrrn.

*/

ison(y. x}
reg iDt y. x:

t

switch (Pattern)

case 0:

f
/* altarn.a.tf:rt.g If:rt.ss */

return !(y &: 01):

(
,.

-17-

Appendi% C

cue 1:

/- bo=-/

it (x >= LlNES && Y >= NCOLS)
return FALSE:
it (y < :3 il y >= N1INES - :3)

"turn TRUE:

return (x < :3 !I x >= NCOLS - :3):
ease 2:
/- ltoly pattarn! • /
return ((x + y) & 01);
case 3:
~ b~T ~oss CnU2T·/
ret.urn
>= 9 && Y <= 15);

,y

puton( ell)
r1!g char

ell: ~
~eg

LOeS

r;

;:oeg int.
reg tOeS

·end;
temp;

LOCS

end = &:Layout[Numstan];
tor (lp Layout; Ip < ec.d:lp++)
r randO 7. Numstars:
temp = -ip;
alp Layout[rJ:
Layout[r] = temp;

=

=
=

~

for (lp = Layout: Ip < end: Ip--) ~
mvaddeb.(lp->y, Ip->x. ch);
retreshO:

2.2. We
This pregram plays the famous computer patter~ gatne of !.i!e (Scierltittc
American. May, 1974:). The calculational routines c!"eate a linked List ot str"J.ctures detiIl.iJ:lg where each piece is. Nothing here clai.ms to be optimal. me:oeiy
demonstrative. !hi!! program. however, is a very good place to use the sc:"ee::
updating reutiIles 12 , as it allows them to worry about what the last position
looked like, so you don't have to. It also democ.strate~ some ot the input routines.

I includO!
., includ.e

/-

-

Ru:n. ~ lila ga:rrul. This is " d.e71't.a'7"tStT:ti.an

• th.a S C"1"2 an [}pd.tJ.tmg sac tum.

I

'J

p7""gT:"'""f7. !O~

t Ita -lC"tLTS R S c-u.TS 07" Fa.: Je:.g 2 .

-/

-18-

Appendilt C

)

struct 1st_st I
tnt
struct lst_st

/. LinJt:ed. List eLem.anl - /
y. x:
/. (y. z) positicrn oJ pi.ece • /
"next. -last;
/a d.o1.l.bly Li:nked - /

typedef struct 1st_st

IJST;

LIST

/* head. ollinJt:ed list - /

ma1n(ac, av)
tnt
ac:
char
-av(];

~

die():

lDt

evalargs(ac, av):

/'I fl'UcUuate a:rgumrrr.ts a /

lmtscrO:
signal(SIGINT. die):
crmadeO:
noechaO:
noDlO;

/a initialize screen

getstartO:

/'I get strzrti:n.g positi.lm. a,/

for (::)

/* set

pa.cka.ge

a,/

to rrrstore tty stats • /

/. sat lor char-by-ch.a:r • /
input a/

/*

/'lIar optim:tza.ti.on - /

l

/'I pri:n.t out curreTrot boa:rd. .,/
/* upcLa.te boa.rd posi.titm. - /

prboardO:
updateO:

1/a
a This is tha r~ 'Wh:it:/a. is called 1JJhrn. ",bout is h.it.
a It rU'cts tha tty sta.ts to th.tri:r origi:n.aJ. VcU1.LQS. This
• is th.a 1&.D'1"77&4l1JJay ollaC1'Uing tlUl yrogra:m..
a/
dieO ~
s~nal(SIGINT, SIG_IGN);
mveur(O, eOLS-l. LINES-l, 0):
enchrin():
exit(O):

/* ig'rr.ore 'NbO'UJ,'1 a,/
/'I go to bottom. of screen. - /
/'I set term,:i:n.cU to initial state

•/

/'I
• GIlt the sta:rf:i:ng positian. from. tluI usar. 171.11'11 keyS' U, i, a, j, L,
a m., " =ut. a:re used lor m.ovi:n.g thrl.i:r rela.tiva d:i.recticrns from. the
a k kay. Th:us. 1.1. move d:ia.grmaU:y u.p to tha Zalt, , moves d:i.rectly down.,
• fltC. % pLa.ces a. piIIce at th.a cu.rrcmt posit'icm., " .. takes it tzWcry.
• '/'h.I! input ccm. also be from. a. file. Th.a list is built a./ter the

- boa.rd satup is rea.d:l.J.
-/

getstartO l
reg char
reg iDt X. To

c;
,

-19-

.•
.......
..

'

.•.~.~.... ~::. ...
. .':,........

.... ~ -:-~: .
;.

.

;.'

~

"

~

_~

... ..
'.: ·'i;::'
... ~

~~- ~. " . '

:

-

.

"

. .' .
;.:. -.. ':'
"

o·

'-

Appendix C
'oox(stc.scr. '1', ' _');
move( 1. 1);
do

/- bo= in the senen e/
/ - m.a'U1!

to u:FFrJ:r l2!t cor.te-:'" •

1
refresb.O:
if «(c=.etcb.O) == 'q')
break:
switch (c) l
ca:se 'U':
case '\':
case '0':
ca:se
case 1':
casQ'm':

'r:

~a',':
e&!Se ',':

adjustyx(c); .
break
case'r':

mvadcistr{O. O. 'Tile oame: ");
getstr(bu!) :
read!1le(but):
break:

case 'x':
addcb.('X') :
break:

case' ':
addcb.(' '):
break:

if (Head != NULL)

dellist(Head):

=t'!alloc(~'Zect (Uc:n):

Hertd
/"

.. loap tJtr:ru.gh tha scnen. z..:,olr:i.ng faT" '='s. tm.d
• a Ltl 'r1un.t / aT" i a.clt ana
-/

for (y

=1: y < LINES for

ex

~ C1

1: y--)

=1:move(y,
x < COLS - 1: x++) 1
x):
if (incb.O == 'r)
addlist(y, x);

/-

- Prt':'tt

~

eM

C"'.J.r."rni

botl.1"oi poriti.:m. f-:-~m the !iN:2!:i !ist

-/

pr!;)oard.()

1
reg UST

-2!]-

list

Appenclix C

eraseO;
box(stdscr. 'I', ' _,);

". clear out la.st poS'f..tiJm. • /
/e bo: in the sc-reen e/

/e
e go through the List a.dd:i:rr.g
e bLank boa.rd

ea.ch piece to the newly
.

-/

for (hp = Head; hp; hp = hp->next)
mvaddch(hp->y. hp->x. 'X');

refreshO:
3. ]lotion optimization
The following example shows how motion optimiZation is written on its OWIl.
Programs which flit from one pla.ce to another without regard for what is alrea.dy
there usually do not need the overhead of both space and time associated With
screen updating, They should instead usc moUon optimization.
3.1. TwiDJde
The t1rinklc program is a good candidate tor simpte motion optimization.,
Here is hoW' it could be written;

mainO I
-sp;
-getenvO:
fputcharO. dieO:

reg char
char

iDt
srand(getpidO):
It (isatty(O»

,hi

iniliaJ:i.ze nu:::iom. saqv.enc E =.'

l

gettmode();
if (sp=getenv(UTERMU»
Je.tE.. m(s?):
signal(SIGlNT, die):

I

ebel

prilltf("Need a terminal on ;:d\n", _tty _ch);
eXit(l):

J
noechoO:
tputs(CL. NUNES. fputchar);
for (::) t
make board 0 :
puton('-'):
puton(' ');

". make the board setu:p . /
/. put on. ' e's • /
/e cover 'Up 'W'i.lh. ' 's e /

J
/.
e

Jpu.tcha.r d.sfi:n.ed.Jo", tputs()

./

fputchar(c)
-21-

.

'."

Appendix C

e: f

reg char

putchar( e);
ciieO

t
sigr:W.(SlGINT. SIG_IGN);
mvcur{O, eOLS-t. LINES-i. 0);
endWin();
exit(O):

putcc.( ell)
char
eh:

l

static iut
reg LOCS
reg iD.t
reg LOeS .

tasty. lastr.
-lp;

LOCS'

temp:

=

r.

-end:

end &Layout(Numstar~J;
far(lp Layout; lp < end: 11'++) ~
r = randO ~ Numstars:
temp = -lp:
-lp Layout( r]:
Layout(r] = temp;

=

=

fer (lp

= Layout: 1p < end:

Ip~+)
/- pr"a'Vtnl.t scrolli:rtg -I'

iZ ~!A)f

- 1 " 1p->o;: -: !,cc:.::
mvcur(lasty. lasa. 1p->y. Ip->x):
putchar(eh);
lasty = Ip- >y~
if «(lastx Ip->x + 1) >= NeOLS)

II :lp->y < m."Nr.S

=

if (A~l) ~

= 0:
lasty++;

lastx

J

ebe-la.:!tx

J

J

-22-

= :scor; - :;

-

'I.) ~



File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c041 52.342996, 2008/05/07-21:37:19
Producer                        : Adobe Acrobat 9.0 Paper Capture Plug-in
Modify Date                     : 2017:11:25 08:45:14-08:00
Create Date                     : 2017:11:25 08:45:14-08:00
Metadata Date                   : 2017:11:25 08:45:14-08:00
Format                          : application/pdf
Document ID                     : uuid:33b93be7-b230-6448-bdcd-57ffa4d29c5b
Instance ID                     : uuid:f1b2350b-4723-a140-924e-03005479476a
Page Layout                     : SinglePage
Page Mode                       : UseOutlines
Page Count                      : 320