690 13500 01_Altos_586_and_ACS8600_Xenix_Development_Systetem_Prog_Ref_May83 01 Altos 586 And ACS8600 Xenix Development Systetem Prog Ref May83 690-13500-01_Altos_586_and_ACS8600_Xenix_Development_Systetem_Prog_Ref_May83 690-13500-01_Altos_586_and_ACS8600_Xenix_Development_Systetem_Prog_Ref_May83
User Manual: 690-13500-01_Altos_586_and_ACS8600_Xenix_Development_Systetem_Prog_Ref_May83
Open the PDF directly: View PDF .Page Count: 494
ALms 586 AIID ACS 868. CORPDBR
SYS~
XB1IIX DBVBLOPIIBft SYSTEM
PROGRAIIIIER' S REPERBRCB GUmB
Al tos Computer Systems
2641 Orchard Park Way
San Joser CA 95134
mE IBPORIIA'.fIOR IB mIS DOCUMBft IS SUBJBC'.f TO
CHARGE WI'.fHOUT NOTICE. NEW EDITIONS OP THIS
DOCUMBft WILL IBCORPORATB CBAlIGES AS mBY ARB
PUBLISHEl).
Copyright ©1983.
All rights reserved.
ALTOS Manual Number:
698-13588-8.1
Altos COliputer Systeas.
May 1983
ACDatLBDGBllBftS
ALTOS is a registered trademark of Altos Computer
Systems.
XENIX is a trademark of Microsoft, Incorporated and
is a l6-bit microcomputer implementation of the
UNIX operating system, version 7.
UNIX is a trademark of Bell Laboratories
UNET is a trademark of 3Com Corporation
TABLE OF CONTENTS
1.
USING THIS MANUAL
Purpose/Scope
Organization
1-2
1-2
1-2
OTHER DOCUMENTATION AVAILABLE
Altos 586 or ACS 8600 Operator's Guide
Altos Introduction to XENIX Manual
XENIX Reference Card
Altos Application Software Guide
Altos UNET User Guide
Bell Laboratories Manuals
UNIX Programmer's Manual
Commercially Available Books
1-4
1-4
1-4
1-4
1-4
1-4
1-4
1-4
1-5
2.
I>
INTRODUCTION
USING XENIX
TOPICS COVERED IN INTRODUCTION TO XENIX MANUAL
2-2
INSTALLING XENIX DEVELOPMENT SYSTEM
2-3
LEARN PROGRAM
Installing Learn
Running Learn
2-7
2-7
2-8
CREATING
2-9
3•
N~'l
MENUS
UTILITY PROGRAMS REFERENCE GUIDE
USEFUL UTILITIES
3-1
UNIX MANUAL CHANGES AND ADDITIONS
3-3
ADD .CT (1)
ADD. HD (l)
AEMAIL (1)
APROPOS ( 1)
BSH (1)
CSE ( 1)
CXREF(l)
DATE (1)
DIGEST(l)
DISABLE(C)
DUMP.HD (1)
ENABLE (C)
EDIT(l)
EX (1)
FCOPY(l)
FINGER (1)
FLEECE(l)
3-6
3-7
3-8
3-l0A
3-11
3-15
3-38A
3-38B
3-39
3-40A
3-40B
3-40C
3-41
3-45
3-49
3-49A
3-49B
i
TABLE OF
3.
UTILITY
PROGRAMS
REFERENCE
FOLD(l)
FO&\1AT( 1)
FROM (1)
FSCK (1)
FTP (1)
HEAD (1)
IUL (1)
LAST (1)
LAYOUT (1)
LEAVE(l)
LS (1)
MAIL{l)
MAKE.HD(l)
MAKEWHATIS(l)
MAP(l)
MKCONF(lM)
MODEM(l) , UNMODEM(l)
MORE (1)
MULTIUSER(l)
PAGE (1)
PRINTENV (1)
PS (1)
RANLIB(l)
RESET(l)
RESTORE.HD(l)
SDDATE(lM)
SETMODE(l)
SIZEFS(l)
TAR(l)
TRANSP(l)
UA (1)
VI (1)
LOCKING (2)
RDCHK(2)
CURSES (3)
MENU S ( 5)
TERMCAP (5)
TTYTYPE(5)
CO~ENTS
GUIDE
(Continued)
3-49C
3-50
3-50A
3-51
3-54
3-55A
3-55B
3-55C
3-56
3-57A
3-58
3-61
3-68A
3-68B
3-69
3-69A
3-69C
3-69D
3-70
3-70A
3-71
3-72
3-74A
3-75
3-75A
3-75B
3-76
3-77
3-78
3-80A
3-81
3-85
3-87
3-89
3-90
3-92
3-97
3-108
APPENDICES:
A.
NUMERIC FORMATS, C, ABD FORTRAlI 77
INTEGER FORMATS
FLOATING-POINT FORMATS
VALUES IN MEMORY
DEVELOP~
SYSTEM
~LITIBS
B.
SAMPLE LIST OF XERIX
C.
TRANSFERRIRG PILES BETWEEN ACS 86.1 AND ALTOS 586 OR OI.rBBR
COIIPOTER SYSTBKS (ASYNCHROROOS CORII1JRICATIORS)
USING CU FACILITY
TRANSFERRING FILES UNDER UUCP FACILITY
CONNECTING THE ACS 8600 AND THE 586
PREPARING THE CONFIGURATION FILES
Recommended Entries
IF YOU HAVE SPECIAL REQUIREMENTS
Assigning the System Names
Defining the Communications Line Characteristics
Supplying the Login Information
Defining the File Accessibility
DISABLING AND ENABLING THE TTY PORTS
TESTING THE UUCP NETWORK
COPYING FILES USING UUCP
USING THE UUCP COMMAND
USING MODEMS WITH ALTOS XENIX SYSTEMS
D.
al86 ASSEMBLY LARGUAGE REFERERCB MARUAL
XENIX Software Development Extract from Microsoft Manual
E.
TUTORIAL ABD REFERERCE MATERIAL
(UNIVERSITY OP CALIFORNIA, BERKBLEY MARUALS)
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 Optimization:
Package
An
v
A Library
CI1AftBR 1:
IftRODUC'.rIOR
This manual describes the Altos XENIX Development System on the
Altos 586 and ACS 8600 Computer Systems. It provides reference
information and step-by-step (tutorial) procedures, which are
primarily aimed at the programmer or the advanced system user. A
first-time computer user can use this manual also, but it is
recommended that the Introduction to XBIIIX Manual be read first.
1-1
USING THIS MAROAL
Purpose/Scope
This manual describes items that are unique to the Altos
implementation of the XENIX operating system or that are useful
for the programmer or advanced system user. It also serves as a
guide to the other documentation that is available on XENIX/UNIX.
Organization
This manual is divided into three chapters:
Chapter 1 lists other Altos documents that you receive as part of
your XENIX operating system.
It also lists commercially-available documentation.
Chapter 2 provides instructions for installing the XENIX Development System, and discusses the online tutorial, learn, and tells
you how to create new menus.
Chapter 3 lists useful utilities and describes the changes and
addi tions that exist between the Al tos implementa tion of XENIX
and the Bell Laboratories Standard Version 7 of the UNIX
operating system.
The variations and additions are documented in the standard Bell
Laboratories format. The Altos documentation can be left in this
supplement or can be inserted into the Bell Laboratories OBIX
Program.erls Manual.
The Appendices contain general reference material.
Appendix A.
Numeric Formats, C, and Fortran 77:
Reference information on the internal format used
for numerical representation in these languages.
Appendix B.
Sample List of XENIX Utilities:
A sample list of utilities fUrnished with your
system.
Appendix C.
Transferring Files Between ACS 8688 and
ALTOS 586 or Other Computer Systems
(Asynchronous Communications):
A description on how to transfer files between the
ACS 8688 and Altos 586 XENIX computer systems, or
between two Altos XENIX computer systems which
support asynchronous (serial) communications. It
discusses the ~ (call UNIX) and .I.W.&R (UNIX-to-UNIX
copy) facilities. For ACS 8608 versions 2.2d and
A1tos 586 versions 2.3 and higher, refer to a
description of the File Transfer Utility for Xenix1-2
to-Xenix (ftp), discussed in Appendix H of the
Introduction ~ Xenix manual. It also discusses how
to use modems with your Altos XENIX systems.
Appendix D.
8086 Assembly Language Reference Manual:
A description of the XENIX 8086 Assembly Language.
Appendix E. 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-3
omBR DOCtJIIBJr.rA'rIOR AVAILABLE
The follow ing documentation is furnished with your XENIX
operating system. The only commercially-available book that is
provided is A User Guide to the ORIX Systea.
Altos 586 or ACS 8688 Operator's Guide
This manual describes the Altos computer system and its operating
specifications. It provides step-by-step procedures on how to
unpack and set up the computer system, how to install
peripherals, how to verify proper functioning of the system, and
briefly describes how to use the Altos diagnostics software.
Altos Introduction to XBRIX Manual
This manual, describes the Altos implementation of the XENIX
operating system on the Altos 586 and ACS 8600 computer systems.
It provides background information and step-by-step procedures,
which are primarily aimed at a first-time computer user, on how
to install XENIX, how to log on/off, how to shut down the system
properly, how to save and restore files, and describes system
maintenance.
XBIIX Reference card
A concise reference card, which contains information on how to
use the Altos implementation of XENIX, describes the XENIX
commands, and lists the Business Shell (BSH) menus.
Altos Application Software Guide
(The ASS Shell is an optional package.) The Altos XBJlIX Applications Software Guide provides information on how to install the
optional ABS Menu Shell and the application programs, and how to
access the ASS menus.
Altos
ORB~
User Guide
(The communication network services is an optional package.)
This document p~ovides information on how to install the optional
communication network services and how to use them.
Bell Laboratories Manuals
OJIIX Prograaaer's Manual, Seventh Edition.
volume set.
This is a three-
Volume 1 provides general information about UNIX and
about the manual set. It contains reference information on utilities and system calls, organized into
chapters.
1-4
Volume 2A contains supplementary and tutorial
information. For example, this volume includes an index
to volume 2A and 2B, tutorials for the UNIX text
editor,
information on document preparation, and
information on Unix programming (C language).
Volume 2B contains additional reference material, and
includes advanced topics and languages. For example,
this volume includes information or supporting tools
and languages such as yacc, which is a tool for writing
compilers for other languages.
It also includes
information on system implementation and maintenance.
Commercially 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.
(This book is supplied with the XENIX operating system.)
It
explains UNIX concepts and provides tutorials for getting started
with UNIX and for the most useful commands. All the utilities
listed in the book may not be provided with your XENIX operating
system. Refer to Appendix B, Sample Listing of XENIX Development
System Utilities, for a listing of utilities provided with your
system.
Using the UNIX Systea, by Richard Gauthier.
This book is more like a textbook than the Thomas and Yates'
book. It presents a more in depth explanation of UNIX, which is
of value to the programmer and those who are already familiar
with A User's Guide to the UNIX System.
Three useful programming books related to UNIX are:
The 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 chapter.
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 RatFor. Many of the tools described in this book are based
on UNIX models.
Learning to Program in C, by Thomas Plum. This book teaches
the C programming language from the ground up. With or without
previous experience, anyone acquainted with computers will find a
clear description of how the language works from this book.
1-5
CIIAftBll 2:
OS:IBG XBRIX
The Altos Introduction to XZBIX lIanual covers the XENIX Run-Time
and portions of the Development System. Topics that are unique
to the development system are described in this chapter.
2-1
'fOPICS OOVBBBD IR nr.rRODUCl'IOR 'fO XBIlIX IlARUAL
This manual covers the bas ic XENIX utili ties and how to use the
business shell menu system. Topics covered include:
Introduction to Operating System Concepts
Introduction to XENIX Operating System Concepts
Introduction to the Business Shell Menu System
Introduction to System Administration and Maintenance
Installing XENIX Run-Time System
Upgrading Older Versions of XENIX
Getting Started with XENIX
Configuring the Ports
Creating and Changing User Accounts
Starting Up XENIX (Booting from Hard Disk)
Log In, Log Off, and Quit
Setting and Changing Passwords
Using XENIX on a Regular Basis
Using the Business Shell Menu System
Basic Utilities
System Administration Utilities
Saving and Restoring Files
Random-Access Diskette Files
Checking and Cleaning Up Files
Shutting Down System
Using the ~ Text Editor
Appendices:
Hard Disk Organizatin
Floppy Disk Organization
Cartridge Tape Organizatio
Printer Information
Terminal Capabilities
File Transfer Program
For more information, refer to the Introduction to XBI1IX BaDual.
2-2
IBS~I-';
URIX DBVBLOPIlBft
SYS~
To install the XENIX Development System on your Al tos Computer
System, you should:
1.
Install the Xenix Run-Time System by following the instructions in the Altos Introduction to Xenix 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 rnterrupted Installation section in
the Altos Introduction to XBRIX Manoal.
2.
Make sure you are logged in as super-user (root).
3.
Enter
# cd
/
(CR)
This command causes the system to go to the top directory
(or parent directory) of the XENIX system.
4.
Insert the diskette labeled nXENIX DEVELOPMENT SYSTEM
UTILITIES #1 of n,n where nnn is the total number of utility
diskettes.
5.
Enter
# tar xv
(CR)
This command causes the directories and files on the utility
diskette to be loaded onto the XENIX System. As files are
copied from diskette to hard disk, you will see messges of
the form:
x nFilename n , nnnnn bytes, nn tape blocks
•
•
•
x "Filename n , nnnnn bytes, nn tape blocks
ROTE
DO RO~
REIIOVE
~OUCB ANY KBYS OR ~BE KBYBOARD OR
DISKE~'lE UR~IL YOU SEE 'lBE SUPBR-USBR
PROIIP'l CBARACUR (I).
2-3
6.
When you see the super-user prompt character (#), remove the
diskette and store it in a safe place.
7.
Repeat steps 4 through 6 for each XENIX Development System
utility diskette.
ROTE:
IF AVAILABLE DISK SPACE IS A PROBLEIl OR YOUR
SYSDIl, YOU CAlI IBSIJIALL I:J()ftIORS OF 1'IIB XBJ[[X
DEVBLOPIlER~ SYS~EIl RATHER ~ ~E ER~IRE
PACKAGE. IF YOU DBSIRE, YOU CAR DISPLAY DE
COR~ER~S OF A DISKE~IJIB BY ER~BRIBG tar tv
(CR>. NO~E THE URWAR~BD FILBS YOU WART ~O
RBIIOVE AF~ER IBS~ALLIBG DISKE~~B PBR ABOVB
IBS'lRUCfiOBS.
8.
When you have loaded all of the utility diskettes, enter
# install (CR>
9.
This step is optional.
optional unlinked kernel can be installed. It contains a
new swapping algorithm, which swaps out processes that are
waiting for other processes first.
The old swapping
algorithm swapped out the largest process that wasn't
actually running. This would occur even if the process was
a large application that was just waiting for terminal
input.
An
If you wish to load the "Unlinked Kernel," you should:
Insert the diskette labeled "UNLINKED KERNEL."
Enter
# tar
"XV
(CR>
Enter
# install (CR>
Unlinked Kernel installed.
Remove the diskette and store it in a safe place.
You have just installed the Unlinked Kernel.
2-4
10.
To load the C compiler onto the XENIX system, you should:
Insert the diskette labeled "C COMPILER."
Enter
t tar xv
F77 installed/Remove diskette and store it in a safe
place.
You have just loaded the UNIX Fortran compiler.
12.
If the prior steps were successful, your XENIX Development
System is correctly installed.
If you purchased the optional Altos communication network
services, refer to the Altos ~ User Guide for information
on how to install the communication network services.
2-5
If you purchased the ABS package or other Altos application
packages, refer to the Altos XB.IX Application Software
Guide for information on how to install the ABS Menu Shell
and application programs.
If you wish to start up XENIX, see the Getting Started with
XENIX chapter in the Altos Introduction to XBBIX Manual.
If you don't plan on using your XENIX system at this time,
you can shut the system down by entering:
# sync
# etc/baltsys
** Normal System Shutdown **
2-6
The learn program is an automated instructional facility which
provides tutorial information about the XENIX system and some of
the programs that run under it. Learn is especially useful for
the first-time user because it is interactive and requires no
prior UNIX experience.
At present, the learn program covers the following topics:
Basic File handling commands
The UNIX ~ text editor
Advanced file handling
The ~ language for typing mathematics
The n-msn macro package for document formatting
The C programming language
For more information, refer to the UNIX Progra••er's Kanua1,
Seventh Edition, Volume 2A, chapter 7, LEARN - Computer Aided
Instruction of UNIX (Second Edition).
Insta11ing Learn
After you have installed the XENIX Development System, install
learn as follows:
1)
Log in as root.
2)
Enter:
t cd /usr/lib/leara (CR>
t .ake
(CR>
t .ake p1ay log (CR>
3)
When the prompt (t) appears, the learn program is completely
activated.
4)
To check that the required files are set up properly, enter:
i .ake check (CR>
2-7
Running Learn
Learn may be run by any user, from any directory in the system,
by entering:
(system prompt) lear.n
OR
(system prompt) lear.n Pilaaa.e
where: Filename
= lesson
desire, such as "editor."
2-8
CREAnBG BBW IIBBUS
A menu system is defined as a collection of menus, each of which
is an ASCII text file. It is relatively easy to create a new,
customized Business Shell (BSH) menu system or to modify the
default menu system. The procedure to create a menu system is as
follows:
Create a text file containing the source menu in the following
format:
&Menuidentifier
• • • the substance of the JleDU • •
• • • not over 24 lines length
&Actions
• • • zero or .ore sequences of • • •
(-> prompt
size
• • • sequences of actions • • •
• • •
• • • for this proapt
This sequence may be repeated as often as desired. The ampersand (&) and tilde (-) must appear in the first column. &Actions
must appear, even if there are no actions.
The substances of each menu is composed of text which will be
reproduced exactly as it appears in the location where it
appears. There are five exceptions where characters have special
meanings:
denotes a valid Rprompt R string (it is the text of
the actual prompt)
"!date"
inserts the current date and time:
Fri Oct 28 16:28 1983
"luser n
inserts the current user id:
n !pwdn
inserts the current directory:
R
1 @n
Don
/user/don/2
: indicates where to leave the cursor
The n! n may appear as a suff ix, in which case the str ing will be
right-justified instead of left-justified.
The prompts must be reproduced as they are expected to be typed,
in the Actions chapter. The actions may be composed of BSH
commands or commands which are executed by the standard XENIX
shell (/bin/sh). The actions should all be indented one tab
stop. RSize R rows will be reserved at the bottom of the screen
for output. If size is omitted, a value of 5 will be used. If
size is 9, the entire screen will be used. After executing the
actions, the message
2-9
[Type return to continue]
will appear .t the bottom of the screen. If size is -1 the
entire screen is used, but no message [Type return to continue]
is issued; and BSH resumes without pause after all the actions
have been executed.
Transfer to another menu is specified by writing the name of the
destination menu in the semantics field.
Commands to be executed by the BSH interpreter must be typed oneper-line.
Commands to be executed by UNIX follow the usual conventions.
See the URZX Progra.aer·s Manual.
For example, the the menu for Electronic Mail can be created as
follows:
&Mail
!date
\ELECTRONIC-MAIL-SERVICES
-a - Receive-mail
-b - Send-mail
-c - Return-to-starting-menu
&Actions
-a
o
mail
-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
Start
See the ~, digest, menus, and ~m~ utilities in the V.IX
Progra•• er's Kanual and Chapter 3, Utility Programs Reference
Guide, for more information.
2-11
CBAPrBR 3:
ftILlft PROGRAIIS RBFBRElICE GUIDE
USEFUL
UTILI~IES
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. This
chapter documents the changed and new utilities.
See Table 3-2
for a quick reference.
Note in particular: .f.su:mAt, fcopy,
multiuser, and YA, and the new version of~.
The Business
Shell, hAh, has two accompanying utilities, menus and digest.
See also Appendix I for reference and tutorial material on the
University of California, Berkeley utilities, such as the screen
editior
n.
3-1
~able
3-1.
UTILITY
A List of Useful Utilities for Getting Started
DESCRIPTION
ar
Object library manager and archiver
as
XENIX 8986relocatable assembler
cat
Display a file
cc
·C· language compiler
cd
Change directory. Changes your current posi tion
in the File System hierarchy.
chmod
Change mode. Changes file protection attributes
chown
Change file ownership
cmp
Compare two files
cp
Copy a file
ed
The standard UNIX editor
ftp
XENIX file transfer program
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
P r in two r kin g d ire c tor y •
Dis P I a y s cur r en t
position in the directory hierarchy
rm
Remove.
rmdir
Delete a directory
setmode
Sets mode for serial printer not run at 9699 baud
stty
Set terminal options, such as baud rate
tar
File system archiver.
dumps and restores
wall
Write to all users.
write
Write to other logged in users.
Deletes a file
3-2
May be used for file system
UNIX MANUAL CHARGES AND
ADDI~IONS
The material in this chapter may remain in this supplement or be
inserted in Chapters 1 through 5 of Volume 1 of the U8IX
Progra•• er's Kanoa~, as you wish. If you insert these documents
into the manual, place them in the chapters corresponding to the
number in parentheses after the utility name. (Entries within
chapters 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.
!fable 3-2.
List of UNXX
UTILITY
SOURCE
add.ct(l}
(altos)
Optional.
Add cartridge tape to system.
add.hd(l)
(altos)
Optional.
system.
Add additional hard disk to
aemail (1)
(altos)
Optional. Altos Electronic Mail Facility is an intelligent, screen-oriented
"user friendly" mail processing system.
bsh (1)
(altos)
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.
(altos)
Create menu systems for the Business
Shell.
(1)
digest (1)
Kan~
Changes and Additions
DESCRIPTION
3-3
'lable 3-2.
List of DlIIX lIanaal Changes and Additions (cont.)
UTILITY
SOURCE
edit (1)
(uofcb)
Text editor (variant of the ex editor
for new or casual users).
ex
(uofcb)
Text editor.
fcopy(l)
(al tos)
Copy a floppy diskette, while in XENIX.
format (1)
(altos)
Format a floppy diskette,
XENIX.
fsck (1)
(bell)
File system consistency check and interactive repair.
ftp(l)
(altos)
File transfer program.
layout (1)
(al tos)
Configure a hard disk.
ls (1)
(uofcb)
List contents of directory.
(uofcb)
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(l)
(altos)
Create an alternate sector map for a
hard disk drive.
mul tiuser (1)
(altos)
Bring the system up multiuser.
printenv(l)
(uofcb)
Print out the environment.
ps(l)
(uofcb)
Processor status.
reset (1)
(uofcb)
Reset the terminal status bits to a
predef ined state.
setmode(l)
(altos)
Sets mode for serial printer not run at
9680 baud.
sizefs(l)
(altos)
Determine the size of a logical device
from the layout information associated
with a hard disk.
tar(l)
(bell)
Tape or floppy archiver.
restores hard disk files.
(l)
Mail
(1)
DESCIUPTION
3-4
while in
Dumps and
Table 3.2.
List of UNIX Manual Changes and Additions (Cant.)
UTILITY
SOURCE
ua(l)
(altos)
User administration. Adds and deletes
user accounts on the system.
vi (1)
(uofcb)
Screen oriented (visual) display editor.
locking (2)
(msoft)
Lock or unlock a record of a file.
rdchk (2)
(msoft)
Check if there is data to be read.
curses(3)
(uofcb)
Screen functions with "optional" cursor
motion. (Has window capability.)
menus(s)
(al tos)
Develop menus for Business Shell.
termcap(5)
(uofcb)
Data base which defines cursor-control
sequences for most commonly used CRT
terminals. It is used by most "screen
oriented n software, such as the Altos
shell and visual screen editor, ~.
ttytype(5)
(altos)
Data base for defining terminal type
associated with each serial port.
DESCRIPTION
3-5
ADD.~(l)
ADD.~(l)
NAME
add.ct - add a cartridge tape drive
SYNOPSIS
add.ct
DESCRIPTION
Add.ct is a shell script which assists the installer of a
cartridge tape drive under XENIX. This script requires no
interaction with the installer.
The purpose of this script is to produce a device entry for
the cartridge tape drive in the /dev directory. When this
script is invoked, a device named /dev/ct9 will be created
in /dev for the ACS 8699.
lion
Add'Gt is an option on the ACS 8688 only, it
is only provided with the cartridge tape.
~he 586 Kernel includes cartridge tape
devices na.ed /dev/ct, /dev/rct, /dev/nct,
and /dev/nrct in the /dev directory.
3-6
ADD.BD(l)
ADD.BD(l)
NAME
add.hd - add a second hard disk
SYNOPSIS
add.hd
DESCRIPTION
A~~~
is a shell script which helps the user to install a
second hard disk under XENIX.
The first thing that the
script does is prompt the user for the size of the second
drive. It asks you whether you have a 10, 20, 30, or a 40
megabyte drive.
Once you reply with a correct number it
will tell you that it is making the appropriate sized disk.
Part of the process of making the extra disk is to run the
layout(l) program, which divides the disk into two areas.
One area is reserved for spare sectors (in case of bad
spots), and the other area is ready to be made into a file
system.
The layout program is immediately followed by the
map(l) program, which checks the second drive for bad spots.
If there are any, it maps them into the spare area. When
the map(l) program is complete (10-20 minutes), a file
system is created on the second drive and checked.
As its final act the script creates the directory /usr2, and
tells you how to insert the second drive into the XENIX
directory hierarchy.
When the shell script is completed and you see the XENIX
prompt again, you should add to the file /etc/rc a line
which mounts the second drive as a subdirectory, such as:
/etc/mount /dev/hdla /usr2
This means that each time you bring the system up multiuser, files and directories created in the directory /usr2
will be physically located on the second drive.
SEE ALSO
layout(l)
BUGS
Add.hd runs significantly slower (3-4 times),
multi-user.
3-7
when running
AEMAIL{l}
XENIX Programmer's Manual
AEMAIL(l}
NAME
aemail - send and receive mail
SYNOPSIS
aemail
DESCRIPTION
The Altos Electronic Mail facility is ~n intelligent, screen
oriented, "user friendly" mail processing system. It incorporates the delivery facilities of both Mail(l) and umtp(l),
as well as letting the user specify which editor to use for
text composition.
Aemail is designed around boxes and files. Commands are
shown on the top of the screen, boxes or files are numbered.
When a command or box/file is chosen it is highlighted (if
the users terminal has reverse video). In addition to the
commands listed, AL and ftR (control-L and -R) cause the
screen to be cleared and redrawn, backspace (usually AH)
unselects the chosen comamnd, and interrupt (the RUB or DEL
key) stops the current command. The message "Status: ••• "
that appears on the bottom right part of the screen always
states what the program is currently doing.
Reading mail. Incoming mail is automaticly picked up and
put in the Inbox. It remains here until it is deleted by the
user.
Sending mail. The send command invokes the editor (see
Options below) on a file with the header lines "To:", "Subject:" and "Archive-a-copy (yin) ? nne The user must put at
least one addressee on the "To: "line. (See Addresses
below.) The "Subject:" line is optional, and the last line
tells whether or not to save a copy of this in the users
Archive Box. The user adds whatever text they desire to the
rest of the file. When the user exits from the editor,
aemail checks the addressee(s) to make sure they exist. If
it finas one" (or more') addressees that it doesn't recognize,
it asks if the user wishes to invoke the editor again to
correct this. If not, the piece of mail is undeliverable
and is left in the users Outbox. If all addresses are
recognized, it is temporarily put in the users Outbox and
then delivered.
.
Addresses And Distribution lists. There are three types of
addresses: a local name, (account name on this machine), a
UNET machine and name (of 'the form "user_name on machine" or
"user_name at machine"), or a UUCP address
("siteluser_name"). Any or all of these three types can be
used in the same distribution list or one "To:" line. The
"To:" line can also have Distribution list names mixed in,
but a Distributiori list cannot have any other distribution
3-8
/
AEMAIL (1)
AEMAIL (1)
XENIX Programmer's Manual
list names in it.
A distribution list has the form:
DistName: address {, address, address, • • • }
.
Note the colon (':') after the DistName, the commas seperating addresses and the ending period ('.'). Distribution
list can extend over several lines. A file in the users
Distribution List Box can contain several Distribution
lists.
Archiye ~ Sayed Mail~. When the user archives a piece
of mail, a copy of it is put in this box.
Recipient ~~. This box contains two lists, of all the
addresses the aemail systems knows about. One is a list of
the users on this machine, the other is a list of all the
other machines this machine has UNET connections to.
Options. The user can set four options, either by editing
them once the user is running the aemail program, or by setting the appropriate environment variables. They are: Editor (environment variable "EDITOR"), a program that takes
one argument, the name of a file to edit, Maildrops ("MAILDROP"), filename(s) of where incoming mail is to be picked
up, Printer ("PRINTPROG"), program that takes one argument,
the name of the file to be printed; and Shell, ("SHELL").
(See below for defaults.)
FILES
-/.aemail_dir/Inbox/*
-/.aemail_dir/Outbox/*
-/.aemail_dir/SavedMail/*
-/.aemail_dir/DistLists/*
/etc/passwd
/etc/UNET/UNET.routes
/usr/bin/vi (8600/586)
/usr/ucb/vi (68000)
/usr/bin/lpr
/bin/csh
Mail
mail
/etc/UNET/umtp (8600/586)
/usr/UNET/umtp (68000)
/usr/bin/aedeliver
/usr/bin/aepickup
users incoming mail
outgoing mail and undeliverable
mail
mail that is "archived"
distribution lists
to identify recipients
to identify UNET machine connections
default editor
default editor
default print program
default shell
to deliver local or UUCP mail
used by Mail to send things
to deliver UNET mail
"
"
"
"
figures out whether to call Mail
or umtp
transfers mail from "maildrops"
to -/.aemail_dir/Inbox
SEE ALSO
vi, Mail(l)
3-9
AEMAIL(I)
BUGS
XENIX Programmer's Manual
AEMAIL(I}
Addresses can not be a mixture of UNET, UUCP and distribution list names.
Distribution list entries should be able to contain other
distribution names.
The locking mechanism has Mail (I) 's imperfections.
The users PATH environment variable must have the proper
path for Mail, vi and lpr.
Due to a curses bug the screen must be redrawn after highlighting.
3-11
APROPOS (I)
APROPOS (1)
NAME
apropos - locate commands by keyword looKup
SYNOPSIS
apropos keyword .••
DESCRIPTION
Apropos shows which manual sections contain instances of any
of the given keywords in their title. Each word is considered separately and case of letters is ignored.
Words
which are part of other words are considered, thus looking
for compile will hit all instances of 'compiler' also. Try
apropos password
and
apropos editor
If the line starts 'name(section)
you can do 'man
section name l to get the documentation for it. Try 'apropos
format l and then 'man 3s printf l to get the manual on the
subroutine printf.
AprQ~
is actually just the -k option to the m.an(l) com-
mand.
FILES
/usr/lib/whatis
SEE ALSO
makewhatis(l)
I
data base
man(l), catrnan(8)
3-1SA
BSB(1)
BSB(1)
NAME
bsh -- Altos Computer Systems Business Shell
SYNOPSIS
hah [
-fh£a ] [ menu system ]
DESCRIPTION
~ is a menu-driven command language interpreter.
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 han is run
in the background.
In the options described below, either "line feed" or
"return" performs the newline function.
Options
-L
Start hah 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
hall.
-g
displays a one-line descriptive summary of the syntax
used to invoke bah.
-~
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
default one (/etc/menusys.bin). Prior to use by hall 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, bah issues an error message and terminates.
~
3-11
8SB(1)
BSB(1)
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 shell script
> Execute a bsh internal command
(e.g., chdir(l)}
menuname
Typing the name of a menu
become the current menu.
spelled, or if it does not
system, an error message is
causes it to immediately
If the menu name is misexist in the current menu
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 "line feed" and "return" -- both
generate a newline.
?
Typing a question mark (?) causes the "help" 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 "xyz", typing a question
mark is entirely equivalent to typing "xyz?"
??
Typing a pair of question marks {??} causes the ~
system help informa tion 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 cur rent
one.
manualpage??
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 hs.h one
3-12
BSB(I)
BSB(I)
may type "bsh??"
typing "lman bsh."
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, sh(l) 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 accomplished by sending the sub-shell an end-of-file. 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 hah 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 us~r is
asked if he wishes to change to the alternate mode. If
your response begins with "yn 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
BREAJ< key.
backspace
~
understands the Backspace function (as obtained
from /etc/termcap).
CANcel
llahinterprets 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 ~~h 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", "Q" or "Quit" all have the same effect:
3-13
BSB(1)
8SH(1)
.b..:Ul is terminated. If l:uih is your login shell, "quit"
also results in your being logged out.
Enyironment
BSHINIT
The BSHlNIT environment variable contains the initial
val ue of the defaul t mode ("fast" or "slow"). If this
variable does not exist in the environment, hah 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 .b..:Ul 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 hah.
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 user1s login name,
password, home directory, shell,
etc.
contains terminal attribute descriptions
system warning and error messages
SEE ALSO
digest(lM), login(l), menus(S), sh(l), termcap(S)
DIAGNOSTICS
The diagnostics produced by .b..:Ul are intended to be selfexplanatory.
BUGS
probably should never allow itself to be run in the
background.
~
should detect the fact that the current terminal is not
defined in /etc/termcap and abort gracefully.
~
3-14
CSH(l}
NAME
XENIX Programmer's Manual
CSH(l}
csh - a shell (command interpreter) with C-like syntax
SYNOPSIS
csh [ -cefinstvVxX ] [ arg •••
]
DESCRIPTION
~ is a command language interpreter.
It begins by executing commands from the file '.cshrc' in the ~ directory of
the invoker. If this is a login shell then it also executes
commands from the file '.login' there. In the normal case,
the shell will then begin reading commands from the terminal~ prompting with '% '.
Processing of arguments and the
use of the shell to process files containing command scripts
will be described later.
The shell then repeatedly performs the following actions: a
line of command input is read and broken into words. This
sequence of words is placed on the command history list and
then parsed. Finally each command in the current line is
executed.
When a login shell terminates it executes commands from the
file '.logout' in the users home directory.
Lexical structure
The shell splits input lines into words at blanks and tabs
with the following exceptions. The characters '&' 'I' ';'
' ( I ' ) ' '(I
' ) ' form separate words.
If doubled in '&&',
'I I', '«' or '»' these pairs form single words. These
parser metacharacters may be made part of other words, or
prevented their special meaning, by preceding them with '\'.
A newline preceded by a '\' is equivalent to a blank.
In addition strings enclosed in matched pairs of quotations,
'I "
"~I or 'R', form parts of a word; metacharacters in
these strings, including blanks and tabs, do not form
separate words. These quotations have semantics to be
described subsequently. Within pairs of " or 'ft, characters a newline preceded by a '\' gives a true newline character.
When the shell's input is not a terminal, the character 'Ii
introduces a comment which continues to the end of the input
line. It is prevented this s~ecial meaning when preceded by
'\' and in quotations using' ., ' I " and 'ft'.
Commands
A simple command is a sequence of words, the first of which
specifies the command to be executed. A simple command or a
3-15
CSB{l)
XENIX Programmer's Manual
CSH (1)
sequence of simple commands separated by 'I' characters
forms a pipeline. The output of each command in a pipeline
is connected to the input of the next. Sequences of pipelines may be separated by 'I', and are then executed sequentially. A sequence of pipelines may be executed without
waiting for it to terminate by following it with an '&'.
Such a sequence is automatically prevented from being terminated by a hangup signal, the nohup command need not be
used.
Any of the above may be placed in '(' ')' to form a simple
command (which may be a component of a pipeline, etc.) It is
also possible to separate pipelines with 'II' or '&&' indicating, as in the C language, that the second is to be executed only if the first fails or succeeds respectively. (See
Expressions.)
Substitutions
We now describe the various transformations the shell performs on the input in the order in which they occur.
History substitutions
History substitutions can be used to reintroduce sequences
of words from previous commands, possibly performing modifications on these words. Thus history SUbstitutions provide
a generalization of a ~. function.
History substitutions begin with the character 'I' and may
begin anywhere in the input stream if a history substitution
is not already in progress. This '1' may be preceded by an
'\' to prevent its special meaning, a ' I ' is passed
unchanged when it is followed by a blank, tab, newline, '='
or ' ( I . History substitutions a1so occur when an input line
begins with 'T'. This special abbreviation will be
described later.
.
Any input line which' contains history substi.tution is echoed
on the terminal before it is executed as it could have been
typed without history substitution.
Commands input from the terminal which consist of one or
more words are saved on the history list, the size of which
is controlled by the history variable. The previous command
is always retained. Commands are numbered sequentially from
1.
For definiteness, consider the following output from the
history command:
3-16
.
XENIX Programmer's Manual
CSH(l)
9
H)
11
12
CSH (1)
write michael
ex write.c
cat oldwrite.c
diff *write.c
The commands are shown with their event numbers. It is not
usually necessary to use event numbers, but the current
event number can be made part of the prompt by placing an
'I' in the prompt string.
With the current event 13 we can refer to previous events by
event number 'Ill', relatively as in '1-2' (referring to the
same event), by a prefix of a command word as in 'ld' for
event 12 or 'lw' for event 9, or by a string contained in a
word in the command as in 'l?mic?' also referring to event
9. These forms, without further modification, simply reintroduce the words of the specified events, each separated by
a single blank. As a special case '11' refers to the previous command 1 thus '11' alone is essentially a ~. The form
'Ii' references the current command (the one being typed
in). It allows a word to be selected from further left in
the line, to avoid retyping a long name, as in 'li:l'.
To select words from an event we can follow the event
specification by a ':' and a designator for the desired
words. The words of a input line are numbered from 0, the
first (usually command) word being 0, the second word (first·
argument) being 1, etc. The basic word deSignators are:
o
n
1
$
%
x-~
-~
*
x*
X-
first (command) word
n'th argument
first argument, i.e. '1'
last argument
word matched by (immediately preceding) ?~? search
range of words
abbreviates '0-~'
abbreviates 'i-$', or nothing if only 1 word in event
abbreviates 'X-Sf
like 'X*' but omitting word '$'
The ':' separating the event specification from the word
deSignator can be omitted if the argument selector begins
with a 'i', '$', '*' '-' or '%'. After the optional word
deSignator can be placed a sequence of modifiers, each preceded by a ':'. The following modifiers are defined:
h
r
s/l1";
t
&
g
Remove a trailing pathname component, leaving the head
Remove a trailing '.xxx' component, leaving the root ru
Substitute ~ for L
Remove all leading pathname components, leaving the ta:
Repeat the previous substitution.
Apply the change globally, prefixing the above, e.g. '
3-17
eSB(l)
XENIX Programmer's Manual
p
q
x
eSB (1)
Print the new command but do not execute it.
Quote the substi tuted words, preventing further substi tl
Like q, but break into words at blanks, tabs and newlinE
Unless preceded by a ~g' the modification is applied only to
the first modifiable word. In any case it is an error for
no word to be applicable.
The left hand side of substitutions are not regular expressions in the sense of the editors, but rather strin~s. Any
character may be used as the delimiter in place of /'; a
~\' quotes the delimiter into the ~ and·~ strings.
The
character '&' in the right hand side is replaced by the text
from the left. A '\' quotes '&' also. A null ~ uses the
previous string either from a ~ or from a contextual scan
string ~ in '1?~?'. The trailing delimiter in the substitution may be omitted if a newline follows immediately as may
the trailing '?' in a contextual scan.
A history reference may be given without an event specification, e.g. '1$'. In this case the reference is to the previous command unless a previous history reference occurred
on the same line in which case this form repeats the previous reference. Thus 'l?foo?1 1$' gives the first and last
arguments from the command matching '?foo?l.
A special abbreviation of a history reference occurs when
the first non-blank character of an input line is a 'T'.
This is equivalent to 'l:s1 1 providing a convenient shorthand for substitutions on the text of the previous line.
Thus 'TlbTlib' fixes the spelling of 'lib' in the previous
command. Finally, a history substitution may be surrounded
with '{I and '}I if necessary to insulate it from the characters which follow. Thus, after 'Is -ld "'paul l we might do
'l{l}a' to do 'Is -ld "'paula l , while ~11al would look for a
command starting 'la'.
Quotations with
I
and •
The· quotation "of strings by .. I I and '" I can be used to
prevent all or some of the remainin9substitutions. Strings
enclosed in 'II are prevented any further interpretation.
Strings enclosed in 'ftl are yet variable and command
expanded as described below.
In both cases the resulting text becomes·· (all or part of) a
single word; only in one special case (see Gommand Substiti.tJ.sm below) does a '"I quoted string yield parts of more
than one word; ' I quoted strings never do.
Alias sUbstitution
3-18
eSH (1)
XENIX Programmer's Manual
eSH(l)
The shell maintains a list of aliases which can be established, displayed and modified by the alias and unalias
commands. After a command line is scanned, it is parsed
into distinct commands and the first word of each command,
left-to-right, is checked to see if it has an alias. If it
does, then the text which is the alias for that command is
reread with the history mechanism available as though that
command were the previous input line. The resulting words
replace the command and argument list. If no reference is
made to the history list, then the argument list is left
unchanged.
Thus if the alias for 'Is' is 'Is -1' the command 'Is /usr'
would map to 'Is -1 /usr', the argument list here being
undisturbed. Similarly if the alias for 'lookup' was 'grep
!T /etc/passwd' then 'lookup bill' would map to 'grep bill
/etc/passwd' •
If an alias is found, the word transformation of the input
text is performed and the aliasing process begins again on
the reformed input line. Looping is prevented if the first
word of the new text is the same as the old by flagging it
to prevent further aliasing. Other loops are detected and
cause an error.
Note that the mechanism allows aliases to introduce parser
metasyntax. Thus we can 'alias print 'pr \1* I lpr" to
make a command which ~'~ its arguments to the line printer.
Variable substitution
The shell maintains a set of variables, each of which has as
value a list of zero or more words. Some of these variables
are set by the shell or referred to by it. For instance,
the ~ variable is an image of the shell's argument list,
and words of this variable's value are referred to in special ways.
The values of variables may be displayed and changed by
using the ~ and unset commands. Of the variables referred
to by the shell a number are togglesl the shell does not
care what their value is, only whether they are set or not.
For instance, the verbose variable is a toggle which causes
command input to be echoed. The setting of this variable
results from the -v command line option.
Other operations treat variables numerically. The '@' command permits numeric calculations to be performed and the
result assigned to a variable. Variable values are, however, always represented as (zero or more) strings. For the
purposes of numeric operations, the null string is considered to be zero, and the second and subsequent words of
3-19
csa (1)
XENIX Programmer's Manual
CSH(l)
multiword values are ignored.
After the input line is aliased and parsed, and before each
command is executed, variable substitution is performed
keyed by '$' characters. This expansion can be prevented by
preceding the "'$' with a .. \' except within ''''s where it
always occurs, and within ""s where it never occurs.
Strings quoted by ..... ' are interpreted later (see Commang
subst;j,tution below) so "'$' substitution does not occur there
until later, if at all. A '$' is passed unchanged if followed by a blank, tab, or end-of-line.
Input/output redirections are recognized before variable
expansion, and are variable expanded separately. Otherwise,
the command name and entire argument list are expanded
together. It is thus possible for the first (command) word
to this point to generate more than one word, the first of
which becomes the command name, and the rest of which become
arguments.
Unless enclosed in . . ". or given the ':q' modifier the
results of variable substitution may eventually be command
and filename substituted. Within ..... , a variable whose value
consists of multiple words expands to a (portion of) a single word, with the words of the variables value separated by
blanks. When the ":q' modifier is applied to a sUbstitution
the variable will expand to multiple words with each word
separated by a blank and quoted to prevent later command or
filename substitution.
The following meta sequences are provided for introducing
variable values into the shell input. Except as noted, it
is an error to reference a variable which is not set.
$name
${name}
Are replaced by the words of the value of variable
.na.m.e., each separated by a blank. Braces insulate .ruun.e.
from following characters which would otherwise be part
of it. Shell variables have names consisting of up to
29 letters, digits, and underscores.
If name is not a shell variable, but is set in the environment, then that value is returned (but : modifiers and the
other forms given below are not available in this case).
$name[selector]
${name[selector]}
May be used to select only some of the words from the
value of ~. The selector is subjected to '$' substitution and may consist of a single number or two
numbers separated by a "'-'. The first word of a
3-28
:SB (1)
CSB (1)
XENIX Programmer's Manual
variables value is numbered '1'. If the first number
of a range is omitted it defaults to 'I'. If the last
member of a range is omitted it defaults to '$#name'.
The selector '*' selects all words. It is not an error
for a range to be empty if the second argument is omitted or in range.
$#name
${#name}
Gives the number of words in the variable.
useful for later use in a '[selector] '.
$0
This is
Substitutes the name of the file from which command
input is being read. An error occurs if the name is
not known.
$number
${number}
Equivalent to '$argv[number] '.
$*
Equivalent to '$argv[*] '.
The modifiers ':h', ':t', ':r', ':q' and ':x' may be applied
to the substitutions above as may ':gh', ':gt' and ':gr'.
If braces '{' '}' appear in the command form then the modifiers must appear within the braces. The current implementation allows only one ':' modifier on each '$' expansion.
The following substitutions may not be modified with ,
modifiers.
.. ,
$?name
${?name}
Substitutes the string 'I' if name is set, '0' if it is
not.
$?0
Substitutes "I' if the current input filename is know,
'0' if it is not.
$$
Substitute the (decimal) process number of the (parent)
shell.
Command and filename substitution
The remaining substitutions, command and filename substitution, are applied selectively to the arguments of builtin
commands. This means that portions of expressions which are
not evaluated are not subjected to these expansions. For
3-21
CSH{I}
XENIX Programmer's Manual
eSB(I)
commands which are not internal to the shell, the command
name is substituted separately from the argument list. This
occurs very late, after input-output redirection is performed, and in a child of the main shell.
Command substitution
Command substitution is indicated by a command enclosed in
"~I.
The output from such a command is normally broken into
separate words at blanks, tabs and newlines, with null words
being discarded, this text then replacing the original
string. Within 'n,s, only newlines force new words; blanks
and tabs are preserved.
In any case, the single final newline does not force a new
word. Note that it is thus possible for a command substitution to yield only part of a word, even if the command outputs a complete line.
Filename substi tution
If a word contains any of the character s '*', '1', '[' or
'{I or begins with the character '-', then that word is a
candidate for filename substitution, also known as 'globbing'. This word is then regarded as a pattern, and
replaced with an alphabetically sorted list of file names
which match the pattern. In a list of words specifying
filename substitution it is an error for no pattern to match
an existing file name, but it is not required for each pattern to match. Only the metacharacters '*', '?' and ' [ I
imply pattern matching, the characters '-I and ' { I being
more akin to abbreviations.
In matching filenames, the character '.' at the beginning of
a filename or immediately following a 'II, as well as the
character '/' must be matched explicitly. The character '*'
matches any string of characters, including the null string.
The character '1' matches any Single character. The
sequence '[ •• el' matches anyone of the character s enclosed.
Within '[ ••• ] " a pair of characters separated by '_I
matches any character lexically between the two.
The character '-I at the beginning of a filename is used to
refer to home directories. Standing alone, i.e. '-I it
expands to the invokers home directory as reflected in the
value of the variable ~. When followed by a name consisting of letters, digits and '_I characters the shell searches
for a user with that name and substitutes their home directory; thus '-ken' might expand to '/usr/ken' and
'-ken/chmach' to '/usr/ken/chmach'. If the character '-I is
followed by a character other than a letter or '/' or
appears not at the beginning ofa word, it is left
3-22
:SB (1)
XENIX Programmer's Manual
CSB (1)
undisturbed.
The metanotation 'a{b,c,d}e' is a shorthand .for 'abe ace
adele Left to right order is preserved, with results of
matches being sorted separately at a low level to preserve
this order. This construct may be nested. Thus
'-source/sl/{oldls,ls}.c' expands to '/usr/source/sl/oldls.c
/usr/source/sl/ls.c' whether or not these files exist
without any chance of error if the home directory for
'source' is '/usr/source'. Similarly ' •• /{memo,*box}, might
expand to ' •• /memo •• /box •• /mbox'. (Note that 'memo' was
not sorted with the results of matching '*box-'.) As a special case '{I, 'I' and '{I' are passed undisturbed.
Input/output
The standard input and standard output of a command may be
redirected with the following syntax:
< name
Open file ~ (which is first variable, command and
filename expanded) as the standard input.
« word
Read the shell input up to a line which is identical to
~ is not subjected to variable, filename or
command substitution, and each input line is compared
to E.I.S1 before any substitutions are done on this input
line. Unless a quoting '\', '.', '" or " I appears in
~ variable and command substitution is performed on
the intervening lines, allowing '\1 to quote '$1, '\1
and " I . Commands which are substituted have all
blanks, tabs, and newlines preserved, except for the
final newline which is dropped. The resultant text is
placed in an anonymous temporary file which is given to
the command as standard input.
~.
> name
>1 name
>& name
>&1 name
The file ~ is used as standard output. If the file
does not exist then it is created, if the file exists,
its is truncated, its previous contents being lost.
If the variable nOQlobber is set, then the file must
not exist or be a character special file (e.g. a terminal or '/dev/null') or an error results. This helps
prevent accidental destruction of files. In this case
the ' I ' forms can be used and suppress this check.
The forms involving '&' route the diagnostic output
3-23
CSB (1)
XENIX Programmer's Manual
CSB(l)
into the specified file as well as the standard output.
is expanded in the same way as '' but places
output at the end of the file. If the variable
noclobber is set, then it is an error for the file not
to exist unless one of the ' ! ' forms is given. Otherwise similar to '>'.
If a command is run detached (followed by '&') then the
default standard input for the command is the empty file
'/dev/null'. Otherwise the command receives the environment
in which the shell was invoked as modified by the inputoutput parameters and the presence of the command in a pipeline. Thus, unlike some previous shells, commands run from
a file of shell commands have no access to the text of the
commands by default; rather they receive the original standard input of the shell. The '«' mechanism should be used
to present inline data. This permits shell command scripts
to function as components of pipelines and allows the shell
to block read its input.
Diagnostic output may be directed through a pipe with the
standard output. Simply use the form '/&' rather than just
,/'
.
Expressions
A number of the builtin commands (to be described subsequently) take expressions, in which the operators are similar to those of C, with the same precedence. These expressions appear in the @, ~, if, and while commands. The
following operators are available:
/
%
"
&&
1
(
/
)
T & ==
1= <= >= < > «
»
+
*
Here the precedence increases to the right, '==' and '1=',
, <=' '> = '<' and '>', , <<, and'" >> " . . +' and '-', , *' . . / '
and '%' being, in groups, at the same level. The '==' and
'1=' operatoI:'s compare their arguments as strings, all others operate on numbers. Strings which begin with '9' are
considered octal numbers. Null or missing arguments are
considered '9'. The result of all expressions are strings,
which represent decimal numbers. It is important to note
that no two components of an expression can appear in the
same word; except when adjacent to components of expressions
I
3-24
XENIX Programmer's Manual
:SH (1)
CSH (1)
which are syntactically significant to the parser ('&' 'I'
'IT (1)
XElnx Programmer I s Manual
EDIT(I)
~ME
edit - text editor (variant of the ex editor for new or
casual user s)
{NOPSIS
edit [ -r ] name
...
ESCRIPTION
~ is a variant of the text editor ~ recommended for new
or casual users who wish to use a command oriented editor.
The following brief introduction should help you get started
with ~. A more complete basic introduction is provided by
~: A tutorial • A ~/~ command summary (yersion z.a)
is also very useful. See ~(l) for other useful documents;
in particular, if you are using a CRT terminal you will want
to learn about the display editor ~.
,RIEF INTRODUCTION
To edit the contents of an existing file you begin with the
command "edit name' I to the shell. ~ makes a copy of
the file which you can then edit, and tells you how many
lines and characters are in the file. To create a new file,
just make up a name for the file and try to run ~ on it;
you will cause an error diagnostic, but don't worry.
prompts for commands with the character ':1, which you
should see after starting the editor. If you are editing an
existing file, then you will have some lines in ~I~
buffer (its name for the copy of the file you are editing).
Most commands to ~ use its "current line l I if you donlt
tell them which line to use. Thus if you say print (which
can be abbreviated p) and hit carriage return (as you should
after all ~ commands) this current line will be printed.
If you delete (d) the current line, ~ will print the new
current line. When you start editing, ~ makes the last
line of the file the current line. If you delete this last
line, then the new last line becomes the current one. In
general, after a delete, the next line in the file becomes
the current line. (Deleting the last line is a special
case. )
~
If you start with an empty file, or wish to add some new
lines, then the append Ca) command can be used. After you
give this command (typing a carriage return after the word
append) ~ will read lines from your terminal until you
give a line consisting of just a ".11, placing these lines
after the current line. The last line you type then becomes
the current line. The command insert Ci) is like append but
places the lines you give before, rather than after, the
current line.
3-41
EDIT(l)
XENIX Programmer's Manual
~
and
again to get it back.
cannot be undone.
EDIT (1)
Note that commands such as write
~
To look at the next line in the buffer you can just hit carriage return. To look at a number of lines hit AD (control
key and, while it is held down D key, then let up both)
rather than carriage return. This will show you a half
screen of lines on a CRT or 12 lines on a hardcopy terminal.
You can look at the text around where you are by giving the
command "z.". The current line will then be the last line
printed; you can get back to the line where you were before
the "z." command by saying "" ". The z command can also
be given other following characters "z-" prints a screen
of text (or 24 lines) ending where you are; "z+" prints
the next screenful. If you want less than a screenful of
lines do, e.g., '·z.12" to get 12 lines total. This method
of giving counts works in general; thus you can delete 5
lines starting with the current line with the command
"delete 5".
To find things in the file you can use line numbers if you
happen to know them; since the line numbers change when you
insert and delete lines this is somewhat unreliable. You
can search backwards and forwards in the file for strings by
giving commands of the form /text/ to search forward for
l l l l or ?text? to search backward for ~. If a search
reaches the end of the file without finding the text it
wraps, end around, and continues to search back to the line
where you are. A useful feature here is a search of the
form /A text / which searches for ~ at the beginning of a
line. Similarly /text$/ searches for ~ at the end of a
line. You can leave off the trailing / or ? in these commanas.
The current line has a symbolic name " . " ; this is most
useful in a range of lines as in ".,$print" which prints
the rest of the lines in the file. To get to the last line
in the file you· can refer to it by its symbolic name' '$" •
Thus the command "$ delete" or "$d" deletes the last
line in the file, no matter which line was the current line
before. Arithmetic with line references is also possible.
Thus the line "$-5" is the fifth before the last, and
".+20" is 20 lines after the present.
You can find out which line you are at by doing ".=' '.
This is useful if you wish to move or copy a section of text
within a file or between files. Find out the first and last
line numbers you wish to copy or move (say 10 to 20). For a
move you can then say "10,20move "al' which deletes these
lines from the file and places them in a buffer named A •
.E.di.t has 26 such buffers named A through z.. You can later
get these lines back by doing ""a move ." to put the
3-42
E:DIT(l)
XENIX Programmerls Manual
EDIT (1)
!dit numbers the lines in the buffer, with the first line
having number 1. If you give the command "1 11 then ~
wi~l type this first line.
If you then give the command
delete ~ will delete the first line, and line 2 will
become line 1, and ~ will print the current line (the new
line 1) so you can see where you are. In general, the
current line will always be the last line affected by a commanCl.
You can make a change to some text within the current line
by using the substitute (s) command. You say "S/~/~II
where ~ is replaced by the old characters you want to get
rid of and ~ is the new characters you want to replace it
with.
The command file (f) will tell you how many lines there are
in the buffer you are editing and will say "[Modified] II if
you have changed it. After modifying a file you can put the
buffer text back to replace the file by giving a write (w)
command. You can then leave the editor by issuing a quit
(q) command. If you run ~ on a file, but don't change
it, it is not necessary (but does no harm) to write the file
back. If you try to quit from .e.sti.t. after modifying the
buffer without writing it out, you will be warned that there
has been "No write since last change" and edit will await
another command. If you wish not to write the buffer out
then you can issue another quit command. The buffer is then
irretrievably discarded, and you return to the shell.
By using the delete and append commands, and giving line
numbers to see lines in the file you can make any changes
you desire. You should learn at least a few more things,
however, if you are to use ~ more than a few times.
The change (c) command will change the current line to a
sequence of lines you supply (as in append you give lines up
to a line consisting of only a ".11). You can tell change
to change more than one line by giving the line numbers of
the lines you want to change, i.e. "3,5change ll • You can
print lines this way too. Thus "1,23p l' prints the first
23 lines of the file.
The undo Cu) command will reverse the effect of the last
command you gave which changed the buffer. Thus if give a
SUbstitute command which doesn't do what you want, you can
say undo and the old contents of the line will be restored.
You can also undo an undo command so that you can continue
to change your mind. ~ will give you a warning message
when commands you do affect more than one line of the
buffer. If the amount of change seems unreasonable, you
should consider doing an ~ and looking to see what happened. If you decide that the change is ok, then you can
3-43
EDIT (1)
XENIX Programmer's Manual
EDIT(l)
contents of buffer A after the current line. If you want to
move or copy these lines between files you can give an edit
(e) command after copying the lines, following it with the
name of the other file you wish to edit, i.e. "·edit
chapter2 11 • By changing ~ to ~ above you can get a
pattern for copying lines. If the text you wish to move or
copy is all within one file then you can just say
"lS,2Smove $" for example. It is not necessary to use
named buffers in this case (but you can if you wish).
SEE
ALSO
ex (1), vi (1), 'Edit: A tutorial', by Ricki Blau and James
Joyce
AUTHOR
William Joy
BUGS
See .0.(1) •
3-44
~X
(1)
XENIX Programmer's Manual
EX(l)
~AME
ex - text editor
SYNOPSIS
ex [ -] [-v] [ -t tag ] [ -r ] [ +lineno ] name •••
DESCRIPTION
~ is the root of a family of editors: ~, ~ and ~. ~
is a superset of ~, with the most notable extension being a
display editing facility. Display based editing is the
focus of ~.
If you have not used~, or are a casual user, you will find
that the editor ~ is convenient for you. It avoids some
of the complexities of ~ used mostly by systems programmers
and persons very familiar with ~.
If you have a CRT terminal, you may wish to use a display
based editor: in this case see ~(l), which is a command
which focuses on the display editing portion of ~.
DOCUMENTATION
For ~ and ~ see the !x/~ command summary - version
~.a. The document ~: A tutorial provides a comprehensive
introduction to ~ assuming no previous knowledge of computers or the UNIX system.
The Ex Reference Manual - version ~.a is a comprehensive and
complete manual for the command m~de features of ~, but you
cannot learn to use the editor by reading it. For an introduction to more advanced forms of editing using the command
mode of ~ see the editing documents written by Brian Kernighan for the editor ~: the material in the introductory
and advanced documents works also with ~.
~ Display Editing lli.t.h .vi introduces the
display editor ~ and provides reference material on ~. The
.vi Quick Reference card summarizes the commands of ~ in a
usetul, functional way, and is useful with the Introduction.
An Introduction
FOR ED USERS
If you have used ~ you will find that ~ has a number of
new features useful on CRT terminals. Intelligent terminals
and high speed terminals are very pleasant to use with ~.
Generally, the editor uses far more of the capabilities of
terminals than ~ does, and uses the terminal capability
data base termcap(l) and the type of the terminal you are
using from the variable TERM in the environment to determine
how to drive your terminal efficiently. The editor makes
use of features such as insert and delete character and line
in its visual command (which can be abbreviated vi) and
which is the central mode of editing when using ~(l).
3-45
EX(l)
EX (1)
XENIX Programmer's Manual
There is also an interline editing open
works on all terminals.
(0)
command which
EX contains a number of new features for easily viewing the
text of the file. The z command gives easy access to windows of text. Hitting AD causes the editor to scroll a
half-window of text and is more useful for quickly stepping
through a file than just hitting return. Of course, the
screen oriented visual mode gives constant access to editing
context.
.
EX gives you more help when you make mistakes. The undo (u)
command allows you to reverse any single change which goes
astray. IX gives you a lot of feedback, normally printing
changed lines, and indicates when more than a few lines are
affected by a command so that it is easy to detect when a
command has affected more lines than it should have.
The editor also normally prevents overwriting existing files
unless you edited them so that you don't accidentally
clobber with a write a file other than the one you are editing. If the system (or editor) crashes, or you accidentally
hang up the phone, you can use the editor recover command to
retrieve your work. This will get you back to within a few
lines of where you left off.
EX has several features for dealing with more than one file
at a time. You can give it a list of files on the command
line and use the next (n) command to deal with each in turn.
The next command can also be given a list of file names, or
a pattern as used by the shell to specify a new set of files
to be dealt with. In general, filenames in the editor ma~
be formed with full shell metasyntax. The metacharacter %'
is also available in forming filenames and is replaced by
the name of the current file. For editing large groups of
related files you can use ~'a tag command to quickly locate
functions and other important points in any of the files.
This is useful when working on a large program when you want
to quickly fin4the definition of a particular function.
The command ctags(l) builds a .tas.a. file or a group of C programs.
For moving text between files and within a file the editor
has a group of buffers, named 4 through ~. You can place
text in these named buffers and carry it over when you edit
another file.
.
There is a command & in ~ which repeats the last substitute
command. In addition there is a confirmed substitute command. You give a range of SUbstitutions to be done and the
editor interactively asks whether each substitution is
desired.
3-46
~X
XENIX Programmer's Manual
(1)
EX(l)
You can use the sUbstitute command in ~ to systematically
convert the case of letters between upper and lower case.
It is possible to ignore case of letters in searches and
substitutions. ~ also allows regular expressidns which
match words to be constructed. This is convenient, for
example, in searching for the word "edit" if your document
also contains the word "editor."
~ has a set of options which you can set to tailor it to
your liking. One option which is very useful is the autoin~ option which allows the editor to automatically supply
leading white space to align text. You can then use the AD
key as a backtab and space and tab forward to align new code
easily.
Miscellaneous new useful features include an intelligent
join (j) command which supplies white space between joined
lines automatically, commands < and> which shift groups of
lines, and the ability to filter portions of the buffer
through commands such as ~.
FILES
/usr/lib/ex2.Bstrings
/usr/lib/ex2.Brecover
/usr/lib/ex2.Bpreserve
/etc/termcap
N/. exrc
/tmp/Exnnnnn
/tmp/Rxnnnnn
/usr/preserve
error messages
recover command
preserve command
describes capabilities of terminals
editor startup file
editor temporary
named buffer temporary
preservation directory
SEE ALSO
awk(l), edell, grep(l), sed(l}, edit(l), grepCl),
termcap(l), viCl)
AUTHOR
William JOy
BUGS
The..\1D.S:lQ command causes all marks to be lost on lines
changed and then restored if the marked lines were changed.
llndQ never clears the buffer modified condition.
The £ command prints a number of logical rather than physical lines. More than a screen full of output may result if
long lines are present.
File input/output errors don't print a name if the command
line '_I option is used.
3-47
EX(l)
EX (1)
XENIX Programmer's Manual
There is no easy way to do a single scan ignoring case.
Because of the implementation of the arguments to
512 bytes of argument list are allowed there.
~,
only
The format of /~termcap and the large number of capabilities of terminals used by the editor cause terminal type
setup to be rather slow.
The editor does not warn if text is placed in named buffers
and not used before exiting the editor.
Null characters are discarded in input files, and cannot
appear in resultant files.
3-48
PmPY(l)
PCOn(l)
NAME
fcopy - copy a floppy diskette
SYNOPSIS
fcopy
DESCRIPTION
Fcopy is used to make duplicate copies of either a single
(ACS 8600 only) or double density floppy diskette. FCoPY is
menu dr iven and will ask whether you wish to copy a single
or double density disk or quit. After one copy has been
made, it will ask if you desire to make more copies of the
same diskette •. All disks must have been previously
formatted. See Format to prepare diskettes (Format) before
making copies. Also check to verify there is enough disk
space available by entering the ~ command.
586 OUTPUT
1440
1440
records in
records out
ACS 8690 OUTPUT
for double density disks:
13+0
records in
13+0
records out
900+0
records in
909+9
records out
for single density disks:
500+0
records in
500+0
records out
BUGS
FILES
Since the routine was written for a single floppy disk
system, it reads the entire disk off and then back on,
requiring 1440 blocks of space on the hard disk (for the 586
system) and either 913 or 500 blocks of space on the hard
disk (for the ACS 8600 system).
./junk.?????? Temporary working file, created and subsequently removed by fcopy.
3-49
POBIIH{l)
NAME
POBIIH{l)
format - format a floppy disk while running XENIX
SYNOPSIS
format
DESCRIPTION
Format is a menu-driven program for formatting floppy disks.
For the Altos 586 computer systems, diskettes are formatted
in Altos 5-1/4 inch, double-density, double-sided format.
For the ACS 8600 computer systems, diskettes can be
formatted in either 8-inch standard IBM single-density
format, Altos standard double-density format for XENIX and
for diagnostics, or finally double-sided double-density
format, if that drive is available.
To use the format utility, enter:
format
(CR>
You are then prompted by the menu to select the desired
format and to insert a diskette.
All double-density diskettes are a combina tion of two
formats for the ACS 8600.
See Appendix B in the
Introduction to XBBIX Kanual. The first two cylinders are
single-density, and the rest of the floppy diskette is in
double-density.
3-58
PCOPY(l)
FCOPY {I}
NAME
fcopy - copy a floppy diskette
SYNOPSIS
fcopy
DESCRIPTION
Fcopy is used to make duplicate copies of a floppy diskette.
Fcopy is menu driven and will ask whether you wish to copy a
diskette or quit. After one copy has been made, it will ask
if you desire to make more copies of the same diskette. All
diskettes must have been previously formatted. See ~~
mat(l) to prepare diskettes (format) before making copies.
Also check to verify there is enough disk space available by
entering the df command.
586 OUTPUT
I 44fl+fl
144fl+0
records in
records out
BUGS
Since the routine was written for a single floppy disk
system, it copies the entire diskette to the hard disk and
then copies it from the hard disk to the new diskette requiring 144fl blocks of space on the hard disk (for the 586
system) .
FILES
./junk.?????? Temporary working file, created and subsequently removed by fcopy.
3-4.9
FINGER(l)
FINGER(l)
NAME
finger - user information lookup program
SYNOPSIS
finger [ options ] name
.. .
DESCRIPTION
By default finger lists the login name, full name, terminal
name and write status (as a '*' before the terminal name if
write permission is denied), idle time, login time, and
office-location and phone number (if they are known) for
each current UNIX user. (Idle time is minutes if it is a
single integer, hours and minutes if a ':' is present, or
days and hours if a 'd' is present.)
A longer format also exists and is used by finger whenever a
list of people's names is given. (Account names as well as
first and last names of users are accepted.) This format is
multi-line, and includes all the information described above
as well as the user's home directory and login shell, any
plan which the person has placed- in the file .plan in their
home directory, and the project on which they are working
from the file .project also in the home directory. .
.
Finger options include:
-m
Match arguments only on user name.
-1
Force long output format.
-p
Suppress printing of the
-s
Force short output format.
.~
files
FILES
/etc/utmp
/etc/passwd
/usr/adm/lastlog
-/ • plan
-/ .project
who file
for users names, offices, •••
last login times
plans projects
SEE ALSO
who (1)
BUGS
Only the first line of the .project file is printed.
The encoding of the gcos field is UCB dependent - it knows
that an office '197MC' is '197M Cory Hall', and that '529BE'
is '529B Evans Hall'.
FLEECE(l)
FLEECE (1)
NAME
fleece - look for files in home directories
SYNOPSIS
fleece name
DESCRIPTION
Flee~ looks for the named file in every home directory on
the system and makes a list on standard output of those
which exist.
FILES
/etc/passwd
to find home directories
3-49B
FOLD(l)
FOLD{l)
NAME
fold - fold long lines for finite width output device
SYNOPSIS
fold [ -width ] [ file ••.
DESCRIPTION
.
is a filter which will fold the contents of the
specified files, or the standard input if no files are
specified, breaking the lines to have maximum width width.
The default for width is 80. Width should be a multiple of
8 if tabs are present, or the tabs should be expanded using
expand(l) before coming to fQld.
~~~a
BUGS
If underlining is present it may be messed up by folding.
FOR.'!AT (1)
FOR.:"!AT ( 1)
NAME
format - format a floppy diskette while running XENIX
SYNOPSIS
format
DESCRIPTION
fQLmAt is a menu-driven program for formatting floppy
diskettes.
For the Altos 586 computer systems, diskettes are formatted
in Altos 5-1/4 inch, double-density, double-sided format.
To use the format utility, enter:
format
You are then prompted by the menu to format (and to insert a
diskette) or to quit.
3-5~
FROM(l)
FROM(l}
NAME
from - who is my mail from?
SYNOPSIS
from
DESCRIPTION
.£..r...Q.m pr in tsout the mail header lines in your mailbox file
to show you who your mail is from
FILES
/usr/spool/mail/*
SEE ALSO
mail (1), Mail (1), aemai1 (1)
PSCX(1)
PSCIC(1)
NAME
fsck - file system consistency check and interactive repair
SYNOPSIS
fsck [option] ••• [filesystemJ • • •
DESCRIPTION
Fsck audits and interactively repairs inconsistent conditions for the named file systems.
If a file system is
consistent, then the number of files, number of blocks used,
and number of blocks free are reported. If the file system
is inconsistent, the operator is prompted for concurrence
before each correction is attempted. Most corrections lose
data: all losses are reported. The default action for each
correction is to wait for the operator to respond 'yes' or
"no". Without write permission ~ defaults to -n action.
These options are recognized:
-y
Assume a yes response to all questions
-n
Assume a no response to all questions
-sX
Ignore the actual free list and (unconditionally)
construct a new one by rewriting the super-block of the
file system. The file system should be unmounted while
this is done, or extreme care should be taken that the
system is quiescent and that it is rebooted immediately
afterwards. This precaution is necessary so that the
old, bad, in-core copy of the superblock will not
continue to be used, or written on the file system.
The free list is created with optimal interleaving
according to the specification X:
space free blocks ~ blocks apart in
cylinders of & blocks each.
-S&:~
If X is not given, the values used when the filesystem
was created are used.
If these values were not
specified, then & = 4fiHJ, ~ = 9 is assumed.
-SA
Condi tionally reconstruct the free list. This option
is like -sx except that the free list is rebuilt only
if there were no discrepancies discovered in the file
system.
It is useful for forcing free list
reorganization on uncontaminated file systems.
-S
forces -n.
3-51
PSCK(l)
PSCK(l)
-t
If ~ cannot obtain enough memory to keep its tables,
it uses a scratch file. If the -t is specified, the
file named in the next argument is used as the scratch
file. Without the -t option, ~ prompts if it needs
a scratch file. The file should 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 fsck
completes.
If no file systems are given to ~, then a default list of
file systems is read from the file jetc/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 andjor free i-node
c~unt
incorrect.
Orphaned files and directories (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 checked and must have empty slots in which
entr ies can be made.
This is accomplished by making
"lost+found", copying a number of files to the directory,
and then removing them (before ~ is executed).
3-52
PSCK(l)
PSCK(l)
Checking the raw device is almost always faster.
FILES
/etc/checklist contains default list of file systems to
check.
SEE ALSO
dcheck(l), icheck(l), checklist(S), fs(S), crash(8)
BUGS
I-node numbers for • and •• in each directory should be
checked for validity.
The -b option of icheckll) should be available.
3-53
PU(l)
NAME
Pft(l)
ftp - transfer files between machines
SYNOPSIS
ftp [ -f device ] [ -s speed ] [ name ]
DESCRIPTION
~ allows file transfer between two Altos Computer Systems
via an asynchronous serial channel. On the sending side,
lUlm~ is a file or list of files to be sent.
If lUl~ is If_A,
standard input is sent. On the receiving side, lUl~ is an
existing directory into which the files are received. If
name is omitted, files are received into the current directory. If nam~ is " __ ", received files are written to standard output.
The following options are interpreted by
~:
-.f
The special file device is used to transfer files
between the machines. The ports associated with the
devices on each machine should be connected via a null
modem cable. The default device is /dev/tty6, which
uses port 6.
-a
The transmission rate is set to speed. Currently supported speeds are 1299, 24gB, 4899, and 96BB bits per
second. The default transmission rate is 9699 baud.
is compatible with the ~ program available for Altos
CP/M and MP/M systems, so files can be transferred betwen
CP/M-MP/M systems and Xenix systems. See the CP/M-MP/M
documentation for details of the CP/M-MP/M ~.
~
must be run on both the sending and receiving computer.
The port that .ftR is running on must have login disabled
(see disableCl». Either side may be started first, but
both sides must be started within about 1 minute of each
other. The sending side will output's' every £ew seconds
until communication is established with the other side;
likewise,' the receiving side will output 'w' every few
seconds. During file transfer, .f...tJ2 will output a '.' every
time a 128 byte block is successfully transmitted, and a '1'
every time a block is retransmitted to overcome a transmission error.
~
BUGS
Since MP/M and CP/M pad files with control-Z's (octal 32),
control-Z's are deleted from the end of files sent to Xenix
systems.
Files sent to MR/M and CP/M systems must have filenames
which are legal on those systems. Files sent from MP/M and
CP/M sys~ems to Xenix systems may end up with filenames
P'fP(1)
r.rP(1)
containing and sometimes ending with spaces; the Xenix
shells can deal wi th these filenames if the enti re name is
enclosed in double quotes.
If the cable gets disconnected during transmission, you must
wait for.f..t.ll to die (which might take up to a minute) before
you can restart on the same port, otherwise the first ~
will interfere with the second.
3-55
LAYom(l)
NAME
LAY~(l)
layout - configure a hard disk
SYNOPSIS
layout layout-device 586
DESCRIPTION
creates a table defining a number of "logical
devices" associated with each physical disk in the XENIX
system. Layout records this table on cylinder zer-o of each
disk. Each entry in the table is in the following format:
Lg~~~~
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:
9
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 correspond to device
numbers in the hard disk driver.
Other device numbers are pre-defined in the XENIX kernel as
follows:
19
Future expansion.
11
All of track9.
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».
~
temporary
The options to layout are used to create some very common
layouts.
3-56
FTP(l}
?'TP{l}
containing and sometimes ending with spaces; the Xenix
shells can deal with these filenames if the entire name is
enclosed in double quotes.
If the cable gets disconnected during transmission, you must
wait for ~ to die (which might take up to a minute) before
you can restart on the same port, otherwise the first ~
will interfere with the second.
3-55
BEAD{l}
BEAD (1)
NAME
head - give first few lines
SYNOPSIS
head [ -count]
[ file .••
DESCRIPTION
This filter gives the first coun~ lines of each of the
specified files, or of the standard input.
If count is
omitted it defaults to 10.
SEE ALSO
tail(l)
IllL(l)
IUL(I}
NAME
iul - do underlining
SYNOPSIS
iul [ -i ] [ -t terminal J [ n..a.m.e ••• ]
DESCRIPTION
reads the named files (or standard input if none are
given) and translates occurrences of underscores to the
sequence which indicates underlining for the terminal in
uses, as specified by the environment variable TERM. The-t
option overrides the terminal kind specified in the environment. The file /~termcap is read to determine the appropriate sequences for underlining. If the terminal is incapable of underlining, but it capable of a standout mode
then that is used instead. If the terminal can overstrike,
or handles underlining automatically, ~ degenerates to
~(l).
If the terminal cannot underline, underlining is
ignored.
~
The -i option causes ~ to indicate underlining onto 5
separate line containing appropriate dashes I-'i this is
useful when you want to look at the underlining which is
present in an nrQff output stream on a crt-terminal.
SEE ALSO
man(l), nroff(l)
BUGS
Nroff usually outputs a series of backspaces and underlines
intermixed with the text to indicate underlining.
No
attempt is made to optimize the backward motion.
3-55B
L..~T(l)
LAST(l)
NAME
last - indicate last logins of users and teletypes
SYNOPSIS
last [ -N ] [ name ••• ] [ tty •••
]
DESCRIPTION
Last will look back in the li~m~ file which records all
logins and logouts for information about a user, a teletype
or any group of users and teletypes.
Arguments specify
names of users or teletypes of interest. Names of teletypes
may be given fully or abbreviated. For example 'last 0' is
the same as 'last tty0'. If multiple arguments are given,
the information which applies to any of the arguments is
printed. For example 'last root console' would list all of
"root's" sessions as well as all sessions on the console
terminal. L~ will print the sessions of the specified
users and teletypes, most recent first, indicating the times
at which the session began, the duration of the session, and
the teletype which the session took place on. If the session is still continuing or was cut short by a reboot, ~
so indicates.
The pseudo-user reboot logs in at reboots of the system;
thus
last reboot
will give an indication of mean time between reboot.
Last with no arguments prints a record of all logins and
logouts, in reverse order. The -N option limits the report
to N lines.
If ~ is interrupted, it indicates how far the search has
progressed in ~~m~.
If interrupted with a quit signal
(generated by a control-l) ~ indicates how far the search
has progressed so far, and the search continues.
FILES
/ u s r / a dm/ wtmp
/usr/adm/shutdownlog
SEE ALSO
wtmp(S), ac(8),
login data base
which records shutdowns and reasons
for same
LAYOO'r(1)
LAYOO'.r (1)
USAGE
layout /dev/hd0.1ayout 586
SEE ALSO
map (I) , sizefs(l}
3-57
LS(!)
LS(!)
NAME
Is - List contents of directory
SYNOPSIS
Is [-ltasdrucifgmnICqbxFRA] [Filenames]
DESCRIPTION
For each directory argument, ~ lists the contents of the
directory; for each file argument, ~ repeats its name and
The output is sorted
any other information requested.
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 director ies and their contents.
There are three major listing formats. The format chosen
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
;ormat; when invoked as ~ this format is also used.
The following options are available:
-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 contain instead the major and
minor device numbers.
-t
Sort by time modified (latest first) instead of by
name; as is normal.
-a
List all entr ies;
pressed.
-s
Give size in blocks, including indirect blocks, for
each entry and total blocks.
-d
If argument isa 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.
usually '.' and ' •• ' are not sup-
3-58
LEAVE (I)
LEAVE (1)
NAME
leave - remind you when you have to leave
SYNOPSIS
leave
hhmm ]
DESCRIPTION
Leaye waits until the specified time, then reminds you that
you have to leave. You are reminded 5 minutes and 1 minute
before the actual time, at the time, and every minute
thereafter. When you log off, leave exits just before it
would have printed the next message.
The time of day is in the form hhmm where hh is a time in
hours (on a 12 or 24 hour clock). All times are converted
to a 12 hour clock, and assumed to be in the next 12 hours.
If no argument is given, leave prompts with "When do you
have to leave?". A reply of newline causes .l.e.a...v.a to exit,
othe rw is e the repl y is as sumed to be a time. Th is form is
suitable for inclusion in a .login or .profile.
Leave ignores interrupts, quits, and terminates. To get rid of
it you should either log off or use "kill -9" giving its process
id.
SEE ALSO
calendar(l)
3-571\
LS(l)
LS(l)
NAME
Is - List contents of directory
SYNOPSIS
Is [-ltasdrucifgmnlCqbxFRA] [Filenames]
DESCRIPTION
For each directory argument, ~ lists the contents of the
directory; for each file argument, .l.a repeats its name and
any other information requested.
The output is sorted
alphabetically by default. 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.
There are three major listing formats. The format chosen
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 ".n characters.
The -m flag enables this
formatj when invoked as ~ this format is also used.
The following options are available:
-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 contain instead the major and
minor device numbers.
-t
Sort by time modified (latest first)
name, as is normal.
-a
Lis t all en t r i e s ;
. pressed.
us uall y
I. '
instead of by
and ' •• I are no t
s u p-
-s
Give size in blocks, including indirect blocks, for
each entry and total blocks.
-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.
LS(l)
LS(l)
-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.
-n
List in long format (similary to 1 option), except that
it lists user number rather than file owner.
-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 '1'; 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 II' 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.
-A
List all entries; usually'.' and ' •• ' are suppressed.
The mode printed under the -1 option contains 11 characters
which are interpreted as follows:
the first character is
d
b
c
if the entry is a directory;
if the entry is a block-type special file;
if the entry is a character-type special file;
3-59
LS(l)
LS(l)
m
if the entry is a multiplexor-type character special
file:
if the entry is a plain file.
The next nine 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-ID mode; likewise, the user-execute
permission character is given as ~ if the file has set-userID mode.
The last character of the mode (normally 'x' or '-') is "t"
if the 1000 bit of the mode is on. See .c..hm.Q.d(l) for the
meaning of this mode and instructions on changing the file
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 ID's for 'Is -1'
/etc/group to get group ID'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 "Is s/lpr". On the other hand, not using this setting would make
old shell scripts which used .la. ineffective.
3-68
IAIL (1)
mail
XENIX Programmer's Manual
MAIL (1)
send and receive mail
SYNOPSIS
mail [ -f [ name 1. 1 [ people •••
]
IN'!'RODUCT ION
Bail is a intelligent mail processing system, which has a
command syntax reminiscent of ~ with lines replaced by messages.
Sending mail. To send a message to one or more other people, mail can be invoked with arguments which are the names
of people to send to. You are then expected to type in your
message, followed by an EOT (control-D) at the beginning of
a line. The section below, labeled Replying ~ ~ originating mail, describes some features of mail available to help
you compose your letter.
Reading mail. In normal usage, mail is given no arguments
and checks your mail out of the post office, then printing
out a one line header of each message there. The current
message is initially the first message (numbered 1) and can
be printed using the print command (which can be abbreviated
pl. You can move among the messages much as you move
between lines in ~, with the commands '+' and '-' moving
backwards and forwards, and simple numbers typing the
addressed message.
Disposing .Qf. u.i.l. After examining a message you can delete
Cd) the message or reply (r) to it. Deletion causes the
mail program to forget about the message. This is not
irreversible, the message can be undeleted (u) by giving its
number, or the mail session can be aborted by giving the
exit (x) command. Deleted messages will, however, usually
disappear never to be seen again.
Specifying meseages. Commands such as print and delete
often can be given a list of message numbers as argument to
apply to a number of messages at once. Thus "delete 1 2"
deletes messages 1 and 2, while "delete 1-5" deletes messages 1 through 5. The special name ,'*', addresses all
messages, and "$" addresses the last message1 thus the
command top which ~rints the first few lines of a message
could be used in ' top *1' to print the first few lines of
all messages.
Replying tQ ~ originating mail. You can use the reply command to set up a response to a message, sending it back to
the person who it was from. Text you then ty~e in, up to an
end-of-file (or a line consisting only of a ' .1') defines
the contents of the message. While you are composing a
3-61
MAIL (I)
XENIX Programmer's Manual
MAIL (I)
message, .mail treats lines beginning wi ththe character'-'
specially. For instance, typing "-m" (alone on a line)
will place a copy of the current message into the response
right shifting it by a tabstop. Other escapes will set up
subject fields, add and delete recipients to the message and
allow you to escape to an editor to revise the message or to
a shell to run some commands. (These options will be given
in the summary below.)
Ending ~ mail srocessing session. You can end a mail session with the quit (q) command. Messages which have been
examined go to your mbQx file unless they have been deleted
in which case they are discarded. Unexamined messages go
back to the post office. The -f option causes mail to read
in the contents of your mbQx (or the specified file) for
processing; when you quit mail writes undeleted messages
back to this file.
Personal and systemwide distribution lists. It is also possible to create a personal distribution lists so that, for
instance, you can send mail to "cohorts" and have it go to
a group of people. Such lists can be defined by placing a
line like
alias cohorts bill ozalp sklower jkf mark cory:kridle
in the file .mailrc in your home directory. The current
list of such aliases can be displayed by the alias (a) command in mail. System wide distribution lists can be created
by editing /usr/lib/aliases, see aliases(S} and deliyermail(8); these are kept in a slightly different syntax. In
mail you send, personal aliases will be expanded in mail
sent to others so that they will be able to reply to the
recipients. System wide aliases are not expanded when the
mail is sent, but any reply returned to the machine will
have the system wide alias expanded as all mail goes through
deliyermail. If you edit /usr/lib/aliases, you must run the
program newalia§es(l).
Network .mail (AReA, ~, Berknet) Mail to sites on the
ARPA network and sites within Bell laboratories can be sent
using "name@si te' 'for ARPA-net sites or "machine luser' ,
for Bell labs sites, provided appropriate gateways are known
to the system. (Be sure to escape the ! in Bell si tes when
giving it on a ~ command line by preceding it with an \.
Machines on an instance of the Berkeley network are
addressed as "machine:user", e.g. "csvax:bill". When
addressed from the arpa-net, "csvax:bill " is known as
"csvax.bill@berkeley".
Mail has a number of options which can be set in the .mailrc
file to alter its behavior; thus "set askcc" enables the
3-62
mIL (1)
... aSkcc"
XENIX Programmer's Manual
feature.
MAIL (1)
(These options are summarized below.)
SUMMARY
(Adapted from the "Mail Reference Manual') Each 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. For the commands which take 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 n ~
previous message and prints it.
?
Prints a brief summary of commands.
!
Executes the UNIX shell command which follows.
alias
(a) With no arguments, prints out all
currently-defined aliases. With one argument,
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.
chdir
(c) Changes the user's working directory to that
specified, if given. If no directory is given,
then changes to the user's login directory.
delete
(d) Takes a list of messages as argument and
marks them all as deleted. Deleted messages
will not be saved in mb2x , nor will they be
av.ailable for most other commands.
dp
(also dt) Deletes the current message and prints
the next message. If there is no next message,
mail says .... at EOF."
edit
(e) Takes a list of messages and pOints the text
editor at each one in turn. On return from the
editor, the message is read back in.
exit
(ex or x) Effects an immediate return to the
Shell without modifying the user's system mailbox, his mb2x file, or his edit file in -f •
from
(f) Takes a list of messages and prints their
3-63
MAIL (1)
XENIX Programmer's Manual
MAIL (1)
message headers.
headers
(h) Lists the current range of headers, which is
an 18 message group. If a "+" argument is
given, then the next 18 message group is
printed, and if a "-" argument is given, the
previous 18 message group is printed.
help
A synonym for ?
hold
(ho, also preserve) Takes a message list and
marks each message therein to be saved in the
user's system mailbox instead of in mbQA. Does
not override the delete command.
mail
(m) Takes as argument login names and distribution group names and sends mail to those people.
next
(n like + or CR) Goes to the next message in
sequence and types it. with an argument list,
types the next matching message.
preserve
A synonym for hold.
print
(p) Takes a message list and types out each message on the user's terminal.
quit
(q) Termina tes the session, saving all
undeleted, unsaved messages in the user's mbQx
file in his login directory, preserving all messages marked with hold or preserve or never
referenced in his system mailbox, and removing
all other messages from his system mailbox. If
new mail has arrived during the session, the
message "You have new mail" is given. If
given while editing a mailbox file with the -f
flag, then the edit file is rewritten. A return
to the Shell is effected, unless the rewrite of
edit file fails, in which case the user can
escape with the exit command.
reply
(r) Takes a message list and sends mail to each
message author just like the mail command. The
default message must not be deleted.
respond
A synonym for reply •
save
(s) Takes a message list and a filename and
appends each message in turn to the end of the
file. The filename in quotes, followed by the
line count and character count is echoed on the
user's terminal.
3-64
AIL (1)
XENIX Programmer's Manual
MAIL (I)
set
(se) With no arguments, prints all variable
values. Otherwise, sets option. Arguments are
of the form "option=value" or '''option.''
shell
(sh) Invokes an interactive version of the
shell.
size
Takes a message list and prints out the size in
characters of each message.
top
Takes a message list and prints the top few
lines of each. The number of lines printed is
controlled by the variable toplines and defaults
to five.
type
(t) A synonym for print •
unalias
Takes a list of names defined by alias commands
and discards the remembered groups of users.
The group names no longer have any significance.
undelete
(u) Takes a message list and marks each one as
nQt being deleted.
unset
Takes a list of option names and discards their
remembered values; the inverse of set •
visual
(v) Takes a message list and invokes the display
editor on each message.
write
(w) A synonym for save •
xit
(x) A synonym for exit.
Here is a summary of the tilde escapes, which are used when
composing messages to perform special functions. Tilde
escapes are only recognized at the beginning of lines. The
name "t11de escape" is somewhat of a misnomer since the
actual escape character can be set by the option escape.
-1 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"
directory into the message.
from your home
Invoke the text editor on the message collected
so far. After the editing session is finished,
you may continue appending text to the message.
3-65
MAIL (1)
XENIX Programmer's Manual
MAIL (1)
Edit the message header fields by typing each
one in turn 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 the 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.
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 screen
editor. After you quit the editor, you may
resume appending text to the end of your message.
-w filename write the message onto the named file.
-Icommand
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. The command fmt(l) is often used
as .command to rejustify the message.
Insert the string of text in the message prefaced by a single -. If you have changed the
escape character, then you should double that
character in 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 the actual value is of interest. The binary
opt~ons include the following:
append
Causes messages saved in mQQx to be appended
to the end rather than prepended. (This is
3-66
AIL (I)
XENIX Programmer's Manual
MAIL (I)
set in /usr/lib/Mail.rc on version 7 systems.)
ask
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.
askcc
Causes you to be prompted for additional carbon copy recipients at the end of each message. Responding with a newline indicates
your satisfaction with the current list.
autoprint
Causes the delete command to behave like dp thus, after deleting a message, the next one
will be typed automatically.
ignore
Causes interrupt signals from your terminal
to be ignored and echoed as @'s.
metoo
Usually, when a group 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.
quiet
Suppresses the printing of the version when
first invoked.
save
Causes the message collected prior to a
interrupt to be saved on the file
"dead.letter" in your home directory on
receipt of two interrupts (or after a -q.)
The following options have string values:
EDITOR
Pathname of the text editor to use in the
edit command and -e escape. If not defined,
then a default editor is used.
SHELL
Pathname of the shell to use in the ! command
and the -1 escape. A default shell is used
if this option is not defined.
VISUAL
Pathname of the text editor to use in the
visual command and -v escape.
escape
If defined, the first character of this
option gives the character to use in the
place of - to denote escapes.
record
If defined, gives the pathname of the file
used to record all outgoing mail. If not
3-67
MAIL (1)
XENIX Programmer's Manual
MAIL (1)
defined, then outgoing mail is not so saved.
toplines
FILES
If defined, gives the number of lines of a
message to be printed out with the top command; normally, the first five lines are
printed.
/usr/spool/mail/*
-/mbox
-/.mailrc
/tmp/R#
/usr/lib/Mail.help*
/usr/lib/Mail.rc
/bin/mail
/etc/delivermail
post office
your old mail
file giving initial mail commands
temporary for editor escape
help files
system initialization file
to do actual mailing
postman
SEE ALSO
binmail(l), fmt(l), newaliases(l), aliases(S), delivermail (8)
'The Mail Reference Manual'
AUTHOR
Kurt Shoens
BUGS
3-68
MAKE.HD(l)
MAKE.BD(l)
NAME
make.hd - initialize a hard disk
SYNOPSIS
make.hd [ swapblocks [inodes] ]
DESCRIPTION
The make.hd command initializes the hard disk for use with
Xenix. The operator is prompted for the size of the hard
disk (l~, 2~, 3~, or 4~ megabytes), and then make.hd creates
the layout table, builds the bad sector map, makes the
special files, and then asks the operator to re-boot the
system. The load.bd command can then be used to copy the
rest of the utilities to the hard disk.
The swapblocks option specifies the number of blocks in the
swap area; if not specified, the default value of swapblocks
depends on the size of the hard disk as shown below.
Likewise, the inodes option specifies the number of i-nodes
and if it is not specified, the default value of ioodes
depends on the size of the hard disk as shown below:
hard disk size
l~ megabytes
2~ megabytes
3~ megabytes
4~ megabytes
SEE ALSO
1 a you t ( 1)
EXAMPLE
make.hd
1
default
swap blocks
332~
332~
5l2~
5l2~
rna P ( I), s i z e f s ( I )
3~~~
default
i-nodes
5~00
3-68A
6~~~
6~~~
.
l~~~~
l~~~~
MAKEWBA~IS(l)
NAME
makewhatis - descr ibe what a command is
SYNOPSIS
makewhatis command
...
DESCRIPTION
Makewhatis makes a data base that whatis uses. Makewhatis looks
up a given command and gives the header line from the manual
section. You can then run the man(1) command to get more information.
If the line starts 'name(section ••• ' you can do 'man
section name' to get the documentation for it. Try 'whatis ed'
and then you should do 'man 1 ed' to get the manual.
Whatis is actually just the -f option to the
FILES
/usr/lib/whatis
SEE ALSO
man (1)
Data base
man(1)
command.
RAP (1)
M&P(1)
NAME
map - create an alternate sector map for a hard disk drive
SYNOPSIS
map layout mapfile drive
DESCRIPTION
Map creates a bad sector map, on mapfile, using the layout
information, in layout, created by layout(l).
The last
argument is the logical device name which references the
whole drive.
The standard invocation is:
map /dev/hdS.layout
/dev/hdS.secmap
/dev/hdS
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
ba~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(l), sizefs(l)
3-69
MUL~IUSER(l)
JIOL~IUSBR(l)
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 i~ "yymmdd." Time is entered as a 24hour clock in the form "hhmm."
SEE
ALSO
date(l)
3-7.
KULTIUSER(l}
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 in multiuser mode.
Fi rst, multiuser displays the cur rent system da te 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
da te (1)
3-79
PAGE(l)
PAGE{l)
NAME
page - file perusal filter for crt viewing
SYNOPSIS
~
[-cdflsu]
[-n] [+linenumber]
[+/pattern] [name •.. ]
page more options
DESCRIPTION
Page is a filter which allows examination of a continuous
text one screenful at a time on a soft-copy terminal. It
normally pauses after each screenful, pr inting --More-- at
the bottom of the screen. If the user then types a carriage
return, one more line is displayed.
If the user hits a
space, another screenful is displayed. Other possibilities
are enumerated later.
The command line options are:
-n
An integer which is the size (in lines) of the window
which more will use instead of the default.
-c
~
-d
~
-f
This causes page to count logical, rather than screen
lines.
That is, long lines arc not folded.
This
options is recommended if nroff output is being piped
through .u.l, since the latter may generate escape
sequences.
These escape sequences contain characters
which would ordinarily occupy screen positions, but
which do not print when they are sent to the terminal
as part of an escape sequence.
Thus page may think
that lines are longer than they actually are, and fold
1 ines erroneously.
-1
Do not treat . . L (form feed) specially. If this option
is not given, ~~ will pause after any line that
contains a . . L, as if the end of a screenful had been
reached. _~lso, if a file begins with a form feed, the
screen will be cleared before the file is printed.
will draw each page by beginning at the top of the
screen and erasing each line just before it draws on
it. This avoids scrolling the screen, making it easier
to read while more is writing.
This option will be
ignored if the terminal does not have the ability to
clear to the end of a line.
will prompt the user with the message "Hi t space
to continue, Rubout to abort" at the end of each
screenful. This is useful if page is being used as a
filter in some setting, such as a class, where many
users may be unsophisticated.
PAGE (I)
-s
Squeeze multiple blank lines from the output, producing
only one blank line. Especially helpful when viewing
nroff output, this option maximizes the useful informa~
tion present on the screen.
-u
Normally, ~ will handle underlining such as produced
by nroff in a manner appropriate to the particular
terminal:
if the terminal can perform underlining or
.has a stand-out mode, page will output appropriate
escape sequences to enable underlining or stand-out
mode for underlined information in the source file.
The -u option suppresses this processing.
+linenumber
Start up at linenumber.
+/pattern
Start up two lines before the line containing the
regular expression pattern.
The screen is cleared before each screenful is printed (but
only if a full screenful is being printed), and k - 1 rather
than k - 2 lines are printed in each screenful, where k is
the number of lines the terminal can display.
~
looks in the file /etc/termcap to determine terminal
character istics, and to detez:mine the defaul t window siz eQ
On a terminal capable of displaying 24 lines, the defaul
window size is 22 lines.
looks in the environment variable MORE to pre-set any
flags desired. For example, if you prefer to view files
using the -c mode of operation, the csh command setenv MORE
-c or the sh command sequence MORE= l-C I i expor t MORE woul:
cause all invocations of pag~, including invocations by
programs such as man and IDASa, to use this mode. Normally,
the user will place the command sequence which sets up "
MORE environment variable in the .cshrc or .profile filee
~
If page is
percentage
This gives
lines) that
reading from a file, rather than a pipe, then
is displayed along with the --More-- prompt.
the fraction of the file (in characters, not
has been read so far.
Other sequences which may be typed when page pauses, and
their effects, are as follows (i is an optional integer
argument, defaulting to 1):
i
display i more lines,
argument is given)
... D
(or another screenful
display 11 more lines (a "scroll").
then the scroll size is set to i.
3-7~B
If i
is
if no
gillen~
PAGE(l)
PAGE (1)
~D
d
same as
iz
same as typing a space except that i,
becomes the new window size.
is
skip i lines and print a screenful of lines
if
skip i screenfuls and print a screenful of lines
q or Q
Exit from
(control-D)
if pr esent,
~.
=
Display the current line number.
v
Start up the editor Yi at the current line.
h
Help command;
commands.
give a description of all the more
i/expr
search for the i-th occurrence of the regular expression expr.
If there are less than i occurrences of
expr, and the input is a file (rather than a pipe),
then the position in the file remains unchanged.
Other~ise, a screenful is displayed, starting two lines
bef or e the place wher e the expr es s ion W(1S found. The
user's erase and kill characters may be used to edit
the regular expression. Erasing back past the first
column cancels the search command.
in
search for the i-th occurrence of the last regular
expression entered.
(single quote)
Go to the point from which the last
search started. If no search has been performed in the
current file, this command goes back to the beginning
of the file.
!corrunand
invoke a shell with command. The characters 1%1 and
'I' in "command" are replaced with the current file
name and the previous shell command respectively.
If
there is no current file name, '%1 is not expanded.
The sequences "\%" and "\1" are replaced by "%" and "!"
respectively.
i:n
skip to the i-th next file given in the command line
(skips to last file if n doesn't make sense)
i:p
skip to the i-th previous file given in the command
line. If this command is given in the middle of printing out a file, then ~ goes back to the beginning of
PAGE(l}
PAGE(l)
the file. If i doesn't make sense, page skips back to
the first file.
If page is not reading from a file,
the bell is rung and nothing else happens.
:f
display the current file name and line number.
: q or : Q
exit from
~
(same as q or
Q) •
(dot) repeat the previous command.
The com man d s take e f f e c tim me d i a tel y, i. e. , i t is no t
necessary to type a carriage return. Up to the time when
the command character itself is given, the user may hit the
line kill character to cancel the numerical argument being
formed. In addi tion, the user may hi t the erase character
to redisplay the --More--(xx%) message.
At any time when output is being sent to the terminal, the
us e rca n hit t he qui t key ( no r mally con t r 01- \) . P age will
stop sending output, and will display the usual --More-prompt. The user may then enter one of the above commands
in the normal manner. Unfortunately, some output is lost
when this is done, due to the fact that any characters
wai ting 'in the terminal's output queue are flushed when the
quit signal occurs.
The terminal is set to noecho mode by this program so that
the output can be continuous. What you type will thus not
show on your terminal, except for the / and ! commands.
If the standard output is not a teletype, then ~~ acts
just like ~, except that a header is printed before each
file (if there is more than one) •
A sample usage of page in previewing nroff output would be
nroff -ms +2 doc.nlpage -s
FILES
/etc/termcap
/usr/lib/more.help
Terminal data base
Help file
SEE ALSO
csh(l) f man(l),
environ(7)
more(l),
msgs(l)
1
script(l)
f
sh(l),
I4.AP(1)
MAP(l)
NAME
map - create an alternate sector map for a hard disk drive
SYNOPSIS
map layout mapfile drive
DESCRIPTION
M.~ creates a bad sector map, on mapf ile, using the layout
information, in layout, created by layout(l}.
The last
argument is the logical device name which references the
whole dr i vee
The standard invocation is:
map
/dev/hd~.layout
/dev/hd~.secmap
/dev/hd3
The structure used for the bad sector to alternate sector
mapping is as follows:
struct mapsec {
int
bad_cyl;
char badJledi
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(l), sizefs(l)
3-69
DCOD (ll4)
GCOD ( IX)
NAME
mkconf - generate configuration tables
. SYNOPSIS
mkconf
DESCRIPTION
Mkconf examines a machine configuration table on its standard input.
Its output is a f ile s:..~, which contains a
vectored interrupt switch, block and character device switch
tables and declarations for system variables.
Input to mkconf is a sequence of lines.
describe devices on the machine:
c8
lp
cf
cd
mf
mw
wp
sa
The following
(Central Data 8 line serial interface)
(Line printer)
(Central Data floppy controller)
(Central Data cartridge disk controller)
(Codata mini-floppy controller)
(Codata mini-winchester controller)
(IMI disk interface)
(SA lBBB disk ,controller)
The Codata console is automatically included. Also included
automatically are several pseudo device drivers.
The following lines are also accepted.
root
~
minor
The specified block device (e.g., hp) is used for the
root.
.minor is a decimal number giving the minor
device. This line must appear exactly once.
swap
~
minor
The specified block device is used for swapping.
not given the root is used.
If
pipe .d..e.2 minor
The specified block device is used to store pipes.
not given the root is used.
If
swplo number
nswap numbez;
Sets the origi~ (block number) and size of the area
used for swapplng. By default, the not very useful
numbers 4000 and 872.
tim e z..o..ru; .ds..t.
Change the default timezone to be zone. Zone may be
the name of any timezone in the continental u.S. or the
MXCOfiF ( IH)
MKCONF(l.M)
number of minutes westward of Greenwich. ~ should be
1 if the daylight savings time conversion should be
done.
nbufs ru;un
The number of sys tern buf fe r s is se t to .n..um.
The
default value is taken from the parameter DNBUF in
param.h.
FILES
c.c
output file
SEE ALSO
Device driver descriptions in section 4.
Setting up XENIX, in Volume 2B.
3-69B
MODEI4(l)
MOD EX (1)
N.r..ME
modem - set up tty port to be used with a modem
unmodem - unset modem port
SYNOPSIS
/etc/modem /dev/ttyn
/etc/unmodem /dev/ttyn
DESCRIPTION
The m~m command is used to set up /~ttyn to be used
with a compatible modem.
The modem command should be executed for every port that has a modem attached, every time
the system is booted.
The modem command ensures that a dial-up tty will be logged
out if the user simply hangs up while logged onto the systern.
The XENIX tty device ignores the state of the RTS signal
(Pin 4) by default. This works well with terminals, which
may become momentarily disconnected. However, modems must
be made aware of tbe RTS signal to maintain system security.
The use of the modem command ensures that a particular tty
will be logged out if the RTS signal goes inactive.
The Ynmodem command does the opposite of the modern command,
Le., it tells the kernel to ignore the state of the RTS
signal.
SEE ALSO
disable(l) , tty(4)
DIAGNOSTICS
The modem(l) command will hang if run on a port that has
already been declared a modem port. Do not run modem(l)
tw ice for the same por t.
EXAMPLE
/etc/modem /dev/tty3
fete/modem tty3
These commands are equivalent and tell the system that a
modern is being used on serial port 3.
3-·59C
MORE (I)
MORE (1)
NA11E
more - file perusal filter for crt viewing
SYNOPSIS
more [-cdf1su]
[-n] [+linenumber] [+/pattern]
[name .•• ]
page more options
DESCRIPTION
is a filter which allows examination of a continuous
text one screenfu1 at a time on a soft-copy terminal. It
normally pauses after each screenful, pr in ting --Mor e-- at
the bottom of the screen. If the user then types a carriage
return, one more line is displayed.
If the user hits a
space, another screenful is displayed.
Other possibi1i ties
are enumerated later.
~
The command line options are:
-n
An integer which is the size (in lines) of the window
which m~ will use instead of the default.
-c
M.~ will draw each page by beginning at the top of the
screen and erasing each line just before it draws on
it. This avoids scrolling the screen, making it easier
to read while ID~ is writing.
This option will be
ignored if the terminal does not have the ability to
clear to the end of a line.
-d
M0 r e will pro mp t the use r wit h the me s sag e n Hit spa c e
to continue, Rubout to abort" at the end of each
screenful. This is useful if ID~~ is being used as a
filter in some setting, such as a class, where many
users may be unsophisticated.
-f
This causes ID.Q..l:...a to count logical, rather than screen
lines.
That is, long lines are not folded.
This
options is recommended if nroft output is being piped
through .u.l., since the latter may generate escape
sequences.
These escape sequences contain characters
which would ordinarily occupy screen positions, but
which do not print when they are sent to the terminal
as part of an escape sequence. Thus m~ may think
that lines are longer than they actually are, and fold
lines er roneously.
-1
Do not treat . . . L (form feed) specially. If this option
is not given, more will pause after any line that
contains a . . . L, as if the end of a screenful had been
reached. Also, if a file begins with a form feed, the
screen will be cleared before the file is printed.
3-690
MOR.E(l)
MORE(l)
-s
Squeeze multiple blank lines from the output, producing
only one blank line. Especially helpful when view ing
nroff output, this option maximizes the useful- information present on the screen.
-u
Normally, m~ will handle underlining such as produced
by Droff in a manner appropriate to the particular
terminal:
if the terminal can perform underlining or
has a stand-out mode, m~ will output appropriate
escape sequences to enable underlining or stand-out
mode for underlined information in the source file.
The -u option suppresses this processing.
+linenumber
Start up at linenumber.
+/pattern
Start up two lines before the line containing the
regular expression pattern.
If the program is invoked as page, then the screen is
cleared before each screenful is printed (but only if a full
screenful is being printed), and k - 1 rather than k - 2
lines are printed in each screenful, where k is the number
of lines the terminal can display.
M..Q.U looks in the file /etc/termcap.·to determine terminal
characteristics, and to determine the default window size.
On a terminal capable of displaying 24 lines, the default
window size is 22 lines.
looks in the environment variable MORE to pre-set any
flags desired. For example, if you prefer to view files
using the -c mode of operation, the csh command setenv MORE
-c or the sh command sequence MORE='-C'i export MORE would
cause all invocations of more, including invocations by
programs such as man and msgs, to use this mode. Normally,
the user will place the command sequence which sets up the
MORE environment variable in the .cshrc or .profile file.
~
If m~ is
percentage
This gives
lines) that
reading from a file, rather than a pipe, then a
is displayed along with the --More-- prompt.
the fraction of the file (in characters, not
has been read so far.
Other sequences which may be typed when m~ pauses, and
their effects, are as follows (i is an optional integer
argument, defaulting to 1) :
i
display i more lines,
argument is given)
... D
(or another screenful if no
display 11 more lines (a " s c r 011
then the scroll size is set to i.
11 )
•
If i i sg i v en,
MORE (1)
d
same as AD (control-D)
iz
same as typing a space except tha t
becomes the new window size.
is
skip i lines and print a screenful of lines
if
skip i screenfuls and print a screenful of lines
q or Q
Exit from
i,
if pr esent 1
.Ill.Q...t..a.
=
Display the current line number.
v
Start up the editor Yi at the current line.
h
Help command;
commands.
give a
description
of all
the more
i/expr
search for the i-th occurrence of the regular expression expr.
If there are less than i occurrences of
expr, and the input is a file (rather than a pipe),
then the position in the file remains unchanged.
Otherwise, a screenful is displayed, starting two lines
before the place where the expression was found. The
user's erase and kill characters may be used to edit
the regular expression. Erasing back past the first
column cancels the search command.
in
search for the i-th occurrence of the last regular
expr es si on enter ed.
(single quote)
Go to the point from which the last
search started. If no search has been performed in the
current file, this command goes back to the beginning
of the file.
!cornmand
invoke a shell with command. The characters '%' and
'II in "command" are replaced with the current file
name and the previous shell command respectively.
If
there is no current file name, '%' is not expanded.
The sequences "\%" and "\1" are replaced by 1'%" and "1"
respectively.
i:n
skip to the i-th next file given in the command line
(skips to last file if n doesn't make sense)
i:p
skip to the i-th previous file given in the command
line. If this command is given in the middle of print~
ing out a file, then more goes back to the beginning of
3-69F
MORE (1)
MORE (1)
the file. If i doesn't make sense, ID.Q...I.:..e.. skips back to
the first file.
If m~ is not reading from a file,
the bell is rung and nothing else happens.
:f
display the current file name and line number.
: q or : Q
exit from
~
(same as q or
Q) •
(dot) repeat the previous command •
.
The com mands tak e ef fect immedia tely, i.e., it is not
necessary to type a carriage return. Up to the time when
the command character itself is given, the user may hit the
line kill character to cancel the numerical argument being
formed. In addition, the user may hit the erase character
to redisplay the --More--(xx%) message.
At any time when output is being sent to the terminal, the
use rca n hit the qui t key ( nor mall y con t r 01- \) • M.Q.L..e. will
stop sending output, and will display the usual --More-prompt. The user may then enter one of the above commands
in the normal manner. Unfortunately, some output is lost
when this is done, due to the fact that any characters
waiting in the terminal's'output queue are flushed when the
quit signal occurs.
The terminal is set to noecho mode by this program so that
the output can be continuous. What you type will thus not
show on your terminal, except for the / and ! commands.
If the standard output is not a teletype, then m~ acts
just like ~, except that a header is printed before eacl)
file (if there is more than one) •
A sample usage of more in previewing nroff output would be
nroff -ms +2 doc.nlmore -s
FILES
/etc/termcap
/usr/lib/more.help
Terminal data base
Help file
SEE ALSO
csh(l), man(l), msgs (1), script(l), sh(l), environ(7)
3-69G
PRINTENV(l)
NAME
XENIX Programmer's Manual
PRINTENV(l)
printenv - print out the environment
SYNOPSIS
printenv [ name ]
DESCRIPTION
Printenv prints out the values of the variables in the
environment. If a ~ is specified, only its value is
printed.
If a ~ is specified and it is not defined in the environment, printeny returns exit status 1, else it returns status
~.
SEE ALSO
shell, environ (5) , csh(l)
BUGS
3-71
PS(I)
NAME
XENIX Programmer's Manual
PS(I)
ps - process status
SYNOPSIS
ps [ acgklrstuvwxi [ corefile ] [ swapfile ] [ system ] ]
DESCRIPTION
~ prints certain indicia about active processes.
To get a
complete printout on the console or lpr, use "ps axlgw"
For a quick snapshot of system activity, "ps au" is recommended. A minus may precede options with no effect. The
following options may be specified.
a
aSks for information about all processes with terminals
(ordinarily only one's own processes are displayed).
c
causes only the ~ field to be displayed instead of
the arguments. (The comm field is the tail of the path
name of the file the process last exec'ed.) This option
speeds up ~ somewhat and reduces the amount of output.
It is also more reliable since the process can't scribble on top of it.
g
Asks for all processes. Without this option, 1lli only
prints "interesting" processes. Processes are deemed
to be uninteresting if they are process group leaders,
or if their arguments begin with a '_I. This normally
eliminates shells and getty processes.
k
causes the file /~~/~ is used in place of
and /~~. This is used for postmortem
system debugging.
/~kmem
I
asks for a long listing. The short listing contains
the user name, process ID, tty, the cumulative execution time of the process and an approximation to the
command line.
r
asks for "raw output". A non-human readable sequence
of structures is output on the standard output. There
is one structure for each process, the format is
defined by
s
Print the size of the kernel stack of each process.
This may only be used with the short listing, and is
for use by system developers.
tttyname
restricts output to processes whose controlling tty is
the·specifiedttyname (which should be specified as
printed by~, e.g. ~ for tty3, tconsole for console,tttydQ.for ttydQ, .t.? for processes with no tty,
3-72
XENIX Programmer's Manual
?S (1)
etc).
PS (1)
This option must be the last one given.
u
A user oriented output is produced. This includes the
name of the owner of the process, process id, nice
value, size, resident set size, tty, cpu time used, and
the command.
w
tells ~ you are on a wide terminal (132 columns). ~
normally assumes you are on an 80 column terminal.
This information is used to decide how much of long
commands to print. The w option may be repeated, e.g.
ww, and the entire command, up to 128 characters, will
be printed without regard to terminal width.
x
aSKS even about processes with no terminal.
#
A process number may be given, (indicated here by i),
in which case the output is restricted to that process.
This option must also be last.
A second argument tells ~ where to "look for ~ if the k
option is given, instead of /vrncore. A third argument is
the name of a swap file to use instead of the default
/dev/drum. If a fourth argument is given, it is taken to be
the file containing the system's namelist • Otherwise,
"/vrnunix" is used.
The output is sorted by tty, then by process ID.
The long listing is columnar and contains
F
Flags associated with the process. These are defined
by idefine lines in /usr/include/sys/proc.h.
S
The state of the process. 0: nonexistent; s: sleeping;
W: waiting; R: running; I: intermediate; Z: terminated;
T: stopped.
UID
The user id of the process owner.
PID
The process ID of the process; as in certain cults it
is possible to kill a process if you know its true
name.
PPID The process ID of the parent process.
CPU
Processor utilization for scheduling.
PRI
The priority of the process; high numbers mean low
priority.
NICE Used in priority computation.
3-73
XENIX Programmer's Manual
PS{l)
PS (1)
ADDR The memory address of the process if resident, otherwise the disk address.
SZ
The size in blocks of the memory image of the process.
WCHAN
The event for which the process is waiting or sleeping;
if blank, the process is running.
TTY
The controlling tty for the process.
TIME The cumulative execution time for the process.
COMMAND
The command and its arguments.
A process that has exited and has a parent, but has not yet
been waited for by the parent is marked
To restore the files under /usr/john, check that there is a
directory entry for /usr/john. Use the mkdir command to
create one, if necessary.
Load the first diskette, and enter
cd./uar/jobn (CR>
tar xv (OR>
For more information, see the tutorials in the Introduction.
to XERIX Manual.
3-8'
TRANSP(l)
'l"RAllSP ( 1)
NAME
transp - set up transparent printer
SYNOPSIS
/etc/transp /dev/ttyn /dev/lpm
DESCRIPTION
The trans12 command is used to set up the proper device files
for serial printers hooked to the back of an Altos II terminal.
The /~~ argument specifies which tty device (n)
has the daisy-chained printer attached to its auxiliary
port.
This terminal must be an Altos II terminal.
The
/~1Dm argument specifies the name of the printer device
(e.g., /dev/lp2).
If the specified printer is /dev/lp, then
this will be the default printer in the system.
The transp command creates a link between a tty port and a
printer port.
Once this link is established, it is not
necessary to perform this command again unless the printer
is moved. Output destined for a printer hooked to the back
of an Altos II switches the terminal into transparent mode,
and the terminal becomes inoperative while the printer is
working. When printing stops (i.e., the user program closes
the print device), the terminal becomes active again.
SEE
ALSO
mkn od ( I), tty ( 4 )
EXAMPLE
transp /dev/tty6 /dev/lp
This command sets up serial port 6, which has an Altos II
terminal attached, to also be the default printer port in
the system.
transp /dev/tty5 /dev/lp2
transp tty5 Ip2
transp 5 2
All these commands are equivalent. They set up serial port
5 to also be line printer 2 in the system.
OA(lK)
NAME
OA(II1)
ua -- user administration
SYNOPSIS
.ua [ -h ]
DESCRIPTION
ua 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 ~m~ and curses
facilities 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 .ua:
-h
Displays the program's current version and copyright
notice as well as a short description of the program's
functions.
ua
displays its legal commands at the top of the screen.
The "Command?" prompt at the bottom of the screen indicates
that .ua is awaiting input. The command language syntax is:
[ addldeletelshowlchange ] [ user I group ]
show [ Users I Groups ]
[ help I ?
!
[
]
quit
The system responds as soon as the first letter of a command
is typed. Full command words are not acceptable as input.
The case of each word is significant: "group" is not the
same as "Group."
Typing an interrupt (usually RUBOUT or DEL) will cause YA to
immediately return to the top-level command interpreter.
allows the addition of a new user or group. After
user/group is specified and a new name provided, the system
immediately enters the change command so as to allow
modification of the new entry. At the conclusion of the
change command the addition is made. If a directory already
exists for a new user, it is not removed. All files under
~
3-81
OA(lJl)
OA(lJl)
/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, .profile. The initial value 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 .s.l.l 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..h211 will show an individual user or group or all users or
groups. The word nshown may be omitted if desired.
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 actua~ 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 Ya with the "-h" option.
! 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 ya resumes. If arguments are
present, a shell is invoked with the "-c" option and the arguments are passed along. lla 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 ~A causes an
appropriate message to be displayed. As a side-effect, the
working portion of the screen is cleared.
Us does not distinguish between RETURN and LINE FEED.
may be used interchangably.
They
If the screen becomes "dirty· for some reason, you can force
to clear it and redisplay the current contents by
~A
3-82
OA(a)
UA(a)
transmitting an ASCII "OC2." This is Control-r on most of
the currently popular terminals.
UA understands the Backspace function (as obtained from
/etc/termcap). In addition, any time a word is partially
formed, the ESCape key will cause the partial word to be
discarded and input restarted.
interprets the CANcel key to mean "terminate the current
operation." The CANcel key is Control-x on many of the more
popular terminals. The CANcel key is more powerful than
ESCape, but not so powerful as "interrupt."
llg
US 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.
ua
creates a special user named "standard" in /etc/passwd if
one is not already present.
This entry is used as the
template for installing new users. Thus, if it is desired
to have all new users defaulted to the standard UNIX shell
(/bin/sh) for the Shell field, it is only necessary to
update the Shell field in the "standard" user.
Before adding a new user with a new group, the new group
should be added.
Otherwise, YA has no way to properly
create the new entry in /etc/passwd since it contains group
numbers rather than group names.
During program initialization YA copies /etc/passwd and
/etc/group to /etc/opasswd and /etc/ogroup, respectively.
Thus, if a mistake or disaster occurs during the use of this
program, the user may recover the prior state of either or
both files.
FILES
/etc/passwd
/etc/group
/etc/opasswd
/etc/ogroup
/etc/newuser
/etc/termcap
/tmp/passwd
/tmp/group
/etc/ua.lock
used for login name to user IO conversions
used for group name to group ID conversions
this file is a copy of /etc/passwd before any
modifications are made
this file is a copy of /etc/group before any
modifications are made
directory containing files which will be installed in a new user's account
contains terminal attribute descriptions
temporary file
temporary file
lock file
SEE ALSO
group(5), passwd(5)
3-83
UA(lll)
UA(lll)
DIAGNOSTICS
The diagnostics produced by YA are intended to be selfexplanatory.
BUGS
ua
should allow specification of alternate passwd and group
files.
Complete consistency checking between the /etc/passwd and
/etc/group files is not done. In particular, it is possible
to install a use r 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.
us 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 ya.
ltO:rB:
DO NOT USB JlA If'O SBIJI A USBR'S PASSWORD. The
password would be incorrectly encrypted r and
the user would NOT be able to log in successfully. Passwords may only be set with the
passyd command, explained in PASSWD(l). The
password field displayed by ~ is the
encrypted version contained in /etc/passwd.
3-84
XENIX Programmer's Manual
rI (1)
VI(l)
~AME
vi - screen oriented (visual) display editor based on ex
;YNOPSIS
vi [ -t tag]
-r] [ +lineno ] name •••
DESCRIPTION
Yl (vlsual) is a display oriented text editor based on
~(l).
~ and ~ run the same code; it is possible to get
to the command mode of ~ from within ~ and vice-versa.
The Yi Ouick Reference card and the Introduction ~ Display
Editing ~ Yi provide full details on using 21.
FILES
See
..ez.(l).
SEE ALSO
ex (1), vi (1); "Vi Quick Reference'
tion to Display Editing with Vi' '.
I
card, "An Introduc-
BUGS
Scans with / and? begin on the next line, skipping the
remainder of the current line.
Software tabs using AT work only immediately after the
autoindent.
Left and right shifts on intelligent terminals don't make
use of insert and delete character operations in the terminal.
The wrapmargin option can be fooled since it looks at output
columns when blanks are typed. If a long word passes
through the margin and onto the next line without a break,
then the line won't be broken.
Insert/delete within a line can be slow if tabs are present
on intelligent terminals, since the terminals need help in
dOing this correctly.
Occasionally inverse video scrolls up into the file from a
diagnostic on the last line.
Saving text on deletes in the named buffers is somewhat
inefficient.
The source command does not work when executed as :source;
there is no way to use the :append, :change, and :insert
commands, since it is not possible to give more than one
line of input to a : escape. To use these on a :global you
must Q to ~ command mode, execute them, and then reenter
3-85
VI(l)
XENIX Programmer's Manual
the screen editor with
~
or
~.
3-86
VI(l}
LOCKDG(2)
LOCKIBG(2)
NAME
locking - lock or unlock a record of a file
SYNOPSIS
locking(fildes, ltype, nbytes), int fildes, ltype, nbytes,
DESCRIPTION
locking performs a locking action Itype on a record of the
open file specified by fildes. The record starts at the
current file position and has a length of nbytes. If the
value of nbytes is a, the entire file is locked. Nbytes may
extend beyond the end of the file, in which case only the
process issuing the lock call may access or add information
to the file within the boundary defined by nbytes. Thus,
lock defines a range in the file controlled by the locking
process, and this control may extend to records that have
yet to be added to the end of the file.
The available
values for Itype are:
UNLOCK
a
Unlock the record.
LOCK
1
Lock the given record, the calling process
will sleep if any part of the record has been
locked by a different process.
NBLOCK
2
Lock the given record, if any part of the
record is already locked by a different
process, return the error EACCESS.
RLOCK
3
Same as LOCK except that reading is allowed
by other processes.
NBRLOCK 4
Same as NBLOCK except that reading of the
record is allowed by other processes.
Any process that attempts a read or write on a locked record
will sleep until the record is unlocked. If the record is
locked with an RLOCK then reading is permissible. When a
process terminates, all locked records are unlocked.
SEE ALSO
read (2), write (2), open (2)
DIAGNOSTICS
If an error occurs, -1 is returned. The error code EACCESS
is returned if any portion of the record has been locked by
another process for the LOCK & RLOCK actions. The error
code EDEADLOCK is returned if locking the record would cause
a deadlock. This error code is also returned if there are
no more free internal locks.
3-87
LOCIIM:(2)
LOCUBG(2)
FILES
/usr/include/user.h contains definitions for EACCESS and
EDEADLOCK.
/usr/include/sys/locking.h contains definitions for UNLOCK,
LOCK, NBLOCK, RLOCK, NBRLOCK.
3-88
RDCB(2)
NAME
BDCIIK(2)
rdchk - check if there is data to be read
SYNOPSIS
rdchk(fdes),
int fdes,
DESCRIPTION
Rdchk checks to see if a process will block if it attempts
to read the file designated by fdes. Rdchk returns 1 if
there is data to be read or if it is the end of the file
(EOF) •. In this context, the proper sequence of calls using
rdchk is:
if (rdchk(fildes) > I) read(fildes, buffer, nbytes),
SEE ALSO
read(2)
DIAGNOSTICS
Rdchk returns -1 if an error occurs (e.g., EBADF), S 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 fil.e specified doesn't exist.
3-89
CURSES (3)
NAME
curses - screen functions with "optimal"
SYNOPSIS
~
CURSES (3)
XENIX Programmer's Manual
cursor motion
[ flags 1 files -lcurses -ltermlib [ libraries ]
DESCRIPTION
These routines give the user a method of updating screens
with reasonable optimization. They keep an image of the
current screen, and the user sets up an image of a new one.
Then the refresh () tells the routines to make the current
screen look like the new one. In order to initialize the
routines, the routine initscr () must be called befor e any of
the other routines that deal with windows and screens are
used.
SEE ALSO
Screen Updating ~ Cursor Moyement Optimizgtion: A Library
Packgge, Ken Arnold,
termcap (5), stty (2), setenv (3), setenv (3),
AUTHOR
Ken Arnold
FUNCTIONS
addch(ch)
add a character to stdscr
addstr(str)
add a string to stdscr
box{win,vert,hor)
draw a box around a window
crmode()
set cbreak mode
clear()
clear stdscr
clearok(scr,boolf)
set clear flag for ~
clrtobot()
clear to bottom on stdscr
clrtoeol()
clear to end of line on stdscr
delwin(win)
delete ~
echo ()
set echo mode
eraser)
erase stdscr
getch()
get a char through stdscr
getstr(str)
get a string through stdscr
gettmode ()
get tty modes
getyx(win,y,x)
get (y,x) co-ordinates
inch()
get char at current (y,x) co-ordinates
initscr{)
initialize screens
leaveok(win,boolf)
set leave flag for ~
longname(termbuf,name)
get long name from termbuf
move(y,x)
move to (y,x) on stdscr
mvcur(lasty,lastx,newy,newx) actually move cursor
newwin(lines,cols,begin-y,begin_x) create a new window
nl ()
set newline mapping
nocrmode()
unset cbreak mode
noecho ()
unset echo mode
nonl ()
unset newline mapping
noraw ()
unset raw mode
3-9.
:URSES (j)
XENIX Programmer's Manual
CURSES(3}
overlay (winl,win2)
overlay winl on win2
overwrite (winl,win2)
overwrite winl on top of win2
printw(fmt,argl,arg2, ••• )
printf on stdscr
raw ()
set raw mode
refresh()
make current screen look like stdscr
restty()
reset tty flags to stored value
savetty()
stored current tty flags
scanw(fmt,argl,arg2, ••• )
scanf through stdscr
scroll (win)
scroll ~ one line
scrollok(win,boolf)
set scroll flag
setterm(name)
set term variables for name
unctrl(ch)
printable version of ~
waddch(win,ch)
add char to ~
waddstr(win,str)
add string to ~
wclear(win)
clear ~
wclrtobot(win)
clear to bottom of ~
wclrtoeol(win}
clear to end of line on ~
werase{win)
erase ~
wgetch(win)
get a char through ~
wgetstr(win,str)
get a string through ~
winch (win)
get char at current (y,x) in ~
wmove(win,y,x)
set current (y,x) co-ordinates on ~
wprintw(win,fmt,argl,arg2, ••• ) printf on ~
wrefresh(win)
make screen look like ~
wscanw{win,fmt,argl,arg2, ••• ) scanf through ~
3-91
MBBUS(5)
MENUS
menus
MEJlUS(5)
format of a Business Shell menu system
DESCRIPTION
A menu system is a collection of menus which has been
processed (digested) by digest (1M). The Business Shell,
bsh(l), requires a menu system upon which to operate: it
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 ~ and the actions. A (digested) menu system
contains an additional part, the index. The index appears
prior to the body. It specifies the byte-offset locations
of each of the body and action chapters as well as the
associated menuidentifiers.
Users should never attempt to
construct an index by hand -- that is the function of
digest(IM). Moreover, users should never attempt to edit a
digested menu system; rather, the source menu files should
be edited and then the menu system recreated using
digest(IM} •
The precise format of a menu source file is described below:
&Menuidentifier
The sUbstance of the menu represented
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-92
IIBJIDS(5)
IIBJIUS(5)
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
1date
-a - Receive-mail
-b - Send-mail
-c - Return-to-starting-menu
&Actions
-a
Ii)
mail
-b
-1
echo -n "To whom do you wish to send mail?"
I
read x
I
echo "Now type the message."
I
echo "Terminate it by typing a control -d."
I
mail $x
I-c
I________________________________________________
Start
1
__
&Henuidentifier must appear beginning in column one.
Menuidentifier is any string having relevance to the
user. A short descriptive string is usually best. The
string may not contain any blanks or punctuation and it
must begin with a capital letter. If the string ends
with a ques tion 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 characters not containing punctuation.
Usually
shorter (1-2 character) prompts are preferred.
A
prompt must be separated from its surroundings by one
3-93
MDUS(S)
MDUS(5)
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.
!~ inserts the current date and time, left-justified
on the "!." The date/time format is "Wed Jul 13 17:10
1983." !date may appear more than once if desired.
!user inserts the current user id, left-justi£ied on
the "!." !user may appear more than once if desired.
!lllUl inserts the current directory, left-j ustif ied on
the "!."
The full path name is displayed, e.g.
/usr/jones/admin/currwork.
!pwd may appear more than
once if desired.
!@ 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.
Wi th 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 character," 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 capabilities (usually
true underline).
The "'" 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 "'" 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, "significant spaces" may be
represented as tildes (n-,,) within a string.
Thus,
\-hi-there- will create a highlighted ten-character
string.
3-94
IIBIIOS(5)
JlBllUS(5)
The tilde "-" is an "escape character," and may not be
used for any other purpose 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 chapter 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 chapters 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. CQlumn 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 zerp 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(l) commands or
commands which are executed by the standard shell,
shell. 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.
Shell commands follow the usual rules as described in
Volume 1 of th~ Progra••er's Reference Kanual.
3-95
KBBUS(S)
KBBOS(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-96
~ERMCAP
(5)
XENIX Programmer's Manual
TERMCAP(5)
\lAME
termcap - terminal capability data base
3YNOPSIS
/etc/termcap
DESCRIPTION
Termcap is a data base describing terminals, used, ~.S., by
~(l) and curses(3).
Terminals are described in termcap by
giving a set of capabilities which they have, and by
describing how operations are performed. Padding requirements and initialization sequences are included in termcap.
Entries in termcap consist of a number of ':' separated
fields. The first entry for each terminal gives the names
which are known for the terminal, separated by 'I' characters. The first name is always 2 characters long and is
used by older version 6 systems which store the terminal
type in a 16 bit word in a systemwide data base. The second
name given is the most common abbreviation for the terminal,
and the last name given should be a long name fully identifying the terminal. The second name should contain no
blanks; the last name may well contain blanks for readability.
CAPABILITIES
(P) indicates padding may be specified
(P*) indicates that padding may be based on no. lines affected
Name
ae
al
am
as
bc
bs
bt
bw
CC
cd
ce
ch
cl
cm
co
cr
cs
cv
da
dB
db
dC
Type
str
str
bool
str
str
bool
str
bool
str
str
str
str
str
str
num
str
str
str
bool
num
bool
num
Pad?
(P)
(P*)
(P)
(P)
(P*)
(P)
(P)
(P*)
(P)
(P*)
(P)
(P)
Description
End alternate character set
Add new blank line
Terminal has automatic margins
Start alternate character set
Backspace if not AH
Terminal can backspace with AH
Back tab
Backspace wraps from column B to last column
Command character in prototype if terminal settable
Clear to end of display
Clear to end of line
Like cm but horizontal motion only, line stays same
Clear screen
Cursor motion
Number of columns in a line
Carriage return, (default AM)
Change scrolling region (vtlBB), like cm
Like ch but vertical only.
Display may be retained above
Number of mil Ii sec of bs delay needed
Display may be retained below
Number of millisec of cr delay needed
3-97
TERMCAP(5}
dc
dF
dl
dIn
dN
do
dT
ed
ei
eo
ff
hc
hd
ho
hu
hz
ic
if
im
in
ip
is
kB-k9
kb
kd
ke
kh
kl
kn
ko
kr
ks
ku
IB-19
Ii
11
ma
mi
ml
mu
nc
nd
nl
ns
os
pc
pt
se
sf
sg
so
sr
XENIX Programmer's Manual
str
num
str
str
num
str
num
str
str
str
str
bool
str
str
str
str
str
str
bool
bool
str
str
str
str
str
str
str
str
num
str
str
str
str
str
num
str
str
bool
str
str
bool
str
str
bool
bool
str
bool
str
str
num
str
str
(P*)
(P*)
(P*)
(P)
(P*)
(P*)
(P)
(P)
TERMCAP (5)
Delete character
Number of millisec of ff delay needed
Delete line
Delete mode (enter)
Number of millisec of nl delay needed
Down 0 ne line
Number of millisec of tab delay needed
End delete mode
End insert mode; give :ei=: if ic
Can erase overstrikes with a blank
Hardcopy terminal page eject (default AL)
Hardcopy terminal
Half-line down (forward 1/2 linefeed)
Home cursor (if no cm)
Half-line up (reverse 1/2 linefeed)
Hazeltine; can't print -'s
Insert character
Name of file containing is
Insert mode (enter); give :im=: if ic
Insert mode distinguishes nulls on display
Insert pad after character inserted
Terminal initialization string
Sent by other function keys B-9
Sent by backspace key
Sent by terminal down arrow key
Out of keypad transmit mode
Sent by home key
Sent by terminal left arrow key
Number of other keys
Termcap entries for other non-function keys
Sent by terminal right arrow key
Put terminal in keypad transmit mode
Sent by terminal up arrow key
Labels on other function keys
Number of lines on screen or page
Last line, first column (if no cm)
Arrow key map, used by vi version 2 only
Safe to move while in insert mode
Memory lock on above cursor.
Memory unlock (turn off memory lock).
No correctly working carriage return (DM25BB,H2~
Non-destructive space (cursor right)
Newline character (default \n)
Terminal is a CRT but doesn't scroll.
Terminal overstrikes
Pad character (rather than null)
Has hardware tabs (may need to be set with is)
End stand out mode
Scroll forwards
Number of blank chars left by so or se
Begin standout mode
Scroll reverse (backwards)
3-98
XENIX Programmer's Manual
rERMCAP (5)
ta
tc
te
ti
uc
ue
ug
ul
up
us
vb
ve
vs
xb
xn
xr
xs
xt
str
str
str
str
str
str
num
bool
str
str
str
str
str
bool
bool
bool
bool
bool
(P)
TERMCAP (5)
Tab (other than AI or with padding)
Entry of similar terminal - must be last
String to end programs that use cm
String to begin programs that use cm
Underscore one char and move past it
End underscore mode
Number of blank chars left by us or ue
Terminal underlines even though it doesn't overstri}
Upline (cursor up)
Start underscore mode
Visible bell (may not move cursor)
Sequence to end open/visual mode
Sequence to start open/visual mode
Beehive (fl=escape, f2=ctrl C)
A newline is ignored after a wrap (Concept)
Return acts like ce \r \n (Delta Data)
Standout not erased by writing over it (HP 264?)
Tabs are destructive, magic so char (Teleray le61)
A Sample Entry
The following entry, which describes the Concept-lee, is
among the more complex entries in the termcap file as of
this writing. (This particular concept entry is outdated,
and is used as an example only.)
cllcleelconceptlee:is=\EU\Ef\E7\ES\E8\El\ENH\EK\E\2ee\Eo&\2ee:\
:al=3*\E"R:am:bs:cd=16*\E"'C:ce=16\E"S:cl=2*"L:cm=\Ea%+ %+ :co#8e:\
:dc=16\E~A:dl=3*\E"B:ei=\E\2ee:eo:im=\EAP:in:ip=16*:li#24:mi:nd=\E=:
:se=\Ed\Ee:so=\ED\EE:ta=8\t:ul:up=\E;:vb=\Ek\EK:xn:
Entries may continue onto multiple lines by giving a \ as
the last character of a line, and that empty fields may be
included for readability (here between the last field on a
line and the first field on the next). Capabilities in
termcap are of three types: Boolean capabilities which indicate that the terminal has some particular feature, numeric
capabilities giving the size of the terminal or the size of
particular delays, and string capabilities, which give a
sequence which can be used to perform particular terminal
operations.
Types of Capabilities
All capabilities have two letter codes. For instance, the
fact that the Concept has automatic margins (i.e. an
automatic return and linefeed when the end of a line is
reached) is indicated by the capability am. Hence the
description of the Concept includes am. Numeric capabilities are followed by the character 'if and then the value.
Thus co which indicates the number of columns the terminal
has gives the value '8e' for the Concept.
3-99
TERMCAP(5}
XENIX Programmer's Manual
TERMCAP (5)
Finally, string valued capabilities, such as ce (clear to
end of line sequence) are given by the two character code,
an '=', and then a string ending at the next following ':'.
A delay in milliseconds may appear after the '=' in such a
capability, and padding characters are supplied by the editor after the remainder of the string is sent to provide
this delay. The delay can be either a integer, e.g. '2fiJ',
or an integer followed by an '*', i.e. '3*'. A '*' indicates that the padding required is proportional to the
number of lines affected by the operation, and the amount
given is the per-affected-unit padding required. When a '*'
is specified, it is sometimes useful to give a delay of the
form '3.5' specify a delay per unit to tenths of milliseconds.
A number of escape sequences are provided in the string
valued capabilities for easy encoding of characters there.
A \E maps to an ESCAPE character, ~x maps to a control-x for
any appropriate x, and the sequences \n \r \t \b \f give a
newline, return, tab, backspace and formfeed. Finally,
characters may be given as three octal digits after a \, and
the characters
and \ may be given as \" and \\. If it is
necessary to place a : in a capability it must be escaped in
octal as \072. If it is necessary to place a null character
in a string capability it must be encoded as \2fiJfiJ. The routines which deal with termcap use C strings, and strip the
high bits of the output very late so that a \200 comes out
as a \000 would.
A
Preparing Descriptions
We now outline how to prepare descriptions of terminals.
The most effective way to prepare a terminal description is
by imitating the description of a similar terminal in
termcap and to build up a description gradually, using partial descriptions with ~ to check that they are correct.
Be aware that a very unusual terminal may expose deficiencies in the ability of the termcap file to describe it or
bugs in H. To easily test a new terminal description you
can set the env:ironment variable TERMCAP to a pathname of a
file containing the description you are working on and the
editor will look there rather than in /~/termcap. TERMCAP
can also be set to the termcap entry itself to avoid reading
the file when starting up the editor. (This only works on
version 7 systems.)
Basic capabilities
The number of columns on each line for the terminal is given
by the co numeric capability. If the terminal is a CRT,
then the number of lines on the screen is given by the Ii
capabili ty. If the terminal wraps around to the beginning
3-11'
~ERMCAP
(5)
XENIX Programmer's Manual
TERMCAP (5)
of the next line when it reaches the right margin, then it
should have the am capability. If the terminal can clear
its screen, then this is given by the cl string capability.
If the terminal can backspace, then it should have the bs
capability, unless a backspace is accomplished by a character other than AH (ugh) in which case you should give this
character as the bc string capability. If it overstrikes
(rather than clearing a position when a character is struck
over) then it should have the os capability.
A very important point here is that the local cursor motions
encoded in termcap are undefined at the left and top edges
of a CRT term~nal. The editor will never attempt to backspace around the left edge, nor will it attempt to go up
locally off the top. The editor assumes that feeding off
the bottom of the screen will cause the screen to scroll up,
and the am capability tells whether the cursor sticks at the
right edge of the screen. If the terminal has switch
selectable automatic margins, the termcap file usually
assumes that this is on, i.e. am.
These capabilities suffice to describe hardcopy and glasstty terminals. Thus the model 33 teletype is described as
t3133Itty33:coi72:os
while the Lear Siegler ADM-3 is described as
clladm3131lsi
adm3:am:bs:cl=~Z:lii24:coi80
Cursor addressing
Cursor addressing in the terminal is described by a cm
string capability, with printf(3s) like escapes %x in it.
These sUbstitute to encodings of the current line or column
position, while other characters are passed through
unchanged. If the cm string is thought of as being a function, then its arguments are the line and then the column to
which motion is desired, and the % encodings have the following meanings:
%d
%2
%3
as in printf, 0 origin
like %2d
like %3d
like %c
%.
%+x adds X to value, then %.
%>xy if value > x adds y, no output.
%r
reverses order of line and column, no output
%i
increments line/column (for 1 origin)
%%
gives a single %
%n
exclusive or row and column with 0140 (DM2500)
%B
BCD (16* (x/10» + (x%10), no output.
3-111
TERMCAP(5)
XENIX Programmer's Manual
%D
TERM CAP (5)
Reverse coding (x-2*(x%16», no output. (Delta Data).
Consider the HP2645, which, to get to row 3 and column 12,
needs to be sent \E&a12c03Y padded for 6 milliseconds. Note
that the order of the rows and columns is inverted here, and
that the row and column are printed as two digits. Thus its
cm capability is cm=6\E&%r%2c%2Y. The Microterm ACT-IV
needs the current row and column sent preceded by a AT, with
the row and column simply encoded in binary, cm=~T%.% ••
Terminals which use %. need to be able to backspace the cursor Cbs or bc}, and to move the cursor up one line on the
screen (up introduced below). This is necessary because it
is not always safe to transmit \t, \n AD and \r, as the system may change or discard them.
A final example is the LSI ADM-3a, which uses row and column
offset by a blank character, thus cm=\E=%+ %+ •
Cursor motions
If the terminal can move the cursor one position to the
right, leaving the character at the current position
unchanged, then this sequence should be given as nd (nondestructive space). If it can move the cursor up a line on
the screen in the same column, this should be given as up.
If the terminal has no cursor addressing capability, but can
home the cursor (to very upper left corner of screen) then
this can be given as hOi similarly a fast way of getting to
the lower left hand corner can be given as 11; this may
involve going up with up from the home position, but the
editor will never do this itself (unless 11 does) because it
makes no assumption about the effect of moving up from the
home position.
Area clears
If the terminal can clear from the current position to the
end of the line, leaving the cursor where it is, this should
be given as ce. If the terminal can clear from the current
position to the end of the display, then this should be
given as cd. The editor only uses cd from the first column
of a line.
Insert/delete line
If the terminal can open a new blank line before the line
where the cursor is, this should be given as al: this is
done only from the first position of a line. The cursor
must then appear on the newly blank line. If the terminal
can delete the line which the cursor is on, then this should
be given as dl: this is done only from the first position on
the line to be deleted. If the terminal can scroll the
3-182
rERMCAP(5)
XENIX Programmer's Manual
TERMCAP(5)
screen backwards, then this can be given as sb, but just al
suffices. If the terminal can retain display memory above
then the da capability should be given~ if display memory
can be retained below then db should be given. These let
the editor understand that deleting a line on the screen may
bring non-blank lines up from below or that scrolling back
with sb may bring down non-blank lines.
Insert/delete character
There are two basic kinds of intelligent terminals with
respect to insert/delete character which can be described
using termcap. The most common insert/delete character
operations affect only the characters on the current line
and shift characters off the end of the line rigidly. Other
terminals, such as the Concept 199 and the Perkin Elmer Owl,
make a distinction between typed and untyped blanks on the
screen, shifting upon an insert or delete only to an untyped
blank on the screen which is either eliminated, or expanded
to two untyped blanks. You can find out which kind of terminal you have by clearing the screen and then typing text
separated by cursor motions. Type abc
def using local
cursor motions (not spaces) between the abc and the def.
Then position the cursor before the abc and put the terminal
in insert mode. If typing characters causes the rest of the
line to shift rigidly and characters to falloff the end,
then your terminal does not distinguish between blanks and
untyped positions. If the abc shifts over to the def which
then move together around the end of the current line and
onto the next as you insert, you have the second type of
terminal, and should give the capability in, which stands
for insert null. If your terminal does something different
and unusual then you may have to modify the editor to get it
to use the insert mode your terminal defines. We have seen
no terminals which have an insert mode not not falling into
one of these two classes.
The editor can handle both terminals which have an insert
mOde, and terminals which send a simple sequence to open a
blank position on the current line. Give as im the sequence
to get into insert mode, or give it an empty value if your
terminal uses a sequence to insert a blank position. Give
as ei the sequence to leave insert mode (give this, with an
empty value also if you gave im so). Now give as ic any
sequence needed to be sent just before sending the character
to be inserted. Most terminals with a true insert mode will
not give ic, terminals which send a sequence to open a
screen position should give it here. (Insert mode is
preferable to the sequence to open a position on the screen
if your terminal has both.) If post insert padding is
needed, give this as a number of milliseconds in ip (a
string option). Any other sequence which may need to be
3-183
TERMCAP(S)
XENIX Programmer's Manual
TERMCAP(S)
sent atter an insert of a single character may also be given
in ip.
It is occasionally necessary to move around while in insert
mode to delete characters on the same line (e.g. if there is
a tab after the insertion position). If your terminal
allows motion while in insert mode you can give the capability mi to speed up inserting in this case. Omitting mi will
affect only speed.
Some terminals (notably Datamedia's)
must not have mi because of the way their insert mode works.
Finally, you can specify delete mode by giving dm and ed to
enter and exit delete mode, and dc to delete a single character while in delete mode.
Highlighting, underlining, and visible bells
If your terminal has sequences to enter and exit standout
mode these can be given as so and se respectively. If there
are several flavors of standout mode (such as inverse video,
blinking, or underlining - half bright is not usually an
acceptable standout mode unless the terminal is in inverse
video mode constantly) the preferred mode is inverse video
by itself. If the code to change into or out of standout
mode leaves one or even two blank spaces on the screen, as
the TVI 912 and Teleray 1961 do, this is acceptable, and
although it may confuse some programs slightly, it can't be
helped.
Codes to begin underlining and end underlining can be given
as us and ue respectively. If the terminal has a code to
underline the current character and move the cursor one
space to the right, such as the Microterm Mime, this can be
given as uc. (If the underline code does not move the cursor to the right, give the code followed by a nondestructive
space.)
If the terminal has a way of flashing the screen to indicate
an error quietly (a bell replacement) then this can be given
as vb; it must not move the cursor. If the terminal should
be placed in a different mode during open and visual modes
of ~, this can be given as vs and ve, sent at the start and
end of these modes respectively. These can be used to
change, e.g., from a underline to a block cursor and back.
If the terminal needs to be in a special mode when running a
program that addresses the cursor, the codes to enter and
exit this mode can be given as ti and tee This arises, for
example, from terminals like the Concept with more than one
page of memory. If the terminal has only memory relative
cursor addressing and not screen relative cursor addressing,
a one screen-sized window must be fixed into the terminal
3-184
rERMCAP (5)
XENIX Programmer's Manual
TERMCAP(5)
for cursor addressing to work properly.
If your terminal correctly generates underlined characters
(w~th no special codes needed) even though it does not overstrike, then you should give the capability ul. If overstrikes are erasable with a blank, then this should be indicated by giving eo.
Keypad
If the terminal has a keypad that transmits codes when the
keys are pressed, this information can be given. Note that
it is not possible to handle terminals where the keypad only
wor ks in local (th is applies, for example, to the unshifted
HP 2621 keys). If the keypad can be set to transmit or not
transmit, give these codes as ks and ke. Otherwise the
keypad is assumed to always transmit. The codes sent by the
left arrow, right arrow, up arrow, down arrow, and home keys
can be given as kl, kr, ku, kd, and kh respectively. If
there are function keys such as f9, fl, ••• , f9, the codes
they send can be given as k9, kl, ••• , k9. If these keys
have labels other than the default f9 through f9, the labels
can be given as 19, 11, ••• , 19. If there are other keys
that transmit the same code as the terminal expects for the
corresponding function, such as clear screen, the termcap 2
letter codes can be given in the ko capability, for example,
:ko=cl,ll,sf,sb:, which says that the terminal has clear,
home down, scroll down, and scroll up keys that transmit the
same thing as the cl, 11, sf, and sb entries.
The ma entry is also used to indicate arrow keys on terminals which have single character arrow keys. It is obsolete
but still in use in version 2 of vi, which must be run on
some minicomputers due to memory limitations. This field is
redundant with kl, kr, ku, kd, and kh. It consists of
groups of two characters. In each group, the first character is what an arrow key sends, the second character is the
corresponding vi command. These commands are h for kl, j
for kd, k for ku, 1 for kr, and H for kh. For example, the
mime would be :ma=~KjRZkAXl: indicating arrow keys left
(A H), down (A K), up (A Z), and right (AX). (There is no home
key on the mime.)
Miscellaneous
If the terminal requires other than a null (zero) character
as a pad, then this can be given as pc.
If tabs on the terminal require padding, or if the terminal
uses a character other than AI to tab, then this can be
given as ta.
3-115
TERMCAP (5)
XENIX Programmer's Manual
TERM CAP (5)
Hazeltine terminals, which don't allow ,-, characters to be
printed should indicate hz. Datamedia terminals, which echo
carriage-return linefeed for carriage return and then ignore
a following linefeed should indicate nc. Early Concept terminals, which ignore a linefeed immediately after an am
wrap, should indicate xn. If an erase-eol is required to
get rid of standout (instead of merely writing on top of
it), xs should be given. Teleray terminals, where tabs turn
all characters moved over to blanks, should indicate xt.
Other specific terminal problems may be corrected by adding
more capabilities of the form xz.
Other capabilities include is, an initialization string for
the terminal, and if, the name of a file containing long
initialization strings. These strings are expected to properly clear and then set the tabs on the terminal, if the
terminal has settable tabs. If both are given, is will be
printed before if. This is useful where if is
/~lib/tabset/~ but is clears the tabs first.
Similar Terminals
If there are two very similar terminals, one can be defined
as being just like the other with certain exceptions. The
string capability tc can be given with the name of the similar terminal. This capability must be .J.a.Q.t and the combi.ned
length of the two entries must not exceed 1924. Since termlib routines search the entry from left to right, and since
the tc capability is replaced by the corresponding entry,
the capabilities given at the left override the ones in the
similar terminal. A capability can be canceled with xx@
where xx is the capability. For example, the entry
hn/262lnl:ks@:ke@:tc=262l:
defines a 262lnl that does not have the ks or ke capabilities, and hence does not turn on the function key labels
when in visual mode. This is useful for different modes for
a terminal, or for different· user preferences.
FILES
/etc/termcap
file containing terminal descriptions
SEE ALSO
ex (1), curses (3), termcap (3), tset (1), vi (1), ul (1), more (1)
AUTHOR
William Joy
Mark Horton added underlining and keypad support
BUGS
~
allows only 256 characters for string capabilities, and
3-116
TERMCAP(S)
TERMCAP(S)
XENIX Programmer's Manual
the routines in termcap(~) do not check for overflow of this
buffer. The total length of a single entry (excluding only
escaped newlines) may not exceed 1024.
The ma, vs, and ve entries are specific to the
~
program.
Not all programs support all entries. There are entries
that are not supported by any program.
3-117
1"i't'!'t PH ( 5 )
NAME
ttytype
'HtftPB(5)
- data base defining terminal type; 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
capabilities. Among these programs are vi(l), bsh(l), and
ua (1) •
FILES
/etc/ttytype
SEE ALSO
vi(l), bsh(l), ua(l), termcap(5)
USAGE
A typical line in the ttytype file might look like "dumb
/dev/tty3" or "wyse /dev/tty5." 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 "wyse." The terminal
name is the name found between the first and second vertical
bars of the appropriate entry in /etc/termcap.
3-118
Appendix AI
8UIIBkIC
PO~,
C,
AlII)
pOftBAll
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.
For more information on Fortran 77, see UJlIX Progra•• erls
Volu.e 2B, A Portab~e Fortran 77 ea.piler.
Fortran 77 Flies are opened at end-of-file.
statement to get to the beginning of the file.
A-~
.anDa~,
Use the REWIND
IftBGBR
POBIIA~S
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-complement form.
The range of values is as follows:
Sign and 15 bits
-32,768 to 32,767
Sign and 31 bits
-2,147,483,648 to 2,147,483,647
A-2
PLOATIBG-POIft POlUlATS
Single precision floating point is 32 bits in length, double is
64. The leftmost eight bits consist of an exponent in excess 80
notation. RExcess 80 R means that the hexadecimal values from 80
to FF are positive exponents, corresponding to 0 through 7F.
Values less than 80 are negative exponents; 7F through 0 cor respond to -1 through -7E.
The remaining 24 or 56 bits consist of a leading sign bit and
magnitude values. Magnitudes are normalized. RNormalized" 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. R
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
R.l" has disappeared. It is the unnecessary Rhidden bit." The
binary and hexadecimal values are shown below.
1000 0100 0111 0100 0000 0000 0000 0000
8
4 s 7
4
0
0
0
0
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 •••
A-3
Negative 5.
complement,
negative sign
the sign bit,
excess 8B, -2
In binary, 5 is IB1.
Before taking the twoswe supply a leading zero which will become the
bit: BIB1. ~he twos-complement is IBll. Removing
Bll. Normalizing, .11BB with the exponent-2. In
is 7E. Resul t:
Blll 1119 119B BBBB •••
7
Ese
B •••
Zero, the exception.
This is an all zero value.
B9BB 9BS9 BB9B 9B99 • • •
B
B
B
B •••
All zeros can be thought of as zero by convention. Otherwise, it
would represent the smallest positive number possible in the
scheme.
Too many intrinsic functions, or too many logical operators in
the same statement can cause the error:
"Floating-point
exception." It means that the expression is too complicated and
should be split into several statements.
A-4
VALUES IN IIBIIORY
As with other values in 8~86 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 single-precision
value 8474~~~~ is stored at location x, it will show as follows
when displaying memory contents:
x
x + 2
~~~~
8474
However, long integers are stored in order. The long integer
with a hexadecimal value of 128A34BF will show as:
x
x + 2
l28A
34BF
A-5
Appendix B:
SAULB r.xft OP ZBIIIX DBVBLOPIIBIl.r
The following is a sample listing of the
provided in a full XENIX Development System.
SYS~ O'.rILI~IBS
typical
utilities
You can obtain a list of your Xenix operating system's
by entering:
utilities
cd / (cr>
18 -PCRllpr(cr>
LIft OP XBBXX
~LI~IBS
bin
boot
boot.fd
boot.fdhd
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
df
diff
du
dump
dumpdir
echo
ed
look
1pr
1s
m4
mail
make
man
refer
restor
rev
rm
rmai1
rmdir
sa
test
time
tk
touch
tp
tr
troff
B-1
basename
bc
bsh
cal
calendar
cat
cb
cc
checkeq
chgrp
chmod
chown
clri
cmp
col
comm
cp
crypt
csh
cu
date
dc
dcheck
dd
deroff
edit
esrep
enroll
eqn
ex
expr
f77
false
fgrep
file
find
flagbad
fsck
graph
grep
icheck
join
kill
I
ld
learn
lex
lint
In
login
mesg
mkdir
mntchk
multiuser
mv
ncheck
ndump
neqn
newgrp
nice
nm
nroff
od
osh
passwd
pr
prep
prof
ps
ptx
pwd
quot
random
ranlib
ratfor
sed
sh
size
sleep
sort
sp
spell
spline
split
strip
struct
stty
su
sum
sync
t300
t300s
t450
tabs
tail
tar
tbl
tc
tee
tek
./dev:
altosnet
console
cua0
cul0
ct**
ct0*
ether
fd0
fd0.swap
fdl
hd0
hd0.boot
hd0.layout
hd0.roc0
hd0.secmap
hd0.spares
hd0.track0
hd0a
hd0b
kmem
lp
mem
nct**
nrct**
null
rct**
rfd0
rfdl
rhd0
rhd0.boot
rhd0.layout
rhd0.roc0
rhd0.secmap
rhd0.spares
rhd0.track0
rhd0a
rhd0b
root
rroot
rswap
swap
tar
tty
tty2
tty3
tty4
tty5
tty6
tty7
tty8
./etc:
accton
asktime
checklist
cron
ddate
getty
group
haltsys
inir
init
menusys
mknod
motd
mount
mtab
newuser
rc
shutdown
systemid
termcap
ttys
umou
upda
utmp
wall
dial-login
dmesg
menusys.bin
mkfs
passwd
ttytype
./etc/newuser:
./fd:
*ACS 8600 only
**58b only
B-2
true
tsorj
tty
uniq
unitl
uucp
uulo~
uux
v7gr~
v7loc
v7ls
v7ps
vi
vplo1
vpr
who
wrib
xget
xsenc
yacc
yes
./lib:
c0
cl
c2
cpp
crt0.o
libt4014.a
libt450.a
libtermlib,
libunet.a
libvt0.a
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:
adm
altos
bin
dict
games
include
lib
preserve
spool
src
sys
tmp
unix
user
./usr/adm:
acct
messages
mssbuf
savacct
usracct
wtmp
l-lail
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
plot
print
printenv
reset
script
sddate
see
sendnet
settime
sizefs
soelim
ssp
strings
tod
tra
tset
ua
ucp
ul
users
uudecode
uuencode
uusend
uversion
v7wc
w
wc
whatis
whereis
whoami
whom
xstr
./usr/dict:
hlista
hlistb
hstop
papers
spellhist
words
./lost+found:
./tmp:
./usr/altos:
qa.text
./usr/bin:
./usr/dict/papers:
Ind.ia
Ind.ib
Ind.ic
Rv7man
runinv
./usr/games:
arithmetic
backgammon
banner
craps
master
number
quiz
quiz.k
random
snake
snscore
ttt
wump
fish
fortune
hangman
lib
B-3
./usr/games/lib:
fortunes
mmhow
snake. log
snakerawscores
./usr/games/quiz.k:
africa
chinese
collectives
america
areas
ed
arith
elements
europe
asia
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
sysexits.h
time.t
tp-def
utmp.t
vararC1
whoamj
xout8E
pr.oc.h
res.h
sc.h
sites.h
stat.h
systm.h
text.h
timeb.
times.
tty.h
types.
user .1
llib-port
lpd
me
menusys
more. help
refer
struct
tabset
term
tmac
uucp
yaccpc
errno.h
execargs.h
grp.h
ident.h
local
math.h
mp.h
mtab.h
./usr/include/local:
layout.h
sspare.h
uparm.h
./usr/includes/sys:
acct.h
file.h
buf.h
filsys.h
callo.h
ino.h
chars.h
i-node.h
conf.h
ioctl.h
dir.h
locking.h
fblk.h
map.h
mount.h
mpx.h
mx.h
param.h
pk.h
pk.p
prim.h
./usr/lib:
Mail.help
Mail.help.atrun
bsh
bsh.messages
calendar
cign
crontab
crontab.noUNET
diff3
ex2.l3reserve
ex2.l3recover
ex2 .. l3strings
ffmt
./usr/lib/font:
ftB
ftCE
ftCS
ftBC
ftCl
ftCW
ftC
ftCK
ftG
./usr/lib/learn:
C.a
Xinfo
Linfo
editor.a
READ....;ME
eqn.a
font
learn
lex
lintl
lint2
llib-lc
llib-lm
ftGl
ftGM
ftGR
ftl
ftL
ftLl
files .a
lcount
macros.a
./usr/lib/lex:
ncform
B-4
ftPA
ftPB
ftPl
ftR
ftS
ftSB
ftSl
ftSM
ftUD
makefile
morefiles.a
tee
ft~
./usr/lib/me:
acm.me
chars.me
deltext.me
index.me
local.me
nUll.me
revisions
sh.me
tbl.me
thesis.mt
./usr/lib/menusys:
Backup
Dir
Backup?
Dir?
Commands?
Execute
Execute?
Help
Help?
Mail
Mail?
Start
Start?
SysAdmin
SysAdmin'
./usr/lib/refer:
hunt
inv
mkey
eqn.me
float.me
footnote.me
./usr/lib/struct:
beautify
structure
./usr/lib/tabset:
beehive
std
diablo
teleray
vtlBB
xeroxl72B
./usr/lib/term:
tab3BB
tab3B8s-l2
tab3BB-l2
tab37
tab38Bs
tab458
tab458-l2
tab45B-l2-8
tab832
tabal
tablp
tabn3BB
./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:
8-5
tmac. sre:
./usr/src:
cmd
./usr/srs/cmd:
decode.c
./usr/sys:
./usr/tmp:
./usr/unix:
./usr/user:
Appendix
c:
TRARSFERRIBG FILES BEWED ACS 8611 AIm ALms 586
OR omBR COIIPMBR SYSBIIS (AS!1fCBBOIIOOS COIlIiOllICA~IORS)
This appendix describes how to transfer files between the ACS
8699 and the Altos 586 XENIX computer systems, or betwe~n two
Altos XENIX computer systems (586 or 8699), or between your Altos
computer system and other computer systems which support
asynchronous (serial) communications.
This appendix also
describes how to use modems with your Altos XENIX systems.
The ~ (call UNIX) and uucp (UNIX-to-UNIX copy) facilities are
standard UNIX programs that enable you to transfer files and
execute commands on remote systems. The ~ program, which is
easier to use than the uUQP program but not as powerful, should
be used to communicate with non-UNIX computer systems. Because
of user difficulty in implementing uUQP, Altos has developed a
File Transfer Utility for Xenix-to-Xenix transfer (ftp).
Refer
to Appendix H of the Introduction ~ XENIX manual for step-bystep instructions for running~.
Note that only ACS 8699
versions 2.2d and Altos 586 versions 2.3 and higher have the
XENIX ~ utility.
If you have an earlier version, the uucp
program should be used.
C-l
PSIJIG CD· PACILI"
The ~~ program can be used for foreground asynchronous
communications with almost any other computer system. Under
light to medium system loads, communication is possible at 12BB
baud. Under heavy loads, 6BB baud or 3BB baud is the maximum
data rate. Facilities are provided for executing commands on the
remote system, and transferring files to or from the remote
system.
To use cu, follow these steps:
1.
Determine the serial port to be used for communication. Any
port not utilized by a terminal or a printer can be used,
for purposes of demonstration, we will assume that port 5 is
available. See Figure C-l for Setup.
ACS8600
OR
ACSS86
PORTS
NULL MODEM CABLE
ANOTHER
COMPUTER
ANY
PORT
-
CONSOLE
Figure C-l.
2.
Cu Facility Setup
Become the super-user (using the su command), then execute:
# di8~le /dev/tty5
This command will prevent a terminal from using port 5.
3.
Execute the command:
i en -t -8 1211 -1 /dev/tty5 -a /dev/nnll
The cu program will attempt to establish a connection with
the other computer, using serial port 5. The speed of the
conection will be 12BrfJ baud (cu will not function properly
at baud rates greater than 12BrfJ baud).
The following
message should be displayed after the connection has been
successfully established:
C-2
Connected
All characters typed from this point onwards will be
processed by the remote system, and all output from the
remote system will be displayed on the screen. If a line
begins with the tilde character (-), it will be processed by
the local UNIX system, and will NOT be passed to the remote
system.
The following commands are available when
communicating with a UNIX or a non-UNIX remote system:
•
Terminate the connection •
-
C-8
PBBPAlUBG '!BE
CORPIGORA~IOR
PILBS
The uucp program comes ready to use.
It does need, however,
certain information to establish the connection between the 586
and 86~~ systems. You provide this information by adding entries
to several files on each system. The follow ing table gives the
steps needed for ~ system to prepare the files:
TASK:
~
EFFECTED:
Assign a system name
to the system
/etc/systemid
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 chapter gives recommended entries.
Some versions of XENIX
that come 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 86~~ files.
You can use the XENIX editor to check the contents of the 586's
files to see if you must modify them.
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 ~ 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 86~~ system
and the name AltosS86 to the 586 system. If you don't, you
must give different system names in the /etc/systemid,
/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
/usr/lib/uucp/L.Sys files.
C-9
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/L.SYS files.
If your requirements don't meet these assumptions, read the
instructions in the chapter nIf You Have Special Requirements. n
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:
.!D.B DB 586;
ENTRY
~
/etc/systemid
Altos586
/usr/lib/uucp/L-devices
tty5 0 9600
/usr/lib/uucp/L.sys
Altos86 Any ttys 9600 ttys ogin:-AMogin:-~M-ogin: uucp
/usr/lib/uucp/USERFILE
root, /
, /usr /tmp
/usr/lib/crontab
0 0-23 * * * /usr/lib/uucico -rl -s
Altos 86
o 4 * * * /usr/lib/uucp/uuclean -pTM
The entry for the /usr/lib/uucp/L.sys file must have the carriage
returns (AM) embedded as shown. See the UNIX manuals for
information on how to embed carriage returns within a character
string using .your editor •
.lOB DB
86,n,;
~
EN~RY
/etc/systemid
Altos86
/usr/lib/uucp/L-devices
ttys 0 9600
/usr/lib/uucp/L"Sys
Altoss86 Never ttys 9600 ttys
/usr/lib/uucp/USERFILE
root, /
, /usr /tmp
/usr/lib/crontab
o
4
* * * /usr/lib/uucp/uuclean -pTM
If these recommended entries meet your needs, skip the next
chapter and go to the chapter nDisabling and Enabling the TTY
ports. n
Refer to Table C-l for a summary of what data should be in the
appropriate 586 and 8600 files to support the uucp package.
C-li
~able
C-l.
Su..ary of Pile BDtries Required for 586 and 86.1
Files on the 586:
/etc/systemid:
AltosS86
/usr/lib/uucp/L-devices:
ttyS 0 9688
/usr/lib/uucp/L.sys:
Altos86 Any ttyS 9688 ttyS ogin:-... M-ogin: ...... M-ogin:uucp
/usr/lib/uucp/USERFILE:
root, /
, /usr /tmp
/usr/lib/crontab:
o
8
0-23 * * * /usr/lib/uucp/uucico -rl -sAltos86
4 * * * /usr/lib/uucp/uuclean -pTM
Files on the 8611:
/etc/systemid:
Altos86
/usr/lib/uucp/L-devices:
ttyS 0 9688
/usr/lib/uucp/L.sys:
Altos586 Never
ttyS 9688 ttyS
/usr/lib/uucp/USERFILE:
root, /
, /usr /tmp
/usr/lib/crontab:
8 4 * * * /usr/lib/uucp/uuclean
C-ll
-pTM
IF YOU HAVE SPECIAL REQUIREMBftS
If you can't use the suggested entries, the following subchapters
give instructions on prepar ing each file. This chapter 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 identi fy each
system in commands and during the login. To assign a system
name, use an editor to add a line to the file /etc/syste.id.
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.
Defining the Ca.munications 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:
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
rat e 0 f 96 00.
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:
C-12
tty5 0 300
tty5 0 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/uDCp/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 ita /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 Rever. This prevents the
8600 from ever making the connection.
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.
port
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:-AM-ogin:-AM-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.
C-l3
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,
I
, lusr Itmp
where:
root,
,
I
lusr Itmp
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 lusr Itmp directories through uucp.
C-14
DXSABLIS &lID BllABLDG BB ft'r
PO~
Before testing the uucp network and copying files using uucp,
the following steps must be performed:
1.
On the 586, enter:
disable /dev/tty5 (CIl>
Substitute the name of the port you're using in this command
if the connection to the 8688 isn't through port tty5.
2.
On the 8688, enter:
enable /dev/tty5 (CR)
If necessary, substitute the name of the port you're using
in this command.
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
/tmp/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:
I
uucp /etc/passvd
Altos86\1/tIIp/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 chapter "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 prope rly
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 informa tion below to try to
debug your setup. These steps describe 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
OBXX progra••:er's Manual. It contains more information on uucp
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.Altos8600n0001,
contains a copy of the file /etc/passwd. The second file,
C.Altos8600n0001, contains control information. (The names
of these files will be different if you didn't assign the
name Altos86 to the 8600J
C-l6
Uucp also places the message, "QUEUED (C.Altos8600n090l)" 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.
The program uucico then begins execution. Its first task is
to examine the 586 file /usr/lib/uucp/L.SYS. The entry in
the file tells uucico to immediately login to the 8600. The
following steps occur as part of the login:
Uucico sends a carriage return to the 8600, which
should respond with a login message. Uucico then logs
in on the 8600.
The uucico program on the 586 executes the uucico
program on the 8600.
The uucico program on the 586 creates two temporary
files in the 586's /usr/spool/uucp directory that are
prefixed with "LCR".
Uucico on the 586 places the message "SUCCEEDED (call
to Altos86)" 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
8600.
The message "REQUEST (S /etc/passwd /tmp/passwd
username) is placed in the /usr/spool/uucp/LOGFILE files on
both systems.
4.
Uucico on the 586 transfers the file D.Altos8600nOOOl, which
is a copy of /etc/passwd, from the 586 to the 8600. The
uucico program on the 8600 places the file in the directory
/usr/spool/uucp. It then moves the file to the file
/tmp/passwd.
5.
The message "REQUEST (SUCCEEDED)" is placed in the
/usr/spool/uucp/LOGFILE files on both systems.
C-17
COPYIBG PILES USIBG UUCP
After you've tested the connection and the configuration files,
you can begin copying files from the 8600 to the 586. Follow
these steps to do the copying:
1.
Turn on and boot both systems.
both systems.
2.
If any of the 8600 files you want to copy aren't part of the
8600 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 chapter in this appendix, nUsing the
Uucp Command," gives instructions on using the uucp command.
You can use the uucp command as many times as necessary to
copy files.
C-18
Log in as the superuser on
OSIBG mE UOCP COIIIlA.ND
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] Altos86lsource-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
Altos86
gives the name you assigned to the 8699 in
its /etc/systemid file. You must follow the
system name with an exclamation mark (1).
source-file
gives the name of the source file or files to
be copied from the 8699. The name must
include the pathname to the directory that
contains the file or files.
The name can
include the metacharaters ? * [] that the
8600 will expand. Uucp will copy every file
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.
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
8690 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 on the ACS
8600:
uucp -d /usr/aarketing/reports/* Altos586\1/usr/marketing/reports
Theasterick (*) following the Altos86 pathname 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.
C-19
OSING MODgS WID ALms JUII sYS'lEMS
The ..cJl and ~ programs can be used for local dedicated pointto-point communication between computers in the same office, or
for remote communication over telephone lines, in which case a
modem must be used at both ends of the connection. Most commercially available asynchronous modems can be attached to an Altos
XENIX system using a standard computer-to-modem cable. Examples
of modems which have been used successfully with Altos systems
include Racal-Vadic, Cermatek, and Hayes.
Figure C-3 shows the
Altos XENIX system connected to another system via a modem.
ACS8600
OR
ACS586
MODEM
CABLE
I
I
MODEM I
I
TELEPHONE
LINE
ANOTHER
COMPUTER
ANY
PORT
CONSOLE
Figure C-3.
Altos XENIX System with Modem
A special cable (usually called a "computer to modem" cable) must
be used to attach a modem to either the ACS 8600 or the 586.
Most modem manufacturers and cable manufacturers supply these
cables as off-the-shelf items. However, if the proper cable
cannot be found, it may be necessary to build your own cable. To
assist you, the RS-232C pins used by the 8600 and the 586 are
shown in Figure C-4.
C-28
TD
..
2 USUALLY CONNECTED TO PIN 3 ON THE MODEM
~
~
...
RS-232C
CONNECTOR
ONTHE
586 OR THE
RD
RTS
CTS
...
3 USUSALL Y CONNECTED TO PIN 2 ON THE MODEM
4 USUALLY CONNECTED TO PIN 5 ON THE MODEM
..
DSR
6 USUALLY CONNECTED TO PIN 20 ON THE MODEM
-...
GND ...
-8600
DCD
~
...
5 USUALLY CONNECTED TO PIN 4 ON THE MODEM
DTR
Figure C-4.
7 USUALLY CONNECTED TO PIN 7 ON THE MODEM
8 USUALLY NOT CONNECTED
10 USUALLY CONNECTED TO PIN 6 ON THE MODEM
RS-232C Connector Pin Assignments
Modems can be used with ~ or uucp. To use a modem without autodial capability, manually dial the desired number to establish
the connection. Then execute the cu command or one or more uucp
commands. ~ and ~ will operate normally. At the conclusion
of the session, you must manually dis-establish the telephone
connection (i.e., hang up the phone).
Modems with auto-dial capability can also be used. To use cu,
simply execute the cu command. Most modems will ask one or more
questions in response to a particular key being pressed. The
modem will then automatically establish the connection.
A special program (named "dial") is necessary to use uucp with an
auto-dial modem. An example of such a program is given on the
next page. For example, the dial program can be invoked by the
following entry in the file /usr/lib/crontab on the 586:
o
0
* * * dial/dev/tty5 4085551234 /usr/lib/uucp/uucico-rl-sAtlos8E
This entry means that the dial program will be run every night at
midnight. The dial program automatically dials the number 408555-1234, and then starts the uucico program.
C-21
/*
* The dial command has the format:
" ,:**
(',
dial ttyline number program
.
*
* where:
[
*
*
ttyline is the name of the serial line
number is the phone number
*
program is the name of the program to run
*
*
* Forexample:
*
dial /dev/tty5' 4985551234 /usr/lib/uucp1uucico -rl-sAltos
*
*
* This version of dial works only with the Cermatek 212A.
*/
iin~lude
iin~lude
iinclude
struct sgttyb termio;
J.
main (argc, argv)
int arge;
!char **argv;
"{
t
int cflag, fd;
char
*Pi
,
1
signal- (SIGNUP, SIG_IGN);
/* Ignore hang-up si,]nal
p, ,setbuf (stdin, (char *) 9) ;
/* Don't buffer standard input
setbuf (stdout, (char *)9);
/* Don't buffer standard output
setbuf (stderr, (char *)9);
/* Don't buffer standard error
signal (SIGALRM, SIG_DFL);
/* Allow 69 seconds to make the
alarm(60);
/* connection
if «fd = open (argv[l], 2» <9) {
printf ("Can't oper %s\n", argv [1]) ;
exit(l);
*/
*/
*/
*/ '
*/ '
*/;
}
ioctl (fd, TIOCGETP, &termio); /*get the terminal I/O structure */
/*
* if called as Idial, use 399 baud else use 1299 bau9_._.... _ ,
*/
. -----~-.--.:~----'-~-. '-'. . ~---, ~ ."'-.~-\"
.
II :....---.....
termio.sg_ispeed = termio.sg_ospeed = (rep = rindex(argv[9], '/')} \
? * ( ++E) : argv [ 9 ] [ 9] ) '== '1') ? B399 : B1290;
\
termio.sg_flags &= -(ECHO 1 CRMOD); /* turn off echo and crmod modes
~'(,
termio.sg_flags 1= CBREAK;
/* set cbreak mode
,
ioctl (fd, TIOCSETP, &termio);
/*restore the terminal i/o
/* structure
/* enter interactive mode of modem */
'y'output("\n\r\n\r", fd);
/* wait for response from modem
\ wait ("NUMBER? •• ", fd);
*/
/* dial number
*/ .'
-C:.,output{argv[2], fd);
/* output carriage return
*/
--~ .. ~ toutput("\r", fd);
*/
.·~t.,-wait("DATA MODE.", fd);
/* wait for response
alar]
/*
connection
made,
turn
off
1"alarm(0)
;
.1:",;,.
c'
f
\'
'"
)
~'1
.'
,:......
i} ;
C-22
' .........-~
execvp(argv[3], &argv[3]);
} Ii.,;
j.~i'i';~
,\",.1:;'\"""
/* execute the remaining part of
/* command
¥:I
/* 'Output characters S LOW L Y
output (p, fd)
char *p;
int fd;
*
*
I
I
*/
{
char c;
while (c
= *p++) {
sleep (2);
write(fd, &c,
1);
}
}
wait (s, fd)
char *s;
int fd;
{
char c;
char *p;
int unget
while (1)
p
= 0;
{
= s;
/* point to the strings to be compared
*/
/* read until the first character matches */
do {
if (unget)
unget = 0;
else
read (fd, &c, 1);
} while (c 1= *p);
while (1) {
/* done if last character */
if (*++p == '\0') {
return;
}
/* read in the next character
read (fd, &c, 1);
/* if the next character doesn't compare ••
if (*p ! = c) {
/* start allover again */
unget = 1;
break;
8
}
}
}
}
C-23
*/
*/
Appendix D:
8186 ASSBllBLY LAIIGOAGB REPBRBRCB IIAROAL
The following pages represent an 8986 Assembly Language Reference
Manual extracted with permission from a Microsoft, Inc. publication.
The section numbers of this excerpt reflect the
enumeration of the original publication.
D-l
8086 Assembler Reference Manual
Microsoft Corporation.
XENIX Support Group
10700 Northup Ave.
Bellevue, WA 98004
~.
Introduction
This document describes the usage and input
the XENIX 8086 assembler ~.
syntax
of
The input syntax of the XENIX 8086 assembler is generally similar to that of the UNIX PDP-II assembler ~.
AQ is an assembler which produces an output file that
contains relocation infor~ation and a complete symbol table.
The output is acceptable to the XENIX link-editor.lJ;i, which
may be used to combine the outputs of several assembler runs
and to obtain object programs from libraries.
The output
format has been designed so that if a progr~ contains no
unresolved references to external symbols, it is executable
without further processing •
.2..
Usage
~
is used as follows:
as ( -1 ] [
-0
output ]
~
If the optional "-1" argument is given, an assembly listing is produced which includes the source, the assembled
(binary) code, and any assembly errors, and placed in
.fli.e.L.
The assembler is expecting the source input to be in
.fli.e •.a., where .f.ll.e is any valid XENIX filename. The output
of the assembler is by default placed on the file ~ •.Q. in
the current directory; the "-0" flag causes the output to
be placed on the named ~.
D-2
~.
Lexical conventions
Assembler
tokens
(alternatively,"symbols"
or
operators.
~.~.
include
"names"),
identifiers
constants, and
Identifiers
An identifier
consists
of
a
sequence
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.
Constants
A hex constant consists of a sequence of digits
the letters " 4 " , "h", "~'I, "~II, "~II, and
"~II (any of which may be capitalized),
preceeded by
the character 'I'.
The letters are interpreted with
the following values:
and
HEX
A
B
C
D
E
F
DECIMAL
IB
11
12
13
14
15
An octal constant consists of a series of digits,
preceeded by the tilde character " - I I . The digits
must be in the range from ~ to 2.
A decimal constant consists simply of a sequence
of digits. The magnitude of the constant should be
representable in ~ bits; i.e., be less than 32,768.
~.~.
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.
~.~.
Comments
The character 'I I introduces a comment, which
extends through the end of the line on which it
appears. Comments are ignored by the assembler.
D-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 placed.
The XENIX system will, if desired, enforce the purity of the
text segment of programs by trapping write operations into
it. Object programs produced by the assembler must be processed by the link-editor ~ (using its '_~I 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 text segment is not
pure, the data segment begins immediately after the text
segment; if the text segment is pure, the data segment is in
an address space of its own, starting at location zero (B).
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 segment and begins immediately after
it. At the start of execution of a program, the bss segment
is set to B. 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.
~.
~
location counter
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 may be aSSigned to, with the restriction that the current segment may not change; furthermore,
the value of ' • I 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 Segments above) •
.[.
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, aSSignment statements, and keyword statements.
The format
for
most
8B 86
assembly
D-4
language
source
statements is:
[]
2R-~
[]
[]
Any kind of statement may be preceded by one or more labels •
.[.~.
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 '.'1 to the name. An error is indicated in
pass 1 if the name is already defined1 an error is
indicated in pass 2 if the '., value assigned changes
the definition of the label.
A numeric label consists of a string of digits ~
to ~ and dollar-~ ($) fOllowed by a colon (:). Such
a label serves to define local symbols of the form
'n$', 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 ~$ is defined only
between the labels £oobar and ~:
£oobar:
~$:
.f..Q.Q. :
.byte
•
~
•
•
.lfQ..t.d .a
As in the case of name labels, a numeric label assigns
the current value and type of '., to the symbol •
.[.~.
~.
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 lines containing only a
label •
.[.~.
Expression 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 •
.[.~.
an
Assignment statements
An assignment statement consists of an identifier,
equal sign (=), and an expression. The value and
0-5
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 permissible to ~ssign to the
location counter '.'.
It is required, however, that
the type of the expression assigned be af the same type
as " .', and it is forbidden to decrease the value of
'.'.
In practice, the most common assignment to
, .' has the form'.= .+n· for some number .n; this has
the effect of generating .n null bytes.
~.~.
Keyword statements
Keyword statements are numerically the most common
type, since most machine instructions are of this sort.
A keyword statement begins with one of the many predefined keywords of the assembler; the syntax of the
remainder depends on the keyword. All the keywords are
listed below with the syntax they require.
2.
Expressions
An expression is a sequence of symbols representing a
value.
Its constituents are identifiers, constants, and
operators. Each expression has a type.
Arithmetic is
equal precedence,
left to right.
2.~.
two's complement. All operators have
and expressions are evaluated strictly
Expression operators
The operators are:
operator
Description
(blank)
+
same as +
Addition
Subtraction
Multiplication
Division
Modulo
Logical AND
Logical OR
Right Shift·
Left Shift
*
/,.
&
!
>
<
D-6
Logical NOT
2.2..
Types
The assembler deals with expressions, each of
which may be of a different type. Most types are
attached to the keywords and are used to select the
routine which treats that keyword. The types likely to
be met explicitly are:
undefined
Upon first encounter, each symbol is
undefined.
It may become undefined if
it is assigned an undefined expression.
undefined external
A symbol which is declared .globl but
not defined in the current assembly is
an undef1ned external. If such a symbol
is declared, the link editor ~ must be
used to load the assembler's output with
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-editor 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 link-edited, 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 ".
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 since previously loaded programs may
have data segments.
After the first
.data statement, the value of ' . ' is
data" •
D-7
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 .bss
statement, the value of "." is bss 9.
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 .globl1
however, their value and type are available to the link editor so that the program may be loaded with others that reference these symbols.
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 were absolute.
2.~.
~
propagation in expre§sions
When operands are 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 complex 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 absolute, the result is absolute.
If an
absolute 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.
0-8
are:
Further rules
applying
to
particular
operators
If one operand is text-, data-, or bss-segment
relocatable, or is an undefined external, the
result has the 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 the first (in which case
the result is absolute). If the first operand is
external undefined, the second must be absolute.
All other combinations are illegal.
others
It is illegal to apply these operators to any
absolute symbols.
~.
but
Pseudo-operations
The keywords listed below introduce
influence the later operations of the
metanotation
statements
assembler.
that
The
[ stuff ] •••
means that 9 or more instances of the given stuff may
appear.
Also, boldface tokens are literals, italic words
are substitutable.
~.~
..
~
If the location counter '.1 is odd, it is advanced
by one so the 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.
~.~.
.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 optionall~ containing a
decimal point, them an optional 'e l or EI, 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
D-9
for the result;
.float sets aside four bytes, while
.double sets aside eight bytes •
.B. •.l.
• globl
.globl
~
[
,
name 1
•••
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 were not given; however, the link editor ~ 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 symbols.
As discussed in 7, it is
possible to force the assembler to make all otherwise
undefined symbols external.
These three pseudo-operations cause the assembler
to begin assembling into the text, 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 •
.B.. 5..
.~
The format of the .comm is:
.comm ARRAY
Provided the name is not defined elsewhere, this
statement is equivalent to .globl. That is, the type of
~ is "undefined external' "
and its size is exgres~.
In fact the ~ behaves in the current assembly
just like an undefl.ned external.
However, the linkeditor ,lg 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
exgression bytes. All symbols which become defined in
this way are located before all the explicitly defined
bss-segment locations •
.B..'[.
• insrt
The format of a .insrt is:
.insrt "filename"
D-18
where filename is any valid XENIX filename. Note that
the filename must be enclosed within double quotes.
The assembler will attempt to open this file for
input.
If it succeeds, source lines will be read from
it until the end of file is reached. If ~ was unable
to open the file, a Cannot ~ insert ~ 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 19 (ten) files may be
at anyone time.
System call names are not predefined.
found in the file I~include/~.~.
.insrted
They may be
.ascii, .asciz
~.2.
The .ascii directive translates character strings
into their 7-bit aSC11 (represented as 8-bit bytes)
equivalents for use in the source program. The format
of the .ascii directive is as follows:
.ascii
Icharacter stringl
where
character string
contains any character valid
in a character constant. Obviously, a must not
appear within the character
string. (It can be represented
by the escape sequence \en).
I
are delimiter
characters,
which may be any character not
appearing in character string
and
I
Several examples follow:
~
22
68
77
2D
68
65
61
97
Code Generated:
65 6C 6C 6F 29 74
72 65 22
72 6E 69 6E 67 29
97 29 9A
61 62 63 64 65 66 67
Statement:
.ascii
I"hello there nI
.ascii nWarning-\997\997 \nn
.ascii *abcdefg*
D-ll
The .asciz directive is equivalent to the .aSC11
directive
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.
Null
terminated strings are used as arguments to some XENIX
system calls.
~.~.
.liat, .nlist
These pseudo-directives control the assembler output listing. These, in effect, temporarily override the
"-I' switch to the assembler. This is useful when certain portions of the assembly output is not necessarily
desired on a printed listing •
• list
turns the listing on
.nlist. turns the listing off
The .~ and .~ directives are used to reserve
blocks of storage: .blkb reserves bytes, .blkw reserves
words.
The format is:
.blkb
.blkw
(expression]
(expression]
where expression is the number of bytes or words to
reserve.
If no argument is given a value of 1 is
assumed. The expression must be absolute, and defined
during pass 1.
This is equivalent to the statement ..... =.+expresbut has a much more transparent meaning.
~II,
The .~ and .ll2..tJ1 directives are used to reserve
bytes and words and to initialize them with certain
values.
The format is:
.byte
.word
[expression]
(expression]
The .~ 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.
D-12
For example,
.byte
~
state: • byte
~
reserves an byte, with a value
of zero.
reserves a byte with a zero
value called state.
The semantics for .~ are identical, except that
l6-bit words are reserved and initialized •
.a. .ll.
. .end
The •.end directive indicates the physical
the source program. The format is:
.end
end
of
[expression]
where expression is an optional argument which, if
present, indicates the entry pOint of the program, i.e.
the starting poine for execution. If the entry point
of a program is not specified during assembly, it
defaults to zero.
Every source program must be terminated with a
• end statement.
Inserted files which contain a .end
statement will terminate assembly of the entire program, not just the inserted portion.
~.
Instruction
Syntax
The 8~86 instructions treat different types of operands
uniformly. Nearly every instruction can operate on either
byte or word data. In the table that follows, with some notable execeptions, an instruction that operates on a byte
operand will have a b suffix on the opcode.
The 8~86 instruction mnemonics which follow are implemented by the Microsoft 8086 assembler desribed in this
document. Some of the opcodes are not found in any other
8086 manual.
For example, this document describes branch instructions not found in any 8~86 manual. The branch instructions
expand into a jump on the 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.
8086 Assembler Opcodes
D-13
8086 Assembler Opcodes
1
1
Opcode
Description
I
Opcode
Description
1
1
1
aaa
aad
aam
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 J
imul
1
imulb 1
in
1
inc
.1
incb
1
int
1
asc11 adjust for addition
I
ascii adjust for division
1
ascii adjust for multiply
I
ascii adjust for subtraction
1
add with carry
I
add with carry
1
add
1
add
I
logical AND
I
logical AND
1
long branch equal
1
long branch grt or equal
I
long branch grt
I
long branch on high
I
long branch high or same
I
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
I
integer division
1
integer multiplication
1
integer multiplication
1
input byte
.
1
increment by one
I
increment by one
__.__--1.I
interrupt
D-14
8886 Assembler Opcodes
I
I
I
I
I
I
I
I
I
I
I
Opcode
Description
into
inw
iret
j
ja
jae
jb
jbe
jcxz
je
jg
jge
jl
jle
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
interrupt if overflow
input word
interrupt return
short jump
short jump if above
short jump if above or equal
short jump if below
short jump if below or equal
short jump if 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 jump not sign
short jump not zero
short jump on overflow
short jump if parity
short jump if parity even
short jump if parity odd
short ~ump if signed
short Jump if zero
load AH from flags
load pointer using DS
load effective address
load pointer using ES
lock bus
load string byte
load string word
loop short label
loop if equal
loop if not equal
loop is not zero
loop if zero
move
move byte
mQ~~
mQ~e
I
I
I
I
I
I
I
I
I
I
J
I
J
~t;tiD9
D-15
8086 Assembler Opcodes
I
I
I
I
Opcode
I
I
I
I
I
wait
xchg
xchgb
xlat
xor
I xorb
.2..~.
Description
wait while TEST pin
exchange
exchange
translate
xclusive OR
xclusiye OR
Addressing Modes
The 8086 assembler provides many different ways to
access instruction operands. Operands may be contained
in registers, within the instruction itself, in memory,
or in I/O ports. In addition, the addresses of memory
and I/O port operands can be calculated in several different ways •
.2..~.~.
Register Operands
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 just a few bits,
and
because
these
operations are performed
entirely within the CPU. Registers may serve as
source operands, destination operands, or both.
EXAMPLES OF REGISTER ADDRESSING
.2..~.2..
sub
mov
mov
mov
cx,di
ax,/3*4
/3*4,ax
ax,*l
Imme~ti.ate
Qpetaoaa
Immediate operands are constant data contained in an instruction. The data may be either
8 or 16 bits in length. Immediate operands can be
accessed
quickly
because they are available
directly from the instruction queue; 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
D-17
and
16
bit
operands.
It does not do any checking on the
operand size, but determines the size of the
operand by the following symbols:
*expr
#expr
an 8 bit immediate
a 16 bit immediate
EXAMPLES OF IMMEDIATE ADDRESSING
mov
mov
mov
add
~.~.
cx,*PAGSIZ
cx,#l
map, #/2
ax,*4
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.
~.~.~.
Direct Addressing
Direct addressing is the simplest memory
addressing 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
call
~.~.~.
savstk
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
call
@moncall
D-18
~.2.~.
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 the 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.
EXAMPLES OF BASED ADDRESSING"
push
~.2.~.
*6(bp)
Indexed Addressing
In indexed addressing, the effective address
is calculated from the sum of a displacement plus
the content of an index
register.
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
selects one element. Since all array elements are
the same length, simple arithmetic on the index
register will select any element.
EXAMPLES OF INDEXED ADDRESSING
mov
~.2.~.
cat, (bx)
Based Indexed Addressing
Based indexed addressing generates an effective address that is the sum of a base register,
an index register, and a displacement.
Based
indexed addressing is a very flexible mode because
two address components 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.
D-19
EXAMPLES OF BASED INDEXED ADDRESSING
mov
mov
mov
li.
(bx) (dx),_sym
*2(bx} (dx),_sym
t/lSS(bx)(dx),_~m
piagnostics
When syntactic errors occur, the line number and
the file in which they occur is displayed. Errors in
pass 1 cause cancellation of pass 2.
***ERROR*** syntax error, line XX
~ errors
filA:
where XX represents the line number(s) in error, and
represents the total number of errors.
0-21
~
Appendix E:
mmRIAL .um REFERBRCE MATERIAL
(URIVBRSIft' OF CALIFORRIA, BBBKBLBY, BERKELEY MAIIOALS)
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 tbe C Sbell
An Introduction to Display Editing with Vi
Quick Reference for Ex, Vi
Ex Reference Manual
Edit: A Tutorial
Ex/Edit Coeaand Sum.ary
-ME Reference Manual
Mail Reference Manual
Screen Updating and Cursor Kove.ent Optimization:
A Library Package
E-l
An introduction to the C shell
ABSTRACT
~ is a new command language interpreter for
UNIX systems.
It incorporates good features of
other shells and a history mechanism similar to
the ~ of INTERLISP. While incorporating many
features of other shells which make writing shell
programs
(shell scripts) easier, most of the
features unique to ~ 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 the shell here.
Simple terminal
interaction with ~ is possible after reading
just the 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 and a glossary of
terms and commands introduced in this manual.
B-2
An
introduction to the C shell
Introduction
A shell is a command language interpreter. ~ is the
name of one particular command interpreter on UNIX. The
primary purpose of ~ is to translate command lines typed
at a terminal into system actions, such as invocation of
other programs. ~ is a user program just like any you
might write.
Hopefully, ~ will be a very useful program
for you in interacting with the UNIX system.
In addition to this document, you will want to refer to
a copy of the "UNIX Programmers Manual. I ' The ~ documentation in the manual provides a full description of all
features of the shell and is a final reference for questions
about the shell.
Many words in this document are shown in italics.
These are important words: names of commands, and words
which have special meaning in discussing the shell and UNIX.
Many of the words are defined in a glossary at the end of
this document. If you don't know what is meant by a word,
you should look for it in the glossary.
B-3
1..
1..1..
Terminal usage .Q.f .t.b..e. shell
~
basic notion .Q.f commands
A shell in UNIX acts mostly as a medium through which
other gommands are invoked. While it has a set of builtin
commands which it performs directly, most useful commands
are, in fact, external to the shell. The shell is thus distinguished from the command interpreters of other systems
both by the fact that it is just a user program, and by the
fact that it is used almost exclusively as a mechanism for
invoking other programs.
Commands in the UNIX system expect a list of strings or
words as arguments. Thus the command
mail bill
consists of two words. The first word mail names the command to be executed, in this case the mail program which
sends messages to other users. The shell uses the name of
the command in attempting to run it for you. It will look
in a number of diregtories for a file with the name .m.a.il
which is expected to contain the mail program.
The rest of the words of the command are given to the
command itself to execute. In this case we specified also
the word ~ which is interpreted by the mail program to be
the name of a user to whom mail is to be sent. In normal
terminal usage we might use the mail command as follows.
mail bill
I have a question about the csh documentation.
My document seems to be missing page 5.
Does a page five exist?
,---Bill
%
%
Here we typed a message to send to ~ and ended this
message with a control-d which sent an end-of-file to the
mail program. Themail program then transmitted our message. The characters '% ' were printed before and after the
mail command by the shell to indicate that input was needed.
After typing the '% ' prompt the shell was reading command input from our terminal. We typed a complete command
'mail bill'. The shell then executed the mail program with
argument ~ and went dormant waiting for it to complete.
The mail program then read input from our terminal until we
signalled an end-of-file after which the shell noticed that
mail had completed and signaled us that it was ready to read
from the terminal again by printing another '% ' prompt.
£-4
This is the essential pattern of all interaction with
UNIX through the shell. A complete command is typed at the
terminal, the shell executes the command and when this execution completes prompts for a new command. If you run the
editor for an hour, the shell will patiently wait for you to
finish editing and obediently prompt you again whenever you
finish editing.
~.2.
~
arguments
A useful notion in UNIX is that of a flaQ argument •
. While many arguments to commands specify file names or user
names some arguments rather specify an optional capability
of the command which you wish to invoke. By convention,
such arguments begin with the character ' _ I . Thus the command
Is
will produce a list of the files in the
The option -a is the size option, and
current
directory.
Is -s
causes ~ to also give, for each file the size of the file
in blocks of 512 characters. The manual page for each command in the UNIX programmers manual gives the available
options for each command. The ~ command has a large number
of useful and interesting options. Most other commands have
either no options or only one or two options. It is hard to
remember options of commands which are not used very frequently, so most UNIX utilities perform only one or two
functions rather than having a large number of hard to
remember options.
~.~.
Output
~
files
Many commands may read input or write output to files
rather than simply taking input and output from the terminal. Each such command could take special words as arguments indicating where the output is to go. It is simpler,
a.nd usually sufficient, to connect these commands to files
to which they wish to write, within the shell itself, and
just before they are executed.
Thus suppose we wish to save the current date in a file
called 'now'. The command
date
will print the current date on our terminal.
This is
because our terminal is the default standard output for the
date command and the date command prints the date on its
standard output.
The shell lets us redirect the standard
B-5
output of a command through a notation using the metacharac.t.e.L. ')' and the name of the file where output is to be
placed. Thus the command
date ) now
runs the ~ command in an environment where its standard
output is the file 'now' rather than our terminal. Thus
this command places the current date and time in the file
'now'.
It is important to know that the ~ command was
unaware that its output was going to a file rather than to
our terminal.
The shell performed this redirection before
the command began executing.
One other thing to note here is that the file 'now'
need not have existed before the ~ command was executed;
the shell would have created the file if it did not exist.
And if the file did exist? If it had existed previously
these previous contents would have been discarded! A shell
option noclobber exists to prevent this from happening
accidentally; it is discussed in section 2.2.
~.~.
Metacharacters in
~
shell
The shell has a large number of special characters
(like ')') which indicate special functions. We say that
these notations have syntaCtic and semantic meaning to the
shell.
In general, most characters which are neither
letters nor digits have special meaning to the shell.
We
shall shortly learn a means of Quotation which allows us to
create words which contain metacharacters and to thus work
without constantly worrying about whether certain characters
are metacharacters.
Note that the shell is only reading input when it has
prompted with '% '. Thus metacharacters will normally have
effect only then. We need not worry about placing shell
metacharacters in a letter we are sending via mail.
~.5..
Input.f..t..Qm files; pipelines
We learned above how to route the standard output of a
command to a file. It is also possible to route the standard input of a command from a file.
This is not often
necessary since most commands will read from a file name
given as argument. We can give the command
sort
< data
to run the ~ command with standard input, where the command normally reads, from the file 'data'. We would more
likely say
sort data
E-6
letting the ~ command open the
itself since this is less to type.
file
'datal
for
input
We should note that if we just typed
sort
then the sort program would sort lines from its standard
input.
Since we did not redirect the standard input, it
would sort lines as we typed them on the terminal until we
typed a control-d to generate an end-of-file.
A most useful capability is the ability to combine the
standard output of one command with the standard input of
the next, i.e. to run the commands in a sequence known as a
pipeline. For instance the command
Is -s
normally produces a list of the files in our directory with
the size of each in blocks of 512 characters. If we are
interested in learning which of our files is largest we may
wish to have this sorted by size rather than by name, which
is the default way in which ~ sorts. We could look at the
many options of ~ to see if there was an option to do this
but would eventually discover that there is not. Instead we
can use a couple of simple options of the ~ command, combining it with ~ to get what we want.
The -n option of sort specifies a numeric
than an alphabetic sort. Thus
sort
rather
Is -s I sort -n
specifies that the output of the ~ command run with the
option -~ is to be piped to the command ~ run with the
numeric sort option. This would give usa sorted list of
our files by size, but with the smallest first. We could
then use the -~ reverse sort option and the ~ command in
combination with the previous command doing
Is -s I sort -n -r I head -5
Here we have taken a list of our files sorted alphabetically, each with the size in blocks. We have run this to
the standard input of the ~ command asking it to sort
numerically in reverse order (largest first). This output
has then been run into the command ~ which gives us the
first few lines out. In this case we have asked ~ for
the first 5 lines. Thus this command gives us the names and
sizes of our 5 largest files.
The metanotation introduced above is called the
mechanism.
Commands
separated by 'I' characters
E-7
~
are
connected together by the shell and the output of each is
run into the input of the next. The leftmost command in a
pipeline will normally take its standard input from the terminal and the rightmost will place its standard output on
the terminal. Other examples of pipelines will be given
later when we discuss the history mechanism; one important
use of pipes which is illustrated there is in the routing of
information to the line printer.
~.~.
Filenames
Many commands to be executed will need the names of
. files as arguments. UNIX pa thnames consist of a number of
components separated by 'I'. Each component except the last
names a directory in which the next component resides. Thus
the pa thname
letclmotd
specifies a file in the directory 'etc' which is a subdirectory of the ~ directory 'I'. Within this directory the
file named is 'motd' which stands for 'message of the day'.
Filenames which do not begin with 'I' are interpreted starting at the current working directory. This directory is, by
default, your ~ directory-and can be changed dynamically
by the chdir change directory command.
Most filenames consist of a number of alphanumeric
characters and '.'s.
In fact, all printing characters
except 'I' may appear in filenames. It is inconvenient to
have most non-alphabetic characters in filenames because
many of these have special meaning to the shell. The character '.' is not a shell-metacharacter and is often used as
the prefix with an extension of a base name. Thus
prog.c prog.o prog.errs prog.output
are four related files. They share a LQ2t portion of a name
(a root portion being that part of the name that is left
when a trailing '.' and following characters which are not
'.' are stripped off).
The file 'prog.c' might be the
source for a C program, the file 'prog.o' the corresponding
object file, the file 'prog.errs· the errors resulting from
a compilation of the program and the file 'prog.output' the
output of a run of the program.
If we wished to refer to all four of these files
command, we could USe the metanotation
in
a
prog.*
This word is expanded by the shell, before the command to
which it is an argument is executed, into a list of names
which begin with'prog.' •. The character '*' here matches
8-8
any sequence (including the empty sequence) of characters in
a file name. The names which match are sorted into the
argument list to the command alphabetically. Thus the command
echo prog.*
will echo the names
prog.c prog.errs prog.o prog.output
Note that the names are in lexicographic order here, and a
different order than we listed them above. The ~ command
receives four words as arguments, even though we only typed
one word as as argument directly. The four words were generated by filename expansion of the metasyntax in the one
input word.
Other metanotations for filename expansion are also
available.
The character '?' matches any single character
in a filename. Thus
echo ? ?? ???
will echo a line of filenames; first those with one characternames, then those with two character names, and finally
those with three character names. The names of each length
will be independently lexicographically sorted.
Another mechanism consists of a sequence of characters
between ' [ I and '] I . This metasequence matches any single
character from the enclosed set. Thus
prog.[co]
will match
prog.c prog.o
in the example above. We can also place two characters
astride a '_I in this notation to denote a range. Thus
chap. [1-5]
might match files
chap.l chap.2 chap.3 chap.4 chap.5
if they existed.
This is shorthand for
chap. [12345]
and otherwise equivalent.
E-9
An important point to note is that if a list of argument words to a command (an argument ~) contains filename
expansion syntax, and if this filename expansion syntax
fails to match any existing file names, then the shell considers this to be an error and prints a diagnostic
No match.
Another very important point is that the character , • I
at the beginning of a filename is treated specially. Neither '*' or '?' or the '[' ']' mechanism will match it.
This prevents accidental matching of the filenames '.1 and
•• 1
in the current directory which have special meaning to
the system, as well as other files such as .cshrc which are
not normally visible. We will discuss the special role of
the file .cshrc later.
Another filename expansion mechanism gives access to
the pathname of the ~ directory of other users. This
notation consists of the character ,-, followed by another
users login name. For instance the word 'Nbill l would map
to the pathname '/mnt/bill ' if the horne directory for 'bill'
was in the directory '/mnt/bill'. Since, on large systems,
users may have login directories scattered over many different disk volumes with different prefix directory names,
this notation provides a reliable way of accessing the files
of other users.
A special case of this notation consists of a 'NI
alone, e.g. '-/mbox ' •
This notation is expanded by the
shell into the file 'mbox ' in your ~ directory, i.e. into
'/mnt/bill/mbox ' for me on the Cory Hall UNIX system. This
can be very useful if you have used chdir to change to
another users directory and have found a file you wish to
copy using~. You can do
cp thatf ile which will be expanded by the shell to
cp thatfile /mnt/bill
e.g., which the copy command will interpret as a request to
make a copy of 'thatfile' in the directory '/mnt/bill ' • The
'-I notation doesn't, by itself, force named files to exist.
This is useful, for example, when using the ~ command, e.g.
cp thatf ile - /savei t
There also exists a mechanism using the characters '{I
and '}I for abbreviating a set of word which have common
parts but cannot be abbreviated by the above mechanisms
B-18
because they are not files, are the names of files which do
not yet exist, are not thus conveniently described.
This
mechanism will be described much later, in section 4.1, as
it is used much less frequently •
.l.2.
Quotation
We have already seen a number of metacharacters used by
the shell.
These metacharacter pose a problem in that we
cannot use them directly as parts of words. Thus the command
echo
*
will not echo the character '*'. It will either echo an
sorted list of filenames in the current directory, or print
the message 'No match' if there are no files in the current
directory.
The recommended mechanism for placing characters which
are neither numbers, digits, 'I', '.' or '_I in an argument
word to a command is to enclose it with single quotation
characters 'I', i.e.
echo '*1
There is one special character ' I ' which is used by the hia=
mechanism of the shell and which cannot be escaped in
this way. It and the character ' I I itself can be preceded
by a single '\1 to prevent their special meaning. These two
mechanisms suffice to place any printing character into a
word which is an argument to a shell command •
~
.l.~.
Terminating commands
When you are running a command from the shell and the
shell is dormant waiting for it to complete there are a couple of ways in which you can force such a command to complete. For instance if you type the command
cat letclpasswd
the system will print a copy of a list of all users of the
system on your terminal.
This is likely to continue for
several minutes unless you stop it. You can send an INTERRUPT signal to the ~ command by hitting the DEL or RUBQUT
key on your terminal. Actually, hitting this key sends this
INTERRUPT signal to all programs running on your terminal,
including your shell. The shell normally ignores such signals however, so that the only program affected by the
INTERRUPT will be~. Since ~ does not take any precautions to catch this signal the INTERRUPT will cause it to
terminate. The shell notices that ~ has died and prompts
you again with "% ' . If you hit INTERRUPT again, the shell
E-11
will just repeat its prompt since it catches INTERRUPT signals and chooses to continue to execute commands rather than
going away like ~ did, which would have the effect of logging you out.
Another way in which many programs terminate is when
they get an end-of-file from their standard input. Thus the
mail program in the first example above was terminated when
we hit a control-d which generates and end-of-file from the
standard input. The shell also terminates when it gets an
end-of-file printing 'logout'; UNIX then logs you off the
system. Since this means that typing too many control-d's
. can accidentally log us off, the shell has a mechanism for
preventing this. This ignoreeof option will be discussed in
section 2.2.
If a command has its standard input redirected from a
file, then it will normally terminate when it reaches the
end of this file. Thus if we execute
mail bill < prepared. text
the mail command will terminate without our typing a
control-d.
This is because it read to the end-of-file of
our file 'prepared.text' in which we placed a message for
'bill' with an editor. We could also have done
cat prepared. text I mail bill
since the ~ command would then have written the text
through the pipe to the standard input of the mail command.
When the ~ command completed it would have terminated,
closing down the pipeline and the mail command would have
received an end-of-file from it and terminated.
Using a
pipe here is more complicated than redirecting input so we
would more likely use the first form. These commands could
also have been stopped by sending an INTERRUPT.
If you write or run programs which are not fully
debugged then it may be necessary to stop them somewhat
ungracefully. This can be done by sending them a QUIT signal, generated by a control-\. This will usually provoke
the shell to produce a message like:
a.out: Quit -- Core dumped
indicating that a file 'core' has been created containing
information about the program 'a.out's state when it ran
amuck. You can examine this file yourself, or forward
information to the maintainer of the program telling him/her
where the ~ Lilg is.
2.6)
If you run background commands (as explained in section
then these commands will. ignore INTERRUPT and QUIT
8-12
signals at the terminal. To stop them you must use the kill
program. See section 2.6 for an example.
1. •.9..
~.D.Qlf?
We have so far seen a number of mechanisms of the shell
and learned a lot about the way in which it operates. The
remaining sections will go yet further into the internals of
the shell, but you will surely want to try using the shell
before you go any further. To try it you can log in to UNIX
and type the following command to the system:
chsh myname /bin/csh
Here 'myname' should be replaced by the name you typed to
the system prompt of "login:' to get onto the system. Thus
I would use 'chsh bill /bin/csh ' • ~ ~ ~ ~ ~ ~
~1
~
takes effect At ~ login. You are now ready to
try using ~.
Before you do the "chsh' command, the shell you are
using when you log into the system is "/bin/sh'. In fact,
much of the above discussion is applicable to "/bin/sh'.
The next section will introduce.many features particular to
~ so you should change your shell to ~ before you
begin
reading it.
B-13
~.
z.~.
Details
QU ~
Shell startup
shell
~
~
terminal users
termination
When you login, the shell is placed by the system in
your ~ directory and begins by reading commands from a
file .cshrc in this directory. All shells which you may
create during your terminal session will read from this
file. We will later see what kinds of commands are usefully
placed there.
For now we need not have this file and the
shell does not complain about its absence.
A login shell, executed after you login to the system,
will, after it reads commands from .cshrc, read commands
from a file .login also in your home directory.
This file
contains commands which you wish to do each time you login
to the UNIX system. My .login file looks something like:
tset -d adm3a -p adm3a
fixexrc
set history=2~
set time=3
on the CORY Hall UNIX system. This file contains four commands to be executed by UNIX each time I login. The first
is a ~ command which informs the system that I usually
dial in on a Lear-Siegler ADM-3A terminal and that if I am
on a patchboard port on the fifth floor of Evans Hall I am
probably also on an ADM-3A. The second command is a fixexrc
which manipulates my ~ startup file in certain ways if I am
on a dialup port.
We need not be concerned with exactly
what this command does. In general you may have certain
commands in your • login which are particular to you.
The next two ~ commands are interpreted directly by
the shell and affect the values of certain shell variables
to modify the future behavior of the shell.· Setting the
variable ~ tells the shell to print time statistics on
commands which take more than a certain threshold of machine
time (in this case 3 CPU seconds). Setting the variable
history tells the shell how much history of previous command
words it should save in case I wish to repeat or rerun modified versions of previous commands. Since there is a certain overhead in this mechanism the shell does not set this
variable by default, but rather lets users who wish to use
the mechanism set it themselves. The value of 2~ is a reasonably large value to assign to history. More casual users
of the history mechanism would probably set a value of 5 or
l~.
The use of the histpry mechanism will be described subsequently.
After executing commands from .login the shell reads
commands from your terminal, prompting for each with '% I .
When it recei vesan end-of-file from the terminal, the shell
E-14
will print 'logout' and execute commands from the file
'.logout' in your home directory. After that the shell will
die and UNIX will log you off the system. If the system is
not going down, you will receive a new login message.
In
any case, after the 'logout' message the shell is doomed and
will take no further input from the terminal.
~.~.
Shell variables
The shell maintains a set of variables. We saw above
variables history and ~ which had values '28' and
'3'. In fact, each shell variable has as value an array of
zero or more strings.
Shell variables may be assigned
values by the set command. It has several forms, the most
useful of which was given above and is
the
set name=value
Shell variables may be used to store values which are
to be reintroduced into commands later through a substitution mechanism. The shell variables most commonly referenced are, however, those which the shell itself refers to.
By changing the values of these variables one can directly
affect the behavior of the shell.
One of the most important variables is the variable
This variable contains a sequence of directory names
where the shell searches for commands.
The ~ command
shows the value of all variables currently defined (we usually say~) in the shell. The default value for path will
be shown by ~ to be
~.
% set
argv
home
path
prompt
shell
status
/mnt/bill
(. /bin /usr/bin)
%
/bin/csh
8
%
This notation indicates that the variable path points to the
current directory'.' and then '/bin' and '/usr/bin ' • Commands which you may write might be in '.' (usually one of
your directories).
The most heavily used system commands
live in '/bin'. Less heavily used system commands live in
'/usr/bin'.
A number of new programs on the system live in the
directory '/usr/new'.
If we wish, as well we might, all
shells which we invoke to have access to these new programs
we can place the command
E-15
set path= (. /usr/new /bin /usr/bin)
in our file .cshrc in our home directory.
and then logging out and back in and do
Try
doing
this
set
again to see that the value assigned to
~
has changed.
Other useful built in variables are the variable ~
which shows your home directory, the variable ignoreeof
which can be set in your .login file to tell the shell not
to exit when it receives an end-of-file from a terminal. To
logout from UNIX with ignoreeof set you must type
logout
This is one of several variables which the shell does not
care about the value of, only whether they are ~ or unset.
Thus to set this variable you simply do
set ignoreeof
and to unset it do
unset ignoreeof
Both
~
and unset are built-in commands of the shell.
Finally, some other built-in shell variables of use are
the variables noclobber and mail. The metasyntax
> filename
which redirects the output of a command will overwrite and
destroy the previous contents of the named file. In this
way you may accidentally overwrite a file which is valuable.
If you would prefer that the shell not overwrite files in
this way you can
set noclobber
in your .login file.
Then trying to do
date> now
would cause a diagnostic
could type
if
'now'
existed
already.
You
date >1 now
if you really wanted to overwrite the contents of "now' •
The '>!' is a special metasyntax indicating that clobbering
8-16
the file is ok.
If you receive mail frequently while you are logged in
and wish to be informed of the arrival of this mail you can
put a command
set mail=/usr/mail/yourname
in your .login file. Here you should change 'yourname' to
your login name. The shell will look at this file every 10
minutes to see if new mail has arrived. If you receive mail
only infrequently you are better off not setting this variable. In this case it will only serve to delay the shells
response to you when it checks for mail.
The use of shell variables to introduce text into commands, which is most useful in shell command scripts, will
be introduced in section 2.4.
~.~.
~
shell'a history
~
The shell can maintain a history list into which it
places the words of previous commands. It is possible to
use a metanotation to reintroduce commands or words from
commands in forming -new commands. This mechanism can be
used to repeat previous commands or to correct minor typing
mistakes in commands.
Consider the following transcript:
% where michael
michael is on tty0
dialup
% write 1$
write michael
Long time no see michael.
Why don't you call me at 524-4510.
300 baud
642-7927
EOF
%
Here we asked the system where michael was logged in.
It
told us he was on 'tty0' and we told the shell to invoke a
'write' command to '1$'. This is a history notation which
means the last word of the last command executed, in this
case 'michael ' • The shell performed this substitution and
then echoed the command as it would execute it. Let us
assume that we don't hear anything from michael.
We might
do
B-17
ps tf(J
PID TTY TIME COMMAND
4af(Ja f(J
f(J:f(JS % 11
ps tf(J
PID TTY TIME COMMAND
Slf(J4 f(J
f(J:f(Jf(J - 7
% lwhere
where michael
michael is not logged in
%
%
Here we ran a ~ on the teletype michael was logged in on to
see that he had a shell. Repeating this command via the
history substitution '11' we saw that he had logged out and
that only a getty process was running on his terminal.
Repeating the where command showed that he was indeed gone,
most likely having hung up the phone in order to be able to
call.
This illustrates several useful features of the history
mechanism.
The form ~!1' repeats the last command execution. The form ~!string' repeats the last command which
began with a word of which 'string' is a prefix. Another
useful command form is ~TlhsTrhs' performing a substitute
similar to that in .e.Q or u. Thus after
% cat -bill/csh/sh •• c
/mnt/bill/csh/sh •• c: No such file or directory
T•• (ua.
cat -bill/csh/sh.c
#include nsh.h"
%
/*
* C Shell
*
* Bill Joy, UC Berkeley
* October, 197 a
*/
char
*pathlist []
=
{ SRCHP
%
here we used the SUbstitution to correct a typing mistake,
and then rubbed the command out after we saw that we had
found the file that we wanted. The substitution changed the
two '.' characters to a single '.' character.
After this command we might do
% !! I lpr
cat -bill/csh/sh.c I lpr
£-18
to put a copy of this file on the line printer, or
ately after the ~ which worked above)
(immedi-
% pr ! $ I lpr
pr -bill/csh/sh.c I lpr
%
to print a copy on the printer using
~.
More advanced forms of the history mechanism are also
possible.
A notion of modification on substitutions allows
one to say (after the first successful ~ above) •
cd ! $: h
cd -bill/csh
%
%
The trailing ':h' on the history substitution here causes
only the head portion of the pathname reintroduced by the
history mechanism to be substituted.
This mechanism and
related mechanisms are used less often than the forms above.
A complete description of history mechanism features is
given in the C shell manual pages in the UNIX Programmers
t-ianual.
2. •.i.
Aliases
The shell has an alias mechanism which can be used to
make transformations on input commands. This mechanism can
be used to simplify the commands you type, to supply default
arguments to commands, or to perform transformations on commands and their arguments. The alias facility is similar to
the macro facility of many assemblers.
Some of the features obtained by aliasing can be
obtained also using shell command files, but these take
place in another instance of the shell and cannot directly
affect the current shells environment and commands such as
chdir which must be done in the current shell.
As an example, suppose that there is a new version of
the mail program on the system called 'Mail' you wish to
use, rather than the standard mail program which is called
'mail'. If you place the shell command
alias mail Mail
in your .login file, the shell will transform an input
of the form
line
mail bill
into a calIon 'Mail'.
More generally, suppose we wish
E-19
the
command 'lsi to always show
always do '-st. We can do
sizes
of files, that is to
alias lsls -s
or even
alias dir ls -s
creating a new command syntax 'dirt which does an
If we say
'ls
-st.
dir -bill
then the shell will translate this to
ls -s /mnt/bill
Thus the alias mechanism can be used to provide short
names for commands, to provide default arguments, and to
define new ·short commands in terms of other commands. It is
also possible to define aliases which contain multiple commands or pipelines, showing where the arguments to the original command are to be substituted using the facilities of
the history mechanism. Thus the definition
alias cd 'cd \1* ; ls '
would do an ~ command after each change directory ~ comWe enclosed the entire alias definition in ' I I charmand.
acters to prevent most substitutions from occurring and the
character ';' from being recognized as a parser metacharacter. The '1.1 here is escaped with a '\' to prevent it from
being interpreted when the alias command is typed in. The
'\1*1 here substitutes the entire argument list to the prealiasing ~ command, without giving an error if there were
no arguments. The ';1 separating commands is used here to
indicate that one command is to be done and then the next.
Similarly the definition
alias whois Igrep \!T /etc/passwd l
defines a command which looks up its first argument
password file.
~.~.
Detached commands;
»
in
the
and >& redirection
There are a few more metanotations useful to the terminal user which have not been introduced yet. The metacharacter '&1 may be placed after a command, or after a sequence
of cOmmands separated by ';' or " ' . This causes the shell
to not wait for the commands to terminate before prompting
again.
We say that they are detached or backgrqund
B-21
processes.
Thus
% pr -bill/csh/sh.c I lpr &
5120
5121
%
Here the shell printed two numbers and came back very
quickly rather than waiting for the ~ and ~ commands to
finish. These numbers are the process numbers assigned by
the system to the ~ and lRL commands.+
Since havoc would result if a command run in the background were to read from your terminal at the same time as
the shell does, the default standard input for a command run
in the background is not your terminal, but an empty file
called '/dev/null'. Commands run in the background are also
made immune to INTERRUPT and QUIT Signals which you may subsequently generate at your terminal.*
If you intend to log off the system before the command
completes you must run the command immune to HANGUP signals.
This is done by placing the word 'nohup' before each program
in the command, i.e.:
nohup man csh I nohup lpr &
In addition to the standard output, commands also have
a diagnostic output which is normally directed to the terminal even when the standard output is directed to a file or a
pipe. It is occasionally desirable to direct the diagnostic
output along with the standard output. For instance if you
want to redirect the output of a long running command into a
file and wish to have a record of any error diagnostic it
produces you can do
command >& file
The '>&' here tells the shell to route both
output and the standard output into 'file'.
output. Similarly you can give the command
the diagnostic
of the standard
command 1& lpr
+Running commands in the background like this tends to
slow down the system and is not a good idea if the system is overloaded. When overloaded, the system will
just bog down more if you run a large number of
processes at once.
*If a background command stops suddenly when you hit
INTERRUPT or QUIT it is likely a bug in the background
program.
E-21
to route both standard and diagnostic
pipe to the line printer daemon ~.#
output
through
the
commands
of
Finally, it is possible to use the form
command
» file
to place output at the end of an existing file.t
~.~.
Useful built-in commands
We now give a few of the useful built-in
the shell describing how they are used.
The alias command described above is used to assign new
aliases and to show the existing aliases. With no arguments
it prints the current aliases. It may also be given an
argument such as
alias Is
to show the current alias for, e.g.,
~ls'.
The ~ and chdir commands are equivalent, and change
the working directory of the shell. It is useful to make a
directory for each project you wish to work on and to place
all files related to that project in that directory. Thus
after you login you can do
% pwd
/mnt/bill
% mkdir newpaper
% chdir newpaper
% pwd
/mnt/bill/newpaper
%
after which you will be in the directory newpaper.
You
#A command form
command >&1 file
exists, and is used when noclobber is set and ~ already exists.
tIf nQclobber is set, then an error will result if ~
does not exist, otherwise the shell will create ~ if
it doesn't exist. A form
command »! file
makes it not be an error for file to not exist when
clobber is set.
£-22
ll.2-
can
place a group of related files there.
You
your 'home l login directory by doing just
can
return
to
chdir
with no arguments. We used the ~ print working directory
command to show the name of the current directory here. The
current directory will usually be a subdirectory of your
home directory, and have it (here '/mnt/bill l ) at the start
of it.
The ~ command prints its arguments.
It is often
used in shell scripts or as an interactive command to see
what filename expansions will yield.
The history command will show the contents of the history list. The numbers given with the history events can be
used to reference previ~us events which are difficult to
reference using the contextual mechanisms introduced above.
There is also a shell variable called prompt. By placing a
'11
character in its value the shell will there SUbstitute
the index of the current command in the history list.
You
can use this number to refer to this command in a history
substitution. Thus you could
set prompt='\! % '
Note that the ' I ' character had
within ' I ' characters.
to
be
escaped
The logout command can be used
shell which has ignoreeof set.
to
terminate
here
even
a
login
The repeat command can be used to repeat a command
several times. Thus to make 5 copies of the file ~ in the
file ~ you could do
repeat 5 cat one
»
five
The setenv command can be used, on version 7 UNIX
tems, to set variables in the environment. Thus
sys-
setenv TERM adm3a
will set the value of the environment variable TERM to
'adm3a'.
A user program printeny exists which will print
out the environment. It might then show:
% printenv
HOME
/usr/bill
SHELL
/bin/csh
TERM
adm3a
%
B-23
The source command can be used
shell to read commands from a file.
to force
Thus
the
current
source • cshrc
can be used after editing in a change to the .cshrc file
which you wish to take effect before the next time you
login.
The ~ command can be used to cause a command
timed no matter how much CPU time it takes. Thus
% time cp
0.0u 0.3s
% time wc
1200
1.2u 0.5s
to
be
five five. save
0: 01 26%
five. save
6300
37650 five. save
0:03 55%
%
indicates that the ~ command used less that 1/10th of a
second of user time and only 3/10th of a second of system
time in copying the file 'five' to 'five.save'. The command
word count 'wc' on the other hand used 1.2 seconds of user
time and 0.5 seconds of system time in 3 seconds of elapsed
time in counting the number of words, character and lines in
'five.save'. The percentage '55%' indicates that over this
period of 3 seconds, our command 'wc' used an average of 55
percent of the available CPU cycles of the machine. This is
a very high percentage and indicates that the system is
lightly loaded.
The unalias and unset commands can be used
aliases and variable definitions from the shell.
to
remove
The ~ command can be used after starting processes
with '&' to quickly see if they have finished. If the shell
responds immediately with another prompt, they have. Otherwise you can wait for the shell to prompt at which point
they will have finished, or interrupt the shell by sending a
RUB or DELETE character. If the shell is interrupted, it
will print the names and numbers of the processes it knows
to be unfinished. Thus:
% nroff paper I Ipr &
2450
2451
% wait
2451 lpr
2450 nroff
wait: Interrupted.
%
You can check again later by doing another
E-24
~,
or see
which commands are still running by doing a~. As 'time'
will show you, ~ is fairly expensive. It is thus counterproductive to run many ~ commands to see how a background
process is doing.+
If you run a background process and decide you want to
stop it for whatever reason you must use the kill program.
You must use the number of the processes you wish to kill.
Thus to stop the nroff in the above pipeline you would do
%
kill 24513
% wait
24513: nroff: Terminated.
% .
Here the
'nroff'
discover
must, in
shell printed a diagnostic that we terminated
only after we did a~. If we want the shell to
the termination of all processes it has created we
general, use ~.
This concludes the basic discussion of the shell for
terminal users. There are more features of the shell to be
discussed here, and all features of the shell are discussed
in its manual pages. One useful feature which is discussed
later is the for each built-in command which can be used to
run the same command sequence with a number of different
arguments.
If you intend to use UNIX a lot you you should look
through the rest of this document and the shell manual pages
to become familiar with the other facilities which are
available to you.
tIf you do you are usurping with these .~ commands the
processor time the job needs to finish, thereby delaying its completion!
£-25
~.
~.~.
Shell control structures
~
command scripts
Introduction
It is possible to place commands in files and to cause
shells to be invoked to read and execute commands from these
files, which are called shell scripts. We here detail those
features of the shell useful to the writers of such scripts.
It is important to first note what shell scripts are
n2t useful for.
There is a program called ~ which is
very useful for maintaining a group of related files or performing sets of operations on related files. For instance a
large program consisting of one or more files can have its
dependencies described in a makefil~ which contains definitions of the commands used to create these different files
when changes occur. Definitions of the means for printing
listings, cleaning up the directory in which the files
reside, and installing the resultant programs are easily,
and most appropriately placed in this makefile. This format
is superior and preferable to maintaining a group of shell
procedures to maintain these files.
Similarly when working on a document a makefile may be
created which defines how different versions of the document
are to be created and which options of nroff or troff are
appropriate.
~.~.
Invocation And
~ ~
variable
A ~ command script may be interpreted by saying
% csh script •••
where script is the name of the file containing a group of
commands and .••• , is replaced by a sequence of arguments. The shell places these arguments in the variable
~
and then begins to read commands from the script.
These parameters are then available through the same mechanisms which are used to reference any other shell variables.
~
If you make the file 'script' executable by doing
chmod 755 script
and place a shell comment at the beginning of the shell
script (i.e. begin the file with a '#' character) then a
'/bin/csh' will automatically be invoked to execute 'script'
when you type
script
8-26
If the file does not begin with a '#' then the standard
shell '/bin/sh' will be used to execute it. This allows you
to convert your older shell scripts to use ~ at your convenience.
~.~.
variable
~ubstitution
After each input line is broken into words and history
substitutions are done on it, the input line is parsed into
distinct commands.
Before each command is executed a
mechanism know as variable substitution is done on these
words.
Keyed by the character '$' this
sUbstitution
replaces the names of variables by their values. Thus
echo $argv
when placed in a command script would cause the current
value of the variable ~ to be echoed to the output of the
shell script. It is an error for ~ to be unset at this
point.
A number of notations are provided for accessing
ponents and attributes of variables. The notation
com-
$?name
expands to 'I' if name is ~ or to '0' if name is not ~.
It 1S the fundamental mechanism used for checking whether
particular variables have been assigned values.
All other
forms of reference to undefined variables cause errors.
The notation
$#name
expands to the number of
Thus
elements
in
the
variable
nam&.
% set argv=(a b c)
% echo $?argv
1
% echo $#argv
3
% unset argv
% echo $?argv
o
% echo $argv
Undefined variable: argv.
%
It is also possible to access the components of a variable which has several values. Thus
B-27
$argv[l]
gives the first component of
, a'. Similarly
~
or in
the
example
above
$argv[$iargv]
would give 'c ' , and
$argv[l-2]
Other notations useful in shell scripts are
$n
where n is an integer as a shorthand for
$argv [n]
the nth parameter and
$*
which is a shorthand for
$argv
The form
$$
expands to the process number of the current shell.
Since
this process number is unique in the system it can be used
in generation of unique temporary file names.
One minor difference between '$nl and '$argv[n]' should
be noted here. The form '$argv[n], will yield an error if Jl
is not in the range 'l-$iargv' while '$n' will never yield
an out of range subscript error. This is for compatibility
with the way older shells handled parameters.
Another important point is that it is never an error to
give a subrange of the form 'n-'1 if there are less than Jl
components of the given variable then no words are substituted.
A range of the form 'm-n l likewise returns an empty
vector without giving an error when m exceeds the number of
elements of the given variable, provided the subscript Jl is
in range.
~.~.
Expressions
In or.der for interesting shell scripts to be constructed it must be possible to evaluate expressions in the
B-28
shell based on the values of variables. In fact, all the
arithmetic operations of the language C are available in the
shell with the same precedence that they have in C.
In particular, the operations '==' and '1=' compare strings and
the operators '&&' and 'II
implement the boolean and/or
operations.
I
The shell also allows file enquiries of the form
-? filename
where '?I is replace by a number of single characters.
instance the expression primitive
For
-e filename
tell whether the file "filename' exists.
Other primitives
test for read, write and execute access to the file, whether
it is a directory, or has non-zero length.
It is possible to test whether a command terminates
normally, by a primitive of the form '{ command }' which
returns true, i.e. '11 if the command succeeds exiting normally with exit status ~, or '~I if the command terminates
abnormally or with exit status non-zero. If more detailed
information about the execution status of a command is
required, it can be executed and the variable '$status'
examined in the next command. Since '$status' is set by
every command, it is very transient. It can be saved if it
is inconvenient to use it only in the single immediately
following command.
For a full list of expression components available
the manual section for the shell.
~.~.
see
Sample shell script
A sample shell script which makes use of the expression
mechanism of the shell and some of its control structure
follows:
E-29
%
'#
'#
cat copyc
Copyc copies those C programs in the specified list
# to the directory - /backup if they differ from the files
'# already in -/backup
#
set noglob
for each i ($argv)
'# not a .c file so do nl
if ($i:r.c 1= $i) continue
if (1 -r -/backup/$i:t) then
echo $i:t not in backup ••• not cp\'ed
continue
endif
'# to set $status
cmp -s $i -/backup/$i:t
if ($status 1= 0) then
echo new backup of $i
cp $i -/backup/$i:t
endif
end
This script makes use of the foreach command, which
causes the shell to execute the commands between the foreach
and the matching ~ for each of the values given between
... (I and "')' with the named variable, in this case . . i I set to
successive values in the list. Within this loop we may use
the command break to stop executing the loop and continue to
prematurely terminate one iteration and begin the next.
After the for each loop the iteration variable (~ in this
case) has the value at the last iteration.
We set the variable noglob here to prevent filename
expansion of the members of~. This is a good idea, in
general, if the arguments to a shell script are filenames
which have already been expanded or if the arguments may
contain filename expansion metacharacters. It is also possible to quote each use of a '$' variable expansion, but
this is harder and less reliable.
The other control construct used here is a statement of
the form
if
endif
expression) then
command
•••
The placement of the keywords here is ll.Q.t
the current implementa tion of the shell. t
E-38
flexible
due
tThe following two formats are not currently acceptable
to
The shell does have another form of the if statement of
the form
if ( expression ) command
which can be written
if ( expression ) \
command
Here we have escaped the newline for the sake of appearance,
and the '\' must immediately. The command must not involve
'I', '&' or ';' and must not be another control command.
The second form requires the final '\'to immediately precede the end-of-line.
The more general i! statements above also admit a
sequence of ~-i! pairs followed by a single ~ and an
endif, e.g.:
if ( expression ) then
commands
else if (expression ) then
commands
•••
else
endif
commands
Another important mechanism used in shell scripts is
':' modifiers. We can use the modifier ':r' here to extract
a root of a filename. Thus if the variable ~ has the value
'foo. bar' then
echo $i $i: r
foo.bar foo
%
%
to the shell:
* Won't
if ( expression
then
command
endif
work!
•••
and
if ( expression ) then command endif
B-31
* Won't work
shows how the ':r' modifier strips off the trailing ... bar'.
Other modifiers will take off the last component of a pa thname leaving the head ':h' or all but the last component of
a pathname leaving the tail ':t'. These modifiers are fully
described in the ~ manual pages in the programmers manual.
It is also possible to use the command substitution mechanism described in the next major section to perform modifications on strings to then reenter the shells environment.
Since each usage of this mechanism involves the creation of
a new process, it is much more expensive to use than the ':'
modification mechanism.i Finally, we note that the character
'i' lexically introduces a shell comment in shell scripts
(but not from the terminal). All subsequent characters on
the input line after a 'i' are discarded by the shell. This
character can be quoted using '" or '\' to place it in an
argument word.
~.2.
Other control structures
The shell also has control structures while and
similar to those of C. These take the forms
while
end
switch
expression )
commands
and
iIt is also important to note that the current implementation of the shell limits the number of ':' modifiers on a '$' SUbstitution to 1. Thus
% echo $i $i:h:t
/a/b/c /a/b:t
%
does not do what one would expect.
E-32
switch ( word )
case strl:
commands
breaksw
•••
case strn:
commands
breaksw
default:
commands
breaksw
endsw
For details see the manual section for~.
C programmers
should note that we use breaksw to exit from a switch while
break exits a while or foreach loop. A common mistake to
make in ~ scripts is to use break rather than breaksw in
switches.
Finally, ~ allows a gQtQ statement, with labels looking like they do in C, i.e.:
loop:
commands
goto loop
~.~.
Supplying input
~
commands
Commands run from shell scripts receive by default the
standard input of the shell which is running the script.
This it is different from previous shells running under
UNIX.
It allowing shell scripts to fully participate in
pipelines, but mandates extra notation for commands which
are to take inline data.
Thus we
to commands
script which
the lines in
need a metanotation for supplying inline. data
in shell scripts. As an example, consider this
runs the editor to delete leading blanks from
each argument file
B-33
% cat deblank
i deblank -- remove leading blanks
for each i ($argv)
ed - $i « 'EOF'
1 ,$s/T [ ] * II
w
q
'EOF'
end
%
The notation '« 'EOF" means that the standard input for
the ~ command is to come from the text in the shell script
file up to the next line consisting of exactly "EOF". The
fact that the 'EOF' is enclosed in '" characters, i.e.
quoted, causes the shell to not perform variable substitution on the intervening lines. In general, if any part of
the word following the '«' which the shell uses to terminate the text to be given to the command is quoted then
these substitutions will not be performed.
In this case
since we used the form '1,$' in our editor script we needed
to insure that this '$' was not variable substituted.
We
could also have insured this by preceding the '$' here with
a '\',
l' .e.:
1, \$s/T [
] * II
but quoting the 'EOF' terminator is a more reliable
achieving the same thing.
~.~.
way
of
Catching interrupts
If our shell script creates temporary files, we may
wish to catch interruptions of the shell script so that we
can clean up these files. We can then do
onintr label
where label is a label in our program. If an interrupt is
received the shell will do a 'goto label' and we can remove
the temporary files and then do a ~ command (which is
built in to the shell) to exit from the shell script. If we
wish to exit with a non-zero status we can do
exit(l)
e.g. to exit with status '1'.
There. are other features of the shell useful to writers
of shell procedures. The verbose and ~ options and the
related -,X. and -x, command line options can be used to help
8 .... 34
trace the actions of the shell. The -n option causes the
shell only to read commands and not to execute them and may
sometimes be of use.
One other thing to note is that ~ will not execute
shell scripts which do not begin with the character ' i i ,
that is shell scripts that do not begin with a comment.
Similarly, the '/bin/sh' on your system may well defer to
'csh' to interpret shell scripts which begin with '#'. This
allows shell scripts for both shells to live in harmony.
There is also another quotation mechanism using 'ft,
which allows only some of the expansion mechanisms we have
so far discussed to occur on the quoted string and serves to
make this string into a single word as '" does.
E-35
~.
~.~.
Misgellaneous,
LOQPs At
~
~
generally useful, shell mechanisms
terminal; variables
~
vectors
It is occasionally useful to use the foreach control
structure at the terminal to aid in performing a number of
similar commands. For instance, there were at one pOint
three shells in use on the Cory UNIX system at Cory Hall,
'/bin/sh', '/bin/nsh', and '/bin/csh'. To count the number
of persons using each shell one could issue the commands
% grep -c csh$ /etc/passwd
27
% grep -c nsh$ /etc/passwd
128
%grep -c -v sh$ /etc/passwd
43e
%
Since these commands are very similar we can use foreach
do this more easily.
%foreach i (' sh$ I I csh$ I
? grep -c $i /etc/passwd
? end
I-V
to
sh $ ')
27
128
43e
%
Note here that the shell prompts for input with
reading the body of the loop.
'?
when
Very useful with loops are variables which contain
lists of filenames or other words. You can, for example, do
% set a=( 'IS')
% echo $a
csh.n csh.rm
% Is
csh.n
csh.rm
% echo $#a
2
%
The u.t. command here gave the variable .a a list of all the
filenames in the current directory as value. We can then
iterate over these names to perform any chosen function.
The output of a command within " " I characters is converted by the shell toalist of words. You can also place
the'" quoted string within "'n, characters to take each
(non-empty) line as a .component of the variable1 preventing
B-36
the lines from being split into words at blanks and tabs. A
modifier ':x' exists which can be used later to expand each
component of the variable into another variable splitting it
into separate words at embedded blanks and tabs.
~.z.
Braces { ••• } in argument expansion
Another form of filename expansion, alluded to before
involves the characters '{' and oJ'.
These characters
specify that the contained strings, separated by',' are to
be consecutively substituted into the containing characters
and the results expanded left to right. Thus
A{strl,str2, ••• strn}B
expands to
AstrlB Astr2B ••• AstrnB
This expansion occurs before the other filename expansions,
and may be applied recursively (i.e. nested). The results
of each expanded string are sorted separately, left to right
order being preserved.
The resulting filenames are not
required to exist if no other expansion mechanisms are used.
This means that this mechanism can be used to generate arguments which are not filenames, but which have common parts.
A typical use of this would be
mkdir -/{hdrs,retrofit,csh}
to make subdirectories 'hdrs', 'retrofit' and 'csh' in your
home directory. This mechanism is most useful when the common prefix is longer than in this example, i.e.
chown bin /usr/{bin/{ex,edit},lib/{exl.1strings,how_ex}}
~.~.
Command substitution
A command enclosed in " I characters is replaced, just
before filenames are expanded, by the output from that command. Thus it is possible to do
set pwd='pwd'
to save the current directory in the variable
~
or to do
ex 'grep -1 TRACE *.c'
to run the editor ~ suppling as arguments those files whose
names end in '.c' which have the string 'TRACE' in them.*
*Command expansion also occurs in input redirected with
E-37
~.~.
Other
detail~
nQt covered
~
In particular circumstances it may be necessary to know
the exact nature and order of different substitutions performed by the shell. The exact meaning of certain combinations of quotations is also occasionally important. These
are detailed fully in its manual section.
The shell has a number of command line option flags
mostly of use in writing UNIX programs, and debugging shell
scripts. See the shells manual section for a list of these
options.
and within ' f t l quotations.
manual section for full details.
'«~I
Refer to the shell
E-38
Appendix - Special characters
The following table lists the special characters of £ah and
the UNIX system, giving for each the section(s) in which it
is discussed. A number of these characters also have special meaning in expressions. See the ~ manual section for
a complete list.
Syntactic metacharacters
2.4
separates commands to be executed sequentially
separates commands in a pipeline
2.2,3.6 brackets expressions and variable values
2.5
follows commands to be executed without waiting for
completion
;
I
(
1.5
&
Filename metacharacters
separates components of a file's pathname
expansion character matching any single character
expans~on character matching any sequence of characters
*
expans~on character matching any single character
[ 1
from a set
1.6 used at the beginning of a filename to indicate home
directories
{ } 4.2 used to specify groups of arguments with common parts
Quotation metacharacters
/
?
\,
"
1.6
1.6
1.6
1.6
1.7
1.7
4.3
prevents meta-meaning of following single character
prevents meta-meaning of a group of characters
like " but allows variable and command expansion
Input/output metacharacters
<
>
1.3
1.5
indicates redirected input
indicates redirected output
Expansion/substitution metacharacters
$
.
!
T
,
3.4
2.3
3.6
2.3
4.3
indicates variable substitution
indicates history sUbstitution
precedes sUbstitution modifiers
used in special forms of history sUbstitution
indicates command substitution
Other metacharacters
3.6
1.2
begins a shell comment
prefixes option (flag) arguments to commands
£-39
Glossary
This glossary lists the most important terms introduced
in the introduction to the shell and gives references to
sections of the shell document for further information about
them.
References of the form 'pr (1)' indicate that the
command la.t is in the UNIX programmers manual in section 1.
You can get an online copy of its manual page by doing
man 1 pr
References of the form (2.5) indicate that more
can be found in section 2.5 of this manual.
information
•
Your current directory has the name '.' as
well as the name printed by the command ~.
The current directory'.' is usually the
first component of the search path contained
in the variable~, thus commands which are
in '.' are found first (2.2). The character
'.' is also used in separating components of
filenames (1.6).
The character ".' at the
beginning of a component. of a pathname is
treated specially and not matched by the
filename expansion metacharacters '1', '*',
and '[. ']' pa irs (1.6).
••
Each directory has a file .••• in it which is
a reference to its parent directory. After
changing into the directory with chdir, i.e.
chdir paper
you can return to
doing
the
parent
directory
by
chdir • •
The current
(2.6).
directory
is
printed
by
~
alias
An alias specifies a shorter or different
name for a UNIX command, or a transformation
on a command to be performed in the shell.
The shell has a command alias which establishes aliases and can print their current
values.
The command unalias is used to
remove aliases (2.6).
argument
Commands in UNIX receive a list
words. Thus the command
echo abc
B.... 48
of
argument
consists of a command name 'echo' and
argument words 'a', 'b' and 'c' (1.1).
three
argv
The list of arguments to a command written in
the shell language (a shell script or shell
procedure) is stored in a variable called
~
within the shell. This name is taken
from the conventional name in the C programming language (3.4).
background
Commands started without waiting for them to
complete
are
called background commands
(1.5).
bin
A
break
Break is a built-in command used to exit from
loops within the control structure of the
sh e 11 ( 3 .6) •
builtin
command executed directly by the shell is
called a builtin command. Most commands in
UNIX are not built into the shell, but rather
exist as files in 'bin' directories. These
commands are accessible because the directories in which they reside are named in the
~ variable.
case
command is used as a label in a switch
statement in the shells control structure,
similar to that of the language C.
Details
are given in the shells documentation 'csh
(NEW)' ( 3 .7) •
cat
The ~ program catenates a list of specified
files on the standard output. It is usually
used to look at the contents of a single file
on the terminal, to 'cat a file' (1.8, 2.3).
cd
The ~ command is used to change the working
directory.
With no arguments, ~ changes
your working directory to be your ~ directory (2.3) (2.6).
directory containing binaries of programs
and shell scripts to be executed is typically
called a 'bin' directory. The standard system 'bin' directories are '/bin' containing
the most-heavily used commands and '/usr/bin'
which contains most other user programs.
Other binaries are contained in directories
such as '/usr/new' where new programs are
placed. You can place binaries in any directory. If you wish to execute them often, the
name of the directories should be a component
of the variable ~.
A
A ~
£-41
chdir
The chdir command is a synonym for~. ~ is
usually used because it is easier to type.
chsh
The ~ command is used to change the shell
which you use on UNIX. By default, you use
an older 'standard' version of the shell
which resides in '" /bin/sh '. You can change
your shell to '/bin/csh' by doing
chsh your-Iogin-name /bin/csh
Thus I would do
chsh bill /bin/csh
It is only necessary to do this once.
The
. next time you log in to UNIX after doing this
command, you will be using ~ rather than
the shell in '/bin/sh' (1.9).
cmp
~
command
A function performed by the system, either by
the shell (a builtin command) or by a program
residing in a file in a directory within the
UNIX system is called a command (l.l).
is a program which compares files. It is
usually used on binary files, or to see if
two files are identical (3.6). For comparing
text files the program Qiff, described in
'diff (I) I is used.
command substitution
The replacement of a command enclosed in "','
characters by the text output by that command
is called command substitution (3.6, 4.3).
component
A part of a pathname between "'/1 characters
is called a component of that pathname. A
variable which has multiple strings as value
is said to have several components, each
string is a component of the variable.
continue
A builtin command which causes execution of
the enclosing foreach or while loop to cycle
prematurely. Similar to the continue command
in the programming language C (3.6).
core dump
When a program terminates abnormally, the
system places an image of its current state
in a file named 'corel. This "'core dump' can
be examined with the system debuggers 'db
(1)1 and "'cdb (1)' in order to determine what
went wrong with the program (1.8). If the
shell produces a message of the form:
E-42
commandname: Illegal instruction -- Core dumped
(where 'Illegal instruction' is only one of
several possible messages) you should report
this to the author of the program and save
the 'core' file. If this was a system program you should report this with the trouble
command 'trouble (I) '.
cp
The ~ (copy) program is used to copy the
contents of one file into another file. It
is one of the most commonly used UNIX commands ( 2 .6) •
.cshrc
The file .cshrc in your h.Qme. directory is
read by each shell as it begins execution.
It is usually used to change the setting of
the variable ~ and to set alias parameters
which are to take effect globally (2.1).
date
The ~ command prints the current date
time (1.3).
debugging
Debugging is the process of correcting mistakes 1n programs and shell scripts. The
shell has several options and variables which
may be used to aid in shell debugging (4.4).
default
The label default: is used within shell
switch statements, as it is in the C language
to label the code to be executed if none of
the ~ labels matches the value switched on
and
(3.7).
DELETE
The DELETE or RUBOUT key on the terminal is
used to generate an INTERRUPT signal in UNIX
which stops the execution of most programs
(2.6) •
detached
A command run without waiting for it to
plete is said to be detached (2.5) •
diagnostic
An error message produced by a program is
often referred to as a diagnostic. Most
error messages are not written to the standard output, since that is often directed
away from the terminal (1.3, 1.5).
Error
messages are instead written to the diagnos~ output which may be
directed away from
the terminal, but usually is not. Tbus diagnostics will usually appear on the terminal
(2.5) •
£-43
com-
directory
A structure which contains files.
At any
time you are in one particular directory
whose names can be printed by the command
'pwd'.
The chdir command will change you to
another directory, and make the files in that
directory visible.
The directory in which
you are when you first login is your ~
directory (1.1, 1.6).
echo
The ~ command prints its
2.6, 3.6, 3.19).
else
The ~ command is part of the 'if-thenelse-endif' control command construct (3.6).
EOF
An .e.rui-gf,-.f.i.l.e is generated by the terminal
by a control-d, and whenever a command reads
to the end of a file which it has been given
as input.
Commands receiving input from a
~ receive an end-of-file when the
command
sending them input completes. Most commands
terminate when they receive an end-of-file.
The shell has an option to ignore end-of-file
from a terminal input which may help you keep
from logging out accidentally by typing too
many control-d's (1.1, 1.8, 3.8).
escape
A character \ used to prevent the special
meaning of a metacharacter is said to escape
the character from its special meaning. Thus
arguments
(1.6,
echo \*
will echo the character
~*'
while just
echo *
will echo the names of the file in the
current
directory.
In this example, \
escapes '*' (1.7).
There is also a nonprinting character called escape, usually
labeled ESC or ALTMODE on terminal keyboards.
Some UNIX systems use this character to indicate that output is to be suspended. Other
systems use control-s.
/etc/passwd
This file contains information about the
accounts currently on the system. If consists of a line for each account with fields
separated by':' characters (2.3). You can
look at this file by saying
cat /etc/passwd
8-44
The command ~ is often used to search for
information in this file. See 'passwd (5)'
and 'grep (1)' for more details.
exit
The ~ command is used to force termination
of a shell script, and is built into the
shell (3.9).
exit status
A command which discovers a problem may
reflect this back to the command (such as a
shell) which invoked (executed) it. It does
this by returning a non-zero number as its
~ status, a
status of zero being considered 'normal termination'. The ~ command can be used to force a shell command
script to give a non-zero exit status (3.5).
expansion
The replacement of strings in the shell input
which contain metacharacters by other strings
is referred to as the process of expansion.
Thus the replacement of the word '*' by a
sorted list of files in the current directory
is a 'filename expansion'.
Similarly the
replacement of the characters '11' by the
text of the last command is a 'history expansion'. Expansions are also referred to as
substitutions (1.6, 3.4, 4.2).
expressions
Expressions are used in the shell to control
the conditional structures used in the writing of shell scripts and in calculating
values for these scripts.
The operators
available in shell expressions are those of
the language C (3.5).
extension
Filenames often consist of a ~ name and an
extension separated by the character '.'. By
convention, groups of related files often
share the same root name. Thus if 'prog.c'
were a C program, then the object file for
this program would be stored in 'prog.o'.
Similarly a paper written with the '-me'
nroff
macro package might be stored in
'paper.me' while a formatted version of this
paper might be kept in 'paper.out' and a list
of spelling errors in 'paper.errs' (1.6).
filename
Each file in UNIX has a name consisting of up
to 14 characters and not including the character 'I' which is used in pathname building.
Most file names do not begin with the character '.', and contain only letters and digits
with perhaps a '.' separating the root portion of the filename from an extension (1.6).
E-45
filename expansion
Filename expansion uses the metacharacters
"*', '?' and . [' and "]' to provide a convenient mechanism for naming files.
Using
filename expansion it is easy to name all the
files in the current directory, or all files
which
have
a common root name.
Other
filename expansion mechanisms use the metacharacter ,~, and allow files in other users
directories to be named easily (1.6, 4.2).
. flag
Many UNIX commands accept arguments which are
not the names of files or other users but are
used to modify the action of the commands.
These are referred to as flag options, and by
convention consists of one or more letters
preceded by the character '_I (1.2). Thus
the ~ list file commands has an option "-s'
to list the sizes of files. This is specified
Is -s
for each
The foreach command is used in shell scripts
and at the terminal to specify repetition of
a sequence of commands while the value of a
certain
shell variable ranges through a
specified list (3.6, 4.1).
getty
The getty program is part of the system which
determines the speed at which your terminal
is to run when you first log in.
It types
the initial system banner and 'login:'. When
no one is logged in on a terminal a R2 command shows a command of the form '- 7' where
'7' here is often some other single letter or
digit.
This '7' is an option to the getty
command, indicating the type of port which it
is running on.
If you see a getty command
running on a terminal in the output of R2 you
know that no one is logged in on that terminal (2.3).
goto
The~shell
scripts
has a command SQtQ used in shell
to transfer control to a given label
(3.7) •
grep
The ~ command searches through a list of
argument files for a specified string. Thus
grep bill /etc/passwd
will
print
each
line
£-46
in
the
file·
which
contains the string
Actually, ~ scans for regular
expressions in the sense of the editors ~ed
(I)' and "ex (I)' (2.3).
~
stands for
"globally find regular expression and print.'
~/etc/passwd'
~bill'.
hangup
When you hangup a phone line, a HANGUP signal
is sent to all running processes on your terminal, causing them to terminate execution
prematurely.
If you wish to start commands
to run after you log off a dialup you must
use the command nohup (2.6).
head
The ~ command prints the first few lines
of one or more files. If you have a bunch of
files containin~ text which you are wondering
about it is sometimes is useful to run ~
with these files as arguments.
This will
usually show enough of what is in these files
to let you decide which you are interested in
(1.5, 2.3).
history
The history mechanism of the shell allows
previous commands to be repeated, possibly
after modification to correct typing mistakes
or to change the meaning of the command. The
shell has a history liat where these commands
are kept, and a history variable which controls how large this list is (1.7, 2.6).
home directory Each user has a home directory, which is
given in your entry in the password file,
1~/passwd.
This is the directory which you
are placed in when you first log in. The ~
or chdir command with no arguments takes you
back
to
this directory, whose name is
recorded in the shell variable~. You can
also access the home directories of other
users in forming filenames using a file
expansion notation and the character 'N'
(1.6).
if
A conditional command within the shell, the
i f command is used in shell command scripts
to make decisions about what course of action
to take next (3.6).
ignoreeof
Normally, your shell will exit, printing
'logout' if you type a control-d at a prompt
of ~% '. This is the way you usually log off
the system. You can ~ the ignoreeofvariable if you wish in your .1Qgin file and then
use the command logout to Ipgout. This is
useful if you sometimes accidentally type too
£-47
many control-d characters, logging yourself
off. If the system is slow, this can waste
much time, as it may take a long time to log
in again (2.2, 2.6).
input
Many commands on UNIX take information from
the terminal or from files which they then
act on. This information is called input.
Commands normally read for input from their
standard input which is, by default, the terminal. This standard input can be redirected
from a file using a shell metanotation with
the character '<'. Many commands will also
read from a file specified as argument. Commands placed in pipelines will read from the
output of the previous command in the pipeline.
The leftmost command in a pipeline
reads from the terminal if you
neither
redirect its input nor give it a file name to
use as standard input.
Special mechanisms
exist for suppling input to commands in shell
s c r i pt s (1 • 2, 1.6, 3. 8) •
interrupt
An interrupt is a signal to a program that is
generated by hitting the RUBOUT or DELETE
key. It causes most programs to stop execution. Certain programs such as the shell and
the editors handle an interrupt in special
ways, usually by stopping what they are doing
and prompting for another command. While the
shell is executing another command and waiting for it to finish, the shell does not
listen to interrupts. The shell often wakes
up when you hit interrupt because many commands die when they receive an interrupt
(1.8, 2.6, 3.9).
kill
A program which terminates processes run
without waiting for them to complete. (2.6)
.login
The file .10gin in your ~ directory is
read by the shell each time you log in to
UNIX and the commands there are executed.
There are a number of commands which are usefully placed here especially ~ commands
and ~ commands to the shell itself (2.1).
logout
The logout command causes a login shell to
exit. Normally, a login shell will exit when
you hit control-d generating an end-of-file,
but if you have set ignoreeof in you .login
file then this will not work and you must use
logout to log off the UNIX system (2.2).
E-48
• logout
When you log off of UNIX the shell will execute commands from the file .logout in your
~ directory after it prints 'logout'.
Ipr
The command ~ is the line printer daemon.
The standard input of lBL is spooled and
printed on the UNIX line printer.
You can
also give ~ a list of filenames as arguments to be printed. It is most common to
use ~ as the last component of a pipeline
(2.3) •
Is
The ~ list files command is one of the most
commonly used UNIX commands. With no argument filenames it prints the names of the
files in the current directory. It has a
number of useful !lAg arguments, and can also
be given the names of directories as arguments, in which case it lists the names of
the files in these directories (1.2).
mail
The mail program is used to send and receive
messages from other UNIX users (1.1, 2.2).
make
The ~ command is used to maintain one or
more related files and to organize functions
to be performed on these files. In many ways
~
is easier to use, and more helpful than
shell command scripts (3.2).
makefile
The file containing command
called 'makef ile (3.2).
for
~
is
I
manual
The 'manual' often referred to is the 'UNIX
programmers manual.' It contains a number of
sections and a description of each UNIX program.
An online version of the manual is
accessible through the man command.
Its
documentation can be obtained online via
man man
metacharacter
Many characters which are neither letters nor
digits have special meaning either to the
shell or to UNIX.
These characters are
called metacharacters. If it is necessary to
place these characters in arguments to commands without them having their special meaning then they must be Quoted. An example of
a metacharacter is the character ')' which is
used to indicate placement of output into a
file.
For the purposes of the history
mechanism, most unquoted metacharacters form
E-49
separate words (1.4). The appendix to this
user's manual lists the metacharacters in
groups by their function.
mkdir
The mkdir command is used
directory (2.6).
modifier
Substi tutions with the history mechanism,
keyed by the character '1' or of variables
using the metacharacter '$' are often subjected to modifications, indicated by placing
the character ':' after the substitution and
following this with the modifier itself. The
command substitution mechanism can also be
used to perform modification in a similar
way, but this notation is less clear (3.6).
noclobber
The shell has a variable noclobber which may
be set in the file .login to prevent accidental destruction of files by the ')1 output
redirection metasyntax of the shell (2.2,
2.5) •
nohup
A shell command used to allow background commands to run to completion even if you log
off a dialup before they complete. (2.5)
nroff
The standard text formatter on UNIX is the
program nroff.
Using nroff and one of the
available macro packages for it, it is possible to have documents automatically formatted
and to prepare them for phototypesetting
using the typesetter program troff (3.2).
onintr
The onintr command is built into the shell
and is used to control the action of a shell
command script when an interrupt signal is
received (3.9).
output
Many commands in UNIX result in some lines of
text. which are called their output. This
output is usually placed on what is known as
the standard output which is normally connected to the users terminal. The shell has
a syntax using the metacharacter ')1 for
redirecting the standard output of a command
to a file (1.3). Using the ~ mechanism
and the metacharacter 'II it is also possible
for the standard output of one command to
become the standard input of another command
(1.5).
Certain commands such as the line
printer daemon .lpL, do not place their results
on the standard output but rather in more
useful places such as on the line printer
8-58
to
create
a
new
(2.3) •
Similarly the write command places
its output on another users terminal rather
than its standard output (2.3). Commands
also have a diagnostic output where they
write their error messages. Normally these
go to the terminal even if the standard output has been sent to a file or another command, but it is possible to direct error
diagnostics along with standard output using
a special metanotation (2.5).
path
The shell has a variable ~ which gives the
names of the directories in which it searches
for the commands which it is given.
It
always checks first to see if the command it
is given is built into the shell. If it is,
then it need not search for the command as it
can do it internally. If the command is not
builtin, then the shell searches for a file
with the name given in each of the directories in the ~ variable, left to right.
Since the normal definition of the ~ variable is
path
(. /bin /usr/bin)
the shell normally looks in the current
directory, and then in the standard system
directories '/bin' and '/usr/bin l for the
named command (2.2). If the command cannot
be found the shell will print an error diagnostic.
Scripts of shell commands will be
executed using another shell to interpret
them if they have 'execute l bits set. This
is normally true because a command of the
form
chmod 755 script
was executed to turn these
(3.3) •
pathname
execute
bits
on
A list of names, separated by '/1 characters
forms a pathname.
Each component, between
successive '/1 characters, names a directory
in which the next component file resides.
Pathnames which begin with the character .. '/1
are interpreted relative to the ~ directory in the filesystem. Other pathnames are
interpreted relative to the current directory
as reported by~. The last component of a
pathname may name a directory, but usually
names a file.
£-51
pipeline
A group of commands which are connected
together, the standard output of each connected to the standard input of the next is
called a pipeline. The ~ mechanism used
to connect these commands is indicated by the
shell metacharacter ~I 1 (1.5,2.3).
pr
The ~ command is used to prepare listings of
the contents of files with headers giving the
name of the file and the date and time at
which the file was last modified (2.3) •
. printenv
The printeny command is used on version 7
UNIX systems to print the current setting of
variables in the environment.
As of this
writing, only the VAX/UNIX system on the
fifth floor of Evans Hall is running a version 7 UNIX system. The other systems are
running version 6, which does not have or
need printeny (2.6).
process
A instance of a running program is called a
process (2.6). The numbers used by kill and
printed by ~ are unique numbers generated
for these processes by UNIX. They are useful
in kill commands which can be used to stop
background processes. (2.6)
program
Usually synonymous with command; a binary
file or shell command script which performs a
useful function is often called a program.
programmers manual
Also referred to as the manual.
glossary entry for ~manuall.
See
the
prompt
Many programs will print a prompt on the terminal when they expect input. Thus the editor ~ex (NEW)' will print a ':1 when it
expects input.
The shell prompts for input
with '% I and occasionally with ~? I when
reading commands from the terminal (1.1).
The shell has a variable prompt which may be
set to a different value to change the shells
main prompt. This is mostly used when debugging the shell (2.6).
ps
The ~ command is used to show the processes
you are currently running. Each process is
shown with its unique process number, an
indication
of
the terminal name it is
attached to, and the amount of CPU time it
has used so far. The command is identified
by printing some of the words used when it
8-52
was invoked (2.3, 2.6). Login shells, such
as the ~ you get when you login are shown
as '- 1 •
pwd
The ~ command prints the full pathname
the current (working) directory.
quit
The SYit signal, generated by a control-\ is
used to terminate programs which are behaving
unreasonably. It normally produces a core
image file (1.8).
quotation
The process by which metacharacters
are
prevented their special meaning, usually by
using the character ' I in pairs, or by using
the character '\1 is referred to as Quotation
of
(1.4) •
redirection
The routing of input or output from or to a
file is known as redirection of input or output (1.3).
repeat
The repeat command iterates another command a
specified number of times (2.6).
RUBOUT
The RUBOUT or DELETE key generates an interrupt signal which is used to stop programs or
to cause them to return and prompt for more
input (2.6).
script
Sequences of shell commands placed in a file
are called shell command scripts.
It is
often possible to perform simple tasks using
these scripts without writing a program in a
language such as C, by using the shell to
selectively run other programs (3.2, 3.3,
3.10) •
set
The builtin ~ command is used to aSSign new
values to shell variables and to show the
values of the current variables. Many shell
variables have special meaning to the shell
itself. Thus by using the set command the
behavior of the shell can be affected (2.1).
setenv
On version 7 systems variables
in
the
environment 'environ (5) 1 can be changed by
using the seteny builtin command (2.6).
The
printeny command can be used to print the
value of the variables in the environment.
Currently, only the VAX/UNIX system on the
fifth floor of Evans Hall is running version
7 UNIX.
The other systems are running version 6, where seteny is not necessary and
£-53
does not exist.
shell
A shell is a command language interpreter.
It is possible to write and run your own
shell, as shells are no different than any
other programs as far as the system is concerned. This manual deals with the details
of one particular shell, called~.
shell script
See script (3.2,
sort
The ~ program sorts a sequence of lines in
ways that can be controlled by argument flags
(1.5) •
source
The source command causes the shell to read
commands from a specified file. It is most
useful for reading files such as .cshrc after
changing them (2.6).
3~3,
3.la).
special character
See metacharacters and the appendix
manual.
to
this
standard
We refer often to the standard input and
standard output of commands. See input and
output (1.3, 3.8).
status
A command normally returns a status when it
finishes.
By convention a status of zero
indicates that the command succeeded.
Commands may return non-zero status to indicate
that some abnormal event has occurred.
The
shell variable status is set to the status
returned by the last command.
It is most
useful in shell command scripts (3.5, 3.6).
substitution
The shell implements a number of substitutions where sequences indicated by metacharacters are replaced by other sequences. Notable examples of this are history SUbstitution keyed by the metacharacter ' I ' and variable substitution indicated by '$'. We also
refer to substitutions as expansions (3.4).
switch
The switch command of the shell allows the
shell to select one of a number of sequences
of commands based on an argument string.
It
is similar to the- switch statement in the
language C (3.7).
term ina ti on
When a command which is being executed finished we say it undergoes termination or Ul:=
minates. Commands .normally terminate when
£-54
they read an end-of-file from their standard
input. It is also possible to terminate commands by sending them an interrupt or ~
signal (1.8). The kill program terminates
specified command whose numbers are given
(2.6) •
then
The ~ command is part of the shells 'ifthen-else-endif' control construct used in
command scripts (3.6).
time
The ~ command can be used to measure the
amount of CPU and real time consumed by a
specified command (2.1, 2.6).
troff
The troff program is used to
ments. See also nroff (3.2).
tset
The ~ program is used to set standard
erase and kill characters and to tell the
system what kind of terminal you are using.
It is often invoked in a .login file (2.1).
unalias
The unalias command removes aliases (2.6).
UNIX
UNIX is an operating system on which ~
runs.
UNIX provides facilities which allow
editors
~ to invoke other programs such as
and text formatters which you may wish to
use.
unset
The unset command removes the definitions
shell variables (2.2, 2.6).
typeset
docu-
of
variable expansion
See variables and expansion (2.2, 3.4).
variables
Variables in ~ hold one or more strings as
value.
The most common use of variables is
in controlling the behavior of the shell.
See ~, noclobber, and ignoreeof for examples. Variables such as ~ are also used
in writing shell programs (shell command
scripts) (2.2).
verbose
The verbose shell variable can be set to
cause commands to be echoed after they are
history expanded. This is often useful in
debugging shell scripts. The verbose variable is set by the shells -~ command line
option (3.10).
E-55
wait
The builtin command ~ causes the shell to
pause, and not prompt, until all commands run
in the background have terminated (2.6).
where
The wbere command shows where the users named
as arguments are logged into the system
(2.3) •
while
The while builtin control construct
in shell command scripts (3.7).
word
A sequence of characters which forms an argument to a command is called a~. Many
characters which are neither letters, digits,
'- I ,
, • I
or '/ I form words all by themselves
even if they are not surrounded by blanks.
Any sequence of character may be made into a
word by surrounding it with ' I I characters
except for the characters ~II and ~11 which
require special treatment (1.1, 1.6).
This
process of placing special characters in
words without their special meaning is called
guoting.
is
used
working directory
At an given time you are in one particular
directory, called your working directory.
This directories name is printed by the ~
command and the files listed by lA are the
ones in this directory. You can change working directories using chdir.
write
The write command is used to communicate with
other users who are logged in'to UNIX (2.3).
8-56
An Introduction to Display Editing with Vi
Reyised
~
versions
~.5/Z.~ ~
ABSTRACT
Yi (visual) is a display oriented interactive
text editor.
When using ~ 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 ~ you can insert new text any place in
the file quite easily. Most of the commands to Yi
move the cursor around in the file.
There are
commands to move the cursor forward and backward
in units of characters, words, sentences and paragraphs.
A small set of operators, like .d for
delete and ~ 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.
Yi 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 phone
lines.
The editor makes allowance for the low
bandwidth 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
£-57
n
on hardcopy terminals, storage tubes and
"glass tty'sl' using a one line editing window;
thus ri',Q, command set is available on all termi
nals. The full command set of the more traditional, line oriented editor ~ is available
within ri.; it is quite simple to switch between
the two modes of editing.
i-
E-58
,
"'
"
,
i
An Introduction to Display Editing with Vi
Revised .f..Q.r. versions .l.'v.2...ll
~.
~
Getting started
This document provides a quick introduction to Yi.
(Pronounced ~-~.) You should be running Yi on a file you
are familiar with while you are reading this.
The first
part of this document (sections 1 through 5) describes the
basics of using Yi. Some topics of' special inte.rest are
-presented in section 6, and some nitty-gritty details of how
the editor functions ,are saved for section 7 to avoid
cluttering the presentation here.
There is also a short appendix here, which gives for
each character the special meanings which this character has
in 21. Attached to this document should be a quick reference card.
This card summarizes the commands of ~ in a
very compact format. You should have the card handy while
you are learning ~.
~.~.
Specifying terminal type
Before you can start Yi you must tell the system what
kind of terminal you are using. Here is a (necessarily
incomplete) list of terminal type codes. If your terminal
does not appear here, you should consul t with one of the
staff members on your system to find out the code for your
terminal. If your terminal does not have a code, one can be
assigned and a description for the terminal can be created.
Code
Full name
Type
2621
Hewlett-Packard 2621A/P
Intelligent
The financial support of an IBM Graduate Fellowship and
the National Science Foundation under grants MCS7407644-A03 and MCS78-0729l is gratefully acknowledged.
E-59
2645
act4
act5
adm3a
adm3l
c100
dm1520
dm2500
dm3025
fox
h1500
h19
i100
mime
t106l
vt52
Hewlett-Packard 264x
Microterm ACT-IV
Microterm ACT-V
Lear Siegler ADM-3a
Lear Siegler ADM-3l
Human Design Concept 100
Datamedia 1520
Datamedia 2500
Datamedia 3025
Perkin-Elmer Fox
Hazeltine 1500
Heathkit h19
Infoton 100
Imitating a smart act4
Teleray 1061
Dec VT-52
Intelligent
Dumb
Dumb
Dumb
Intelligent
Intelligent
Dumb
Intelligent
Intelligent
Dumb
Intelligent
Intelligent
Intelligent
Intelligent
Intelligent
Dumb
Suppose for example that you have a Hewlett-Packard
HP262lA terminal. The code used by the system for this terminal is '2621'. In this case you can use one of the following commands to tell the system the type of your terminal:
% setenv TERM 2621
This command works with the shell ~ on both version 6 and
7 systems.
If you are using the standard version 7 shell
then you should give the commands
$ TERM=2621
$ export TERM
If you want to arrange to have your terminal type set
up automatically when you log in, you can use the tset program. If you dial in on a~, but often use hardwired
ports, atypical line for your .login file (if you use csh)
would be
setenv TERM 'tset - -d mime'
or for your .profile file (if you use sh)
TERM="tset - -d mime'
~
knows which
needs only to be
on a~. ~
kill characters,
terminals are hardwired to each port and
told that when you dial in you are probably
is usually used to change the erase and
too.
8-68
\
"
l. •.2..
Editing.a.f..i.l.e
After telling the system which kind of terminal you
have, you should make a copy of a file you are familiar
with, and run ~ on this file, giving the command
%
vi
~
replacing ~ with the name of the copy file you just
created.
The screen should clear and the text of your file
should appear on the screen.
If something else happens
refer to the footnote.++
l..~.
~ editor'~~:
~
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 buffer, and remembers the file's name.
You do not affect the contents of the file unless and until
you write the changes you make back into the original file.
l..~.
Notational conventions
In our examples, input which must be typed as is will
be presented in bold face. Text which should be replaced
with appropriate input will be given in italics.
We will
represent special characters in SMALL CAPITALS.
l..2.
you
Arrow
~
The editor command set is independent of . the terminal
are using.
On most terminals with cursor positioning
++ If you gave the system an incorrect terminal type
code then the editor may have just made a mess out of
your screen. This happens when it sends control codes
for one kind of terminal to some other kind of terminal. In this case hit the keys:q (colon and the q
key) and then hit the RETURN key. This should get you
back to the command level interpreter. Figure out what
you did wrong (ask someone else if necessary) and try
again.
Another thing which can go wrong is that you typed
the wrong file name and the editor just printed an error diagnostic. In this case you should follow the
above procedure for getting out of the editor, and try
again this time spelling the file name correctly.
If the edi tor dO'esn' t seem to respond to the commands which you type here, try sending an interrupt to
it by hitting the DEL or RUB key on your terminal, and
then hitting the :q command again followed by a carriage return.
£-61
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 1 keys as cursor positioning keys
(these are labeled 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.)
~.~.
Special characters: ESC,
~
and
~
Several of these special characters are very important,
so be sure to find them right now. Look on your keyboard
for a key labeled ESC or ALT. It should be near the upper
left corner of your terminal. Try hitting this key a few
times. The editor will ring the bell to indicate that it is
in a quiescent state.++ Partially formed commands are canceled 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 don't know what is
going on until the editor rings the bell.
The CR or RETURN key is important because it is used to
terminate certain commands. It is usually at the right 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 'II
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 'II
printed as a prompt. You can get the cursor back to the
current pOSition by hitting the DEL or RUB keY7 try this
now.* From now on we will simply refer to hitting the DEL or
RUB key as "sending an interrupt. I 1**
* As we will see later, h moves back to the left (like
control-h which is a backspace), i moves down (in the
same column), ok. moves up (in the same column), and ~
moves to the right.
++ On smart terminals where it is possibl~, the editor
will quietly flash the screen rather than ringing the
bell.
* Backspacing over the 'II will also cancel the search.
** On some systems, this interruptibility comes at a
price: you cannot type ahead when the editor is computing with the cursor on the bottom line.
£-62
,
"'
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 computation,
such as computing a new position in the file after a search
or running a command to reformat part of the buffer.
When
this is happening you can stop the editor by sending an
interrupt.
~.2.
Getting
~
Qf
~
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 buffer 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 giving the command :qlCR;+
this is a dangerous but occasionally essential command which
ends the editor session and discards all your changes.
You
need to know about this command in case you change the
editor's copy of a file you wish only to look at.
Be very
careful not to give this command when you really want to
save the changes you have made.
2.
2.~.
Moying around in
Scrolling
~
~ ~
paging
The editor has a number of commands for moving around
in the file. The most useful of these is generated by hitting the control and 0 keys at the same time, a control-O or
'A O'.
We will use this two character notation for referring
to these control keys from now on.
You may have a key
labeled ,A, on your terminal. This key will be represented
as 'T' in this document; "'A, is exclusively used as part of
the 'AX' notation for control characters.++
As you know now if you tried hitting ~O, this command
scrolls down in the file. The 0 thus stands for down. Many
editor commands are mnemonic and this,makes them much easier
to remember.
For instance the command to scroll up is ~U.
Many dumb terminals can't scroll up at all, in which case
hitting ~U clears the screen and refreshes it with a line
which is farther back in the file at the top.
If you want to see more of the file below where you
are, you can hit "E to expose one more line at the bottom of
the screen, leaving the cursor where it is.
++++ The
+ All commands which read from the last display line
can also be terminated with a ESC as well as an CR.
++ If you don't have a ,A, key on your terminal then
there is probably a key labeled 'T'; in any case these
characters are one and the same.
++++ Version 3 only.
£-63
command -Y (which is hopelessly non-mnemonic, but next to ~U
on the keyboard) exposes one more line at the top of the
screen.
There are other ways to move around in thefile1 the
keys AF and ftB ++ move forward and backward a page, keeping
a couple of lines of continuity between screens so that it
is possible to read through a file using these rather than
ftD and -U if you wish.
Notice the difference between scrolling and paging. If
you are trying to read the text in a file, hitting ftF .to
move forward a page will leave you only a little context to
look back at. Scrolling on the other hand leaves more context, and happens mor e" smoothly. You can continue to read
the text as scrolling is taking place •
. 2..2..
Searching, SQ.t.Q, .and previous context
Another way to position yourself i~ the file is by giving the editor a string to search for. Type the character /
followed by a string of characters terminated by CR.
The
editor will position the cursor at the next occurrence of
this string.
Try hitting n to then go to the next
occurrence of this string.
The character? will search
backwards from where you are, and is otherwise like /.+
If the search string you give the editor is not present
in the file the editor will print a diagnostic on the last
line of the screen,. and the cursor will be returned to its
initial position.
If you wish the search to match only at the beginning
of a line, begin the search string with an T. To match only
at the end of a line, end the search string with a $.
Thus
/fsearchCR will search for the word .. search I at the beginning of a line, and /last $CR searches for the word 'last I at
the end of a line.*
++ Not available in all v2 editors due to
memory constraints.
+ These searches will normally wrap around the end of
the file, and thus find the string even if it is not on
a line in the direction you search provided it is anywhere else in the file.
You can disable this wraparound in
scans' by
giving
the
command
:se
nowrapscanCR, or more briefly :se nowsCR.
*Actually, the string you give to search for here can
be a regular expression in the sense of the editors
~(l) and ~(l).
If you don't wish to learn about this
yet, you can disable this more general facility by doing :se nomagicCR: by putting this command in EXINIT in
your environment, you can have this always be in effect
(more about EXINIT later.)
£-64
,
"
""
i
position
The~command G, when preceded by a number will
the cursor at that line in the file. Thus lG will move the
If you give G no
cursor to the first line of the file.
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 ' - I on each remaining line.
This indicates that the last line in the file is on the screen; that
is, the '-I lines are past the end of the file.
You can find out the state of the file you are editing
by typing a
G• The editor will show you the name of the
file you are editing, the number of the current line, the
number of lines in the buffer, and the percentage of the way
through the buffer which you are. Try doing this now, and
remember the number of the line you are on. Give a G command to get to the end and then another G command to get
back where you were.
A
You can also get back to a previous position by using
the command ., (two back quotes). This is often more convenient than G because it requires no advance preparation.
Try giving a G or a search with / or ? and then a " to get
back to where you were. If you accidentally hit n or any
command which moves you far away from a context of interest,
you can quickly get back by hitting " •
.2. •.1.
Moving around
.Q..U ~
screen
Now try just moving the cursor around on the screen.
If your terminal has arrow keys (4 or 5 keys with arrows
going 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 always
use h, i, k, and~. Experienced users of ~ prefer these
keys to arrow keys, because they are usually right underneath their fingers.
Hit the + key. Each time you do, notice that the cursor advances to the next line in the file, at the first
non-white position on the line. The - key is like + but
goes the other way.,
These are very common keys for moving up and down lines
in the file.
Notice that if you go off the bottom or top
with these keys then the screen will scroll down (and up if
possible) to bring a line at a time into view. The RETURN
key has the same effect as the + key.
Yi 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 screen. Try preceding it with a number as in
3H.
This will take you to the third line on the screen.
E-65
Many Yi commands take preceding numbers and do interesting
things 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 from the bottom.
Moying within
2.~.
~ ~
Now try picking a word on some line on the screen, not
the first word on the line. move the cursor using RETURN
and - to be on the line where the word is. Try hitting the
w key. This will advance the cursor to the next word on the
line. Try hitting the b 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 beginning of the next word.
Also try SPACE (the space bar) which moves right one character and the BS (backspace or ~H) key which moves left one
character.
The key h works as -H does and is useful if you
don't have a BS key. (Also, as noted just above, 1 will
move to the right.)
If the line had punctuation in it you may have noticed
that that the wand b keys stopped at each group of punctuation. You can also go back and forwards words without stopping at punctuation by using Wand B rather than the lower
case equivalents. Think of these as bigger words.
Try
these on a few lines with punctua tion to see how they differ
from the lower case wand b.
.
The ,wor d keys wrap around the end of line, rather than
stopping at the end. Try moving to a word on a line below
where you are by repeatedly hitting w.
2 •.5..
Summary
SPACE
~B
"'D
"'E
AF
"G
"H
AN
"p
-u
Ay
+
/
?
B
G
H
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
tell what is going 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 following string forwards
scan backwards
back a word, ignoring punctuation
go to specified line, last default
home screen line
E-66
«
.,
M~
L
W
b
e
n
w
2. •.2.e
~
middle screen line
last screen line
forward a word, ignoring punctuation
back a word
end of current word
scan for next instance of / or ? pattern
word after this word
++
If you want to use the editor to look at a file, rather
than to make changes, invoke it as .:x.W instead of n. This
will set the readonly option which will prevent you from
accidently overwriting the, file.,
~.
.l.~.
Making simple changes
Inserting
One of the most useful commands is the i (insert) comAfter you type i, everything you type until you hit
mand.
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, fo~
a minute, that some of 'the characters in your line have been
overwritten, but they will reappear when you hit 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 make sure
you understand how this works; i placing text to the left of
the cursor, a to the right.
It is often the case that you want to add new lines to
the file you are editing, before or after some specific line
in the file. Find a line where this makes sense and then
give the command 0 to create a new line after the line you
are on, or the command 0 to create a new line before the
line you are on. After you create a new line in this way,
text you type up to an ESC is inserted on the new line.
Many related editor commands are invoked by the same
letter key and differ only in that one is given by a lower
case key and the other is given by an upper case key.
In
these cases, the upper case key often differs from the lower
++ Not available in all v2 editors due to
straints.
£-67
memory
con-
case key in its sense of direction, with the upper case key
working backward and/or up, while the lower case key moves
forward and/or down.
'I"'
Whenever you are typing in text, you can give many
'lines of input or just a few characters. To type in more
than one line of text, hi t a RETURN 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 terminal
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 delay 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
ftH or i) to backspace over
the last character which you
typed, and the character which you use to kill input lines
(usually @, AX, or ftu) to erase the input you have typed on
the current line.+ The character -W will erase a whole word
and leave you after the space after the previous word;.it is
useful for quickly backing up in an insert.
Notice that when you backspace during an insertion the
characters you backspace over are not erased; the cursor
moves backwards, and the characters remain on the display.
This is often useful if you are planning 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 again.
Notice also that 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 apd use the insert or append command again.
~.z.
Making small corrections
You can make small corrections in existing 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 ftH or even just h) or
SPACE (using the space bar) until the cursor is on the
+ In fact, the character -H (backspace) always works to
erase the last input character here, regardless of what
your erase character is.
E-68
,
"
\
'i
\
character which is wrong. If the character is not needed
then hit the x key; this deletes the character from the
file. It is analogous to the way you x out characters when
you make mistakes on a typewriter (except it's not as
messy) •
If the character is incorrect, you can replace it with
the correct character by giving the command r~, where ~ is
replaced by the cor;rect character. Finally if the character
which is incorrect should be replaced by more than one character, give the command s which substitutes a string of
characters, ending with ESC, for it. If there are a small
number of characters which are wrong you can precede s with
a count of the number of characters to be replaced. Counts
are also useful with x to specify the number of characters
to be deleted.
.
~.~.
~
corrections: operators
You already know almost enough to make changes at a
higher level.
All you need to know now is that the ~ key
acts as a delete operator. Try the command ~ to delete a
word.
Try hitting • a few times. Notice that this repeats
the effect of the dw. . The command • repeats the last commandwpich made a change. You can remember it by analogy
with an ellipsis ' ••• '.
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 ~ or change. The command ~ 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 '$' so that you can see this as you are typing in
the new material.
~.~.
Operating
~
lines
It is often the case that you want to operate on lines.
Find a line which you want to del~te, and type dd, the ~
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 terminal without a
delete line capability.
Try repeating the ~ operator twice; this will change a
whole line, eraSing its previous contents and replacing them
£-69
with text you type up to an ESC.+
You can delete or change more than one line by preceding the ~ or ~ with a count, i.e. Sdd deletes S 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 d3L 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 large 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 affects text which you cannot see •
.1 •.5..
Undoing
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 regret a change or make a change
incorrectly, the editor provides a ~ (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 ~ also
undoes a .\.1.
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.l! command restores the current line to the state
before you started changing it.
You can recover text which you delete, even if 'undo
will not bring it back: see the section on recovering lost
text below •
.1 •.6... Summary
SPACE
advance the cursor one pOSition
AH
backspace the cursor
AW
erase a word during an insert
erase
your erase (usually AH or i),
erases a character during an insert
kill
your kill (usually @, AX, or AH) I
kills the insert on this line
repeats the changing command
•
+ The command S is a convenient synonym for for ce , by
analogy with s. Think of S as a substitute on lines,
while s is a sUbstitute on characters.
* One subtle point here involves using the / search
after a d. This will normally delete characters from
the current position to the point of the match. If
what is desired is to delete whole lines including the
two points, give the pattern as /pat/+0, a line address.
E-78
\
,
.
'.
i
\
.~
0
U
a
c
d
i
0
u
~.
~.~.
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
deletes the object you specify
inserts text before the cursor
opens and inputs new lines, below the current
undoes the last change '
Moying about; rearranging
~
~
duplicating text
level character motions
Now move the cursor to a line where there is a punctuation or a bracketing character such as a parenthesis or a
comma or period. Try the command fx where X is this character.
This command finds the next X 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 f command and then a sequence of ;'s you can often
get to a particular place in a line much faster than with a
sequence of word motions or SPACEs. There is also a F command, which is like f, but searches 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 dfx for
some A now and notice that the X character is deleted. Undo
this with u and then try dtx; the t here stands for to,
i.e. delete up to the next X, but not the x. The command T
is the reverse of ~.
When working 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 $a will append
new text at the end of the current line.
Your file may have tab ("I) characters in it.
These
characters aI:e represented as a number of spaces 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
spaces which represent that tab. Try moving the cursor back
and forth 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
* This is settable by a command of the form :se tS=XCR,
where X is 4 to set tabstops every four columns. This
has effect on the screen representation within the editor.
£-71
they are represented in this document, that is with a two
character code, the first character of which is ~ft'. On the
scr een non-pr inting ,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 setting of the beautify
option, if you attempt to insert them in your file. You can
get a control character in the file by beginning an insert
and then typing a ~V before the control character.
The"V
quotes the following character, causing it to be inserted
directly into the file.
~.z.
Higher level
~
objects
In working with a document it is often advantageous to
work in terms of sentences, paragraphs, and sections. The
operations ( and) move to the beginning of the previous and
next sentences respectively.. Thus the command d) will
delete the rest of the current sentence7 likewise d ( will
delete the previous sentence if you are at the beginning of
the current sentence, or the current sentence up to where
you are if you are not at the beginning of the current sentence.
.
A sentence is defined to end ata '.', ' I ' or '?' which
is followed by either the end of a line, or by tw.o spaces.
Any number of closing ') " '] " 'ft, and 'II characters may
appear after the '.', 'I' or ~?' before the spaces or end of
line.
The operations { and } move over paragraphs
operations [[ and ]] move over sections.+
and
the
A paragraph 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
paragraphs. The default setting for this option defines the
paragra~h macros of the -~ and -mm macro packages, i.e. the
'.IP', .LP', '.PPI and '.QP', '.P' and '.LI' macros.++ Each
+ The [[ and ]] operations require the operation char-
acter to be doubled because they can move the cursor
far from where it currently is. While it is easy to
get back with the command ", these commands would
still be frustrating if they were easy to hit accidentally.
++ You can easily change or extend this set of macros
by assigning a different string to the paragraphs option in your EXINIT. See section 6.2 for details. The
'.bp' directive is also considered to start a para8-72
,
"
,',
\
paragraph 1 boundary is also a sentence boundary.
The sentence and paragraph commands can be given counts to operate
over groups of sentences and paragraphs.
Sections in the editor begin after 'each macro in the
sections option, normally '.NH', '.SH', '.H' and '.HU', and
each line with a formfeed -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 how they work. If you have a large
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 successive section heading in a
small window.
~.~.
Rearranging
~
duplicating
~
The editor has a single 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 .between files.
The operator ~ yanks a copy of the object which follows
into the unnamed buffer. If preceded by a buffer name, "AY,
where X here is replaced by a letter a-z, it places the text
in the named buffer. The text can then be put back in the
file with the commands ~ and ~i 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 command.
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 yy. The command Yp will also make a copy of the current
line, and place it after the current line. You can give Y a
count of lines to yank, and thus duplicate several· lines;
try 3YP.
graph.
E-73
To move text within the buffer, you need to delete it
in one place, and put it back in another. You can precede a
delete operation by the name of a buffer in which the text
is to be stored as in "a5dd deleting 5 lines into the named
buffer~.
You can then move the cursor to the eventual
resting place of the these lines and do a nap or naP to put
them back. In fact, you can switch and edit another file
before you put the lines back, by giving a command of the
form :e ~CR where ~ is the name of the other file you
want to edit. You will 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 file to another you should
use an unnamed buffer •
Summary.
.i . .i.
r
$
)
}
]]
(
{
[[
fZ
p
y
tz
FX
P
TZ
..5..
..5.~~.
first non-white on line
end of line
forward sentence
forward paragraph
forward section
backward sentence
backward paragraph
backward section"
find A forward"in line
put text back, after cursor or below current line
yank operator, for copies and moves
up to Z forward, for operators
f backward in line
put text back, before cursor or above current line
t backward" in line
Hish level commands
Writing, guitting, editing.n.elt files
So far we have seen how to enter ri. and to write out
our file using either ZZ or :wCR. The first exits from the
editor, (writing if changes were made), the second writes
and stays in the editor.
If you have changed the editor I s copy of the file but
do not wish to save your changes, ei ther because you messed
up the file or decided that the changes are not an improvement to the file, then you can give the command :qlCR to
quit from the editor without writing the changes.
You can
also reedit the same file (starting over) by giving the command :e lCR. These commands should be used only rarely, "an,d
~~
E-74
,
"
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 different file without leaving the editor by giving the command :e ~CR. If you have not written out your file before you try to do this, then the editor
will tell you this, and delay editing the other file. You
can then give the command :wCR to save your work and then
the :e ~CR command again, or carefully give the command
:e! ~CR, which edits the other file discarding the
changes you have made to the current file. To have the editor automatically save changes, include ~ autowrite in
your EXINIT, and use :n instead of :e.
~.2.
'Escaping
~
A shell
You can get to a shell to execute a single command by
giving a Yi command of the form :!&mdCR. The system will
run the single command ~ and when the command finishes,
the editor will ask you to hit a RETURN to continue. When
you have finished looking at the output on the screen, you
should hit RETURN and the editor will clear the screen and
redraw it. You can then continue editing.
You can also
give . another : command when it asks you for a RETURN; in
this case the screen will not be redrawn.
If you wish to execute more than one command in the
shell, then you can give the command :shCR. This will give
you a new shell, and when you finish with the shell, ending
it by typing a ~D, the editor will clear the screen and continue.
On systems which support it, -Z will suspend the editor
and return to the (top level) shell. When the editor is
resumed, the screen will be redrawn.
~.~.
Marking And returning
The command " returned to the previous place after a
motion of the cursor by a command such as I, ? or G. You
can also 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 ~, say 'al. Then move the cursor to a different line (any way you like) and hit 'a. The cursor will
return to the place which you marked. Marks last only until
you edit another file.
When using operators such as ~ 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 'X rather than 'x. Used
without an operator, 'X will move to the first non-white
character of the marked line; similarly" moves to the
E-75
first non-white character of the line containing the
ous context mark "~a
2.~.
Adjusting
~
previ-
sCreen
If the screen 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 ASCII form-feed character, to cause the screen 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 get rid
of these lines by typing ~R to cause the editor to retype
the screen, closing up these holes.
Finally, if you wish to place a certain line on the
screen at the top middle or bottom of the screen, 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. (z.,
z-, and z+ are not available on all v2 editors.)
~.
Q.~.
Special topics
Editing
Qn ~
terminals
When you are on a slow terminal, it is important to
limit the amount of output which is generated to your screen
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 @ when they are deleted on dumb terminals.
.
The use of the slow terminal insertion mode is controlled by the slowopen option. You can force the editor to
use this mode even on faster terminals by giving 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 noslowCR.
The editor can simulate an intelligent terminal on a
dumb one. Try giving the command :se redrawCR. This simulation generates a great deal of output and is generally
tolerable only on lightly loaded systems and fast terminals.
You can disable this by giving the command
:se noredrawCR.
.
The editor also makes editing more pleasant at low
speed by starting editing in a small window, and letting the
window expand as you edit. This works particularly well on
E-76
\
\
intelligent 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 which is redrawn
each time the screen is cleared by giving window sizes as
argument to the commands which cause large screen motions:
:
/
?
[[
]]
"
Thus if you are searching for a particular instance of a
common string in a file you can precede the first search
command by a small number, say 3, and the editor will draw
th ree line wlndows around each instance of the str ing which
it locates.
You can easily expand or contract the window, placing
the current line as you choose, by giving a number on a z
command, after the z and before the following RETURN, • or
• Thus the command zS. redraws the screen with the current
line in the center of a five line window.+
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 the
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 again, ignoring the current state of the display.
~
See section 7.8 on ~ mode for another way to use the
command set on slow terminals.
~.z.
Options,~,
And 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.
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
+ Note that the command 5z. has an entirely different
effect, placing line 5 in the center of a new window.
B-77
Name
Default
autoindent
autowrite
ignorecase
lisp
list
magic
number
paragraphs
redraw
sections
shiftwidth
showmatch
slowopen
term
set
noai
noaw
noic
nolisp
nolist
nomagic
nonu
para=IPLPPPQPbpP LI
nore
sect=NHSHD DU
sw=S
nosm
slow
dumb
Description
Supply indentation automatically
Automatic write before :n, :ta, ~f,
Ignore case in searching
( { ) } commands deal with S-expressions
Tabs print as AI; end of lines marked with $
The characeers • [ and * are special in scans
Lines are displayed prefixed with line numbeI
Macro names which start paragraphs
Simulate a smart terminal on a dumb one
Marco names which start new sections
Shift distance for <,>' and input ~D and ~T
Show matching ( or { as ) or } is typed
Postpone display updates during inserts
The kind of terminal you are using
~=nJ.
and toggle options can be set or unset by statements of
of. the forms
one
set ~
set no.w2,t
These statements can be placed in your EXINIT in your
environment, or given while you are running ~ by preceding
them with a : and fol~owing them with a CR.
You can get a list of all options which you have
changed by the command :setCR, or the value of a single
option by the command :set ~?CR. A list of all possible
options and their values is generated by :set allCR. Set
:can be abbreviated see Multiple options can be placed on
.~ne.line, e.g.
:se ai aw nuCR •.
Options set by the set command only last while you stay
in the editor. It is common to want to have certain options
set whenever· you use the edi tor. This can be accomplished
by creating a list of .ex commands+ which are to be run every
time you start up .ex, ~, or~. A typical list includes
a set command, and possibly a few map commands (on v3 editors).
Since it is advisable to get these commands on one
line, they can be separated with the I character, for example:
set ai aw terselmap @ ddlmap i x
which sets the options autoindent, autowrite, terse, (the
makes @ delete a line, (the first mAl1), and
.s..e.t command),
.--'II:
+ All commands which start with : are .ex commands.
E-78
,
"
"
.
.
'.
makes ~Hdelete a character, (the second ~) • (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 ~, put this line
in the file .login in your home directory:
setenv EXINIT 'set ai aw terse Imap @ ddlmap i x'
If yOll use the standard v7 shell, put
file .profile in your home directory:
these
lines
in
the
EXINIT='set ai aw terselmap @ ddlmap i x'
export EXINIT
On a version 6 system, the concept of environments is not
present.
In this case, put the line in the file .exrc in
your home directory.
set ai aw terselmap @ ddlmap t x
Of course, the particulars of the line would depend on which
options you wanted to set.
~.~.
Recoyering
~
lines
You might have a serious problem if you delete a number
of lines and then regret that tney 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' thprevious deleted text back in your file by the command wnp.
The
n here says that a buffer na~e is to follow, n is the number
of the buffer you wish to try (use the number 1 for now),
and ~ is the put command, which puts text in the buffer
after the cursor. If this doesn't bring back the text you
wanted, hit y 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 buffer before repeating the command.
Thus a sequence of the form
"lpu.u.u.
will, if repeated long enough, show you all the deleted' text
which has been saved for you. You can omit the y commands
here to gather up all this text in the buffer, or stop after
any • command to keep just the then recovered text. The
command ~. can also be used rather than R to put the
recovered text before rather than after the cursor.
~.~.
were
Recoyering
~
files
If the system crashes, you can recover the work you
doing to within a few changes. You will normally
£-79
receive mail when you next login g1v1ng you the name of the
, file which has been saved for you. You should then change to
the directory where. you were when the system crashed and
give a command of the form:
%
vi - r
1l.allle.
replacing name with the name of the file which you were
editing.
This will recover your work to a point near where
you left off.+
You can get a listing of the files which are saved
you by giving the command:
%
for
vi -r
If there is more than one instance of a particular file
saved, the edi tor gives you the newest instance each time
you recover it. You can thus get an older saved copy back
by first recovering the newer copies.
For this feature to work, ~ must be
correctly
installed. by a super user on your system, and the mail program must exist to receive mail. The invocation "~ -L"
will not always list all saved files, but they can be
recovered even if they are not listed.
~.~.
Continuous
~
input
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 happen by giving the command
:se wm=l0CR. This causes all lines to be broken at a space
at least 10 columns from the right hand edge of the screen.*
If the editor breaks an input line and you wish to put
it back together you can tell it to j·oin the lines with J.
You can give J a count of the number of lines to be joined
as in 3J to join 3 lines. The editor supplies white space,
if appropriate, at the juncture of the joined lines, and
leaves the cursor at this white space. You can kill the
+ In rare cases, some of the lines of the file may be
lost.
The editor will give you the numbers of these
lines and the text of the lines will be replaced by the
string 'LOST'. These lines will almost always be among
the last few which you changed. You can either choose
to discard the changes which you made (if they are easy
to remake) or to replace the few lost lines by hand.
* This feature is not available on some v2 editors. In
v2 editors where it is available, the break can only
occur to the right of the specified boundary instead of
to the left.
B-81
,
\
white space with x if you don't want it.
~.~.
Features
~
editing programs
The editor has a number of commands for editing programs.
The thing that most distinguishes editing of programs from editing of text is the desirability of maintaining an indented structure to the body of the program. The
editor has a autoindent facility for helping you generate
correctly indented programs.
To enable this facility you can give the command :se
aiCR. Now try opening a new line with 0 and type some characters on the line after a few tabs.
If you now start
another line, notice that the editor supplies white space at
the beginning of the line to line it up with the previous
line.
You cannot backspace over this indentation, but you
can use AD key to backtab over the supplied indentation.
Each time you type -0 you back up one pOSition, normally to an 8 column boundary. This amount is settable: the
editor has an option called shiftwidth which you can set to
change this value.
Try giving the c'ommand :se sw=4CR and
then experimenting with autoindent again.
For shifting lines in the program left and right, there
are operators < and >~ These shift the lines you specify
right or left by one shiftwidth. Try« and » which· shift
one line left or right, and L shifting the rest of
the display left and right.
If you have a complicated expression and
how the parentheses match, put the cursor at a
parenthesis and hit %. This will show you
parenthesis. This works also for braces { and
ets [ and ].
wish to see
left or right
the rna tching
}, and brack-
If you are editing C programs, you can use the [[ and
]] keys to advance or retreat to a line starting with a {,
i.e. a function declaration at a time. When]] is used with
an operator it stops after a line which starts with }; this
is sometimes useful with y]].
~.2.
Filtering pOrtions Qf
~
buffer
You can run system commands over portions of the buffer
using the operator 1. 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 l}sortCR.
This says to sort the next paragraph of material, and the
blank line ends a paragraph.
£-81
~.~.
Commands
~
editing
~+
If you are editing a LISP program you should set the
option .l.i..w2 by doing :se lispCR. This changes the ( and )
commands to move backward and forward over s-expressions.
The { and } commands are like ( and) but don't stop at
atoms. These can be used to skip to the next list, or
through a comment quickly.
The auto indent option works differently for LISP, 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
LISP, the showmatch option. Try setting it with :se smeR
and then try typing a '(I some words and then a ') I. Notice
that the cursor shows the position of the '(I which matches
the ') I briefly. This happens only if the matching ' ( I 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 ~ and autoin~ set.
This is the = operator. Try the command =% at
the beginning of a function.
This will realign all the
lines of the function declaration.
When you are editing LISP" the [[ and]] advance and
retreat to lines beginning with a (, and are useful for
dealing with entire function definitions.
~
•.2...
Macros++
Yi has a parameterless macro facility, which lets you
set it up so that when you hit a single keystroke, the editor will act as though you had hit 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 followed by another @ to repeat the last
macro.
+ The LISP features are not available on some v2 editors due to memory ponstraints.
++ The macro feature is available only in version 3 editors.
E-82
,
\
b)
\
You; can use the maR command from ti (typically in
EXINIT) with a command of the form:
your
:map .lha .t.b..aCR
mapping-lhQ into~.
There are restrictions: lha
should be one keystroke (either I character or one
function key) since it must be entered within one
second (unless notimeout is set, in which case you can
type i.t as slowly as you wish, and n will wait for you
to finish it before it echoes anything). The.lha. can
be no longer than 19 characters, the Lha no longer than
199.
To get a space, tab or newline into.lha. or ~
you should escape them with a ~V. (It may be necessary
to double the -V if the map command is given inside ti,
rather than in ~.) Spaces and tabs inside the Lha need
not be escaped.
.
Thus to make the q key write and exit the
can give the command
editor,
you
:map q :wq··V"VCR CR
which means that whenever you type q, it will be as though
you had typed the four characters :wqCR. A "V's is needed
because without it the CR would end the : command,_ rather
than becoming part of the ~ definition. There are two
Ay'S because from within ti, two "y's must be typed to get
one. The first CR is part of the~, the second terminates
th e : command.·
Macros can be deleted with
unmap lhs
If the ~ of a macro is "19"
through '~i9", this
the particular function key instead of the 2 character
"~I"~ sequence.
So that terminals without function keys can
access such definitions, the form "Ix" will mean function
key X on all terminals (and need not be typed within one
second.) The character "i" can be changed by using a macro
in the usual way:
maps
:map AV"V"I I
to use tab, for example. (This won't affect the maR command, which still uses I, but just the invocation from
visual mode.
The undo command reverses an entire
unit, if it made any changes.
Placing a 'I' after the word
~
E-83
macro
call
as
causes the mapping
a
to
apply to input mode, rather than command mode. Thus, to
arrange for ftT to be the same as 4 spaces in input mode, you
can type:
:map "T fttn.n.lww
v"",,,","''''
where ~ is a blank. The ftV is necessary to prevent the
blanks from being taken as white space between the lha and
.r.h.a.
2.
,.
".'
~
Abbreviatione ++++
A feature similar to macros in input mode is word
abbreviation. This allows you to type a shor t wor d and have
it expanded into a longer word or words. The commands are
and :uDabbte~iate . (:ab and :WlA) and have the
:abbte~;i.gte
same syntax as : maR· For example:
:ab eecs Electrical Engineering and Computer Sciences
causes the word 'eecs' to always be changed into the phrase
'Electrical Engineering and Computer Sciences'. Word abbreviation is different from macros in that only whole words
are affected.
If 'eecs' were typed as part of a larger
word, it would be left alone. Also, the partial word is
echoed as it is typed. There is no need for an abbreviation
to be a Single keystroke, as it should be with a macro.
2.~.
AbbteviatioDS
The editor has a number of short commands'which abbreviate longer commands which we have introduced here. You
can find these commands easily on the quick reference card.
They often save a bit of typing and you can learn them as
convenient.
~.
~.~.
Nitty-gtitty detaile
~
tePteeentation in
~
display
The editor folds long logical lines onto many physical
lines in the display. Commands which advance lines advance
logical lines and will skip over all the segments of a line
in o·ne motion. The command I moves the cursor to a specific
column, and may be useful for getting near the middle of a
long line to split it in half. Try 801 on a line which is
more than 80 columns long.+
The editor only puts full
lines
on
the
++++ Version 3 only.
+ You can make long lines very easily
join together short lines.
by
using
£-84
display;
J
to
if
there is'lnot enough room on the display to fit a logical
line, the editor leaves the physical line empty, placing
only an @ on the line as a place holder.
When you delete
lines on a dumb terminal, the editor will often just clear
the lines to @ to save time (rather than rewriting the rest
of the screen.) You can always maximize the information on
the screeu by giving the ~R command.
If you wish, you can have the editor place line numbers
before each line on the display. Give the command :se nuCR
to enable this, and the command :se nonuCR to turn it off.
You can have tabs represented as ~I and the ends of lines
indicated with "$' by giving the command :se listCR: :se
nolistCR turns this off.
Finally, lines consisting of only the character ,-, are
displayed when the last line in the file is in the middle of
the screen. These represent physical lines which are past
the logical end of file •
.a..2..
Counts
Most ~ commands will use a preceding count to affect
their behavior in some way. The following table gives the
common ways in which the counts are used:
new window size
scroll amount
line/column number
repeat effect
:. /
?
AD "U
[[
]]
.
z G I
most of the rest
The editor maintains a notion of the current default
window size. On terminals which run at speeds greater than
1200 baud the editor uses the full terminal screen. On terminals which are slower than l2SS baud (most dialup lines
are in this group) the editor uses 8 lines as the default
window size. At l2SS baud the default is 16 lines.
This size is the size u.sed when the editor clears and
refills the screen 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 all often cause the screen
to be redrawn. If you anticipate this, but do not need as
large a window as you are currently using, you may wish to
change the screen size by specifying the new size before
these commands.
In any case, the number of lines used on
the screen will expand if you move off the top with a
or
similar command or off the bottom with a command such as
RETURN or ~D. The window will revert to the last specified
size the next time it is cleared and refilled.+
B-85
The scroll commands ~D and ··U likewise remember the
amount of 'scroll 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 lea+----ESC
will insert a grid-like string of text. A few commands also
use a preceding count as a line or column number.
',.
Except for a few commands which ignore any counts (such
as "R), the rest of the editor commands use a count to indicate a simple repetition of their effect. Thus 5w advances
five words on the current line, while 5RETURN advances five
lines. A very useful instance of a count as a repetition is
a count given 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 delete two
more words with 2 ••
~~~.
~ ~
manipulation commands
The following table lists the fil·e manipulation
mands which you can use when you are in ~.
:w
:wq
:x
:e~
:e!
:e + .na..m.e.
:e +n
.:e i
:w
.ruu:n.e
:w! n..mn.e
: X, ::lw .wllIUit
: r .ruu:n.e
:r !~
:n
:n!
:n ..a.t..SLa
:ta .tag
com-
write back changes
write and quit
write (if necessary) and quit (same as ZZ).
edit file Jl.alDf:.
reedit, discarding changes
edit, starting at end
edit, starting at line n
edit alternate file
write file name
overwrite file name
write lines X through :t. to name
read file Jl.alDf:. into buffer
read output of ~ into buffer
edit next file in argument list
edit next file, discarding changes to current
specify new argument list
edit file containing tag ~, at .tag
All of these commands are followed by a CR 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 give :w commands occasionally after major amounts of editing, and then finish with a
ZZ.
When you edit more than one file, y~u can· finish with
one with a :w and start editing a new file by giving a :e
command, or set autowrite and use :n .
+ But not by a AL which just redraws the screen
is.
as
it
£-86
"
.,
"
,
:'1
\
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 +n argument to start at line n.
In actuality, n may be any editor command not containing a
space, usefully a scan like +/~ or +?~. 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 haven't written the file, you can give a :w
command and then a :e # command to redo the previous :e.
You can write part of the buffer 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 m and
then use an address of the form 'x,'~ on the w command here.
A
You can read another file into the buffer after the
current line by using the :r command. You can similarly
read in the output from a command, just use 19nsi instead of
a file name.
If you wish to edit a set of files in succession, 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 giving the :n
command a list of file names, or a pattern to be expanded as
you would have given it on the initial .Do. command.
If you are editing large programs, you will find the
:ta command very useful. It utilizes a data base of function names and their locations, which can be created by programs such as ctags, to quickly find a function whose name
you give. If the :ta command will require the editor to
switch files, then you must :w or abandon any changes before
switching. You can repeat the :ta command without any arguments to look for the same tag again. (The tag feature is
not available in some v2 editors.)
~.~.
~
about searching
~
strings
When you are searching for strings in the file with /
and ?, the editor normally places you' at the next or previousoccurrence of the string. If you are using an operator
such as d, c or y, then you may well wish to affect lines up
to the line before the line containing the pattern. You can
give a search of the form /~-n to refer to the n'th line
E-87
before the next line containing ~, or you can use +
instead of - to refer to the lines after the one containing
~.
If you don't give a line offset, then the editor will
affect characters up to the match place, rather than whole
lines; thus use .. '+0" to affect to the line which matches.
You can have the editor ignore the case of words in the
searches it does by giving the command :se icCR. The command :se noicCR turns this off.
Strings given to searches may actually be regular
expressions.
If you do not want or need this facility, you
should
set nomagic
in your'EXINIT. In this case, only the characters T and $
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 / in a forward scan
or a ? in a backward scan, in any case. The following table
gives the extended forms when magic is set.
T
$
•
\<
\>
[nl:l
[Tnl:l
[x.-ltl
*
at beginning of pattern, matches beginning of line
at end of pattern, matches end of line
matches any character
matches the beginning of a word
matches the end of a word
matches any single character in .s.t.I.
matches any single character not in ~
matches any character between X and ~
matches any number of the preceding pattern
If you use nomagic mode, then the • [ and
given with a preced,ing \.
~.~.
~
about input
*
primitives
are
~
There are a number of characters which you can use to
make corrections during input mode. These are summarized in
the following table.
£-88
"'H
"'w
erase
kill
\
ESC
DEL
CR
"'0
B"'O
1"0
"'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 "H and your erase and kill
ends an insertion
interrupts an insertion, terminating it abnormally
starts a new line
backtabs over autoindent
kills all the autoindent
same as B"'O, 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 "'H to correct a single character, or by typing one or
more "WIS to back over incorrect words. If you use t 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 you have given on the current line. In
general, you can neither erase input back around a line
boundary nor can you erase 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 make the correction, and then return to where you were to continue. The
command A which appends at the end of the current line is
often useful for continuing.
If you wish to type in your erase or kill character
(say t 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 non-printing characters into the file is to
precede them with a "'V. The "'V echoes' as a T character on
which the cursor rests.
This indicates that the editor
expects you to type a control character. In fact you may
type any character and it will be inserted into the file at
that point.*
* This is not quite true. The implementation of the
editor does not allow the NULL ("@) character to appear
in files. Also the LF (linefeed or "'J) character is
used by the editor to separate lines in the file, so it
cannot appear in the middle of a line. You can insert'
any other character, however, if you wait for the editor to echo the T before you type the character.
In
fact, the editor will treat a following letter as a request for the corresponding control character. This is
the only way to type "'s or "0, since the system normalB-89
If you are using autoindent you can backtab over the
indent which it supplies by typing a ftD. This backs up to a
shiftwidth boundary. This only works immediately after the
supplied autoindent.
When you are using autoindent you may wish to place a
label at the left margin of a line. The way to do this
easily is to type T and then ~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 B followed
immediately by a ~D if you wish to kill all the indent and
not have it come back on the next line.
~.~.
Upper
~ ~
terminals
If your terminal has only upper case, you can still use
vi by using the normal system convention for typing on such
a terminal. Characters which you normally type are converted to lower case, and you can type upper case letters by
preceding them with a \. The characters { - } I ' are not
available on such terminals, but you can escape them as \(
\T \) \1 \1.
These characters are represented on the
display in the same way they are typed.++ ++
Y..i is actually one mode of editing within the editor
When you are running
you can escape to the line
oriented editor of .ex by giving the command O. All of the :
commands .which were introduced above are available in ~.
Likewise, most .ex commands can be invoked from n 'using :.
Just give -them without the : and follow them with a CR.
n
.ex.
n.
In rare instances, an internal error may occur in
In this case you will get a diagnostic and be left in the
command mode of .ex. You can then save your work and quit if
. you wish by giving a command x after the : which ~ prompts
you with, or you can reenter n by giving ~ a n command.
There are a number of things which you can do more
easily in ~ than in
Systematic changes in line
oriented material are particularly easy. You can read the
advanced editing documents for the editor ~ to find out a
lot more about this style of editing.
Experienced users
often mix their use of ~ command mode and
command mode
to speed the work they 'are doing.
n.
n
ly uses them to suspend and resume output and never
gives them to the editor to process.
++ The \ character you give will not echo until you
type another key.
++ Not available in all v2 editors due to memory constraints.
E-98
,
B..B..
o1.en
J;.U r .§. r r':f=
~:
.ti.
.2n
hardcopy
terminals
.and
' 'glass
If you are on a hardcopy terminal or a. terminal which
does not have a cursor which can move off the bottom line,
you can still use the command set of ~, but in a different
mode.
When you give a ~ command, the editor will tell you
that it is using ~ mode. This name comes from the ~
command in ~, which is used to get into the same mode.
The only difference between visual mode and
is the way in which the text is displayed.
open
mode
In ~ mode the editor uses a single line window into
the file, and moving backward and forward in the file causes
new lines to be displayed, always below the current line.
Two commands of ~ work differently in open: Z and ftR. The
Z command does not take parameters, but rather draws a window of context around the current line and then returns you
to the current line.
If you are on a hardcopy terminal, the ftB command will
retype the current line. On such terminals, the editor normally. uses two lines to represent the current line.
The
first line is a copy of the line as you started to edit it,
and you work on the line below this line. When you delete
characters, the editor types a number of \'s to show you the
characters which are deleted. The editor also ~eprints the
current line soon after such changes so that you can see
what the line looks like· again.
It is sometimes useful to use this mode on very slow
terminals which can support n in the full screen mode. You
can do this by entering ~ and using an ~. command.
£-91
Ex Quick Reference
Vi Quick Reference
Specifying terminal
Entering/leaving ex
,
,
,
,
,
,
,
ex
ex
ex
ex
ex
ex
ex
x
, setenv TERM
edit name, start at end
••• at line Jl
start at .tAg
list savee files
recover file name
edit first: rest via :n
read only mode
exit, saving changes
exit, discarding changes
JlAlll.e
+n JlAlll.e
-I; .tAg
-r
- r JlAlll.e
JlAlll.e •••
-R JlAlll.e
ql
$
See also
2621
264S
3 Us
33
31
4814
Command
I
Open/visual
~
N
ab
a
ar
c
co
d
e
f
Entered by a i and
Arbitrary text
c.
then term ina tes wi th
line having only.
character on it or
abnormally
with
interrupt.
9
i
j
1
ma
m
n
nu
0
pre
p
pu
q
re
rec
rew
se
sh
so
st
s
unabbrev
undo
unmap
..
version
visual
write
xit
yank
ldndax
~
l.Ihif..t
•
$
+
.,
,.'
+n
,
li ne Jl
current
last
next
previous
Jl forward
1,$
/RAt
?RAt
.I.-n
.I.,~
'.I.
"
I
<
CR
nh.ill
G.t.o.ll
~D
.,."Excomrriand addresses
11
una
u
unm
ve
vi
w
x
ya
z
~Jlnt
teaubat
•>
autoindent
autowrite
ignorecase
lisp
Ust
magic
number
paragraphs
redraw
scroll
sections
shiftwidth
showmatch
slowopen
window
wrapscan
wrapmargin
dwl
dw2
gl:48
gl:42
hlS88
h1518
h19
il""
mime
owl
tl861
vt52
place set's here in environment var.
enable option
disable option
give value JfllJ.
show changed options
show all options
show value of option .&
ai
aw
ic
nu
para
sect
sw
am
slow
ws
,.
supply indent
write before changing files
in scanning
( ) { } are s-exp's
print ~I for tab, $ at end
• ( • special in patterns
number lines
macro names which start
Simulate smart terminal
command mode lines
macro names •••
for ( >, and input ~D
to ) and } as typed
choke updates during insert
visual mode lines
around end of buffer?
automatic line splitting
Scanning pattem formation
T
$
\<
\>
(all)
next with RAt
previous with Rat
n before .I.
.I. through JJ.
marked with .&
previous context
adm31
adm3a
cUl8
dmlS28
dm2SIJ8
dm3825
, vi JlAlll.e
, vi +11 nAme.
, vi + nAme.
, vi -r
, vi -r nAme.
, vi nAme. •••
, vi -1:.tAg
, vi +/RAt nAme.
, view nAme.
ZZ
~z
edit nAme. at top
••• at line 11
••• at end
list saved files
recover file nAme.
edit first, rest via :n
start at .tAg
search for Rat
read only mode
exit from vi, saving change
stop vi for later resumpti~
The display
Last line
lines
- lines
@
~X
tabs
Error messages, echoing input to
I
/
? and I, feedback about i/o
and large changes.
On screen only, not in file.
Lines past end of file.
Control characters, ~? is delete.
Expand to spaces, cursor at last.
Useful options
Entered by open or
vi, termina tes with
Q or ~\.
next
number
open
preserve
print
put
quit
read
recover
rewind
set
shell
source
stop
substitute
11iH.(1)
43
733
14S
act4
actS
adm]
EXINIT
set .I.
set no.l.
set .I.-W
set
set all
set .&?
Ex commands
abbrev
append
args
change
copy
celete
edit
file
global
insert
join
list
map
mark
move
export TERM
Initializing options
Normal and initial
state.
Input
proRtpted for by :.
Your kill character
cancels partial command.
Insert
Entering/leaving vi
and all version 6
.lib in Version 7
~
Some terminal types
Ex statel
till
TER~i=.t.Y.Re1
type .
~
(Tau)
lx-~)
•
beginning of line
end of line
any character
beginning of word
end of word
any char in .a.tJ:.
not in .a.tJ:.
••• between X and JJ.
any number of preceding
Vi statas
Command
Insert
Last line
Normal
initial
and
Others return
state.
ESC
(escape)
here.
cancels partial command.
Entered by a i A I 0 0
c CaS R. Arbitrary
text then terminates
with ESC character, or
abnormally with interrupt.
Reading input for: /
? or 11 terminate with
ESC or CR to execute,
interrupt to cancel.
Counts before vi commands
z G ,
line/column number
scroll amount
replicate insert
repeat effect
~D
·'0
a i A I
most rest
Simple Commands
dw
de
dd
3dd
i.t..e.xJ;ESC
delete a word
••• leaving punctuation
delete a line
••• 3 linea
insert text A1u::
cw.D.eltESC
change word to Jl£K
ea,aESC
plurali:le word
transpose characters
,
Interrupting, cancelling
end insert or incomplete cmd
(delete or ruboutl interrupts
reprint screen if ~? scrambles it
ESC
~?
~L
File manipulation
:w
write back changes
:wq
:q
Iql
Ie na.ow.
lei
Ie + ~
Ie +.11
Ie •
~T
IW na.ow.
IW I na.ow.
Ish
I
I gad
In
In JU:SUl
If
~G
Ita .tAIl
~J
,.
~
write and quit
quit
quit, discard changes
edit file JlAIIIa
reedit, discard changes
edit, starting at end
edit starting at line B
edit alternate file
synonym for :e •
write file ~
overwrite file nAmA
run shell, then return
run gad, then return
edit next file in arglist
specify new arglist
show current file and line
synonym for If
to tag file entry .tAIl
Ita, following word 1s .tAIl
Positioning within file
~r
AB
-D
AU
G
lat
?u.t
n
N
Iat/+a
?u.t?-a
JI
II
,
forward screenfull
backward acreenfull
scroll down half screen
scroll up half screen
goto line (end default)
next line matching u.t
prev line matching RAt
repeat last / or ?
reverse last I or ?
n'th line after RAt
n'th line before RAt
next section/function
previous section/function
find matching ( I { or }
Line positioning
U
L
M
+
CR
or j
l or k.
Character positioning
T
"
$
h or -)
1 or (-
AU
space
fx
F,lt
tll.
,
,
T,lt
,
I
zCR
z-
z.
lat/z-
zn.
-E
·Y
clear and redraw
retype, eliminate @ lines
redraw, current at window top
at bottom
••• at center
at line at bottom
use .11 line window
scroll window down I line
scroll window up 1 line
w
b
e
)
}
(
{
W
B
E
"
m,lt
'x
'x
previous conte·xt
••• at first non-white in line
mark position with letter X
to mark JI.
••• at first non-white in line
word forward
back word
end of word.
to next sentence
to next paragraph
back sentence
back paragraph
blank delimited word
back W
to end of W
Commands for LISP
Forward a-expression
••• but don't atop at at~ls
Back s-expression
••• but don't stop at atoms
Corrections during insert
~u
-W
erase
kill
\
Marking and retuming
first non white
beginning of line
end of line
forward
backwards
same as (same as -)
find ,It forward
f backward
upto ,It forward
back upto ,It
repeat last f F t or T
inverse of ,
to specified column
find matching ( ( ) or
Words, sentences, paragraphs
Adjusting the screen
-L
-R
home window line
last wir.dow line
middle window line
next line, at first non-white
previous line, ,at first non-white
return, same as +
next line, same column
previous line, same column
ESC
~?
~D
T"o
1l~0
-V
erase last character
erases last word
your eraEe, same as -U
your kill, erase input this line
escapes ~U, your erase and kill
ends insertion, back to command
interrupt, terminates insert
backtab over autoindent
kill autoiqdent, save for next
••• but at margin next also
quote non-prjnting character
Insert and replace
a
i
I.
I
o
o
rll.
R
append after cursor
inse r t bef or e
append at end of line
insert before filst n0r.~~~k
open line belOW
,.•,,open above
replace Single char with lI.
replace characters
Operators (double to affect lines)
d
c
<
>
I
y
delete
change
left shift
right shift
filter through command
indent for LISP
yank lines to buffer
Miscellaneous operations
C
o
s
S
J
x
X
Y
change rest of line
delete rest of line
substitute chars
substitute lines
join lines
delete characters
.,. before cursor
yank lines
Vmkmdp~
p
P
-JtP
-JtY
-lI.d
put back lines
put before
put from buffer ,It
yank to buffer ,It
delete into buffer
,It
Undo, redo, retrieve
u
U
-dp
undo last change
restore current line
repeat last change
retrieve g'th last delete
Ex Reference Manual
Version 3.5/2.13 - September, 1989
Revised
~
versions
~.5/2.~
ABSTRACT
~ a line oriented text
editor, which supports both command and display oriented editing.
This reference manual describes
the
command
oriented part o·f .e..x1 the display editing features
of .e..x are described in An Introduction ~ Display
Editing ~~. Other documents about the editor
include the introduction ~: A tutorial, the
~/~
Command Summa;y, and a Yi Quick Reference
card.
B-94
\
\
-.
\
Ex Reference Manual
Version 3.5/2.13 - September, 1989
Reyised
1..
~
versions
~.5/2.~
Starting n
Each instance of the editor has a set of options, which
can be set to tailor it to your liking. The command ~
invokes a version of ~ designed for more casual or beginning users by' changing the default settings of some of these
options. To simplify the descriptio~ which follows we
assume the default settings of the options.
When invoked, n determines the terminal type from the
TERM variable in the environment. It there is a TERMCAP
variable in the environment, and the type of the terminal
described
there matches the TERM variable, then that
description is used. Also if the TERMCAP variable contains
a pathname (beginning with a I) then the editor will seek
the description of the terminal in that file (rather than
the default letc/termcap.) If there is a variable EXINIT in
the environment, then the editor will execute the commands
in that variable, otherwise if there is a file .~ in your
HOME directory n reads commands from that file, simulating
a source command. Option setting commands placed in EXINIT
or .~ will be executed before each editor session.
A command to enter
~
has the following prototype:t
ex [ - ] [-v] [ -t ..t..a.g] [ -r ] [ -1] [ -Wll ] [ -x ] [ -R ] [ +comma
The most common case edits a single file
i. e. :
with
no
options,
The financial support of an IBM Graduate Fellowship and
the National Science Foundation under grants MCS7497644-A93 and MCS78-9729l is gratefully acknowledged.
+ Brackets '[I '] 1 surround optional parameters here.
8-95
ex name
line
option
option
suppresses
all
The
command
interactive-user feedback and is useful in processing editor
scripts in command files. The -y option is equivalent to
using Yi rather than~. The -~ option is equivalent to an
initial ~ command, editing the file containing the ~ and
positioning the editor at its definition. The -L option is
used in recovering after an editor or system crash, retrieving the last saved version of the named file or, if no file
is specified, typing a list of saved files. The -~ option
sets up for editing LISP, setting the showmatch and ~
options. The -~ option sets the default window size to n,
and is useful on dialups to start in small windows. The-x
option causes ~ to prompt for a ~, which is used to
encrypt and decrypt the contents of the file, which should
already be encrypted using the same key, see crypt(l).
The
-R option sets the readonly option at the start.
+ ~
arguments indicate files to be edited. An argument of the
form +command indicates that the editor should begin by executing the specified command. If command is omitted, then
it defaults to "$", 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.
Z.~.
~ ~anipulation
Current
~
~ is normally editing the contents of a
single file,
whose name is recorded in the current file name. ~ performs all editing actions in a buffer (actually a temporary
file) into which the text of the file is initially read.
Changes made to the buffer have no effect on the file being
edited unless and until the buffer contents are written out
to the file with a write command. After the buffer contents
are written, the previous contents of the written file are
no longer accessible. When a file is edited, its name
becomes the current file 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 with the current file name, so that writing
the current buffer contents onto. that file, even if it
exists, is a reasonable action. If the current file is not
edited then ~ will not normally write on it if it already
exists.*
~ Not available in all v2 editors due
to memory constraints.
* The ~ command will say "[Not edited]"
if the
£-96
\
\
2.2:
Alternate ~
Each time a new value is given to the current file
the previous current file name is saved as the alter~ file name.
Similarly if a file is mentioned but does
not become the current file, it is saved as the alternate
file name.
name,
2.~.
Filename expansion
Filenames within the editor may be specified using the
normal shell expansion conventions. In addition, the character '%' in filenames is replaced by the current file name
and the character 'it by the alternate file name.+
2.~.
Multiple files AnQ named buffers
If more than one file is given on the command line,
then the first file is edited as described above. The
remaining arguments are placed with the first file in the
argument~.
The current argument list may be displayed
with the ~ command. The next file in the argument list
may be edited with the ~ command. The argument list may
also be respecified by specifying a list of names to the
~
command. These names are expanded, the resulting list
of names becomes the new argument list, and ~ edits the
first file on the list.
For saving blocks of text while editing, and especially
when editing more than one file, ~ has a group of named
buffers. These are similar to the normal buffer, except
that only a limited number of operations are available on
them. The buffers have names .a through Z.:f:
It is possible to use ~ in ~ ~ mode to look at
files that you have no intention of modifying. This mode
protects you from accidently overwriting the file.
Read
only mode is on when the readonly option is set. It can be
turned on with the -R command line option, by the ~ command line invocation, or by setting the readonly option. It
can be cleared by setting noreadonly.
It is possible to
current file is not considered edited.
+ This makes it easy to deal alternately with two files
and eliminates the need for retyping the name supplied
on an ~ command after a HQ write since l.aat change
diagnostic is received.
:f: It is also possible to refer to A through Z; the
upper case buffers are the same as the lower but commands append to named buffers rather than replacing if
upper case names are used.
£-97
write, even while in read only mode, by indicating that you
really 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 •
.1.
.1.~.
Exceptional Conditions
Errors And interrupts
When errors occur ~ (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
"Interrupti. and returns to -its command level. If the primary input is a file, then n will exit when this occurs •
.1.2.
Recovering!LQm hangups And crashes
If a hangup 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 hangup or editor
crash. To recover a file you can use the -L option. If you
were editing the file resume, then you should change to the
directory where you were when the crash occurred, giving the
command
ex -r resume
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 telling
when a file has been saved after a crash. The command
you
ex -r
will print a list of the files which have been saved for
you.
(In the case of a hangup, the file will not appear in
the list, although it can be recovered.)
~.
Editing modes
~ has five distinct modes.
The primary mode is ~
ma.n,g mode. Commands are entered in command mode when a ' : '
prompt is present, and are executed each time a complete
line is sent. In ~ input mode .ex gathers input lines and
places them in the file. The append, insert, and change
commands use text input mode. No prompt is printed when ~ou
are in text input mode. This mode is left by typing a
.'
alone at the beginning of a line, and command mode resumes.
,
,
£-98
.
'6
,
"
\
The last three modes are ~ and visual modes, entered
by the commands of the same name, and, within open and
visual modes ~ insertion mode.
~
and visual modes
allow local editing operations to be performed on the text
in the file. The.QJ2.fm command displays one line at a time
on any terminal while visual works on CRT terminals with
random positioning cursors, using the screen as a (single)
window for file editing changes. These modes are described
(only) in An Introduction ~ Display Editing ~ Yi.
~.
Command structure
Most command names are English words, and initial prefixes of the words are acceptable abbreviations. The ambiguity of abbreviations is resolved in favor of the more commonly used commands.*
~.~.
Command parameters
Most commands accept prefix addresses specifying the
lines in the file upon which they are to have effect. The
forms of these addresses will be discussed below. A number
of commands also may take a trailing count specifying the
number of lines to be involved in the command.+ Thus the
command "19p,J will print the tenth line in the buffer
while "delete 5" will delete five lines from the buffer,
starting with the current line.
Some commands take other information or parameters,
this information always being given after the command name.+
2.2.
Command variants
A number of commands have two distinct variants.
The
variant form of the command is invoked by placing an '1'
immediately after the command name.
Some of the default
variants may be controlled by options; in this case, the ' I '
serves to toggle the default.
~.~.
Flags after commands
The characters 'it, 'pi and 'I' may be placed after
many commands.** In this case, the command abbreviated by
* As an example, the command substitute can be abbreviated 's' while the shortest available abbreviation for
the ~ command is 'set.
+ Counts are rounded down if necessary.
+ Examples would be option names in a ~ command i.e.
"set number", a file name in an ~ command, a regular expression in a substitute command, or a target address for a ~ command, i.e. "1,5 copy 25".
** A 'pi or 'I' must be preceded by a blank or tab except in the single special case 'dp'.
£-99
these characters is executed after the command completes.
Since ~ normally prints the new current line after each
change, 'p' is rarely necessary. Any number of '+' or '-'
characters may also be given with these flags. If they
appear, the specified offset is applied to the current line
value before the printing command is executed •
.5. •.4..
Comments
It is possible to give editor commands which are
ignored.
This is useful when making complex editor scripts
for which comments are desired. The comment character is
the double quote:". Any command line beginning with W is
ignored. Comments beginning with " may also be placed at
the ends of commands, except in cases where they could be
confused as part of text (shell escapes and the substitute
and map commands).
5...5...
Multiple commands
~ ~
More than one command may be placed on a line by
separating each pair of commands by a 'I' character. However the global commands, comments, and the shell escape 'I'
must be the last command on a line, as they are not termina ted by a 'I' .
.5..~.
Reporting large changes
Most commands which change the contents of· the editor
buffer' give feedback if the scope of the change exceeds a
threshold given by the report option. This feedback helps
to detect undesirably large changes so that they may be
quickly and easily reversed with an~.
After commands
with more global effect such as global or visual, you will
be informed if the net change in the number of lines in the
buffer during this command exceeds this threshold.
~.
Command addressing
Addressing primitives
•
The current line. Most commands leave
the current line as the last line which
they affect. The default address for
most commands is the current line, thus
'.' is rarely used alone as an address.
n
The nth line
lines being
1.
$
The last line in the buffer.
in the editor's buffer,
numbered sequentially from
B-18'
,
\
%
An abbreviation for "1,$", the
buffer.
+n -n
An offset relative to the current buffer
line.+
/ l2.at/ ?l2.at?
Scan forward and backward respectively
for a line containing ~, a regular
expression (as defined below).
The
scans normally wrap around the end of
the buffer. If all that is desired is
to print the next line containing ~,
then the trailing / or ? may be omitted.
If Rat is omitted or explicitly empty,
then the last regular expression specified is located.+
II
'x.
,
~.~.Combining
entire
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 easy
to refer or return to this previous context.
Marks may also be established by
the maLK command, using single lower
case letters ~ and the marked lines
referred to as . . , X'.
addressing primitives
Addresses to commands con.sist of a series of addressing
primitives, separated by',' or 'I'. Such address lists are
evaluated left-to-right. When addresses are separated by
';' the current line '.' is set to the value of the previous,
addressing expression before the next address is interpreted.
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.+
+ The forms '.+3' '+3' and '+++' are all equivalent; if
the current line is line 100 they all address line 103.
+ The forms \1 and \? scan using the last regular expression used in a scanl after a substitute II and ??
would scan using the substitute's regular expression.
+ Null address specifications are permitted in a list
of addresses, the default in this case is the'current
line .... '; thus ',100' is equivalent to .... ,100'. It is
an error to give a prefix address to a command which
expects none.
B-181
2.
Command descriptions
The following form is a prototype for all
~
commands:
address command 1 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, ~ ignores a ":" preceding any command.
In the following command descriptions, the default
addresses are shown in parentheses, which a,re.D.Qt., however,
part of the command.
abbreviate
~
Lhs
abbr: ab
Add the named abbreviation to the current list.
When
in input mode in visual, if ~ is typed as a complete
word, it will be changed to Lha.
,
( • ) append
abbr: a
.t..eKt
•
Rea,ds 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 '9 1 is given, text is placed at the beginning
of the buffer.
al
.t.e.x.t
•
The variant flag to append toggles the setting for
autoindent option during the input of ~.
the
The members of the argument list are printed, with
current argument delimited by ' [ I and '] '.
the
args
( • , . ) change count
abbr: c
.t.e.x.t
•
E-112
,
\
,
Replaces the specified lines with the input~.
The
current line becomes the last line input; if no lines
were input it is left as for a delete.
c!
~
•
The variant toggles autoindent during the change.
( • , • ) copy
~
flags
abbr: co
A ~ of the specified lines is placed after ~,
which may be '9'. The current line '.' addresses the
last line of the copy. The command ~ is a synonym for
~.
( • , • )delete buffer count flags
abbr: d
Removes the specified lines from the buffer. The line
after the last line deleted becomes the current line;
if the lines deleted were or iginally 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 buffer, or appended to it
if an upper case letter is used.
edit ~.
ex .f..il..e.
abbr: e
Used to begin an editing session on a new file.
The
editor first checks to see if the buffer has been modified since the last write command was issued.
If it
has been, a warning is issued and the command is
aborted. The command otherwise deletes the entire contents of the editor buffer, makes the named file the
current file and prints the new filename. After insuring that this file is sensible+ the editor reads the
file 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-ASCII characters in the file they are
stripped of their non-ASCII high bits, and any null
+ I.e., that it is not a binary file such as a directory, a block or character special file other than
/~~, a terminal, or a binary
or executable file
(as indicated by the first word).
B-113
characters in the file are discarded. If none of these
errors occurred, the file is considered edited. If the
last line of the input file 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.+
e! .f..il.e
The variant form suppresses the complaint about modifications having been made and not written from the editor buffer, thus discarding all changes which have been
made before editing the new file.
e
+n~
Causes the editor to begin at line n rather than at the
last line; n may also be an editor command containing
no spaces, e.g.: "+/pat".
file
abbr: f
Prints the current file name, whether it has been
'[Modified]' since the last write command, whether it
is ~~, the current line, the number of lines in
the buffer, and the percentage of the way through th'e
buffer of the current line.*
file
.~
The current file name is changed to
sidered '[Not edited] '.
( I , $ ) global /R£t/
~
which is
con-
abbr: g
~
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.
+ If executed from within ~ or visual, the current
line is initially the first line of the file.
* In the rare case that the current file is '[Not edited]' this is noted also; in this case you have to use
the form w! to write to the file, since the editor is
not sure that a write will not destroy a file unrelated
to the current contents of the buffer.
£-184
"\
,
The command list consists of the rema~n~ng commands on
the current input line and may continue to multiple
lines by ending all but the last such line with a '\1.
If ~ (and possibly the trailing / delimiter) is
omitted, each line matching ~ is printed.
Append,
insert, and change commands and associated input are
permitted: the '.' terminating input may be omitted if
it would be on the last line of the command list~ ~
and visual commands are permitted in the command list
and take input from the terminal.
The global command itself may not appear in~.
The
command is also not permitted there, as ~
instead can be used to reverse the entire global command.
The options autoprint and autoindent are inhibited during a global, (and possibly the trailing /
delimiter) and the value of the report option is temporarily infinite, in deference to a report for the
entire global.
Finally, the context mark ' I I I is set
to the value of ' . f before the global command begins
~nd
is not changed during a global command, except
p~rhaps by an ~ or visual within the global.
~
g1 /~~
abbr: v
The variant form of global runs
matching ~.
~
( • ) insert
at each
line
not·
abbr: i
~
Places the given 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.
i 1
~
•
The variant toggles autoindent during the insert.
( • , .+1 ) join count flags
abbr: j
Places the text from a specified range of lines
together on one line. White space is adjusted at each
jonction to provide at least one blank character, two
if there was a ' . f at the end of the line, or none if
£-115
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 j,Q.i.n with no white space
processing; the characters in the lines are simply concatenated.
(.)k.x.
The k command is a synonym for~.
It does not
.require a blank or tab before the following letter.
( • , • ) list count flags
Prints the specified lines in a more unambiguous way:
tabs are printed as 'AI' and the end of each line is
marked with a trailing '$'. The current line is left
at the last line printed.
ma p .lb.Q .th.a
The mAR command is used to define macros for use in
visual mode. Lha should be a single cha~acter, or the
sequence "tn", for n a digit, referring to function
key~.
When this character or function key is typed in
visual mode, it will be as though the corresponding .th.a
had been typed.
On terminals without function keys,
you can type "tn". 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 not affected by this command.
( • , • ) move
abbr: m
~
~ command repositions the specified lines to
after~.
The first of the moved lines becomes
The
current line.
be
the
B-116
,
"
,
abbr: n
next
The next file from the command line
edited.
argument
list
is
n!
The variant suppresses warnings about the modifications
to the buffer not having been written out, discarding
(irretrievably) any changes which may have been made.
n filelist
n +command filelist
The specified filelist is expanded and the resulting
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: t or nu
( • , • .) number count flags
Prints each specified line preceded by its buffe·r line
number.
The current line is left at the last line
printed.
( • ) open flags
( • ) open/Rat! flags
abbr:
0
Enters intraline editing .2J2Jm mode at each addressed
line.
If ~ is given, then the cursor will be placed
initially at the beginning of the string matched by the
pattern. To exit this mode use O. See An Introduction
~ Display Editing ~ Yi for more details.
+
preserve
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.
+ Not available in all v2 editors due
straints.
E-187
to
memory
con-
( • , • )print count
abbr: p or P
Prints the specified lines with non-printing characters
printed as control characters ·~X'7 delete (octal 177)
is represented as '~?I. The current line is left at
the last line printed.
( • ) put buffer
abbr: pu
Puts back previously deleted or yanked lines. Normally
used with delete to effect movement of lines, or with
~ to effect duplication of lines.
If no buffer is
specified, then the last deleted 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 ~ to terminate. No automatic write of the editor buffer to a file is performed. However, AX issues
a warning message if the file has changed since the
last write command was issued, and does not ~.+ 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
abbr: r
~
Places a copy of the text of the given file in the
editing buffer after the specified line. If no ~ is
given the current file name is used. The current file
name is not changed unless there is none in which case
~ becomes the current name.
The sensibility restrictions for the ~ command apply here also. If the
file buffer is empty and there is no current name then
~ treats this as an ~ command.
* But no modifying commands may intervene between the
gelete or ~ and the ~, nor may lines be moved
betwe.en files without using a named buffer.
+ ~ will also issue a diagnostic if there are more
files in the argument list.
£-118
\
\
-,
.
Address '9' is legal for this command and causes the
file to be read at the beginning of the buffer.
Statistics are given as for the ~ command when the
~ successfully terminates.
After a ~ the current
line is the last line read.+
( • ) read
1command
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.
recover
~
Recovers ~ from the system save area. Used after a
accidental hangup of the phone** or a system crash** or
preserve command.
Except when you use preserve you
will be notified by mail when a file is saved.
rewind
abbr: rew
The argument list is rewound, 'and the first file in the
list is edited.
rew!
Rewinds the argument list discarding any
to the current buffer.
changes
made
set parameter
With no arguments, prints those options whose values
have been changed from their defaults; with parameter
~ it prints all of the option values.
Giving an option name followed by a '?' causes the
current value of that option to be printed. The '?' is
unnecessary unless the option is Boolean
valued.
Boolean options are given values either by the form
'set option' to turn them on or 'set nooption' to turn
them off; string and numeric options are aSSigned via
+ Within ~ and visual the current line is set to the
first line read rather than the last.
** The system saves a copy of the file you were editing
only if you have made changes to the file.
B-119
the form 'set option=value'.
More than one parameter may be given to..&.e.t;
interpreted left-to-right.
shell
they
are
abbr: sh
A new shell is created.
resumes.
When
it
source .f.J..a
substi~ute
editing
abbr: so
Reads and executes commands from
Source commands may be nested.
( • , • )
terminates,
the
specified
file.
/pat/repl/ options count flagsabbr: s
On each specified line, the first instance of pattern
is replaced by replacement pattern~. If the
global indicator option character 'g' appears, then all
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' one 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 ~ must be escaped by
preceding it with a '\'. Other metacharacters available in ~ and ~ are described below.
Suspends the editor, returning control to the top level
shell.
If aytowrite is set and there are unsaved
changes, a write is done first unless the form ~1
is used.
This commands is only available where supported by the teletype driver and operating system.
( • , • ) substitute options count flagsabbr: s
If ~ and ~ are omitted, then the last substitution
is repeated. This is a synonym for the & command.
£-118
( • , • ) t
The
~
~
flags
command is a synonym for
~.
ta .tag
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.+
The tags file is normally created by a program such as
ctags, and consists of 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
'IRati' to ·be immune to minor changes in the file.
Such scans are always performed as if nomagi~ was set.
The tag names in the tags file must be sorted alphabetically. :+:
unabbreviate
abbr: una
~
Delete ~ from the list of abbreviations.
abbr: u
undo
Reverses the changes made in the buffer by the last
buffer editing command. Note that global commands are
considered a single command for the purpose of ~ (as
are ~ and yisual.) Also, the commands write and ~
which interact with the file system cannot be undone.
llndQ is its own inverse.
UndQ always marks the previous
value of the current
line '.' as ~"'. After an ~ 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 global and visual the
current line regains it's pre-command value after an
.wl.dQ.
:+: If you have modified the current file before g1v1ng a
command, you must write it out; giving another ~
. command, specifying no tag will reuse the previous tag.
:+: Not available in all v2 editors due to memory constraints.
1£g
B-lll
unmap .l.b.a
The macro
removed.
( I
, $ )
expansion
v IRatI
associated
by
~
for
lhQ
is
~
A synonym for the global command variant gl, running
the specified ~ on each line which does not match
Rat.
version
abbr: ve
Prints the current version number of the editor as well
as the date the editor was last changed.
( • ) visual
~
count flags
abbr: vi
Enters visual mode at the specified line.
~
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 specifies an initial window size; the default is
the value of the option window. See the document An
In-troduction .t.Q Display Editing ld.th Yi. for mor e
details. To exit this mode, type O.
visual file
visual +n file
From visual mode, this command is the same as edit.
( I , $ ) write
abbr: w
~
writes changes made back to ~, printing the number
of lines and characters written.
Normally ~ is
omitted and the text goes back where it came from.
If
a -~ is specified, then text will be written to that
file.* If the file does not exist it is created.
The
current file name is changed only if there is no
current file name; the current line is never changed.
* The editor writes to a file only if it is the current
file and is edited, if the file does not exist, or if
the file is actually a teletype, I~~, I~~.
Otherwise, you must give the variant form wI-to force
the write.
B-112
If an error occurs while writing the current and edited
file, the editor considers that there has been "No
write since last change" even if the buffer had not
previously been modified.
( 1 , $ ) write»
abbr: w»
~
Writes the buffer contents at the end
file.
of
an
existing
w! n.run..e.
Overrides the checking of the normal write command, and
will write to any file which the system permits.
( 1 , $ ) w
I command
Writes the specified lines into command.
Note the
difference between wI which overrides checks and w
which writes to a command.
wq n.run..e.
Like a write and then a gait command.
wq! n.run..e.
The variant overrides checking on
the write command, as w! does.
the
sensibility
of
xit n.run..e.
If any changes have been made and not written,
the buffer out. Then~ in any case, quits.
( • , • )yank buffer count
writes
abbr: ya
Places the specified lines in the named buffer, for
later retrieval via~. If no buffer name is specified, the lines go to a more volatile p1ace1 see the
~ command description •
• +1 ) z count
B-113
Print the next count lines, default window.
( • ) z
~
count
Prints a window of text with the specified line at the
top.
If ~ is '-' the line is placed 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 scroll 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 the line after the ·'1' character is
sent to a shell to be executed. Within the text of
cOmmand the characters '%' and '#' are expanded as in
filenames and the character ' I ' is replaced with the
text of the previous command.
Thus, in particular,
'11' 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 the buffer contents
since the last change to the .edi ting buffer, then a
diagnostic will be printed before the command is executed as a warning. A single ' I ' is printed when the
command completes.
~
,
~
) 1 command
Takes the specified address range and supplies it as
standard input to command; the resulting output then
replqces the input lines.
( $ )
=
* Forms 'z=' and 'zT' also exist; 'z=' places the
current line in the center, surrounds it with lines of
'-' characters and leaves the current line at this
line.
The form 'zT' prints the window before 'z-'
would. The characters '+', 'T' and '-' may be repeated
for cumulative effect. On some v2 editors, no ~ may
be given.
£-114
Prints the line number of
current line is unchanged.
the
addressed
line.
The
( • , • ) > count flags
( • , • ) < count flags
Perform intelligent shifting on the specified lines; <
shifts left and> shift right. The quantity of shift
is determined by the shiftwidth 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 current line becomes the last line which changed due to the shifting.
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 )
An address alone causes the addressed lines to be
printed.
A blank line prints the next line in the
file.
( • , • ) & options count flags
Repeats the previous substitute command.
( • , • ) - options count flags
Replaces the previous regular expression with the
vious replacement pattern from a sUbstitution.
~.
~.~.
pre-
Regular expressions and substitute replacement patterns
Regular expressions
A regular expression specifies a set of strings of
characters.
A member of this set of strings is said to be
matched by the regular expression. £X 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 ~, e.g. 'IIi or '??'.
E-115
~.~.
Magic
~
nomaqic
The regular expressions allowed by ~ are constructed
in one of two ways depending on the setting of the magic
option. The ~ and ~ 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
them with the character '\' to use them as .. 'ordinary' I
characters.
with nomagic, the default for ~, 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 "\1 is thus always a metacharacter.
The remainder of the discussion of regular expressions
assumes that that the setting of this option is magic.+
~.~.
Basic regular expression summary
The following basic constructs are
magic mode regular expressions.
used
to
construct
An ordinary character matches itself.
The
characters 'T' at the beginning of a line,
~$I at the end of line, "*1 as any
character
other than the first, '.', '\1, '[I, and '-I
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 beginning of a
line.
$
At the end of a regular expression forces the
match to succeed only at the end of the line.
•
Matches any single character except the
line character.
\<
Forces the match to occur only at the beginning of a .... variable" or .... word"1 that is,
ei ther at the beginning of a line, or just
before a letter, digit, or underline and
new-
+ To discern what is true with nomagi~ it suffices to
remember that the only special characters in this case
will be 'TI at the beginning of a regular expression,
'$' at the end of a regular expression, and '\'. With
nomagic the characters 'HI and '&' also lose their special meanings related to the replacement pattern of a
substitute.
£-116
\
\
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.
[string]
Matches any (single) character in the class
defined by string. Most characters in string
define themselves.
A pair of characters
separated by ' _ I in string defines the set of
characters collating between the specified
lower and upper bounds, thus '[a-z] I as 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' [Ta-z]' matches anything but a
lower-case letter (and of course a newline).
To place any of the characters 'T', ' [ I , or
'-' in string you must escape them with a
preceding '\ I .
~.~.
Combining regular 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 (sin~
gle 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 9) of characters matched by the regular expression it follows.
The character '-I may be used in a regular expression,
and matches the text which defined the replacement part of
the last substitute command. A regular expression may be
enclosed between the sequences '\(' and '\)' with side
effects in the substitute replacement patterns.
~.~.
Substitute
repl~cement
patterns
The basic metacharacters for the replacement pattern
are '&' and '-I; these are given as '\&' and '\-' when
nomagic is set. Each instance of '&' is replaced by the
characters which the regular expression matched. The metacharacter ,-, stands, in the replacement pa ttern, for the
defining text of the previous replacement pattern.
Other metasequences possible in the replacement pattern
are always introduced by the escaping character '\1. The
sequence '\n' is replaced by the text matched by the n-th
E-117
regular subexpression enclosed between '\(' and '\) '.+ The
sequences '\u' and '\1' cause the immediately following
character in the replacement to be converted to upper- or
lower-case respectively if this character is a letter. The
sequences '\U' and '\L' turn such conversion on, either
until '\E' or 'O\e' is encountered, or until the end of the
replacement pattern.
~.
Option descriptions
autoindent, ai
default: noai
Can be used to ease the preparation of structured program text. At the beginning of each append, change or
insert command or when a new line is opened or created
by an append, change, insert, or substitute operation
within ~ or visual mode, ~ looks at the line being
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 aligned 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 theshiftwidth option. You cannot backspace over the indent; except by sending an end-of-file
with a ~D.
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 'OT' and immediately followed by a ~D.
This causes the input to be repositioned at the beginning of the line, but retaining the
previous indent for the next line. Similarly, a '9'
followed by a ~D repositions at the beginning but
without retaining the previous indent.
Autoindent doesn't happen in global
the input is not a terminal.
commands
or
+ When nested, parenthesized subexpressions are
present, n 1S determined by counting occurrences of
'\(' starting from the left.
E-118
when
autoprint, ap
default: ap
Causes the current line to be printed after each
delete, ~,JQ4n,~, substitute, ~, YndQ or shift
command. This has the same effect as supplying a
trailing 'p' to each such command.
Autoprint is
suppressed in globals, and only applies to the last of
many commands on a line.
autowrite, aw
default: noaw
Causes the contents of the buffer to be written to the
current file if you have modified it and give a ~,
rewind, ~, tsg, or
!
command, or a ~T
(switch
files)
or~]
(tag goto) command in visual. Note, that
the ~ and ~ commands do nQt autowrite.
In each
case, there is an equivalent way of switching when
autowrite is set to avoid the autowrite (~ for ~,
rewind!
for .I rewind ,~! for~,~! for
~, shell for 1, and :e #
and a :ta! command from
within visual).
beaut1fy, 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. Beautify does not apply to command input.
directory, dir
default: dir=/tmp
Specifies the directory in which ~ places its buffer
file.
If this directory in not writable, then the editor will exit abruptly when it fails to be able to
create its buffer there.
edcompatible
default: noedcompatible
Causes the presence of absence of S and ~ suffixes on
substitute commands to be remembered, and to be toggled
by repeating the suffices. The suffix ~ makes the substitution be as in the - command, instead of like &.
**
**
Version 3 only.
E-119
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, ht
default: ht=8
Gives the boundaries on which terminal hardware
are set (or on which the system expands tabs).
ignorecase, ic
tabs
default: noic
All upper case characters in the text are mapped to
lower case in regular expression matching. In addition, all upper case characters in regular expressions
are mapped to lower case except in character class
specif ica tions.
lisp
default: nolisp
Autoindent indents appropriately for lis~ code, and the
( ) { } [[ and ]] commands in o~en and visual are modified to have meaning for lisp.
list
default: nolist
All printed lines will be displayed (more) unambiguously, showing tabs and end-of-lines as in the liat
command.
magic
default: magic for
~
and
~+
If nomagic is set, the number of' regular expression
metacharacters is greatly reduced, with only 'TI and
'$' having special effects. In addition the metacharacters --, and -&1 of the replacement pattern are
treated as normal characters. All the normal metacharacters may be made magic when nomagic is set by preceding them with a " .
mesg
default: mesg
Causes write permission to be turned off to the terminal while you are in visual mode, if nomesg is set. ++
* Bell ringing in ~ and visual on
suppressed by setting ~.
£-128
+ Nomagic for ~.
++ Version 3 only.
errors
is
not
,
\
,
number, 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·noopen, the commands ~ and visual are not permitted. This is set for ~ 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.
paragraphs, para
default: para=IPLPPPQPP LIbp
Specifies the pazagraphs for the { and } operations in
and visual.
The pairs of characters in the
option's value are the names of the macros which start
paragraphs.
~
prompt
default: prompt
Command mode input is prompted for with a
redraw
... , .
default: noredraw
The editor simulates (using great amounts of output),
an intelligent terminal on a dumb 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.
remap
default: remap
If on, macros are repeatedly tried until they are
unchanged. +* For example, if ~ is mapped to Q, and Q
is mapped to~, then if remap is set, ~ will map to ~,
but if noremap is set, it will map to Q.
** Version 3 only.
£-121
report
default: report=5+
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, ~, ~, and
visual which have 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.
scroll
default: scroll=I/2 window
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 Z command (double the value of scroll).
sections
default: sections=SHNHH HU
Specifies the section macros for the [[ and ]] operations in .QJ2M and visual. The pairs of characters in
the option's value are the names of the macros which
start paragraphs.
shell, sh
default: sh=/bin/sh
Gives the path name of the shell forked for the shell
escape command ' I ' , and by the shell command. The
default is taken from SHELL in the environment, if
present.
shiftwidth, sw
default: sw=8
Gives the width a software tab stop, used in reverse
tabbing with ~D when using autoindent to append text,
and by the shift commands.
sh owma tch , sm
default: nosm
In open and visual 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 ~.
+ 2 for .e.Q.i.t..
E-122
\
,
slowopen, slow
terminal dependent
Affects the display algorithm used in visual mode,
holding off display updating during input of new text
to improve throughput when the terminal in use is both
slow and unintelligent. See An Introduction ~ Display
Editing~ Yi for more details.
tabstop, ts
default: ts=8
The editor expands tabs in the input file to
tabstop boundaries for the purposes of display.
taglength, tl
be
on
default: tl=9
Tags are not significant beyond this many characters.
A value of zero (the default) means that all characters
are significant.
tags
/usr/lib/tags
tags=tags
default:
A path of files to be used as tag files for the .t.a.sl
command •. ++ A requested tag is searched for in the
specified files, sequentially.
By -default (even in
version 2) files called .tas..s. are searched for in the
current directory and in /usr/lib (a master file for
the entire system.)
term
from environment TERM
The terminal type of the output device.
terse
default: noterse
Shorter error diagnostics are produced for the
enced user.
warn
default: warn
Warn if there has been '[No write since
before a '11 command escape.
window
++
experi-
default:
Version 3 only.
8-123
last
window=speed
change]
I
dependent
The number of lines in a text window in the visual command.
The default is 8 at slow speeds (699 baud or
less), 16 at medium speed (1299 baud), and the full
screen (minus one line) at higher speeds.
w309, w1290, w9600
These are not true options but set window only if the
speed is slow (309), medium (1290), or high (9699),
respectively. They are suitable for an EXINIT and make
it easy to change the 8/l6/full screen rule.
wrapscan, ws
default: ws
Searches using the regular expressions in
will wrap around past the end of the file.
wrapmargin, wm
addressing
default: WID=9
Defines a margin for automatic wrapover of text during
input in ~ and visual modes. See An Introduction ~
~ Editing ~ Yi for details •.
writeany, wa
default: nowa
Inhibit the checks .normally made before write commands,
allowing a .write to any file which the system protection mechanism will allow.
~.
Limitations
Editor limits that the user is likely to encounter are
as follows: 1024 characters per line, 256 characters per
global command list, 128 characters per file name, 128 characters in the previous inserted and deleted text in ~ or
visual, 109 characters in a shell escape command, 63 characters in a string valued option, and 30 characters in a tag
name, and a limit of 250009 lines in the file is silently
enforced.
The visual implementation limits the number of macros
defined with map to 32, and the total number of characters
in macros to be less than 512.
£-124
\
Edit:
A Tutorial
ABSTRACT
This narrative introduction to the use of the
text editor ~ assumes no prior familiarity with
computers or with text -editing.
Its aim is to
lead the beginning UNIX+ user through· the fundamental steps of writing and revising a file of
text. Edit, a version of the text editor~, was
designed to provide an informative environment for
new and casual users.
This edition documents Versions 2.0 thru
of edit and ~.
3.1
We welcome comments and suggestions about
this tutorial and the UNIX documentation in general. Contact the UNIX consultant in 217 Evans,
642-4072.
+UNIX is a trademark of Bell Laboratories.
E-125
Edit:
A Tutorial
Ricki Blau
James Joyce
Computing Services
University of California
Berkeley, California 9472e
Text editing using a terminal connected to a computer
allows a user to create, modify, and print text easily.
Creating text is as easy as typing it much as one would on
an electric typewriter. Modifying text involves telling the
text editor what to add, change, or delete. Text is printed
by giving the proper command to print the file contents,
with or without special instructions as to the format of the
desired output.
These lessons assume no prior familiarity with comput~
ers or with text editing. They consist of a series of text
editing sessions which will lead you through the fundamental
steps of creating and revising a file of text. After scanning each lesson and before beginning the next, you should
follow the examples at a terminal to get a feeling for the
actual process of text editing. Set aside some time for
experimentation, and you will soon become familiar with
using the computer to write and modify text. In addition to
the actual use of the text editor, other features of UNIX
will be very important to your work. You can begin to learn
about these other features by reading "Communicating with
UNIX I 'or one of the other tutorials which provide a general
introduction to the system. You will be ready to proceed
wi th this lesson as soon as you are familiar with your terminal and its special keys, the login procedure, and the
ways of correcting typing errors. Let's first define some
terms:
program
A set of instructions given to the computer,
describing the sequence of steps which the computer performs in order to accomplish a specific
task.
As an example, a series of steps to balance your checkbook is a program.
E-126
,
UNIX
UNIX is a special type of program, called an
operating system, that supervises the machinery
and all other programs comprising the total computer system.
edit
~
file
Each UNIX account is allotted space for the permanent storage of information, such as programs,
data or text. A file is a logical unit of data,
for example, an essay, a program, or a chapter
from a book, which is stored on a computer system.
Once you create a file, it is kept until
you instruct the system to remove it.
You may
create a file during one UNIX session, log out,
and return to use it at a later time.
Files
contain anything you choose to write and store
in them. The sizes of files vary to suit your
needs 1 one file might hold only a single number
while another might contain a very long document
or program.
The only way to save information
from one session to the next is to store it in a
file.
filename
Filenames are used to distinguish one file from
another, serving the same purpose as the labels
of manila folders in a file cabinet.
In order
to write or access information in a file, you
use the name of that file in a UNIX command, and
the system will automatically locate the file.
disk
Files are stored on an input/output device
called a disk, which looks something like a
stack of phonograph records.
Each surface is
coated with a material similar to the coating on
magnetic recording tape, on which information is
recorded.
buffer
A temporary work space, made available to the
user for the duration of a session of text editing and used for building and modifying the text
file. We can imagine the buffer as a blackboard
that is erased after each class, where each session with the editor is a class.
is the name of the UNIX text editor which
you will be learning to use, a program that aids
you in writing or revising text.
Edit was
designed for beginning users, and is a simplified version of an editor called ~.
£-127
Session~:
Creating
A ~
Qf Text
To use the editor you must first make contact with the
computer by logging in to UNIX. We'll quickly review the
standard UNIX login procedure.
If the terminal you are using is directly linked to the
computer, turn it on and press carriage return, usually
labeled ~~RETURN'J. If your terminal connects with the computer over a telephone line, turn on the terminal, dial the
system access number, and, when you hear a high-pitched
tone, place the receiver of the telephone in the acoustic
coupler. Press carriage return once and await the login
message:
:login:
Type your login name, which identifies you to UNIX, on
the same line as the login message, and press carriage
return. If the terminal you are using has both upper and
lower case, be sure you enter your login name in lower case~
otherwise UNIX assumes your terminal has only upper case and
will not recognize lower case letters you may type. UNIX
types ":login:" and you reply with your login name, for
example "susan":
':login: susan (and press carriage return)
(In the examples, input typed by the user appears in
face to distinguish it from the responses from UNIX.)
~
UNIX 'will next respond with a request for a password as
an additional precaution to prevent unauthorized people from
using your account. The password will not appear when you
type it, to prevent others from seeing it. The message is:
Password:
(~~
passwQrd and press carriage return).
If any of the information you gave during the login sequence
was mistyped or incorrect, UNIX will respond with
Login incorrect.
:login:
in which case you should start the login process anew.
Assuming that you have successfully logged in, UNIX will
print the message of the day and eventually will present you
with a % at the beginning of a fresh line. The % is the
UNIX prompt symbol which tells you that' UNIX is ready to
accept a command.
£-128
,
Asking
.f.Q..t.
rl.i.t.
You are ready to tell UNIX that you want to work with
edit, the text editor. Now is a convenient time to choose a
name for the file of text which you are about to create. To
begin your editing session type ~ followed by a space and
then the filename which you have selected, for example
"text' '.
When you have completed the command, press carriage return and wait for edit's response:
% edit text
(followed ~ A carriage return)
"text" No such file or directory
If you typed the command correctly, you will now be in communication with edit. Edit has set aside a buffer for use
as a temporary working space during your current editing
session.
It also checked to see if the file you named,
'"text' " already existed. As we expected, it was unable to
find such a file since "text" is the name of the new file
that we will create. Edit confirms this with the line:
"text" N6 such file or directory
On the next line appears edit's prompt " : " , announcing
that edit expects a command from you. You may now begin to
create the new file.
~
"nQt found"
message
If you misspelled edit by typing, say, "editor' "
request would be handled as follows:
your
% editor
editor:
not found
%
Your mistake in calling edit "editor" was treated by UNIX
as a request for a program named "editor". Since there is
no program named "editor' " UNIX reported that the program
was "not found". A new % indicates that UNIX is ready for
another command, so you may enter the correct command.
A summary
Your exchange with UNIX as you logged in and made
tact with edit should look something like this:
E-129
con-
:login: susan
Password:
Computer Center UNIX System
••• A Message of General Interest •••
% edit text
"text" No such file or directory
Entering
~
You may now begin to enter text into the buffer.
.Thi s
is done by appending text to whatever is currently in the
buffer. Since there is nothing in the buffer at the moment,
you are appending text to nothing: in effect, you are creating text. Most edit commands have two forms: a word which
describes what the command does and a shorter abbreviation
of that word. Either form may be used. Many beginners find
the full command names easier to remember, but once you are
familiar with editing you may prefer to type the shorter
abbreviations.
The command to input text is "append"
which may be abbreviated "a". Type append and press carriage return.
% edit text
: append
Messages- from
~
If you make a mistake in entering a command and type
something that edit does not recognize, edit will respond
with a message intended to help you diagnose your error.
For example, if you misspell the command to input text by
typing, perhaps, "add" instead of "append" or • 'a' " you
will receive this message:
:add
add: Not an editor command
.
When you receive a diagnostic message, check what you typed
in order to determine what part of your command confused
edit. The message above means that edit was unable to
recognize your mistyped command and, therefore, did not execute it. Instead, a new":" appeared to let you know that
edit is again ready to execute a command •
.I.ext input
~
By giving the command "append" (or using the abbreviation "a' I), you entered text input mode, also known as
append mode. When you enter text input mode, edit responds
B-138
,
by doing nothing. You will not receive any prompts while in
text input mode. This is your signal that you are to begin
entering lines of text. You can enter pretty much anything
you want on the lines. The lines are transmitted one by one
to the buffer and held there during the editing session.
You may append as much text as you want, and ~ ~ wish
1Q ~ entering ~ lines ~ should ~ a period ~ ~
Qllly character ~ ~ line ~ press carriage return.
When
you give this signal that you want to stop appending text,
you will exit from text input mode and reenter command mode.
Edit will again prompt you for a command by printing " : " .
Leaving append mode does not destroy the text in the
buffer.
You have to leave append mode to do any of the
other kinds of editing, such as changing, adding, or printing text.
If you type a period as the first character and
type any other character on the same line, edit will believe
you want to remain in append mode and will not let you out.
As this can be very frustrating, be sure to type ~ the
period and carriage return.
This is as good a place as any to 'learn an important
lesson about computers and text: a blank space is a character as far as a computer is concerned. If you so much as
type a period followed by a blank (that is, type a period
and then the space bar on the keyboard), you will remain in
append mode with the last line of text being:
Let's say that the lines of text you enter are (try to
exactly what you see, including "thiss' I):
~ I I ..Q.Q.ID..e sample ~.
Aru1 thiss I I ~ ~ ~.
~ editing I I strange, ~
type
~•
•
The last line is the period followed by a carriage return
that gets you out of append mode. If while typing the line
you hit an incorrect key, recall that you may delete the
incorrect character or cancel the entire line of input by
eraSing in the usual way.
Refer to "Communicating with
UNIX"
if you need to review the procedures for making a
correction. Erasing a character or cancelling a line must
be done before the line has been completed by a carriage
return. We will discuss changes in lines already typed in
session 2.
Wr i t i ng llx.t. .tQ. .din
You are now ready to edit the text. The simplest kind
of editing is to write it to disk as a file for safekeeping
after the session is over. This is the only way to save
E-131
information from one session to the next, since the editorls
buffer is temporary 'and will last only until the end of the
editing session. Thus, learning how to write a file to disk
is second in importance only to entering the text. To write
the contents of the buffer to a disk file, use the command
"write" (or its abbreviation '''W ll ):
:write
Edit will copy the buffer to a disk file. If the file does
not yet exist, a new file will be created automatically and
the presence of a "[New file] 'I will be noted. The newlycreated file will be given the name specified when you
entered the editor, in this case "text". To confirm that
the disk file has been successfully written, edit will
repeat the filename and give the number of lines and the
total number of characters in the file. The buffer remains
unchanged by the . 'write' I command. All of the lines which
were written to disk will still be in the buffer, should you
want to modify or add to them.
Edit must have a filename to use before it can write a
file.
If you forgot to indicate the name of the file when
you began the editing session, edit will print
No current filename
in response to your write command. If this happens, you can
specify the filename in a new write command:
:write text
After the "write'l (or "w l ') type a
name of the file.
Signing
space
and
then
the
.Q..f:f
We have done enough for this first lesson on using the
UNIX text editor, and are ready to quit the session with
edit. To do this we type "quitll (or "qll) and press carriage return:
:write
ntext" [New file]
:quit
3 lines, 90 characters
%
The % is from UNIX to tell you that your session with edit
is over and you may command UNIX further. Since we want to
end the entire session at the terminal we also need to exit
from UNIX.
In response to the UNIX prompt of "%11 type a
"control d l I . This is done by holding down the control key
(usually labeled "'CTRL") and simultaneously pressing the d
key. This will end your session with UNIX and will ready
£-132
'.
..
the terminal for the next user. It is always important to
type a "control-d" at the end of a session to make absolutely sur e no one could accidentally stumble into your
abandoned session and thus gain access to your files, tempting even the most honest of souls.
This is the end of the first session on UNIX text editing.
E-133
Session .2.
Login with UNIX as in the first session:
:login: susan
Password:
(carriage return)
(~ password ~ carriage return)
computer Center UNIX System
%
This time when you say that you want to edit, you can
specify the name of the file you worked on last time. This
will start edit working and it will fetch the contents of
the file into the buffer, so that you can resume 'editing the
same file. When edit has copied the file into the buffer,
it will repeat its name and tell you the number of lines and
characters it contains. Thus,
% ~.t.eAt
"text" 3 lines,
·
9~
characters
means you asked edit to fetch the file named "text"
for
editing, causing it to copy the 9~ characters of text into
the buffer. Edit awaits your further instructions. In this
session, we will append more text to our file, print the
contents of the buffer, and learn to change the text of, a
line.
Adding
~
text
~ ~ ~
If you want to add more to the end of your text you may
do so by using the append command to enter text input mode.
Here we'll use the' abbreviation for the append command,
~'a":
:a
This is text added in Session 2.
It doesn't mean much here, but
it does illustrate the editor.
•
Interrupt
Should you press the RUBOUT key (sometimes labeled
DELETE) while working with edit, it will send this message
to you:
Interrupt
·•
Any command that edit might be executing is terminated by
rubout or delete, causing edit to prompt you for a new
E-134
,
command. If you are appending text at the time, you will
exit from append mode and be expected to give another command. The line of text that you were typing when the append
command was interrupted will not be entered into the buffer.
Making corrections
If you have read a general introduction to UNIX, such
as "Communicating with UNIX", you will recall that it is
possible to erase individual letters that you have typed.
This is done by typing the designated erase character, usually the number sign (i), as many times as there are characters you want to erase. If you make a bad start in a line
and would like to begin again, this technique is cumbersome
what if you had 15 characters in your line and wanted to
get rid of them? To do so either requires:
~ ~
yukky
~iiittttttitittt
with no room for the great text you'd like to type, or,
.nu...a
.ia yukky
~@~
.ia great
~.
When you type the at-sign (@), you erase the entire line
typed so far. You may immediately begin to retype the line.
This, unfortunately, does not help after you type the line
and press carriage return. To make corrections in lines
which have been completed, it is necessary to use the editing commands covered in this session and those that follow.
Listing
~'~
in
~
buffer
Having appended text to what you wrote in Lesson 1, you
might be curious to see what is in the buffer. To print the
contents of the buffer, type the command:
:l,$p
The "1'1 stands for line 1 of the buffer, the "$"
is a
special symbol designating the last line of the buffer, and
"pI' (or print) is the command to print from line 1 to the
end of the buffer. Thus, "l,$p" gives you:
This is some sample text.
And thiss is some more text.
Text editing is strange, but nice.
This is text added in Session 2.
It doesn't mean much here, but
it does illustrate the editor.
Occasionally, you may enter into the buffer a character
which can't be printed, which is done by striking a key
while the CTRL key is depressed. In printing lines, edit
uses a special notation to show the existence of nonE-135
printing cha~acters. Suppose you had introduced the nonprinting character "control-a"
into the word "illus. trate l ' by accidently holding down the CTRL key while typing
"al'. Edit would display
it does illustrAAte the editor.
if you asked to have the line printed.
To represent the
control-a, edit shows' "AA'·. The sequence' , .. ,' followed
by a capital letter stands for the one character entered by
holding down the CTRL key and typing the letter which
appears after the , ..
We'll soon discuss the commands
which can be used to correct this typing error.
ft.,.
In looking over the text we see that "this" is
as "thiss"
in the second line, as suggested.
correct the spelling.
Finding things in
~
typed
Let's
buffer
In order to change something in the buffer we first
need to find it. We can find "thiss" in the text we have
entered by looking a t a listing of the lines.
Physically
speaking, we search the lines of text looking for "thiss"
and stop searching when we have found it. The way to tell
edit to search for something is to type it inside slash
marks:
:/thiss/
By typing /thiss/ and pressing carriage return edit is
instructed to search for .... thiss· I . If we asked edit to
look for a pattern of characters which it could not find . in
the buffer, it would respond "'Pattern not found". When
edit finds the characters "thiss' " it will print the line
of text for your inspection:
And thiss is some more text.
Edit is now positioned in the buffer at the line
just printed, ready to make a change in' the line.
~
which
it
current line
At all times during an editing session, edit keeps
track of the line in the buffer where it is positioned. In
general, the line which has been most recently printed,
entered, or changed is considered to be the current position
in the buffer. You can refer to your current position in
the buffer by the symbol period (.) usually known by the
name "dot". If you type • ... 1' and carriage return you
will be instructing edit to print the current line:
E-136
,
,
·.
And thiss is some more text.
If you want to know the number of the current line, you
can type.= and carriage return, and edit will respond with
th e line numbe r :
·.--
2
If you type the number of any line and a carriage return,
edit will position you at that line and print its contents:
:2
And thiss is some more text.
You should experiment with these commands to assure yourself
that you understand what they do.
Numbering lines
(nY)
The number (nY) command is similar to print,
both .the number and the text of each printed line.
the "number and the text of the current line type
:nu
2
giving
To see
And thiss is some more text.
Notice that the shortest abbreviation for the number command
is "nu'l (and not "nil which is used for a different commana). You may specify a range of lines to be listed by the
number command in the same way that lines are specified for
print. For example, "l,$nu' I lists all lines in the buffer
with the corresponding line numbers.
Substitute command
(~)
Now that we have found our misspelled word it is time
to change it from "thissl I to "thisll. As far as edit is
concerned, changing things is a matter of substituting one
thing for another. As A stood for a~pend, so ~ stands for
substitute. we will use the abbreviation "S'I to reduce
the chance of mistyping the SUbstitute command. This command will instruct edit to make the change:
2s/thiss/this/
We first indicate the line to be changed, line 2, and then
type an "Sl I to indicate we want substitution. Inside the
first set of slashes are the characters that we want to
change, .followed by the characters to replace them and then
a closing slash mark. To summarize:
E-137
2s1 lihat
~ !Q Qe
changed I
~ !Q
change
~
I
If edit finds an exact match of the characters to be changed
it will make the change only in the first occurrence of the
characters. If it does not find the characters to be
changed it will respond:
Substitute pattern match" failed
indicating your instructions could not be carried out. When
edit does find the characters which you want to change, it
will make the substitution and automatically print the
changed line, so that you can check that the correct substitution was made. In the example,
:2s/thiss/this/
And this is some more text.
line 2 (and line 2 only) will be searched for the characters
"thissl I ,
and when the first exact match is found,
• "thiss' I will be changed to "this' '.
Strictly speaking,
it was not necessary above to specify the number of the
line to be changed. In
:s/thiss/this/
edit will assume that we mean to change the line where we
are currently positioned (".'"'). In this case, the command
without a line number would have produced the same result
because we were already positioned at the line we wished to
change.
For another illustration of substitution we may
the line:
choose
Text editing is strange, but nice.
We might like to be a bit more positive.
take out the characters "strange, but'
read:
I
Thus, we could
so the line would
Text editing is nice.
A command which will first position edit at
then make the substitution is:
that
line
and
:/strange/s/strange, but II
What we have done here is combine our search with our
substitution.
Such combinations are perfectly legal. This
illustrates that we do not necessarily have to use line
E-138
\
numbers to identify a line to edit. Instead, we may identify the line we want to change by asking edit to search for
a specified pattern of letters which occurs in that line.
The parts of ~he above command are:
Istrangel
s
Istrange, but II
tells edit to find the characters "strange" in the tex1
tells edit we want to make a substitution
substitutes nothing at all for the characters
"strange, but"
-
You should note the space after "but" in "/strange,
but I". If you do not indicate the space is to be taken
out, your line will be:
Text editing is
nice.
which looks a little funny because of the extra space
between "is"
and "nice". Again, we realize from this
that a blank space is a real character to a computer, and in
editing text we need to be aware of spaces within a line
just as we would be aware of an "a" or a "4".
Another
~ ~ ~ ~'a
in
~
buffer (z)
Although the print command is useful for looking at
specific lines in the buffer, other commands can be more
convenient for viewing large sections of text. You can ask
to see a screen full of text at a time by using the command
z. If you type
:lz
edit will start with line I and continue printing lines,
stopping either when the screen of your terminal is full or
when the last line in the buffer has been printed.
If you
want to read the next segment of text, give the command
:z
If no starting line number is given for the z command,
printing will start at the "current" line, in this case
the last line printed. Viewing lines in the buffer one
screen full at a time is known as paging. Paging can also
be used to print a section of text on a hard-copy terminal.
Saying
modified
~
~
This seems to be a good place to pause in our work, and
so we should end the second session. If you (in haste) type
"q" to quit the s~ssion your dialogue with edit will be:
:q
No write since last change (q! quits)
:
E-139
This is edit's warning that you have not written the modified contents of the buffer to disk. You run the risk of
losing the work you have done during the editing session
since the latest write command. Since in this lesson we
have not written to disk at all, everything we have done
If we did not want to save the work done
would be lost.
during this editing session, we would have to type "q11' to
confirm that we indeed wanted to end the session immediately, losing the contents of the buffer. However, since we
want to preserve what we have edited, we need to say:
:w
"text" 6 lines, 171 characters
and then,
:q
%
{control~}
and hang up the phone or turn off the terminal when UNIX
asks for a name. This is the end of the second session on
UNIX text editing.
E-148
\'.
Session
Bringing
~
intQ
~
buffer
~
(~)
Login to UNIX and make contact with edit. You should
try to login without looking at the notes, but ~f you must
then by all means do.
Did you remember to give the name
wanted to edit? That is, did you say
of
the
file
you
% edit text
or simply
% edit
Both ways get you in contact with edit, but the first way
will bring a copy of the file named "text" into the
buffer. If you did forget to tell edit the name of your
file, you can get it into the buffer by saying:
:e text
"text" 6 lines, 171 characters
The command~, which may be abbreviated "e", tells edit
that you want to erase anything that might already be in the
buffer and bring a copy of the file "text" into the buffer
for editing.
You may also use the edit (e) command to
change files in the middle of an editing session or to give
edit the name of a new file that you want to create.
Because the edit command clears the buffer, you will receive
a warning if you try to edit a new file without having saved
a copy of the old file. This gives you a chance to write
the contents of the buffer to disk before editing the next
file.
Moying
~
in
~
buffer (m)
Edit allows you to move lines of text from one location
in the buffer to another by means of the ~ (m) command:
:2,4m$
This command directs
end of the buffer
that you specify the
to be moved, the
which the moved text
edit to move lines 2, 3, and
($). The format for the move
first line to be moved, the
move command "m " , and the
is to be placed. Thus,
4 to the
command is
last line
line after
:1,6m2~
would instruct edit to move lines 1 through 6 (inclusive) to
a position after line 2~ in the buffer. To move only one
E-141
11ne, say, line 4, to a position in the buffer after line 6,
the command would be "4m6".
Let's move some text using the command:
:5,$ml
2 lines moved
it does illustrate the editor.
After executing a command which changes more than one line
of the buffer, edit tells how many lines were affected by
the change. The last moved line is printed for your inspection.
If you want to see more than just the last line, use
the print (p), z, or number (nu) command to view more text.
The buffer should now contain: '
This is some sample text.
It doesn't mean much here, but
it does illustrate the editor.
And this is some more text.
Text editing is nice.
This is text added in Session 2.
We can restore the original order by typing:
:4,$ml
or, combining context searching a.nd the mov,e command:
.
:/And this is some/,/This is text/m/This is some samplel
The problem with combining context searching with the move
command is that the chance of making a typing error in such
a long command is greater than if one types line numbers.
Copying lines
(~)
The ~ command is used to make a second copy of
specified lines, leaving the original lines where they were.
Copy has the same format as the move command, for example:
:12,15copy $
makes a copy of lines 12- through 15, placing the added lines
after the buffer's end ($). Experiment with the copy command so that you can become familiar with how it works.
Note that the shortest abbreviation for copy is "co" (and
nQt the letter "c" which has another meaning).
Del~ting
lines (d)
Suppose you want to delete the line
This is text added in Session 2.
E-142
'. ,
",
,
from the buffer. If you know the number of the line to
deleted, you can type that number followed by "delete"
"d' '. This example deletes line 4:
be
or
:4d
It doesn't mean much here, but
Here "4" is the number of the line to be deleted and
"delete"
or "d"
is the command to delete the line.
After executing the delete command, edit prints the line
which has become the current line (' .••• ).
If you do not happen to know the line number you can
search for the line and then delete it using this sequence
of commands:
:/added in Session 2./
This is text added in Session 2.
:d
It doesn't mean much here, but
The "/added in Session 2./" asks edit to locate and print
the next line which contains the indicated text. Once you
are sure that you have correctly specified the line that you
want to delete, you can enter the ~elete (d) command. In
this case it is not necessary to specify a line number
before the "d". If no line number is given, edit deletes
the current line (, .• '.), that' is, the line found by our
search. After the deletion, your buffer should contain:
This is some sample text.
Ahd this is some more text.
Text editing is nice.
It doesn't mean much here, but
it does illustrate the editor.
To delete both lines 2 and 3:
And this is some more text.
Text editing is nice.
you type
: 2,3d
which specifies the range of lines from 2 to
operation on those lines - "d" for delete.
3,
and
the
Again, this presumes that you know the line numbers for
the lines to be deleted. If you do not you might combine
the search command with the delete command as so:
:/And this is some/,/Text editing is nice./d
8-143
A
~ ~ ~
Qf caution:
In using the search function to locate lines to be
deleted you should be absolutely sure the characters you
give as the basis for the search will take edit to the line
you want deleted. Edit will search for the first occurrence
of the characters starting from where you last edited - that
is, from the line you see printed if you type dot (.).
A search based on too few characters may result in the
wrong lines being deleted, which edit will do as easily as
if you had meant it. For this reason, it is usually safer
to specify the search and then delete in two separate steps,
at least until you become familiar enough with using the
editor that you understand how best to specify searches.
For a beginner it is not a bad idea to double-check each
command before pressing carriage return to send the command
on its way.
~
(M) tQ ~
rescue
The ~ (M) command has the ability to reverse the
effects of the last command. To undo the previous command,
type "u" or "undo". Undo can rescue the contents of the
buffer from many an unfortunate mistake.
However, its
powers are not unlimited, so it is still wise to be reasonably careful about the commands you give. It is possible to
undo only commands which have the power to chan-ge the
buffer, for example delete, append, move, copy, substitute,
and even undoritself. The commands wr~te (w) and edit (e)
which interact with disk files cannot be undone, nor can
commanas such as print which do not change the buffer. Most
importantly, the ~ command which can be reversed by undo
is the last "undo-able" command which you gave.
To illustrate, let's issue an undo command.
Recall
that the last buffer-changing command we gave deleted the
lines which were formerly numbered 2 and 3. Executing undo
a t this moment will reverse the effects of the deletion,
causing those two lines to be replaced in the buffer.
:u
2 more lines in file after undo
And this is some more text.
Here again, edit informs you if the command affects more
than one line, and prints the text of the line which is now
"dot" (the current line).
~
about ..t.b.e.do.t (.) arui buffer Jmd
($)
The function assumed by the symbol dot depends
context. It can be used:
on
its
£-144
\
,
1. to exit from append mode we type dot (and
dot) on a line and press carriage return;
2.
only
a
to refer to the line we are at in the buffer.
Dot can also be combined with the equal sign
number of the line currently being edited:
to
get
the
... Thus if we type " . = 1
line and if we type
I we
".11
are asking for the number of the
we are asking for the text of the
l~ne.
In this editing session and the last, we used the dollar sign to indicate the end of the buffer in commands such
as print, copy, and move. The dollar sign as a command asks
edit to print the last line in the buffer. If the dollar
sign is combined with the equal sign ($=) edit will print
the line number corresponding to the last line in the
buffer.
".11
and "$11 therefore represent line numbers.
Whenever appropriate, these symbols can be used in place of
line numbers in commands. - For example
:.,$d
instructs edit to delete all lines from the current line (.)
to the end of the buffer.
Moying around .in
~
buffer
(+.and-)
It is frequently convenient during an editing session
to go back and re-read a previous line. We could specify a
context search for a line we want to read if we remember
some of its text, but if we simply want to see what was
written a few, say 3, lines ago, we can type
-3p
This tells edit to move back to a position
the current line (.) and print that line.
ward in the buffer similarly:
3 lines before
We can move for-
+2p
instructs edit to print the line which is
current position.
2
ahead
of
our
You may use "+11 and " _ I I in any command where edit
accepts line numbers. Line numbers specified with "+11 or
"_" can be combined to print a range of lines.
The commana
£-145
:-I,+2copy$
makes a copy of 4 lines: the current line, the line before
it, and the two after it. The copied lines will be placed
after the last line in the buffer ($) •.
Try typing only ~~-' '; you will move back one line just
as if you had typed '~-lp' '. Typing the command ~'+" works
similarly. You might also try typing a few plus or minus
signs in a row (such as ~~+++") to see edit's response.
Typing a carriage return alone on a line is the equivalent
of typing "+lp"; it will move you one line ahead in the
buffer and print that line.
If you are at the last line of the buffer and try to
move further ahead, perhaps by typing a "+" or a carriage
return alone on the line, edit will remind you that you are
at the end of the buffer:
At end-of-file
Similarly, if you try to move to a position before the first
line, edit will print one of these messages:
Nonzero address required on ~his command
Negative address - first buffer line is I
The number associated with a buffer line is the line's
"address", in that 'it can be used to locate the line.
Changing lines
(~)
There may be occasions when you want to delete certain
lines and insert new text in their place. This can be
accomplished easily with the change (~) command. The change
command instructs edit to delete specified lines and then
sWitch to text input mode in order to accept the text which
will replace them.
Let's say we want to change the first
two lines in the buffer:
This is some sample text.
And this is some more text.
to read
This text was created with the UNIX text editor.
To do so, you can type:
E-146
,
:1,2c
2 lines changed
~ ~ ~ created nth
~
.IlN.IX
~
editor.
•
·
In the command ~,2& we specify that we want to change the
range of lines beginning with 1 and ending with 2 by giving
line numbers as with the print command. These lines will be
deleted. After a carriage return enters the change command,
edit notifies you if more than one line will be changed and
places you in text input mode. Any text typed on the following lines will be inserted into the position where lines
were deleted by the change command. You will remain in text
input mode until you exit in the usual way, by typing a
period alone on a line. Note that the number of lines added
to the buffer need not be the same as the number of lines
deleted.
This is the end of the third session
with UNIX.
E-147
on
text
editing
SessiQn .!
This lessQn CQvers several tQpics, starting with CQmmands which apply thrQughQut the buffer, characters with
special meanings, and hQW tQ issue UNIX cQmmands while in
the editQr. The next tQpics deal with files: mQre Qn reading and writing, and methQds Qf recQvering files IQst in a
crash. The final sectiQn suggests SQurces Qf further infQrrna ti Qn.
Making cQmmands glQbal (g)
One disadvantage tQ the cQmmands we have used fQr
searching Qr substituting is that if YQU have a number Qf
instances Qf a wQrd tQ change it appears that YQU have tQ
type the command repeatedly, Qnce fQr each time the change
needs to be made. Edit, hQwever, provides a way to make
commands apply tQ the entire contents Qf the buffer - the
glQbal (g) command.
TQ print all lines cQntaining a certain
characters (say, "text' ') the cQmmand is:
sequence
of
:g/text/p
The "~gil instructs edit to make a glQbal search fQr all
lines in the buffer containing the characters "text' '.
The "p" prints the lines fQund.
TQ issue a global cQmmand, start by typing a "g"
and
then a search pattern identifying the lines to be affected.
Then, on the same line, type the command to be executed on
the identified lines. Global substitutions are frequently
usetul. For example, to change all instances of the wQrd
"text"
to the word "material" the command would be a
combination Qf the glQbal search and the substitute command:
:g/text/s/text/material/g
NQte the "g" at the end of the global cQmmand which
instructs edit tQ change each and every instance of "text"
tQ "material' '. If YQU dQ not type the "~gIl at the end Qf
the command only the first instance Qf "text" in each line
will be changed (the nQrmal result of the substitute command).
The "g" at the end Qf the cQmmand is independent
of the "~gil at the beginning. You may give a cQmmand such
as:
:14s/text/material/g
to change every instance Qf
Further,
neither
cQmmand
"material" because "Text"
than a lower-case ~.
"text'l in line 14 alone.
will
change
"Text"
tQ
begins with a capital rather
E-148
Edit does not automatically print the lines modified by
a global command. If you want the lines to be printed, type
a "p" at the end of the global command:
:g/text/s/text/material/gp
The usual qualification should be made about using the global command in combination with any other - in essence, be
sure of what you are telling edit· to do to the entire
buffer. For example,
:g/ fd
72 less lines in file after global
will delete every line containing a blank anywhere in it.
This could adversely affect your document, since most lines
have spaces between words and thus would be deleted.
After
executing the global command, edit will print a warning if
the command added or deleted more than one line.
Fortunately, the undo command can reverse the effects of a global command. You should experiment with the global command
on a small buffer of text to see what it can do for you.
~
about searching 4nd substituting
In using slashes to identify a charact·er string that we
want to search for or change, we have always specified the
exact characters. There isa less tedious way to repeat the
same string of characters. To change "noun" to ··nouns"
we may type either
:/noun/s/noun/nouns/
as we have done in the past, or a somewhat abbreviated
mand:
com-
:/noun/s//nouns/
In this example, the characters to be changed are not specified
there are no characters, not even a space, between
the two slash marks which indicate what is to be changed.
This lack of characters between the slashes is taken by the
editor to mean "use the characters we last searched for as
the characters to be changed."
Similarly, the last context search may be repeated
typing a pair of slashes with nothing between them:
by
:/does/
It doesn't mean much here, but
:/f
it does illustrate the editor.
Because no characters are specified for the
£-149
second
search,
the editor scans the buffer for the next occurrence of the
characters "does".
Edit normally searches forward through the buffer,
" wrapping around from the end of the buffer to the beginning,
until the specified character string is found. If you want
to search in the reverse direction, use question marks (7)
instead of slashes to surround the character string.
Special characters
Two characters have special meanings when used in
searches:
~'$"
and ~~ft". "$11 is taken by
the editor to mean "end of the line" and is used to identify strings which occur at the end of a line.
specify~ng
, :g/ing$/s//ed/p
tells the editor to search for all lines ending in '"ing'l
(and nothing else, not even a blank space), to change each
final "ing" to "ed" and print the changed lines.
Thus,
The symbol
"" "" - , I
indicates the
beginning
of
a
line.
:s/"'/l. /
instructs the editor to insert
beginning of the current line.
~
'1. ' , and
a
space
at
the
The characters "$" and "ft"
have special meanings
only in the context of searching. At other times, they are
ordinary characters. If you ever need to search for a character that has a special meaning, you must indicate that the
character is to temporarily lose its special Significance by
typing another special character, the backslash (\), before
it.
:s/\$/dollar/
looks for the character "$1' in the current line and
replaces it by the word' ~dollar' '. Were it not for the
backslash, the "$" would haverepr esented ~. the end of the
line"
in your search, not necessarily the character "$".
The backslash retains its special significance at all times.
Issuing
~
commands from
~
editor
After creating several files with the editor, you may
want to delete files no longer useful to you or ask for a
list of your files. Removing and listing files are not
functions of the editor, and so they require the use of UNIX
system commands (also referred to as "shell'l commands, as
, 'shell"
is the name of the program that processes UNIX
\
.
\'
"
E-158
,
commandS). You do not need to quit the editor to execute a
UNIX command as long as you indicate that it is to be sent
to the shell for execution. To use the UNIX command Lm to
remove the file named "junk" type:
:!rm junk
!
The exclamation mark (1) indicates that the rest of the line
is to be processed as a UNIX command. If the buffer contents have not been written since the last change, a warning
will be printed before the command is executed. The editor
prints a "I" when the command is completed. The tutorial
"Communicating with UNIX" describes useful features of the
system, of which the editor is only one part.
Filenames
~ ~
manipulation
Throughout each editing session, edit keeps track of
the name of the file being edited as the current filename.
Edit remembers as the current filename the name given when
you entered the editor. The current filename changes whenever the edit (e) command is used to specify a new file.
Once edit has recorded a current filename, it inserts that
name into any command where. a filename has been omitted. If
a write command dO'es not specify a file, edit, as we have
seen, supplies the current filename. You can have the editor write onto a different file by including its name in the
write command:
:w' chapter3
"chapter3" 283 lines, 8698 characters
The current filename remembered by the editor ~ ~ .~
changed ~ A result ~ ~ write command unless ~ ~ ~
first filename given in ~ editing session. Thus, in the
next write command which does not specify a name, edit will
write onto the current file and not onto
the
file
, . ch apt e r 3 ' • •
~ ~
(~)
command
To ask for the current filename, type file (or ~) •
In
response, the editor provides current information about the
buffer, including the filename, your current position, and
the number of lines in the buffer:
:f
"text" [Modified] line 3 of 4 --75%-If the contents of the buffer have changed since the last
time the file was written, the editor will tell you that the
file has been "[Modified] ". After you save the changes by
£-151
writing onto a disk file, the buffer will no longer be considered modified:
:w
"text" 4 lines, 88 characters
:f
"text" line 3 of 4 --75%-Beading additional files (L)
The ~ (L) command allows you to add the contents of
a file to the buffer without destroying the text already
there. To use it, specify the line after which the new text
will be placed, the command ~, and then the name of the
file.
:$r bibliography
"bibliography" 18 lines, 473 characters
This command reads in the file bibliography and adds it to
the buffer after the last line. The current filename is not
changed by the read command unless it is the first filename
given in the editing session.
Writing parts Qf
~
buffer
The write (~) command can write all or part of the
buffer to a file you specify. We are already familiar with
writ1ng the entire contents of the buffer to a disk file.
To write only part -of the buffer onto a file, indicate the
beginning and ending lines before the write command, for
example
:45,$w ending
, Here all lines from 45 through the end of the buffer are
written onto the file named ending. The lines remain in the
buffer as part of the document you are editing, and you may
continue to edit the entire buffer.
.
Recoyering 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 file, enter
the editor and type the command recover (rec), followed by
the name of the lost file.
:recover chap6
,"
i
E-152
\
Recover {s sometimes unable to save the entire buffer successfully, so always check the contents of the saved buffer
carefully before writing it back onto the original file.
Other recovery technigues
If something goes wrong when you are using the editor,
it may be possible to save your work by using the command
preserve (pre), which saves the buffer as if the system had
crashed.
If you are writing a file and you get the message
"Quota exceeded ' ·, you have tried to use more disk storage
than is allotted to your account. Proceed ~ caution
because it is likely that only a part of the editor IS buffer
is now present in the file you tried to write. In this case
you should use the shell escape from the editor (1) to
remove some files you don't need and try to write the file
again. If this is not possible and you cannot find someone
to help you, enter the command
:preserve
and then seek help. Do not simply leave the editor. If you
do, the buffer will be lost, and you may not be able to save
your file. After a preserve, you can use the recover command once the problem has been corrected.
If you make an undesirable change to the buffer and
issue a write command before discovering your mistake, the
modified version will replace any previous version of the
file.
Should you ever lose a good version of a document in
this 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 state with
the undo command. After fixing the damaged buffer, you can
again write the file to disk.
Further reading And other information
Edit is an editor designed for beginning and casual
users.
It is actually a version of a more powerful editor
called~.
These lessons are intended to introduce you to
the editor and its more commonly-used commands. We have not
covered all of the editor's commands, just a selection of
commands which should be sufficient to accomplish most of
your editing tasks. You can find out more about the editor
in the ~ Reference Manual, which is applicable to both ~
and edit. The manual is available from the Computer Center
Library, 218 Evans Hall. One way to become familiar with
the manual is to begin by reading the description of commands that you already know.
£-153
Using ..ex
As you become more experienced with using the editor,
you may still find that edit continues to meet your needs.
However, should you become interested in using ex, it is
easy to switch.
To begin an editing session with ex, use
the name ..ex in your command instead of edit.
Edit commands work the same way in ex, but the editing
environment is somewhat different. You should be aware of a
few differences that exist between the two versions of the
editor.
In edit, only the characters "~", "$", and
, '\" have special me'anings in searching the buffer or indicating characters to be changed by a sUbstitute command.
Several additional characters have "magic" meanings in ex,
as described in the Ex Reference Manual. Another feature of
the edit environment prevents users from accidently entering
two alternative modes of editing, ~ and visual, in which
the editor behaves quite differently than in normal command
mode. If you are using ex and the editor behaves strangely,
you may have accidently entered open mode by typing " 0 " .
Type the ESC key and then a "q'l to get out of open or
visual mode and back into the regular editor command mode.
The document An Introduction ~ Display Editing ~ Yi provides a full discussion of visual mode.
tutorial ~ produced ~ ~ Computer
Center Qf ~ University Qf California, Berke~.
~ welcome comments ~ suggestions ~
cerning ~ ~ ~ ~ ~ documentation
in general. Contact ~ ~ consultant in
212 Evans, ~-4072.
~
E-154
,
Ex/Edit Command Summary (Version 2.0)
£A and'.e.d.it. are text editors, used for creating and
modifying files of text on the
UNIX computer system.
Edit is
a variant of ~ with features
designed to make it less complicated to learn and use.
In
terms of command syntax and
effect the editors are essentially identical, and this command summary applies to both.
The summary is meant as a
quick
reference
for
users
already acquainted with ~ or
~.
Fuller explanations of the
editors are available in the
documents Edit:
A Tutorial (a
self-teaching introduction) and
the £A Reference Manual (the
comprehensive reference source
for both ~ and ~). Both of
these writeups are available in
the Computing Services Library.
In
the examples included
with the summary, commands and
text entered by the user are
printed in boldface to distinguish
them
from
responses
printed by the computer.
~
Editor Buffer
In order to perform
its
tasks the editor sets aside a
temporary work space, called a
buffer,
separate
from
the
user's permanent file.
Before
starting to work on an existing
file the editor makes a copy of
it in the buffer, leaving the
original untouched.
All editing changes are made to the
buffer copy, wnich must then be
written back to the permanent
file in order update the old
version. The buffer disappears
at the end of the editing session.
Editing: Command
And
~ ~
~
During an editing session
there are two usual modes of
operation:
command mode and
.t.e.At. .i.n.ru.J..t. mode.
(This disregards, for the moment, ~ and
visual modes, discussed below.)
In command mode, the editor
issues a colon prompt (:)
to
show that it is ready to accept
and execute a command. In text
input mode, on the other hand,
there is no prompt and the editor merely accepts text to be
added to the buffer.
Text
input mode is initiated by the
commands append, insert, and
change, and is terminated by
typing a period as the first
and only character on a line.
Line Numbers and Command Syntax
The editor keeps track of
lines of text in the buffer by
numbering
them consecutively
starting with I and renumbering
as lines are added or deleted.
At any given time the editor is
positioned
at one of these
lines; this position is called
the current~.
Generally,
commands that change the contents of the buffer print the
new current line at the end of
their execution.
Most commands can be preceded by one or two line-number
addresses which indicate the
lines to be affected.
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
ar given.
The default assumed
by each command is designed to
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
to this rule should be noted.
The ~ command by itself,
for instance, causes one line,
the current line, to be printed
at the terminal.
The summary
shows
the
number of
line
addresses that can be prefixed
to each command as well as the
defaults assumed if they are
omitted.
For example,
(.,.)
means
that up to 2
linenumbers may be given, and that
if none is given the command
operates on the current line.
(In the address prefix notation,
"."
stands for
the
current line and "$" stands for
the last line of the buffer.)
If no such notation appears, no
line-number prefix may be used.
Some
commands take trailing
information;
only the
more
important instances of this are
mentioned in the summary.
.owm and
Visual
~
Besides command and
text
input modes, ~ and ~ provide on some CRT
terminals
other modes of editing, ~
and visual. In these modes the
cursor can be moved to individual words or characters in a
line.
The commands then given
are very different from the
standard editor commands; most
do not appear on the screen
E-155
when typed. An Introduction
Display Editing ~ Yi pr
vides
a
full
discussio
Special Characters
Some characters take on sp
cial meanings when used
context searches and in pa
terns given to the substitu
command.
For~,
these a
"An and "$", meaning the begi
ning and end of a line, respe
tively.
~ has the
followi
additional special character
•
$
*
[
]
To use one of the special cha
acters as its Simple graph
representation rather than wi
its speCial meaning, precede
by a backslash (\).
The bac
slash
always has a speci
meaning.
Name
(.)append
Abbr
Example
Begins text input mode,
adding lines to the buffer
after the line specified.
Appending continues until
"." is typed alone at the
beginning of a new line,
followed by a
carriage
return.
fa places lines
at the beginning of the
buffer.
:a
Three
lines
of
text are added to
the buffer after
the current line.
Deletes indicated line(s)
and initiates text input
mode to replace them with
new text which follows.
New text is terminated the
same way as with append.
:5,6c
Lines 5 and 6 are
deleted
and replaced by
these
three lines.
(.,.)copy AddL co
Places
a copy of
the
specified lines after the
line indicated by AddL.
The example places a copy
of lines 8 through 12,
inclusive, after line 25.
:8,12co 25
Last line
is printed
(.,.)delete
Removes
lines from
buffer
and prints
current line after
deletion.
:13,l5d
New current
is printed
(.,.)change
edit ~
edit! .f.i.l.e
file
~
a
Description
c
d
e
el
f
the
the
the
·
•
·
copied
line
·•
Clears the editor buffer
and then. copies into it
the named
.fi.l.f:.,
which
becomes the current file.
This is a way of shifting
to a different file without leaving the ~ditor •.
The
editor
issues
a
warning message if this
command
is used before
saving changes made to the
file
already
in
the
buffer; using the form e!
overrides this protective
mechanism.
:e chlO
No
write
since
last chang~
:el chlO
"chlO" 3 lines, 62
characters
If followed by a name,
renames the current file
to name.
If used without
~,
prints the name of
the current file.
:f ch9
"ch9" [Modified] 3
lines •••
·
:f
"ch9" [Modified] 3
lines •••
.
,
Name
Abbr
(l,$)global
(l,$}global!
g
g!
or
v
global/pattern/commands
Searches the entire buffer
(unless a smaller range is
specified by line-number
prefixes)
and
executes
commands on every
line
with
an
expression
matching
pattern.
The
second form, abbreviated
either gl or v, executes
commands on lines that dQ
~ contain the expression
pattern.
.:g/nonsense/d
( .) insert
i
Inserts new linei of text
immediately
before
the
specified line.
Differs
trom append only in that
text
is placed before,
rather than after,
the
indicated line.
In other
words, Ii has the same
effect as 0a.
:li
These
lines
of
text will be added
prior to line 1.
(.,.+l)join
j
Join lines together, adjusting
white
space
(spaces
and
tabs)
as
necessary.
'
(.,.)list
(.,.)move
~
(.,.)number
Description
Example
:2,5j
Resulting
printed
.
1
Prints lines in a more
unambiguous way than the
print command does.
The
end of a line, for example, is marke~ with a "$",
and tabs printed as "-I".
m
Moves the specified lines
to a position after the
line indicated by ~.
New current
is printed
Prints each line preceded
by its buffer line number.
:nu
13
13
nu
: 91
This is line 9$
:12,15m 25
:
( .) open
line is
o
Too involved to discuss
here, but if you enter
open mode
accidentally,
press the ESC key followed
by q to get back into
normal
editor
command
mode. Edit is designed to
prevent accidental use of
the open command.
E-157
line
This is line
Name
Abbr
Example
Description
preserve
pre
Saves
a
copy of
the
current buffer contents as
though the system had just
crashed.
This is for use
in an emergency when a
write command has failed
and you don't know how
else to save your work.
Seek
assistance from a
consultant
as soon
as
possible after saving a
file with the
preserve
command, because the file
is
saved for only one
week.
:preserve
File preserved.
(.,.)print
p
Prints
line(s).
:+2,+3p
The
second
and
third lines after
the curent line
the
text
of
..
quit
quit!
(.)read
Ends the editing session.
You will receive a warning
if you have changed the
buffer since last writing
its contents to the file.
In this event you must
either type w to write, or
type q! to exit from the
editor without saving your
changes.
:q
No
write
last change
r
Places a copy of ~ in
the buffer after the specified line. Address 0 is
permissable and causes the
copy of ~ to be placed
at the beginning of the
buffer.
The ~ command
does not erase any text
already in the buffer. If
no line number is specified, .f..il.e. is placed after
the current line.
:0r newfile
nnewfile n 5 lines,
86 characters
rec
Retrieves a copy of the
editor buffer after a system crash, editor crash,
phone line disconnection,
or preserve command.
q
q!
~
recover .f..il.e.
E-158
since
: q!
%
,
Name
(.,.)substitute
Abbr
s
Description
substitute/pattern/replace-
:3p
ment
Line 3 contains a
misstake
:s/misstake/mistake/
Line 3 contains a
mistake
Reverses the changes made
in the buffer by the last
buffer-editing
command.
Note that this
example
contains
a
notificaion
about the number of lines
affected.
:1,15d
15 lines deleted
new line number 1
is printed
:u
15 more lines in·
file •••
old line number 1
is printed
substitute/pattern/replacement/gc
Replaces the first occurrence of pattern on a line
with
replacement.
Including
a g after the
command changes all occurrences of pattern on the
line. The c option allows
the user to confirm each
substitute before it is
made; see the manual for
details.
undo
u
Example
.
(l,$}write Lile w Copies- data from the buf(l,$)write! ~ wI fer onto a permanent file.
If no ~ is named, the
current filename is used.
The file is automatically
created if it does not yet
exist.
A
response containing
the number
of
lines and characters in
the file indicates that
the write has been completed successfully.
The
editor's built-in protections against overwriting
existing files will
in
some circumstances inhibit
a write.
The form w!
forces the write,
confirming that an existing
file is to be overwritten.
(.)z count
z
Prints a screen full of
text
starting with the
line indicated:
or, if
count is specified, prints
that
number of
lines.
Variants of the z command
are
described
in
the
manual.
E-159
:w
"file7" 64 lines,
1122 characters
:w fileS
"fileS" File exists
•••
:wl fileS
"fileS" 64 lines,
1122 characters
Name
!command
Abbr
Example
Description
Executes the remainder of
the line after ! as a UNIX
command.
The buffer is
unchanged by this,
and
control is returned to the
editor when the execution
of command is complete.
: !date
Fri Jun 9 12:15:11
PDT 1978
..
control-d
Prints the next scroll of
text, normally half of a
screen.
See the manual
for details of the scroll
option.
An address alone followed
by
a
carriage
return
causes
the line to be
printed.
A carriage return by itself prints the
line following the current
line.
:
the line after the
current line
Searches for the next line
in which pattern occurs
and prints it.
:/This patternl
This pattern next
occurs here.
(.+1)
Ipatterni
:
:
II
Repeats
search.
the
most
recent
:11
This pattern also
occurs here.
:
?pattern?
Searches in the reverse
direction for pattern.
??
Repeats the most recent
search,
moving in
the
reverse directin through
the buffer.
E-168
ADDENPUM lQ ~ -~
REFERENCE MANUAL
Version 1.1, Mod 4
~
Reguest:
.~
The request .~ ~ will print unnumbered headings.
Th1s is preterable to .an ~ in a number of ways.
Parameters changed
~
.$R
Because of the request above, there are now three
parameters to .$R. The first is the section title, the
second is the section number, and the third is the sect10n depth.
Correction
~
.an
Section
It is nQt legal to perform a .At
number registers 1n($~ through ~($~.
B-161
request
on
the
-~
REFERENCE MANUAL
Release .l..l/li
This document describes in extremely terse form the
features
of the -~ macro package for version seven
NROFF/TROFF. Some familiarity is assumed with those programs, specifically, the reader should understand breaks,
fonts, po~ntsizes, the use and definition of number registers and strings, how to define macros, and scaling factors
for ens, po~nts, ~'s (vertical line spaces), etc.
For a more casual introduction to text processing using
NROFF, reter to the document Writing Papers xith NROFF using
-~
.
There are a number of macro parameters that may be
adjusted. Fonts may be set to a font number only. In NROFF
font 8 is underlined, and is set in bold font in TROFF
(although font 3, bold in TROFF, is not underlined in
NROFF). Font 0 is no font change; the font of the surrounding text is used instead. Notice that fonts 0 and 8 are
"pseudo-fonts"; that is, they are Simulated by the macros.
Th~s
means that a~though it is legal to set a font register
to zero or eight, it is not legal to use the escape character form, such as:
Al~ distances are in
basic units, so it is nearly
always necessary to use a scaling factor. For example, the
request to set the paragraph indent to eight one-en spaces
is:
+NROFF and TROFF are Trademarks of Bell Laboratories.
-M~
REFERENCE MANUAL
£-162
1
-M~
REFERENCE MANUAL
.nr pi 8n
ana not
.nr pi 8
wnich would set the paragraph indent to eight basic units,
or about 0.02 inch. Default parameter values are given in
brackets in the remainder of this document.
Registers and strings of the form $A may be used in
expreSS1Uns but snould not be changed. Macros of the form
$x perform some function (as described) and may be redefined
to change this function. This may be a sensitive operation;
look at the bOdy of the original macro before changing it.
Ali names in -me follow a rigid naming convention. The
user may detine number registers, strings, and macros, provided that s/he uses single character upper case names or
double character names consisting of letters and digits,
witn at least one upper case letter. In no case should special characters be used in user-defined names.
On daisy wnee~ type printers in twelve pitch, the -LAl
flag can be stated to make lines default to one eighth inch
(tne norma~ spacing for a new11ne in twelve-pitch). This is
normally too small for easy readability, so the default is
to space one s1xth inch.
Th1s documentation was NROFF'ed on May
applies to version 1.1/20 of the -me macros.
~.
9,
1983
and
Paragraphing
These macros are used to begin paragraphs.
The standard paragrapn macro is .~; the others are all variants to
be usea for special purposes.
The first call to one of the paragraphing macros
detined in this section or the .Ah macro (defined in the
next session) initializes the macro processor.
After 1n1t1a11zation it is not possible to use any of the following
requests: .~, .lQ, .th, or .~.
Also, the effects of
changing parameters which will have a global effect on the
format of the page (notably page length and header and
footer margins) are not well defined and should be avoided.
and underlining are turned off if they were
on, the font is set to n(~ [1] the type
size is set to n(DD [10p], and a n(~ space
is inserted before the paragraph [0.35v in
TROFF, Iv or 0.5v in NROFF depending on
E-163
-ME REFERENCE MANUAL
device reSolution]. The indent is reset to
n($.i [8] plusn(~ [8] unless the paragraph
is inside a display. (see .ha).
At least
the first two lines of the paragraph are kept
together on a page.
units ot indent.
graph macro.
This is the standard para-
body of the following paragraph is indented ~
spaces (or n(il [5n] spaces if ~ is not
specified) more than a non-indented paragraph
(such as with .~) is.
The title % is
exdented (opposite of indented). The result
is a paragraph with an even left edge and %
printed in the margin. Any spaces in % must
be unpaddable.
Numbering is reset after a .~, .RR, or
The current paragraph number is in n($R •
.2..
.an.
Section Headings
Numbered sections are similiar to paragraphs except
that a sect10n number is automatically generated for each
one. The section numbers are ot the form l.2..J.. The depth
of the section is the count of numbers (separated by decimal
pOints) in the section number.
Unnumbered section heaaings are similar, except that no
number is attached to the heading.
missing the current depth (maintained in the
number register n($a) is used.
The values
of the individual parts of the section number
are maintained in n($~ through n($~. There
is a n(u [Iv] space before the section. %
is printed as a section title in font n(~
[8] and size n(~ [18p]. The "name" of the
section may be accessed vian~ If n(ai
is non-zero, the base indent is set to n(ai
times the section depth, and the section
title is exdented. (See .ha.) Also, an additional indent of n(aQ [8] is added to the
section title (but not to the body of the
section). The font is then set to the paragraph font, so that more information may
occur on the line with the section number and
title. .Ah insures that there is enough room
B-164
-ME REFERENCE MANUAL
to print the section head plus the beginning
of a paragraph (about 3 lines total). If A
through L are specified, the section number
is set to that number rather than incremented
automat1cally. If any of A through L are a
hyphen that number is not reset. If ~ is a
single underscore ("_") then the section
depth and numbering is reset, but the base
indent is not reset and nothing is printed
out. This is useful to automatically coordinate section numbers with chapter numbers.
the number and title, and do not increment
the section number at level~. This has the
effect of starting a new paragraph at level
~.
printed w1th the
font, etc., as for
same
rules
for spacing,
.~.
get fancier headings. ~ is the title passed
on the .~ or .Yh line: B is the section
number for this section, and H is the depth
ot this section. These parameters are not
always present; in particular, .~ passes all
three, .Yh passes only the first, and .RA
passes three, but the first two are null
strings. Care should be taken if this macro
is redefined; it is quite complex and subtle.
every call to .$R. It is normally undefined,
but may be used to automatically put every
section title into the table of contents or
for some similiar function. ~ is the section
title for the section title which was just
printed, B is the section number, and H is
the section depth.
section.
May be defined to (for example)
give variable spacing before sections. These
macros are called from .$~, so if you redefine that macro you may lose this feature.
~.
Headers And Footers
Headers and footers are put at the top and bottom of
every page automat1cally.
They are set in font n(tL [3]
ana size n(~ [lOp]. Each of the definitions apply as ot
E-165
-ME REFERENCE MANUAL
the ~ page.
Three-part titles must be quoted if there
are two blanks adjacent anywhere in the title or more than
e~ght blanks total.
The spacing of headers and fo·oters are controlled by
three number registers. n(hm [4v] is the distance from the
top ot the page to the top of the header, n(fm [3v] is the
distance from the bottom of the page to the bottom of the
footer, ntt.m [7v] is the distance from the top of the page
to the top ot the text, and n(bm [6v] is the distance from
the bottom of the page to the bottom of the text (nominal).
The macros .ml, .~, .ml, and .m! are also supplied for compat~bility w~th ROFF documents.
the top of every page.
every page.
every even-numbered page.
every odd-numbered page.
every even-numbered page.
every odd-numbered page.
page.
/
the header [4v].
first line of text [2v].
and the footer [2v].
tom of the page [4v).
page.
Useful for forcing out footnotes, but
other than that hardly every used.
Must be
followed by a •.b.g, or the end of input.
£-166
-ME REFERENCE MANUAL
May be redefined to provide fancy (e.g.,
multi-line) headers, but doing so loses the
function ot the .M, .~, . .iill, • .Q.h, • .e.f, and
.Qf requests, as well as the chapter-style
title feature of .+~.
the top of each page (after outputing the
header, initial saved floating keeps, etc.) 1
in other words, this macro is called immediately before printing text on a page. It can
be used for column headings and the like •
.i.
Displays
All displays except centered blocks and block quotes
are preceeded and followed by an extra n(ha [same as n(ua]
space. Quote spacing is stored in a separate register, centered blocks have no default initial or trailing space. The
verticai spacing of all displays except quotes and centered
blocks is stored in register n($B instead of n($L.
unfilled text.
If ~ is ~, the list will be
filled. If m [Xl is X the list is indented
by n(hi [4n], if H the list is indented to
the left margin; if L the list is left justified with respect to the text (different from
H only if the base indent (stored in n{$~
and set with .ha) is not zero) 1 and if ~ the
list is centered on a line-by-line basis.
The list is set in font n{gf [9]. Must be
matched by a .)~. This macro is almost like
.(h except that no attempt is made to keep
the display on one page.
filled, moved in from the text on both sides
by n(~ [4n], preceeded and followed by
n(g,a
[same as n(ha] space, and are set in
point size n(gp [one pOint smaller than surrounding text].
where the text of a keep is kept together on
one page if possible (keeps are useful for
E-167
-ME REFERENCE MANUAL
tables and figures which should not be broken
over a page). If the block will not fit on
the current page a new page is begun, unless
that would leave more than n(ht [0] white
space at the bottom of the text. If n(ht is
zero, the threshold feature is turned off.
Blocks are not filled unless ~ is ~, when
they are filled. The block will be leftjustified if m is L, indented by n(h! [4n]
if m is I or absent, centered (line-for-line)
if m is~, and left justified to the margin
(not to the base indent) if m is M.
The
block is set in font n(~ [0].
the keep is floated to the bottom of the page
or the top of the next page. Therefore, its
position relative to the text changes. The
float1ng keep is preceeded and followed by
nCz.a [Iv] space. Also, it defaults to mode
M.
tered as a block, rather than on a line-byline basis as with .(~~. This call may be
nestea ins1de keeps •
.5..
Annotations
keep is saved for output later with
manner similar to footnotes.
.~,
in a
register n($d and the associated string _
are incremented if _has been referenced •
. (d is printed and truncated. This might be
used at the end of each chapter.
floated to the bottom of the page and set in
font n(Lf [1] and size n(~ rap].
Each
entry is preceeded by n(ll [0.2v] space, is
indented n(!i [3n] on the first line, and is
indentea n(fu [0] from the right margin.
E-168
-ME REFERENCE MANUAL
Footnotes line up underneath two columned
output. If the text of the footnote will not
all fit on one page it will be carried over
to the next page.
the assoc1ated string _are incremented if
they have been referenced.
This macro may be redefined to give other
size lines or other types of separators.
Currently it draws a 1.Si line.
in the index X [X] until called up with .XR.
Each entry is preceeded by a n(xa [0.2v)
space.
Each entry is "undented n by n(n
[0.Si); this register tells how far the page
number extends into the right margin.
with a row of dots with A [null] right justified on the last line (such as for an
author's name), followed by P [n%]. If A is
specified, ~ must be specified; n% can be
used to print the current page number. If ~
is an underscore, no page number and no row
of dots are printed.
the font, size, and so forth in effect at the
time it is printed, rather than at the time
it is collected.
~.
Columned Output
is set to +~ [4n, 0.Si in ACM mode] (saved in
n($a). The column width, calculated to fill
the single column line length with both
columns, is stored in n($~.
The current
column is in n($~. You can test register
n($m [1] to see if you are in single column
or double column mode. Actually, the request
enters N [2] columned output.
it begins a new column on a new page only if
necessary, rather than forcing a whole new
page if there is another column left on the
E-169
-ME REFERENCE MANUAL
current page.
2.
Fonts·~
Sizes
spacing is set proportionally. The ratio of
line spacing to pOintsize is stored in n($L.
The ratio used internally by displays and
annotations is stored in n($.R(although this
is not used by .~).
vious
font.
To
append different font
requests, use X = &.
If no parameters,
change to roman font.
font.
font.
If no parameters,
Underlines in NROFF.
change to italic
ous font.
It no parameters, switch to bold
font. In NROFF, underlines.
ous font.
It no parameters, switch to bold
font. .~ differs from .~ in that .Lh does
not underline in NROFF.
underlining, as opposed to the .~ request,
which changes to "underline font" (usually
italics in TROFF). It wonlt work right if H
is spread or broken (including hyphenated).
In other words, it is safe in nofill mode
only.
surrounds H with double quote marks ('nl),
but in TROFF uses directed quotes.
ally, sets Ii in italic and overstrikes once.
Underlines in NROFF. It won't work right if
H is spread or broken (including hyphenated).
In other words, it is safe in nofill mode
only.
in NROFF. It won't work right if H is spread
or broken (including hyphenated). . In other
words~ it is safe in nofill mode only.
8-171
-ME REFERENCE MANUAL
page
if not enough room on this
Equivalent to a .AQ B inside a block.
Equivalent to
.~
page.
% ~.
% l.
headers and footers. This is used to leave
space for a full-page diagram which is produced externally and pasted in later. To get
a partiai-page paste-in display, say .~ B,
where B is the amount of space to leave, this
space will be output immediately if there is
room, and will otherwise be output at the top
of the next page. However, be warned: if B
is greater than the amount of available space
on an empty page, no space will ever be output.
m
is ~ or omitted, indented n(hi [4nJ if m
is ~, and left justified if m is L. ~ is a
title printed on the right margin next to the
equation.
See Typesetting Mathematics
~'a
Guide by Brian W. Kernighan and
Lorinda L. Cherry.
continued
by
immediately following with
another .~, the text of which can be centered aiong with this one. Otherwise, the
equation is printed, always on one page, with
n(~
[~.5v
in TROFF, Iv in NROFFJ space
above and below it.
kept
on one page if possible.
B-111
If you have a
-ME REFERENCE MANUAL
large table which will not fit on one page,
use h = R and follow the header part (to be
printed on every page of the table) with a
.~.
See ~ - A Program ~ Format Tables by
M. E. Lesk.
table.
float, in fact, it is not even guaranteed to
stay on one page if you use requests such as
.~
intermixed with the text of the table.
If you want it to float (or if you use
requests inside the table), surround the
entlre table (including the .xa and .~
requests) with the requests .(z and .)z.
li.
Miscellaneous
every 0.8i in NROFF.
n($~)
•
All
paragraphs,
sections, and
displays come out indented by this amount.
Titles and footnotes are unaffected. The.~
request performs a •.b.a request if n(n [0]
is not zero, and sets the base indent to
n(n*n( $11..
differs from.~ because it only affects the
current environment.
[6.0i]. This should not be used after output
has begun, and particularly not in twocolumned output. The current line length is
storeo in n($~.
page.
This is useful inside floating keeps
to differentiate between the text and the
figure.
/~lib/~local.me)
which is intended to be
a set of locally defined macros. These macros should all be of the form .*X, where X is
any letter (upper or lower case) or digit.
E-172
-ME REFERENCE MANUAL
ll.
Standard Papers
page can occur, and headers and footers are
supressed. Also, the page number is not
incremented for this page.
acceptable for a doctoral dissertation at
Berkeley.
It double spaces, defines the
header to be a single page number, and
changes the margins to be 1.5 inch on the
left and one inch on the top. .++ and .+~
should be used with it. This macro must be
stated before initialization, that is, before
the first call of a paragraphing macro or
.~.
which we are entering. The section type is
defined by m. ~ means that we are entering
the chapter portion of the paper, A means
that we are entering the appendix portion of
the paper, ~ means that the material following should be
the
preliminary
portion
(abstract, table of contents, etc.) portion
of the paper, Aa means that we are entering
the abstract (numbered independently from 1
in Arabic numerals), and ~ means that we are
entering the bibliographic portion at the end
of the paper. Also, the variants ~ and BA
are allowed, which specify renumbering of
pages from one at the beginning of each
chapter or appenaix, respectively.
The li
parameter defines the new header.
If there
are any spaces in it, the entire header must
be quoted. If you want the header to have
the chapter number in it, Use the string
n{Qh. For example, to number appendixes
A.~
etc., type .++ BA "'n(Qh.%'. Each
section (chapter, appendix, etc.) should be
preceeded by the .+~ request. It should be
ment~oned that it is easier when using
TROFF
to put the front material at the end of the
paper, so that the table of contents can be
cOllected and output; this material can then
be physically moved to the beginning of the
paper.
number is maintained in n(Qh. This register
is incremented every time .+~ is called with
a parameter.
The title and chapter number
E-173
-ME REFERENCE MANUAL
13
are printed by .$~. The header is moved to
the footer on the first page of each chapter.
If ~ is omitted, .$~ is not called; this is
useful for doing your own "title page" at the
beginning of papers without a title page
proper.
.$~
calls .$~ as a hook so that
chapter titles can be inserted into a table
of contents automat.lcally.
This macro can be redefined to your liking.
It is defined by default to be acceptable for
a PhD thesis at Berkeley. This macro calls
$~,
which can be defined to make index
entries, or whatever.
undefined, but can be used to automatically
insert index entries, or whatever.
K is a
keyword,
either
nChapter n or nAppendix n
(depending on the .++ mode); H is the chapter
or appenaix number, and ~ is the chapter or
appendix title.
environment for photo-ready papers as used by
the ACM. This format is 25% larger, and has
no headers or footers. The author1s name A
is printed at the bottom of the page (but 6ff
the part which will be printed in the conference proceedings), together with the current
page number and the total number of pages H.
Additionally, this macro loads the
file
/~lib/me/a&m.~,
which may later be augmented with other macros useful for print.lng
papers for ACM conferences.
It should be
noted that this macro will not work correctly
in TROFF, since it sets the page length wider
than the physical width of
the
phototypesetter roll.
li.
Predefined Strings
Footnote number, actually n($f...
This
macro is incremented after each call to .)L.
Delayed text number.
Actually [n($.d].
Superscript. This string gives upward movement and a change to a smaller point size if
POSSible, otherwise it gives the left bracket
character ('[I).
8-174
-ME REFERENCE MANUAL
Unsuperscript. Inverse to ~ For example,
to produce a superscript you might
xlL which will produce x[Z].
Subscript. Defaults to '<' if
motion not possible.
Inverse to
type
half-carriage
~
The day of the week, as a word.
m.Q.
The month, as a word.
t.si
Today's date, directly printable.·
The date
is ot the form May 9, 1983. Other forms of
the date can be used by using n(~ (the day
of the month; for example, 9) ,m.Q. (as
noted above) or n(mQ (the same, but as an
ordinal number; for example, May is 5), and
n{~ (the last two
digits of the current
year) •
19
Lett quote marks.
rg
Right quote.
Double quote in NROFF.
3/4 em dash in TROFF; two hyphens in NROFF.
~.
Special Characters And Marks
There are a number of special characters and diacritimarks (such as accents) available through -me. To
ret~rence these characters, you must call the macro
.~
to
detine the charac~ers before using them.
cal
marks, as described in the remainder of this
section. This macro must be stated before
initialization.
The special characters available are listed below.
Usage
Example
Acu~e accent
a!
Grave accent
e e
Umlat
u u
Tilde
n fi,..
Caret
e e
c ~
Cedilla
Czech
e e
A A
Circle
There exists
EXISTS
For all
FORALL
Name
E-175
WRITING PAPERS
~
NROFF USING
-a&
This document describes the text processing facilities
available on the UNIX+ operating system via NROFF+ and the
-me macro package. It is assumed that the reader already is
generally familiar with the UNIX operating system and a text
editor such as.ex. This is intended to be a casual introduct~on, and as such not all material is covered.
In part~cular,
many variations and additional features of the -me
macro package are not explained. For a complete discussion
ot this and other issues, see ~ -m& Reference Manual and
~ NROFF/TROFF Reference Manual.
NROFF, a computer program that runs on the UNIX operatsystem, reads an input file prepared by the user and
ou~puts a formatted paper suitable for publication or
framing.
The input consists of~, or words to be printed,
ana requests, which give instructions to the NROFF program
telling how to format the printed copy.
ing
Sect~on I describes
the basics of
Sect~on
2 describes the basic requests.
text processing.
Section 3 introduces displays. Annotations, such as footnotes, are handled
in sec~~on 4. The more complex requests which are not discussea in section 2 are covered in section 5. Finally, sect~on 6 discusses things you will need to know if you want to
typeset documents. If you are a novice, you probably won't
want to read beyond section 4 until you have tried some of
the basic features out.
When you have your raw text ready, call the NROFF
matter by typing as a request to the UNIX shell:
±UNIX, NROFF, and TROFF are Trademarks
tories
USING NROFF AND -ME
£-176
of
Bell
for-
Labora-
USING NROFF AND -ME
nrorf -me
-T~
files
where ~ describes the type of terminal you are outputting
to. Common values are ~ for a DTC 300s (daisy-wheel type)
printer ana ~ for the line printer. If the -~ flag is
omitted, a "lowest common denominator" terminal is assumed;
this is good for previewing output on most terminals.
A
complete description of options to the NROFF command can be
fauna in ~ NROFF/TROFF Reference Manual.
The word argument is used in this manual to mean a word
or number wnich appears on the same line as a request which
moaifies the mean~ng of that request.
For example, the
request
.sp
spaces one
l~ne,
but
.sp 4
spaces four lines. The number ~ is an argument to the .~
request wnich says to space four lines instead of one.
Arguments are separated from the request and from each other
by spaces.
~.
Basics Qf
~
Processing
The primary function of NROFF is to collect words
from input lines, fill output lines with those words,
justify the right hand margin by inserting extra spaces
in the line, and output the result. For example, the
input:
Now is the t~me
for all good men
to come to the aid
at their party.
Four score and seven
years ago, •••
be read, packed onto output lines, and justified
proauce:
w~ll
to
Now is the time for all good men to come to the
aid at their party. Four score and seven years
ago, •••
Sometimes you may want to start a new output line even
though the line you are on is not yet full; for example,
at the end of a paragraph. To do this you can cause a
break, wnich starts a new output line. Some requests
cause a break automat~cally~ as do blank input lines and
E-177
US!NG NROFF AND -ME
input lines beginning with a space.
Not all input lines are text to be formatted.
Some
ot the input lines are reguests which describe how to
format the text. Requests always have a period or an
apostrophe {"I"} as the first character of the input
11ne.
The text formatter also does more complex things,
such as automatically numbering pages, skipping over page
folds, pu~ting footnotes in the correct place, and so
forth.
I can offer you a few hints for preparing text for
input to NROFF.
First, keep the input lines short.
Short input lines are easier to edit, and NROFF will pack
words onto longer lines for you anyhow. In keeping with
this, it is helpful to begin a new line after every
periou, comma, or phrase, since common corrections are to
add or delete sentences or phrases. Second, do not put
spaces at the end of lines, since this can sometimes confuse the NROFF processor. Third, do not hyphenate words
at the end at lines (except words that should have
hyphens in them, such as "mother-in-law") 1 NROFF is smart
enough to hyphenate words for you as needed, but is not
smart enough to take hyphens out and join a word back
together. Also, words such as "mother-in-law" should not
be broken over a line, since th~n you will get a space
where not wanted, such as "mother- in-law".
2.
Basic Reguests
z.~.
Paragraphs
Paragraphs are begun by using
For example, the input:
the
.~
request.
.pp
Now is the time for all good men
to come to the aid of their party.
Four score and seven years ago, •••
proauces a blank line followed by
line. The result is:
an
indented
first
Now is the time for all good men to come
to the aid of their party. Four score and
seven years ago, •••
Notice that the sentences of the paragraphs ~
begin with a space, since blank lines and lines
begining with spaces cause a break. For example, if I
n.Q.t
£-178
US1NG NROFF AND -ME
had typed:
.pp
Now is the time for all good men
to come to the aid of their party.
Four score and seven years ago, •••
The output would be:
Now is the time for all good men
to come to the aid of their party.
score and seven years ago, •••.
Four
A new line begins after the word "men" because
second line began with a space character.
the
There are many fancier types of paragraphs, which
w111 be described later.
2.2.
Headers And Footers
Arbitrary headers and footers can be put at the
top and bottom of every page. Two requests of the
form .~ title and .LQ title define the titles to put
at the head and the foot of every page, respectively.
The titles are called three-~ titles, that is,
there is a left-justified part, a centered part, and a
right-justified part. To separate these three parts
the first character of title (whatever it may be) is
usee as a delimiter. Any character may be used, but
backslash and double quote marks should be avoided.
The percent sign is replaced by the current page
number whenever found in the title. For example, the
input:
• he ,'%',
.fo 'Jane Jones 'My Book'
I
results in the page number centered at the top of each
page, "Jane Jones" in the lower left corner, and "My
BOOK" in the lower right corner.
2.~.
Double Spacing
NROFF will double space output text automatically
if
you use the request
tion.
.l£
.l£~,
as is done in this sec-
You can revert to single spaced mode by
~.
E-179
typing
2..J..
b.sLe. Layout
A number of requests allow you to change the way
the printed copy looks, sometimes called the layout of
the output page. Most of these requests adjust the
placing of "white space" (blank lines or spaces). In
these explanat10ns, characters in italics should be
replaced with values you wish to use1 bold characters
represent characters which should actually be typed.
The .hR request starts a new page.
The request .~ N leaves N lines of blank space.
N can be omitted (meaning skip a single line) or can
be of the form Ni (for N inches) or ~ (for N centimeters). For example, the input:
.sp 1.5i
My thoughts on the subject
.sp
leaves one and a half inches of space, followed by the
line "My thoughts on the subject", followed by a single blanK line.
The .in +N request changes the amount of white
space on the left of the page (the indent). The argument N can be of the form +.ti (meaning leave .N spaces
more than you are already leaving), -N (meaning leave
less than you do now), or just N (meaning leave
exactly N spaces).
.ti can be of the form.Hi or ~
also. For example, the input:
init1al text
.in 5
some text
.in +1i
more text
.in -2c
final text
prOduces "some text" indented exactly five spaces from
the lett margin, "more text" indented five spaces plus
one inch from the left margin (fifteen spaces on a
pica typewriter), and "final text" indented five
spaces plus one inch minus two centimeters from the
margin. That is, the output is:
in1tial text
some text
more text
final text
B-18'
The .~ +H (temporary indent) request is used
like .in +H when the indent should apply to one line
only, after which it should revert to the previous
inaent. For example, the input:
.in Ii
.ti 0
Ware, James R. The Best of Confucius,
Halcyon House, 1950.
An excellent book containing translations of
most of Confucius' most delightful sayings.
A definite must for anyone interested in the early foundations
of Chinese philosophy.
proauces:
Ware, James R.
The Best of Confucius, Halcyon House,
An excellent book containing translations of most of Confucius' most delightful
sayings.
A definite
must for anyone
interested in the early foundations
of
Chinese philosophy.
1950.
Text lines can be centered by using the .~
request. The line after the .~ is centered (horizontaily) on the page. To center more than one line, use
.~ H (wnere N is the number of lines to center), followed by the H lines. If you want to center many
lines but don't want to count them, type:
.ce 1000
lines to center
.ce 0
The
.~ ~
l~nes, in
request tells NROFF to center
other words, stop centering.
zero
more
All of these requests cause a break: that is,
they always start a new line. If you want to start a
new line without performing any other action, use .~.
z.~.
Underlining
Text can be underlined using the .~ request.
.~
request causes the next input line to be
unaeri~ned when output.
You can underline multiple
lines by stating a count of input lines to underline,
followed by those lines (as with the .~ request).
For example, the input:
The
.ul 2
Notice that these two input lines
are underlined.
£-181
USING NROFF AND -ME
Wlll underline those eight words in NROFF.
they wlll be set in italics.)
J..
(In
TROFF
Displays
Displays are sections of text to be set off from the
bOdy of the paper. Major quotes, tables, and figures are
types of displays, as are all the examples used in this
document. All displays except centered blocks are output
single spacea.
J..~.
Major Quotes
Major quotes are quotes which are several lines
and hence are set in from the rest of the text
wl~hout quote marks arouna them.
These can be generated using the commmands .(g and .)g to surround the
quote. For example, the input:
long,
As Weizenbaum pOints out:
• (q
It is said that to explain is to explain away.
ThlS maxim is nowhere so well fulfilled
as in the areas of computer programming, •••
•)q
generates as output:
As Weizenbaum pOints out:
It is said that to explain is to explain away.
ThlS maxim is nowhere so well fulfilled as in
the areas of computer programming, •••
J..2..
Lists
A ~ is an indented, single spaced, unfilled
display. Lists should be used when the material to be
printed should not be filled and justified like normal
text, such as columns of figures or the examples used
in this paper. Lists are surrounded by the requests
• (~ and .)~. For example, type:
Alternatives to avoid deadlock are:
• (I
Lock in a specified order
Detec~ deadlock and back out one process
Lock all resources needed before proceeding
.)I
will produce:
Alternatives to avoid deadlock are:
E-182
USLNG
NROFF AND -ME
Lock in a specified order
Detect deadlock and back out one process
Lock all resources needed before proceeding
1.1.
Keeps
A ~ is a
single page if
would use a keep
from lists in
boundary wnereas
display of lines which are kept on a
possible.
An example of where you
might be a diagram.
Keeps differ
that lists may be broken over a page
keeps will not.
Blocks are the basic kind of keep.
They begin
W1~n tne request .(h and end with the request .)h.
If
there is not room on the current page for everything
in the block, a new page is begun. This has the
unpleasant etfect of leaving blank space at the bottom
of the page.
When this is not appropriate, you can
use the alternat1ve, called floating keeps.
Floating keeps move relative to the text. Hence,
they are good for things which will be referred to by
name, such as "See figure 3". A floating keep will
appear at the bottom of the current page if it will
fit: otherw1se, it will appear at the top of the next
page.
Float1ng keeps begin with the line .(z and end
with the line .)z. For an example of a floating keep,
see figure 1. The.hl request is used to draw a horizontal line so that the figure stands out from the
text.
l.~.
Fancier Displays
moae,
Keeps and lists are normally collected in nofill
so that they are good for tables and such. If
• (z
.hl
Text of keep to be floated •
• sp
.ce
Figure 1. Example of a Floating Keep •
• hl
•) z
Figure 1.
Example of a Floating Keep.
E-183
USL~u
NROFF AND -ME
you want a display in fill mode (for text), type .{~ ~
(Throughout this section, comments applied to .{~ also
apply to .(h and .(z). This kind of display will be
inaented from both margins. For example, the input:
.(1 F
Ana now boys and girls,
a newer, bigger, better toy than ever before!
Be the first on your block to have your own computer!
Yes kids, you too can have one of these modern
data processing devices.
You too can produce beautifully formatted papers
without even batting an eye!
.) 1
will be output as:
And now boys and girls, a newer, bigger,
better toy than ever before! Be the first on
your block to have your own computer!
Yes
kids, you too can have one of these modern
data processing devices. You too can produce
beaUlafully formatted papers without even batt~ng, an eye!
Lists and blocks are also normally indented
(fioating keeps are normally left justified). To get
a lett-justifiea list, type • (~L. To get a list centered l~ne-for-line, type .(~~. For example, to get
a fillea, left justified list, enter:
.(1 L F
text of block
•)1
The input:
.(1
first line of unfilled display
more lines
•)1
prOduces the indented text:
first line of unfiiled display
more lines
Typing the character L after the
the lett justified result:
E-184
.(~
request
produces
USLNG NROFF AND -ME
f~rst line of unfilled display
more lines
Using ~ instead of L produces the line-at-a-time
tered output:
cen-
first line of untilled display
more lines
Somet~mes it may
be that you want to center
several l~nes as a group, rather than centering them
one l~ne at a time. To do this use centered blocks,
which are surrounded by the requests .(~ and .)~. All
the l~nes are centered as a unit, such that the longest l~ne is centered and the rest are lined up around
that line. Notice that lines do not move relative to
each other using centered blocks, whereas they do
us~ng the ~ argument to keeps.
Centered blocks are llQt keeps, and may be used in
with keeps.
For example, to center a
group of lines as a unit and keep them on one page,
use:
conjunct~on
.(b L
• (c
first line of unfilled display
more lines
•)c
•)b
to produce:
first line of unfilled display
more lines
If the block requests (.(h and .)h) had been omitted
the result would have been the same, but with no
guarantee that the lines of the centered block would
have all been on one page. Note the use of the L
argument to .(h; this causes the centered block to
center within the ent~re l~ne rather than within the
l~ne minus the indent.
Also, the center requests must
be nested inside the keep requests •
.i.
Annotations
There are a number of requests to save text for
later printing.
Footnotes are printed at the bottom of
the current page. Delayed ~ is intended to be a variant form of footnote; the text is printed only when
explicitly called for, such as at the end of each
E-185
US~~~
NROFF AND -ME
chapter.
Indexes are a type of, delayed text having a tag
the page number) attached to each entry after a
Indexes are also saved until called for
row Ot dots.
explicitly.
(usua~ly
J..~.
Footnotes
Footnotes begin with the request .(.f and end with
the request .).f. The current footnote number is maintained automat1cally, and can be used by typing ,
to produce a footnote number[l].
The number is
au~omatically
incremented after every footnote. For
example, the input:
• (q
A man who is not upright
and at the same time is presumptuous;
one who is not diligent and at the same time is ignorant;
one who is untruthful and at the same time is incompetent;
such men I do not count among acquaintances.
• (f
James R. Ware,
.ul
The Best of Confucius,
Halcyon House, 1959.
Page 77.
•)f
.) q
generates the result:
A man who is not upright and at the same time
is presumptuous; one who is not diligent and
at the same time is ignorant; one who is untruthful and at the same time is incompetent;
such men I do not count among
acquaintances. [2]
It is important that the footnote appears insj"de the
quote, so that you can be sure that the footnote will
appear on the same page as the quote.
J..~.
Delayed
~
Delayed text is very similar to a footnote except
that it is printed when called for explicitly. This
allows a list of references to appear (for example) at
the end of each chapter, as is the convention in some
9
[l]Like this.
[2]James R. Ware, l.b.e.
1959. Page 7/.
~
.Q.f Confucj"us, Halcyon House,
£-186
USI~G
NROFF AND -ME
disciplines. Use _on delayed text instead
as on footnotes.
of
If you are uSing delayed text as your standard
reterence mechanism, you can still use footnotes,
except that you may want to reference them with special characters* rather than numbers •
.i . .l.
Indexes
An "inaex" (actually more like a table of contents, since the entries are not sorted alphabetically) resembles delayed text, in that it is saved
until ca~led for.
However, each entry has the page
number (or some other tag) appended to the last line
of the index entry after a row of dots.
Inaex entries begin with the request .(x and end
with .)x. The .)x request may have a argument, which
is the value to print as the "page number".
It
deraults to the current page number. If the page
number given is an underscore ("_") no page number or
line ot dots is printed at all. To get the line of
dots without a page number, type .)x un, which specifies an explicitly null page number.
The
.~
request prints the index.
For example, the input:
• (x
Sealing wax
•)x
• (x
Cabbages and kings
•)x
• (x
Why the sea is bOiling hot
.)x 2.Sa
.(x
Whether pigs have wings
• ) x ""
• (x
is a terribly long index entry, such as might be used
for a list of illustrations, tables, or figures; I expect it to
take at least two lines •
Th~s
•)x
.xp
generates:
*Such as an asterisK.
£-187
US1Nu NROFF AND -ME
Seal1ng wax •••••••••••••••••••••••••••••••••••••
12
Cabbages and kings
Why the sea is bOiling hot •••••••••••••••••••••• 2.Sa
Whether pigs have wings •••••••••••••••••••••••••
ThiS is a terribly long index entry, such as
might be used for a list of illustrations,
tables, or figures; I expect it to take at
least two lines. •••••••••••••••••••••••••••••••
12
The .(x request may have a single character argument, specifY1ng the "name" of the index; the normal
index is x. Thus, several "indicies" may be maintained simultaneously (such as a list of tables, table
ot contents, etc.).
Notice that the index must be printed at the ~
ot the paper, rather than at the beginning where it
W111 probably appear (as a table of contents); the
pages may have to be physically rearranged after
printing.
~.
Fancier' Features
A large number of fancier requests exist, notably
requests to provide other sorts of paragraphs, numbered
seC~1ons of the form ~.~.~ (such as used
in this document), and multicolumn output.
~.~.
~
Paragraphs
Paragraphs generally start with a blank line and
the first line indented. It is possible to get
lett-justified block-style paragraphs by using .~
instead of .RP, as demonstrated by the next paragraph.
W1~n
Sometimes you want to use paragraphs that have the
~
indented, and the first line exdented (opposite
of indented) with a label. This can be done with the
•.iJa request •. A word specified on the same line as •.iJa
is printed in the margin, and the body is lined up at
a prespecified position (normally five spaces). For
example, the input:
B-188
US1NG NROFF AND -ME
.ip one
ThiS is the first paragraph.
Notice how the first line
of the resulting paragraph lines up
with the other lines in the paragraph •
• ip two
And here we are at the second paragraph already.
You may not1ce that the argument to .~
appears
in the margin •
• lp
We can continue text •••
prOduces as output:
one
Th1S is the first paragraph.
Notice how the
first line of the resulting paragraph lines up
with the other lines in the paragraph.
two
And here we are at the second paragraph already.
You may notice that the argument to .~ appears
in the margin.
.
We can cont1nue text without starting a
paragraph by using the .~ request.
new
indented
If you have spaces in the label of a .iD request,
you must use an nunpaddable space" instead of a regular space. This is typed as a backs lash character
("
label "Part 1", enter:
.ip "Part 1"
If a label of an indented paragraph (that is, the
argument to .~) is longer than the space allocated
for the label, the label will not be separated from
the text, and the rest of the text will be lined up at
the old margin (and not with the first line of text).
For example, the input:
.ip longlabel
Th1s paragraph had a long label.
The first character of text on the first line
will not line up with the text on second and subsequent lines,
although they will line up with each other.
will produce:
longlmbes paragraph had a long label. The first character ot text on the first line will not line up
with the text on second and subsequent lines,
8-189
USING NROFF AND -ME
although they will line up with each other.
It is possible to change the size of the label by
USing a second argument which is the size of the
label. For example, the above example could be done
correc~ly by saying:
.ip longlabel 10
wnich w111 make the paragraph indent 10 spaces for
this paragrapn only. If you have many paragraphs to
inaent all the same amount, use the number register
...
For example, to leave one inch of space for the
label, type:
.nr ii Ii
somewhere before the first call to .~.
reterence manual for more information.
Refer to
the
If .~ is used with no argument at all no hanging
tag will be printed. For example, the input:
.ip [a]
ThiS is the first
We have seen this
• ip
Th1S paragraph is
but it has no tag
paragraph of the example.
sort of example before •
lined up with the previous paragraph,
in the margin.
proauces as output:
[a]
Tll1s is the first paragraph of the example.
have seen this sort of example before.
We
ThiS paragraph is lined up with the previous
paragraph, but it has no tag in the margin.
A special case of .~ is .llJ2" which automatically
numbers paragraphs sequent1ally from 1. The numbering
is reset at the next .~, .~, or .~ (to be described
in the next section) request. For example, the input:
B-191
US1NG NROFF AND -ME
.np
This is the first pOint •
• np
ThlS is the second pOint.
POints are just regular paragraphs
which are given sequence numbers automatically
by the .np request •
• pp
ThlS paragrapn will reset numbering by .np •
• np
.
For example,
we have reverted to numbering from one now.
generates:
(1)
This is the first point.
(2)
ThiS is the second point. Points are just regular paragraphs which are given sequence numbers
automatlcally by the .np request.
This paragraph will reset numbering by .np.
(1)
~.z.
For example, we have reverted to
one now.
numbering
from
Section Headings
Sectlon numbers (such as the ones used in this
document) can be automatically generated using the .~
request. You must tell .~ the depth of the section
number and a section title. The depth specifies how
many numbers are to appear (separated by decimal
pOints) in the section number. For example, the sectlon number ~.Z.~ has a depth of three.
Sectlon numbers are incremented in a fairly
intuitive fashion. If you add a number (increase the
depth), the new number starts out at one. If you subtrac~
sectlon numbers (or keep the same number) the
final number is incremented. For example, the input:
• sn
.sh
.sh
.sh
.sh
.sh
.sh
1
2
2
3
3
1
3
nThe Preprocessor n
nBasic Concepts n
nControl Inputs n
nCode Generation n
proauces as output the result:
B-191
US1NG NROFF AND -ME
~.
Preprocessor
Basic Concepts
Control Inputs
~
~.~.
~.~.
~.~.~.
~.~.~.
~.
~
Generation
l.~.~.
You can specify the section number to begin by
placing the section number after the section title,
uS1ng spaces instead ot dots.
For example, the
request:
.sh 3 "Another section" 7 3 4
Will begin the section numbered 2.~.~; all subsequent
.~ requests will number relat1ve to this number.
There are more complex features which will cause
each seC~10n to be indented proportionally to the
depth of the section. For example, if you enter:
.nr si li
each section will be indented by an amount lie H must
have a scaling factor attached, that is, it must be of
the form liX., where .x. is a character telling what units
H is in. Common values for .x. are ~ for inches, ~ for
centimeters, and n for ~ (the width of a single
charac~er) •
For example, to indent each section onehalf inch, type:
.nr si B.Si
After this, sections will be indented by one-half inch
per level ot depth in the section number. For example, this document was produced using the request
.nr si 3n
at the beginning of the input file,
spaces of indent per section depth.
'Section heaaers without
numbers can be done using:
giving
automatically
three
generated
.uh "Title"
wnich w1ll do a section
number on the section.
heading,
£-192
but
will
put
no
US!~u
NROFF AND -ME
~.l.
Parts Qf
~
Basic Paper
There are some requests which assist in setting
up papers.
The .~ request initializes for a title
page. There are no headers or footers on a title
page, and unlike other pages you can space down and
leave blank space at the top. For example, a typical
ti~le page might appear as:
.tp
.sp 2i
.(1 C
THE GROWTH OF TOENAILS
IN UPPER PRIMATES
.sp
by
.sp
Frank N. Furter
.)1
.bp
The request .tA sets up the environment of the
NROFF processor to do a thesis, using the rules established at Berkeley. It defines the correct headers
ana footers
(a page number in the upper right hand
corner only), sets the margins correctly, and double
spaces.
The .+~ ~ request can be used to start chapters.
Each chapter is automatically numbered from one, and a
heading is printed at the top of each chapter with the
chapter number and the chapter name~. For example,
to begin a chapter called ·Conclusions·, use the
request:
.+c ·CONCLUSIONS·
which w1ll produce, on a new page, the lines
CHAPTER 5
CONCLUSIONS
wi~h
appropriate spacing for a thesis.
Also, the
header is moved to the foot of the page on the first
page of a chapter. Although the .+~ request was not
designed to work only with the.tA request, it is
tuned for the format acceptable for a PhD thesis at
Berkeley.
If the title parameter ~ is omitted from the .+~
request, the result is a chapter with no heading.
This can also be used at the beginning of a paper1 for
B-193
US!NG NROFF AND -ME
example, .+k
document.
was
used
to generate page one of this
Although papers traditionally have the abstract,
table or contents, and so forth at the front of the
paper, it is more convenient to format and print them
last wnen using NROFF. This is so that index entries
can be collected and then printed for the table ot
contents (or whatever).
At the end of the paper,
issue the .++ g request, wnich begins the preliminary
part or the paper. After issuing this request, the
.+k request will begin a preliminary section of tne
paper. Most notably, this prints the page number restarteo from one in lower case Roman numbe"rs. .+k may
be usea repeatedly to begin different parts of the
front material for example, the abstract, the table of
contents, acknowledgments, list of illustrations, etc.
The request .++ ~ may also be used to begin the
bibliographic section at the end of the paper. For
example, the paper might appear as outlined in figure
2.
(In this figure,. comments begin with the sequence
~.~.
Eguations
~
Tables
Two special UNIX programs exist to format special
types of material. Egn and ~ set equations for the
phototypesetter and NROFF respectively. ~ arranges
to print extremely pretty tables in a variety of formats. Th1s document will only describe the embellishments to the standard features~ consult the reference
manua~s for those
processors for a description of
their use.
The ~ and ~ programs are described fully in
the document Typesetting Mathematics - Users' Guide by
Br1an W. Kernighan and Lorinda L. Cherry.
Equations
are centered, and are kept on one page. They are
introauced by the .~ request and terminated by the
. 9 request.
The .~ request may take an equation number as an
opt1una! argument, which is printed vertically centered on the right hand side of the equation. If the
equation becomes too long it should be split between
two lines. To do this, type:
B-194
· USING NROFF AND -ME
GROWTH OF TOENAILS
IN UPPER PRIMATES
TH~
by
FranK Furter
Introauctl.on
text of chapter one
Next Chapter
text of chapter two
Conclusions
text of chapter three
Bibliograpny
text of bibliography
text of pretace
Figure 2.
Outline of a Sample Paper
.EO (eq 34)
text of equation 34
.EN C
.EO
continuation of equation 34
.EN
£-195
USING NROFF AND -ME
The ~ on the.U request specifies that
w111 be continued.
the
equation
The .tlll program produces tables.
It is fully
described (including numerous examples) in the document Xbl - A Program ~ Format Tables by M. E. Lesk.
Tables begin with the .j!S, request and end with the .n
request. Tables are normally kept on a single page.
If you have a table which is too big to fit on a single page, so that you know it will extend to several
pages, begin the table with the request .j!S,.Ii and put
the request .lR after the part of the table which you
want duplicated at the top of every page that the
table is printed on. For example, a table definition
for a long table might look like:
.TS H
c s s
n n n.
THE TABLE TITLE
.TH
text of the table
.TE
~.~.
~
Column Output
You can get two column output automatically by
using the request •.2..Q..This causes everything after
it to be output in two-column form. The request .~
will start a new column; it differs from .AR in that
.AR may leave a totally blank column when it starts a
new page. To revert to single column output, use .~.
~.~.
Defining Macros
A macro ~s a collection of requests and text
Which may be used by stating a Simple request. Macros
begin with the line .~ XA (where XA is the name of
the macro to be defined) and end with the line consisting of two dots. After defining the macro, stating the line .XA is the same as stating all the other
11nes. For example, to define a macro that spaces 3
lines and then centers the next input line, enter:
.de SS
.sp 3
.ce
••
and use it by typing:
E-196
US1Nu NROFF AND -ME
.S8
Title Line
(beginning ot text)
Macro names may be one or two characters.
In
order to avoid contlicts with names in -me, always use
upper case letters as names. The only names to avoid
are x.s" ,m, U, ~, and 9.
~.2.
Annotations Inside Keeps
Sometimes you may want to put a footnote or index
entry inside a keep.
For example, if you want to
maintain a nlist of figures n you will want to do something like:
• (z
• (c
text of figure
•)c
.ce
Figure 5 •
• (x f
Figure 5
.) x
.) z
which you may hope will give you a figure with a label
ana an entry in the index L (presumably a list of figures index). Unfortunately, the index entry is read
ana interpreted when the keep is read, not when it is
printed, so the page number in the index is likely to
be wrong. The solution is to use the magic string _
at the beginning of all the lines dealing with the
inaex. In other words, you should use:
.(z
.(c
Text of figure
•)c
.ce
Figure 5 •
• (x f
Figure 5
•)x
•)z
which w~ll defer the proceSSing of the index until the
figure is outpu~. This will guarantee that the page
number in the index is correct.
The same comments
apply to blocks (with .(h and .)h) as well.
B-197
USiNG NROFF AND -ME
.[e
TROFF.arui
~
Photosetter
With a little care, you can prepare documents that
print n~celY on either a regular terminal or when
phototypeset using the TROFF formatting program •
w~ll
.[e~.
Fonts
A !Qnt is a style of type. There are three fonts
are available simultaneously, Times Roman, Times
Ital~c, and Times Bold, plus the
special math font.
The normai font is Roman. Text which would be underlined in NROFF with the .~ request is set in italics
in TROFF.
that
There are ways of switching between fonts.
The
requests .L, .~, and .~ switch to Roman, italic, and
bold fonts respectively. You can set a single word in
some font by typing (for example):
.i word
which w~ll set ~ in italics but does not affect the
surrounding text.
In NROFF, italic and bold text is
underlined.
Not~ce that if you are setting more than one word
in whatever font, you must surround that word with
double quote marks ('"I) so that it will appear to the
NROFF processor as a single word. The quote marks
will not appear in the formatted text. If you do want
a quote mark to appear, you should quote the entire
string (even if a single word), and use ~ quote
marks wnere you want one to appear. For example, if
you want to produce the text:
"Master Control"
in
itai~cs,
you must type:
.i """Master Control"""
The _produces a very narrow space so that the "1"
does not overlap the quote sign in TROFF, like this:
"Master Control"
There are alSo several "pseudo-fonts"
The input:
£-198
available.
USiNG NROFF AND -ME
• (b
.u underlined
.bi "bold italics"
.bx "words in a box"
.) b
generates
underlined
.b.Qll italics
wo r d s .in. .a 1Lo.A
In NROFF these all just underline the text.
Notice
that pseudo font requests set only the single parameter in the pseudo font; ordinary font requests will"
begin setting all text in the special font if you do
not provide a parameter. No more than one word should
appear with these three font requests in the middle of
lines. This is because of the way TROFF justifies
text. For example, if you were to issue the requests:
.bi "some bold italics"
and
.bx "words in a box"
in the middle of a line TROFF would produce ~ hQlg
italics and words .in..a 1Lo.A, which would look really
lousy in TROFF.
The second parameter ot all font requests is set
in the original font. For example, the font request:
.b bold face
generates "bold" in bold font, but sets "face" in
font of the surrounding text, resulting in:
the
l2.Ql.gface.
To set the two words h2ld and
type:
~
both in
~
~,
.b "bold face"
You can mix fonts in a word by using the special
sequence ~ at the end of a line to indicate "continue
text processing"; this allows input lines to be joined
together w1thout a space inbetween them. For example,
the input:
E-199
USINu NROFF AND -ME
.u under
.i italics
generates underitalics, but if we had typed:
.u under
.i italics
the result would have been under italics as two words •
.
~.z.
Point Sizes
The phototypesetter supports different sizes of
type, measured in pOints. The default pOint size is
Ie p01nts for most text, 8 points for footnotes.
To
change the pOintsize, type:
.sz +N
The vertical
wnere N is the size wanted in pOints.
spacing (distance between the bottom of most letters
(tne baseline) between adjacent lines) is set to be
proport10nal to the type size.
Warn1ng: changing pOint sizes on the phototypesetter is a slow mechanical operation.
Size
changes should be conSidered carefully.
~ . .l.
Quotes
It is conventional when using the typesetter to
use pairs of grave and acute accents to generate double quotes, rather than the double quote character
('"').
This is because it looks better to use grave
and acute accents1 for example, compare "quote" to
, 'quote' , •
In order to make quotes compatible between the
typesetter and terminals, you may use the sequences
19 andrg to stand for the left and right quote
respec~1vely.
These both appear as " on most termina~s, but are typeset as "
and "respectively.
For
example, use:
Some things aren't true
even if they did happen.
to generate the result:
"Some things aren't true even if they did happen."
As a shorthand, the special font request:
USING NROFF AND -ME
.q nquotea text"
w1ll generate nquoted text n •
Notice that you must
surround the material to be quoted with double quote
marks if it is more than one word.
B-2'1
MAIL REFERENCE MANUAL
Version 2.B
~.
Introduction
Rail provides a simple and friendly environment for
sending and receiving mail. It divides incoming mail into
its constituent messages and allows the user to deal with
them in any order. In addition, it provides a set of ~
like commands for manipulating messages and sending mail.
Hail offers the user simple editing capabilities to ease
the composition of outgoing messages, as well as providing
the ability to define and send to names which address
groups of users.
Finally, Hail is able to send and
receive messages across such networks as the ARPANET, Bell
Telephone net, Berkeley network, and COCANET.
This document describes how to use the Hail program
to send and receive messages. The reader is not assumed
to be familiar with other message handling systems, but
should be familiar with the UNIX[l] shell, the text editor, and some of the common UNIX commands. nThe UNIX
Programmer's Manual," nAn Introduction to Csh,n and nText
Editing with Ex and Vin can be consulted for more information on these topics.
[1] UNIX is a trademark of Bell Laboratories.
E-282
Mail Reference Manual
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 message 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 "EOT" and return you
to the Shell.
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.
If, while you are composing the message you decide
that you do not wish to send it after all, you can abort
the letter with a RUBOUT. Typing a single RUBOUT causes
Mail to print
(Interrupt -- one more to kill letter)
Typing a second RUBOUT causes Mail to save your partial
letter on the file "dead.letter" in your home directory
and abort the letter. Once you have in fact 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) and the date and time it was
sent.
If you want to send the same message to several other
people, you can list all of their login names on the command line. Thus,
% Mail sam bob john
Tuition fees are due next Friday.
EaT
Don't forget!!
%
will send the reminder to sam, bob, and john.
B-213
Mail Reference Manual
If, when you log in, you see the message,
You have mail.
you can read the mail by typing simply:
% Mail
Hail will respond 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. The messages are assigned numbers starting with 1 -- you refer to
the messages with these numbers.
To look at a specific message, use the ~ command,
which may be abbreviated to simply~. For example, if you
had the following messages:
1 root
2 sam
Wed Sep 21 99:21
Tue Sep 20 22:55
nTuition fees n
you could examine the first message by giving the command:
type I
which might cause Hail to respond with, for example:
Message 1:
From root Wed Sep 21 99:21:45 1978
Subject: Tuition fees
Tuition fees are due next Wednesday.
Don't forget!!
Many Hail commands which operate on messages take a message number as an argument like the ~ command. For all
of these commands, there is a notion of a current message.
When you enter the Hail program, the current message is
initially the first one. Thus, you can often omit the
message number and use, for example,
t
to type the current message. As a further shorthand, you
can type a message by simply giving its message number.
Hence,
B-214
Mail Reference Manual
1
would type the first message.
Frequently, it is useful to read the messages in your
mailbox in order, one after another. You can read the
next message in Mail by simply typing a newline.
As a
special case, you can type a newline as your very first
command to Hail to type the first message.
If, after typing a message, you wish to immediately
send a reply, you can do so with the reply command.
Reply, like ~, takes a message number as an argument.
HAil then begins a message addressed to the user who sent
you the message. You may then type in your letter in
reply, followed by a at the beginning of a
line, as before. M£il will type EOT, then type the underscore prompt to indicate its readiness to accept another
command. In our example, if, after typing the first message, you wished to reply to it, you might give the command:
reply
Mail responds by typing:
To: root
Subject: Tuition fees
and waiting for you to enter your letter.
Note that it
copies the subject header from the original message. This
is useful in that correspondence about a particular matter
will tend to retain the same subject heading, making it
easy to recognize. If there are other header fields in
the message, the information found will also be used. For
example, if the letter had a "To:" header listing a number
of recipients, Hail would arrange to send your replay to
the same people as well. Similarly, if the original message contained a "Cc:" (carbon copies to) field, Mail
would send your reply to those users, too. H£il is careful, though, not too send the message to ~, even if you
appear in the "To:" or "Cc:" field, unless you ask to
included explicitly. See section 3 for more details.
After typing in your letter, the dialogue
might look like the following:
reply
To: root
Subject: Tuition fees
E-285
with
HAil
Mail Reference Manual
Thanks for the reminder
EOT
The reply command is especially useful for sustaining
extended conversations over the message system, with other
nlistening n users receiving copies of the conversation.
The reply command can be abbreviated to ~.
If you wish, while reading your mail, to send a message to someone, but not as a reply to one of your messages, you can send the message directly with the ma.il.
command, which takes as arguments the names of the recipients you wish to send to. For example, to send a message to nfrank,n you would do:
mail frank
This is to confirm our meeting next Friday at 4.
EOT
The mail command can be abbreviated to
m.
Normally, each message you receive is saved in the
mbgx
in your login directory at the time you leave
Hail. 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 mbQx you can
delete it using the delete command. In our example,
file
delete I
will prevent Mail from saving message I (from root) in
mbQx.
In addition to not saving deleted messages, Hail
will not let you type them, either. The effect is to make
the message disappear altogether, along with its number.
The delete command can be abbreviated to simply ~.
A number of features of l:1a..U. can be tailored to your
liking with the ~ command.
The ~ command has two
forms, depending on whether you are setting a binary
option or a valued option. Binary options are either on
or off. For example, the naskn option informs Hail that
each time you send a message, you want it to prompt you
for a subject header, to be included in the message.
To
set the "askn option, you would type
set ask
B-286
Mail Reference Manual
Valued options are values which Hail uses to adapt to
your tastes.
For example, the "SHELL" option tells Hail
which shell you like to use, and is specified by
set SHELL=/bin/csh
for example.
Note that no
"SHELL=/bin/csh." A complete
appears in section 4.
spaces are
allowed
in
list of the Hail options
Another adaptation to user needs that H.a.il provides
is that of aliases.
An alias is simply a name which
stands for one or more real user names. H.a.il sent to an
alias is actually sent to the list of real users associated with it. For example, an alias can be defined for
the members of a project, so that you can send mail to the
whole project by sending mail to just a single name.
The
alias command in Mail is used to define an alias. Suppose
that the users in a project are named Sam, Sally, Steve,
and Susan. To define an alias called "project" for them,
you would use the Hail command:
alias project sam sally steve susan
The alias comman-d can also be used to provide a convenient
name for someone whose user name is inconvenient. For
example, if a user named nBob Anderson n had the login name
nanderson,"n you might want to use:
alias bob anderson
so that you could send mail to the shorter name, nbob."
While the alias and ~ commands allow you to customize Mail, they have the drawback that they must be retyped
each time you enter Hail. To make them more convenient to
use, Mail always looks for two files when it is invoked.
It first reads a system wide file "/usr/lib/Mail.rc," then
a user specific file, ".mailrc," which is found in the
user's home directory. The system wide file is maintained
by the system administrator and is usually used to define
aliases that are of general interest, such as the list of
users which constitutes the system staff. The ".mailrc"
file is usually used by each user to set options the way
he likes. For example, my .mailrc file looks like this:
set ask nosave SHELL=/bin/csh
E-287
Mail Reference Manual
As you can see, it is possible to set many options in the
same ~ command.
The "nosave" option is described in
section 4.
We have seen that Hail can be invoked with command
line arguments which are people to send the message to, or
with no arguments to read mail. In addition, there are
two flag arguments to Hail which are useful. First,
unreliable'terminal connections (such as poor connections
over a phone line) cause spurious RUBOUT characters to be
produced. RUBOUT characters cause Hail to terminate a
message, as described previously. To prevent these spurious RUBOUT characters from causing trouble, you can give
the -i flag to ignore them. For example,
% Mail -i
reads your mail with RUBOUT characters ignored, and
% Mail -i bob joe sarah
mails to the named people with RUBOUT characters ignored.
Unfortunately, even if Hail ignores RUBOUT's, the system
discards all text typed on the current line when it
receives a
RUBOUT. To warn the user that this has happened, Hail echoes RUBOUTs as @'s. If, when using -i an @
at appears on your terminal, you must retype the text on
the line you were typing. If the @ appears at the beginning of a line, you can safely ignore it.
The other Hail flag is -f which allows you to use
Hail to examine a file of messages other than your default
system mailbox. For example, if you have a collection of
messages in the file "letters" you can use Mail. to read
them with:
% Mail -f letters
You can use all of the Mail. commands described in this
document to examine, modify, or delete messages from your
"letters" file, which will be rewritten when you leave
MAil with the suit command described below.
Since mail that you read is saved in the file mbQx in
your home directory by default, you can read mbQx in your
home directory by using simply
% Mail -f
E-288
Mail Reference Manual
Normally, messages which you examine using the ~
command are saved in the file nmboxn in your home directory if you leave Mail with the ~ command described
below.
If you wish to retain a message in your system
mailbox you can use the preserve command to tell Mail to
leave it there.
The preserve command accepts a list of
message numbers, just like ~ and may be abbreviated to
~.
Messages in your system mailbox which you do not
examine are normally retained in your system mailbox
automatically. If you wish to have such a message saved
in mbQ& without actually reading it, you may use the mbQ&
command to have them so saved. For example,
mbox 2
in our example would cause the second message (from sam)
to be saved in mbQ& when the ~ command is executed.
MbQx can be abbreviated to mQ.
When you have perused all of the messages
of
interest, you can leave Mail with the ~ command, which
saves all of the messages you have typed but not deleted
in the file mbQ& in your login directory. Deleted messages are discarded irretrievably, and messages left
untouched are preserved in your system mailbox so that you
will see them the next time you type:
% Mail
The
~
command can be abbreviated to simply
~.
If you wish for some reason to leave Mail quickly
without altering either your system mailbox or ml2.Q.x., you
can type the X command (short for ~), which will
immediately return you to the Shell without changing anything.
If, instead, you want to execute a Shell command
without leaving Mail, you can type the command preceded by
an exclamation point, just as in the text editor.
Thus,
for instance:
!date
will print the current date without leaving Hail.
Finally, the ~ command is available to print out a
brief summary of the MAil commands, using only the single
character command abbreviations.
£-2'9
Mail Reference Manual
1.
~
1.~.
about sending mail
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 • .M.a..i..l
provides these capabilities through tilde escapes, which
consist of a tilde (-) at the beginning of a line, followed by a single character which indicates the function
to be performed. For example, to print the text of the
message so far, use:
which will print a line of dashes, the recipients of
your message, and the text of the message so far. Since
Mail requires two consecutive RUBOUT's to abort a
letter, you can use a single RUBOUT to abort the output
of -p or any other - escape without killing your letter.
If you are dissatisfied with the message as it
stands, you can invoke the text editor on it using the
escape
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 • .M.a..i..l will respond by typing
(continue)
after which you may continue typing text which will be
appended to your message, or type to end the
message. A standard text editor is provided by Mail.
You can override this default by setting the valued
option "EDITOR n to something else.
For example, you
might prefer:
set EDITOR=/usr/ucb/ex
Many systems offer a screen editor as an alternative to the standard text editor, such as the Yi editor
from UC Berkeley. In order to use the screen, or visual
editor, on your current message, you can use the -v
escape, which works like -e, except that the screen
E-2l"
Mail Reference Manual
editor is invoked instead. A default screen editor is
defined by Hail. If it does not suit you, you can set
the valued option "VISUAL n to the path name of a different editor.
It is often useful to be able to include the
tents of some file in your message: the escape
con-
-r filename
is provided for this purpose, and causes the named file
to be appended to your current message. Hail 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. The filename may contain shell
metacharacters like * and? which are expanded according to the conventions of your shell.
As a special case of -r, the escape
- directory.
reads in the file "dead. letter" in your home
This is often useful since Hail copies the text of your
message there when you abort a message with RUBOUT.
In order to save the current text of
on a file you may use the
your
message
-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. Shell metacharacters may be used in the filename, as in -r and are
expanded with the conventions of your shell.
If you are sending mail from within Hail1a command
mode you can read a message sent to you into the message
you are constructing with the escape:
-m 4
which will read message 4 into the current message,
shifted right by one tab stop. You can name any nondeleted message, or list of messages. This is the usual
way to forward a message.
B-211
Mail Reference Manual
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 namel name2 •••
You may name as few or many additional recipients as you
wish.
Note that the users originally 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
message by using the escape
your
-s Arbitrary string of text
which replaces any previous subject with "Arbitrary
string of text." The subject, if given, is sent near the
top of the message prefixed with "Subject: n You can see
what the message will look like by using -p.
For political reasons, one occasionally prefers to
list certain people as recipients of carbon copies of a
message rather than direct recipients. The escape
-c namel name2 •••
adds the named people to the nCc: n list, similar to -t.
Again, you can execute -p to see what the message will
look like.
The recipients of the message together constitute
the "To:" field, the subject the "Subject: n field, and
the carbon copies the nCc: n field. If you wish to edit
these in ways impossible with the -t, -s, and-c
escapes, you can use the escape
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 characters, 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 kill character
to erase them altogether. Thus, for example, if your
erase and kill characters are the standard I and @ symbols,
£-212
Mail Reference Manual
-h
To: root kurt****bill
would change the initial recipients nroot kurt n to nroot
bill." When you type a newline, Hail advances to the
nSubject:n field, where the same rules apply.
Another
newline brings you to the "ec: n field, which may be
edited in the same fashion. Another newline leaves you
appending text to the end of your message. ~ou can use
-p to print the current text of the header fields and
the body of the message.
To effect a temporary
escape
escape
to
the
shell,
the
-!command
is used, which executes 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 shell command, then you can use
-Icommand
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 is the command Lmt which is
designed to format outgoing mail.
To effect a temporary escape to Mail
instead, you can use the
command
mode
-:Hail command
escape. This is especially useful for retyping the message you are replying to, using, for example:
It is also useful
aliases.
for
setting
options
and
modifying
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,
B-213
Mail Reference Manual
--This line begins with a tilde.
sends the line
-This line begins with a tilde.
Finally, the escape
prints out
escapes.
a
brief
summary
of
the
availa.ble
tilde
On some terminals (particularly ones with no lower
case) tilde's are difficult to type. Hail allows you to
change the escape character with the nescape" option.
For example, I set
set escape=]
and use
need to
ble it,
removes
~.2.
a right bracket instead of a tilde. If I ever
send a line beginning with right bracket, I doujust as for -. Changing the escape character
the special meaning of -.
Network access
The header capabilities described in the previous
section are useful for communicating with users on other
networks. This section describes other aspects of sending mail across networks.
Network names are distinguished from local names
using the naming conventions of each network. One
effect of this is that the name "at" can never be a
local name, because the recipient
kurt at Berkeley
is a single ARPANET address, not three local names.
When you use the reply command to respond to a
letter, there is a problem of figuring out the names of
the users in the "To:" and nCc:" lists r.elatiye .t.Q .t.he.
current machine. If the original letter was sent to you
by someone on the local machine, then this problem does
not exist, but if the message carne from a remote
machine, the problem must be dealt with.
Hail uses a
8-214
Mail Reference Manual
heuristic to construct the correct name for each user
relative to the local machine. For this reason, when
you reply to remote mail, the names in the "To:" and
"Cc:" lists may change somewhat.
~.~.
Special recipients
As described previously, you can send mail to
either user names or alias names. It is also possible
to send messages directly to files or to programs, using
special conventions.
If a recipient name has a 'I' in
it, it is assumed to be the path name of a file into
which to send the message. If the file already exists,
the message is appended to the end of the file.
If you
want to name a file in your current directory (ie, one
for which a '/' would not usually be needed) you can
precede the name with './' So, to send mail to the file
"memo" in the current directory, you can give the command:
% Mail ./memo
This ability to send mail to files can be used for a
variety of purposes, such as maintaining a journal and
keeping a record of mail sent to a certain group of
users.
The second example can be done automatically by
including the full pathname of the record file in the
alias command for the group_ Using our previous alias
example, you might give the command:
alias project sam sally steve susan lusr/project/mail_record
Then, all mail sent to "project" would be saved on the
file "/usr/project/mail_record" as well as being sent to
the members of the project. This file can be examined
using Mail -L.
It is sometimes useful to send mail directly to a
program, for example one might write a project billboard
program and want to access it using Hail. In order to
send messages to the billboard program, one can send
mail to the special name 'Ibillboard' for example. Hail
treats recipient names which begin with a 'I' as a program to send the mail to. An alias can be set up to
reference a ' I' prefaced name if desired. Caveats: the
shell treats 'I' specially, so it must be quoted on the
command line.
Also, the 'I program' must be presented
as a single argument to mail. The safest course is to
surround the entire name with double quotes. This also
applies to usage in the alias command. For example, if
we wanted to alias 'rmsgs' to 'rmsgs -s' we would need
E-215
Mail Reference Manual
to say:
alias rmsgs "I rmsgs -so
E-216
Mail Reference Manual
~.
Additional features
This section describes some additional commands of use for
reading your mail, setting options, and handling lists of messages.
i.~.
Additional commands
This section describes additional Hail commands
available when receiving mail.
The ~ command goes to the next message and
types it. If given a message list, ~ goes to the
first such message and types it. Thus,
next root
goes to the next message sent by "root" and types
it. The ~ command can be abbreviated to simply a
newline, which means that one can go to and type a
message by simply giving its message number or one
of the magic characters "T" "." or "$". Thus,
•
prints the current message and
4
prints message 4, as described previously.
The - command goes to the previous message and
prints it.
The
command may be given a decimal
number n as an argument, in which case the nth previous message is gone to and printed.
It is often useful to be able to save messages
on related topics in a file. The ~ command gives
you ability to do this. The ~ command takes as
argument a lit of message numbers, followed by the
name of the file on which to save the messages. The
messages are appended to the named file, thus allowing one to keep several messages in the file, stored
in the order they were put there. The ~ command
can be abbreviated to~. An example of the ~
command relative to our running example is:
s 1 2 tuitionmail
£-211
Mail Reference Manual
Sayed messages are not automatically saved in mb.Q.x.'
at quit time, nor are they selected by the ~com
mand described above, unless explicitly specified.
The ~ command always writes the entire message, including the headers, into the file. If you
want to write just the message itself, you can use
the write command. The write command has the same
syntax as the ~ command, and can be abbreviated
to simply ~. Thus, we could write the second message by doing:
w 2 file.c
As suggested by this example, the write command is
useful for such tasks as sending and receiving
source program text over the message system.
The undelete command causes a message which had
been
deleted previously to regain its initial
status. Only messages which are already deleted may
be undeleted. This command may be abbreviated to ~.
In order to edit individual messages using the
text editor, the ~ command is provided. The ~
command takes a list of message as described under
the ~ command and processes each by writing it
into the file Messagex where X is the message number
being edited and executing the text editor on it.
When you have edited the message to your satisfaction, write the message out and quit, upon which
MAil will read the message back and remove the file.
~ may be abbreviated to ~.
It is often useful to be able to invoke one of
two editors, based on the type of terminal one is
using. To invoke a display oriented editor, you can
use the visual command. The operation of the visual
command is otherwise identical to that of the .e.d.it
command.
Both the ~ and visual commands assume some
default text editors. These default editors can be
overriden by the valued options nEDITOR n and nVISUAL n for the standard and screen editors. You might
want to do:
set EDITOR=/usr/ucb/ex VISUAL=/usr/ucb/vi
Thechdir and shell commands allow you to
change your current directory and escape to the
shell, respectively. .Chdir takes a single argument,
B-218
Mail Reference Manual
which is taken to be the pathname of the directory
to change to.
If no argument is given, chdir
changes to your home directory. Shell invokes an
interactive shell and allows you to type commands to
it.
When you leave the shell, you will return to
Mail. The shell used is a default assumed by Hail;
you can override this default by setting the valued
option "SHELL," eg:
set SHELL=/bin/csh
When you start up Mail to read your mail, it
lists the message headers that you have. These
headers tell you who each message is from, when they
were sent, how many lines and characters each message is, and the "Subject:" header field of each
message, if present.
In addition, Hail tags the
message header of each message which has been the
object of the preserve command with a "P." Messages
which have been sayed or written are flagged with a
"*." Finally, deleted messages are not printed at
all. If you wish to reprint the current list of
message headers, you can do so with the headers command. The headers command (and thus the initial
header listing) only lists the first 18 message
headers. Hail maintains a notion of the current
"window" into your messages for the purposes of
printing headers. You can move Hail'~ attention
forward to the next window by giving the
headers +
command. Analogously, you can move to the
window with:
previous
headers Finally, you can move MAilI~ notion of the current
window directly to a particular message by using,
for example,
headers 40
to move Maill~ attention to the messages around message 40. The headers command can be abbreviated to
h.
The !LQm command takes a list of messages
prints out the header lines for each one; hence
E-219
and
Mail Reference Manual
from joe
is the easy way to display all the
from "joe."
message
headers
The ~ command takes a message list and prints
the first five lines of each addressed message. It
may be abbreviated to tQ.
If you wish, you can
change the number of lines that ~ prints out by
setting the valued option "toplines." On a CRT terminal,
set toplines=19
might be preferred.
The ~ command deletes the current message and
prints the next message. It is useful for quickly
reading and disposing of mail.
~.~.
Message l1sts
The ~ and delete commands described in section two take a list of messages as argument, as do
many of the commands described in section six. This
section describes the construction of message lists
in general.
A message liat 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 "T" "." or "$" to specify the
first relevant, current, or last relevant message,
respectively. Releyant 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
sage to the last message, use
type .-$
£-221
mes-
Mail Reference Manual
A ~ 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
Thus,
type
get
every
relevant
(same sense) message.
*
prints all undeleted messages,
delete
*
deletes all undeleted messages, and
undelete
*
undeletes all deleted messages.
~.~.
Other options
Throughout this manual, we have seen examples
of
binary
and
valued options.
This section
describes each of the options in alphabetical order,
including some which you have not seen yet. To
avoid confusion, please note that all of the options
are either all lower case letters or all upper case
letters. When I start a sentence such as: "Ask n
causes Hail to prompt you for a subject header, I am
only capitalizing "ask" as a courtesy to English.
The "append" option is binary and causes messages saved in mb2X to be appended to the end rather
than prepended. Normally, Hailwill mb2X in the same
order that the system puts messages in your system
mailbox. By setting "append,n you are requesting
that mbQx be appended to regardless. It is in any
event quicker to append.
B-221
Mail Reference Manual
"Ask" is a binary option which causes Hail to
prompt you for the subject of each message you send.
If you respond with simply a newline, no subject
field will be sent.
"Askcc" is a binary option which causes you to
be prompted for additional carbon copy recipients at
the end of each message. Responding with a newline
indicates your satisfaction with the current list.
"Autoprint" is a binary option which causes the
delete command to behave like ~ -- thus, after
deleting a message, the next one will be typed automatically. This is useful to quickly scanning and
deleting messages in your mailbox.
The binary option "ignore" causes RUBOUT characters from your terminal to be ignored and echoed
as @'s while you are sending mail.
RUBOUT characters retain their original meaning in .M.ail command
mode.
When sending mail to an alias, Hail makes sure
that if you are included in the alias, that mail
will not be sent to you. This is useful if a single
alias is being used by all members of the group. If
however, you wish to receive a copy of all the messages you send to the alias, you can set the binary
option "metoo."
The binary option "quiet" suppresses the printing of the version when Hail is first invoked, as
well as printing the for example "Message 4:" from
the ~ command.
Normally, when you abort a message with two RUBOUTs, Mail copies the partial letter to the file
"dead. letter" in your home directory.
Setting the
binary option "nosave" prevents this.
The valued option "EDITOR" defines the pathname
of the text editor to be used in the ~ command
and -e. If not defined, a standard editor is used.
The valued option "SHELL" gives the path
of your shell. This shell is used for the 1
mand and -1 escape. In addition, this shell is
to expand file names with shell metacharacters
* and ? in them.
name
comused
like
The valued option "VISUAL" defines the pathname
of your screen editor for use in the visual command
and -v escape. A standard screen editor is used if
£-222
Mail Reference Manual
you do not define one.
In order to allow you to change the escape
character used when sending mail, you can set the
valued option ftescape. n Only the first character of
the nescape n option is used, and it must be doubled
if it is to appear literally as the first character
of a line of your message. If you change your escape character, then - loses all its special meaning, and need no longer be doubled at the beginning
of a line.
If you love to keep records, then the valued
option nrecordft can be set to the name of a file to
save all of your outgoing mail.
Each new message
you send is appended to the end of the file.
The valued option fttoplines n defines the number
of lines that the fttopn command will print out instead of the default five lines.
B-223
Mail Reference Manual
.5..
Summary.Q.f. commands, options, ..arul escapes
This section gives a quick summary of all of the
commands, binary and valued options, and tilde
escapes. The following table describes the commands:
Mail
Command
Description
8 ________________________________________________________________
___
1
alias
chdir
delete
dt
edit
exit
from
headers
help
mail
mbox
next
preserve
quit
reply
save
set
shell
top
type
undelete
unset
visual
write
Single command escape to shell
Back up to previous message
Define an alias as a set of user names
Change working directory, home by default
Delete a list of messages
Delete current message, type next message
Edit a list of messages
Leave mail without changing anything
List headers of a list of messages
List current window of messages
Print brief summary of .Mail. commands
Send mail to specified names
Arrange to save a list of messages in mbQx
Go to next message and type it
Arrange to leave list of messages in system mailbox
Leave .Mail.; update system mailbox, mbQx as appropriate
Compose a reply to a message
Append messages, headers included, on a file
Set binary or valued options
Invoke an interactive shell
Print first so many (5 by default) lines of list of mes:
Print messages
Undelete list of messages
Undo the operation of a set
Invoke visual editor on a list of messages
Append messages to a file, don't include headers
The following table describes the options. Each option is indicated as being either a binary or valued option.
£-224
Mail Reference Manual
Option
Description
8______________________________________________________________________
__
EDITOR
SHELL
VISUAL
append
ask
askcc
autoprint
escape
ignore
metoo
nosave
quiet
record
toplines
valued
valued
valued
binary
binary
binary
binary
valued
binary
binary
binary
binary
valued
valued
Pathname of editor for -e and edit
Pathname of shell for shell, -1 and!
Pathname of screen editor for -v, visual
Always append messages to end of mbgx
Prompt user for Subject: field when sending
Prompt user for additional ec's at end of message
Print next message after delete
Escape character to be used instead of Ignore RUBOUT while sending mail
Include sending user in aliases
Don't save partial letter in ~.letter
Suppress printing of ~ version
File to save all outgoing mail in
Number of lines to print in top
Finally, the following table summarizes the tilde
escapes available while sending mail.
Escape
Arguments
Description
8
command
.na.m.e. •••
messages
filename
string
.na.m.e. •••
filename
command
string
Execute shell command
Add names to Cc: field
Read ~.letter into message
Invoke text editor on partial message
Edit the header fields
Read named messages, right shift by tab
Print message entered so far
Abort entry of letter; like RUBOUT
Read file into message
Set Subject: field to string
Add names to To: field
Invoke screen editor on message
Write message on file
Pipe message through command
Quote a - in front of string
B-225
Mail Reference Manual
.[.
Conclusion
HAil is an attempt to provide a simple user interface
to a variety of underlying message systems. Thanks are
due to the many users who contributed ideas and testing to
HAil.
8-226
Screen Updating and Cursor Movement Optimization:
A Library Package
ABSTRACT
This document describes a package
functions which allow the user to:
of
C
library
1)
update a screen with reasonable optimization,
2)
get input from the terminal
fashion, and
3)
independent from the above, move the
timally from one point to another.
in
a
screen-oriented
cursor
op-
These routines all use the /~termcap database to
describe the capabilities of the terminal.
E-227
Contents
1 Overview • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
1.1 Terminology (or, Words You Can Say to Sound
Brilliant) • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
1.2 Compiling Things • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
1.3 Screen Updating • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
1.4 Naming Conventions • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
2 Variables •••••••••••••••••••••••••••••••••••••••••••••
3 Usage • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
3.1 Starting up • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
3.2 The Nitty-Gritty • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
3.2.1 Output
3.2.2 Input • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
3.2.3 Miscellaneous • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
3.3 Finishing up
... 4 Cursor Motion Optimization: Standing Alone ."
4.1 Terminal Information • • • • • • • • • • • • • • • • • • • • • • • • • • •
4.2 Movement Optimizations, or, Getting Over
Yonder • • • • • • • • • • • • • • • • • • • • • • • • • - • • • • • • e.- • • • • • • • • • • •
5 The Functions • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
5.1 Output Functions
5.2 Input Functions • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
5.3 Miscellaneous Functions • • • • • • • • • • • • • • • • • • • • • • • •
5.4 Details • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
... ................................
~
. ........
......
.........................•
·..............-...............
Appendixes
Appendix A • • • • • • • • • • • • • • • • • • • • • • • • • • • • •• • • • • • • • • • • • • • • •
1 Capabilities from termcap • • • • • • • • • • • • • • • • • • • • • • • • • • •
1.1 Disclaimer • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
1.2 Overview • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
1.3 Variables Set By setterm () • • • • • • • • • • • • • • • • • • • • •
1.4 Variables Set By gettmode() • • • • • • • • • • • • • • • • • • • •
Appendix .a • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
1 The WINDOW structure • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
Appendix .c • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
1 Examples • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
2 Screen Updating • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
2.1 Twinkle • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
2.2 Life • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
3 Motion optimization • • • • • • • • • • • • • • • • • • • • • • • • • • • •• • • • •
3.1 Twinkle • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •
8-228
1
1
1
2
2
3
4
4
5
5
5
5
6
6
6
7
8
8
13
14
18
Screen Package
1.
Overview
In making available the generalized terminal descriptions in /~termcap, much information was made available
to the programmer, but little work was taken out of one's
hands.
The purpose of this package is to allow the C programmer to do the most common type of terminal dependent
functions, those of movement optimization and optimal screen
updating, without doing any of the dirty work, and (hopefully) with nearly as much ease as is necessary to simply print
or read things.
The package is split into three parts: (1) Screen updating; (2) Screen updating with user input; and (3) Cursor
motion optimization.
It is possible to use the motion optimization without
using either of the other two, and screen updating and input
can be done without any programmer knowledge of the motion
optimization, or indeed the database itself.
~.~.
Terminology
(~,
Words XQy
~
SAy
tQ
Sound
Brilli-
.an.:I;.)
In this document, the following terminology is kept
with reasonable consistency:
to
window: An internal representation containing an image of
what a section of the terminal screen may look like at
some point in time. This subsection can either encompass the entire terminal screen, or any smaller portion
down to a single character within that screen.
terminal: Sometimes called terminal screen.
The package's
idea of what the terminal's screen currently looks
like, i.e., what the user sees now. This is a special
screen:
screen: This is a subset of windows which are as large as
the terminal screen, i.e., they start at the upper left
hand corner and encompass the lower right hand corner.
One of these, stdscr, is automatically provided for the
programmer.
l.Z.
Compiling Things
In order to use the library, it is
certain types and variables defined.
grammer must have a line:
#include
at
the
top
necessary to have
Therefore, the pro-
of
the
program
£-229
source.
The
header
file
Screen Package
needs to include , so the one should not
do so oneself[l]. Also, compilations should have the following form:
.QQ [
~.~.
flags J file ••• -lcurses -ltermlib
Screen Updating
In order to update the screen optimally, it is necessary for the routines to know what the screen currently
looks like and what the programmer wants it to look like
next.
For this purpose, a data type (structure) named lUB=.
UQN is defined 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 curscr for current screen) is a
screen image of what the terminal currently looks like.
Another screen (called stdscr, for standard screen) is provided by default to make changes on.
A window is a purely internal representation.
It
used to build and store a potential image of a portion
the terminal. It doesn't bear any necessary relation
what is really on the terminal screen. It is more like
array of characters on which to make changes.
is
of
to
an
When one has a window which describes what some part
the terminal should look like, the routine refresh () (or
wrefresh() if the window is not stdscr) is called.
~
fresh() makes the terminal, in the area covered by the window, look like that window. Note, therefore, that changing
something on a window ~ nQt change ~ terminal. Actual
updates to the terminal screen are made only by calling ~
fresh() or wrefresh(). This allows the programmer to maintain several different ideas of what a portion of the terminal screen should look like. Also, changes can be made to
windows in any order, without regard to motion efficiency.
Then, at will, the programmer can effectively say nmake it
look like this,n and let the package worry about the best
way to do this.
~.~.
Naming Conventions
As hinted above, the routines can use several windows,
but two are automatically given: curscr, which knows what
the terminal looks like, and stdscr, which is what the programmer wants the terminal to look like next. The user
[lJ The screen package also uses the Standard I/O library, so includes . It is redundant
(but harmless) for the programmer to do it, too.
B-238
Screen Package
should never really access curscr directly. Changes should
be made to the appropriate screen, and then the routine ~
fresh() (or wrefresh(» should be called.
Many functions are set up to deal with stdscr as a default screen.
For example, to add a character to stdscr,
one calls addch() with the desired character.
If a different window is to be used, the routine waddch() (for
~indow-specific addch(»
is provided[2]. This convention of
prepending function names with a n~n when they are to be applied to specific windows is consistent. The only routines
which do nQt do this are those to which a window must always
be specified.
In order to move the current (y, x) co-ordinates from
one point to another, the routines ~() and wmoye() are
provided. However, it is often desirable to first move and
then perform some I/O operation. In order to avoid clumsyness, most I/O routines can be preceded by the prefix "mx"
and the desired (y, x) co-ordinates then can be added to the
arguments to the function. For example, the calls
move(y, X)1
addch(ch) 1
can be replaced by
mvaddch(y, x, ch);
and
wmove(win, y, x) 1
waddch(win, ch);
can be replaced by
mvwaddch(win, y, x, ch);
Note that the window description pointer (~) comes before
the added (y, x) co-ordinates. If such pointers are need,
they are always the first parameters passed.
~.
Variables
Many variables which are used to describe the terminal
environment are available to the programmer. They are:
type
name
WINDOW* curscr
WINDOW* stdscr
char*
boo I
char*
int
int
description
current version of the screen (terminal screen).
standard screen. Most updates are usually done
here.
Def_term default terminal type if type cannot be determine
My_term use the terminal specification in Def term as terminal, irrelevant of real terminal type
ttytype full name of the current terminal.
LINES
number of lines on the terminal
COLS
number of columns on the terminal
E-231
Screen Package
ERR
OK
int
int
error flag returned by routines on a fail.
error flag returned by routines when thiI
right.
There are also several "#define"
which are of general usefulness:
and
types
storage class "register" (e.g., ~ int i;)
boolean t¥pe, actually a "char" (e.g., ~
boolean' true" flag (1).
boolean "false" flag (0).
reg
boo 1
TRUE
FALSE
.1.
constants
~
Usage
This is a description of how to actually use the screen
package.
In it, we assume all updating, reading, etc. is
applied to stdscr. All instructions will work on any window, with changing the function name and parameters as mentioned above.
J..~.
Starting
~
In order to use the screen package, the routines must
know about terminal characteristics, and the space for
curscr and stdscr must be allocated.
These functions are
performed by initscr().
Since it must allocate space for
the windows, it can overflow core when attempting to do so.
On this rather rare occasion, initscr() returns ERR. in=
itscr() must always be called before any of the routines
which affect windows are used. If it is not, the program
will core dump as soon as either curscr or stdscr are referenced. However, it is usually best to wait to call it until
after you are sure you will need it, like after checking for
startup errors. Terminal status changing routines like nl()
and crmode() should be called after initscr().
Now that the screen windows have been allocated, you
can set them up for the run. If you want to, say, allow the
window to scroll, use scrollok (). If you want the cursor to
be left after the last change, use leayeok(). If this isn't
done, refresh() 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 newwin() and
subwin() •
delwin() will allow you to get rid of old windows. If you wish to change the official size of the terminal by hand, just set the variables LINES and m.I.uS. to be
what you want, and then call initscr(). This is best done
before, but can be done either before or after, the first
call to initscr(), as it will always delete any existing
stdscr and/or curscr before creating new ones.
E-232
Screen Package
~.2.
~
~ • .2..~.
Nitty-Gritty
Output
Now that we have set things up, we will want to actually update the terminal. The basic functions used to change
what will go on a window are addch()
and ~().
addch()
adds a character at the current (y, x) co-ordinates, returning ERR if it would cause the window to illegally scroll,
i.e., printing a character in the lower right-hand corner of
a terminal which automatically scrolls if scrolling is not
allowed.
~() changes the current (y, x) co-ordinates to
whatever you want them to be. It returns ERR if you try to
move off the window when scrolling is not allowed. As mentioned above, you can combine the two into myaddch()
to -do
both things in one fell swoop.
The other output functions, such as addstr()
and
printw(), all call addch() to add characters to the window.
After you have put on the window what you want there,
when you want the portion of the terminal covered by the
window to be made to look like it, you must call refresh().
In order to optimize finding changes, refresh() assumes that
any part of the window not changed since the last refresh()
of that window has not been changed on the terminal, i.e.,
that you have not refreshed a portion of the terminal with
an overlapping window. If this is not the case, the routine
touchwin() is provided to make it look like the entire window has been changed, thus making refresh() check the whole
subsection of the terminal for changes.
If
screen
ful for
in case
you call wrefresh() with curscr, it will make the
look like curscr thinks it looks like. This is useimplementing a command which would redraw the screen
it get messed up.
~.2.2..
Input
Input is essentially a mirror image of output.
The
complementary function to addch() is getch() which, if echo
is set, will call addch() to echo the character. Since the
screen package needs to know what is on the terminal at all
times, if characters are to be echoed, the tty must be in
raw or cbreak mode.
If it is not, getch() sets it to be
cbreak, and then reads in the character.
~ • .2..~.
Miscellaneous
All sorts of fun functions exists for maintaining and
changing information about the windows. For the most part,
the descriptions in section 5.4. should suffice.
E-233
Screen Package
~.~.
Finishing YR
In order to do certain optimizations, and, on some terminals, to work at all, some things must be done before the
screen routines start up. These functions are performed in
getttmode() and setterm(), which are called by initscr().
In order to clean up after the routines, the routine
endwin() is provided.
It restores tty modes to what they
were when initscr() was first called. Thus, anytime after
the call to initscr, endwin() should be called before exiting.
~.
Cutsor Motion Optimization: Standing Alone
It is possible to use the cursor optimization functions
of this screen package without the overhead and additional
size of the screen updating functions. The screen updating
functions are designed for uses where parts of the screen
are changed, but the overall image remains the same.
This
includes such programs as ~ and ~[3]. Certain other programs will find it difficult to use these functions in this
manner without considerable unnecessary program overhead.
For such applications, such as some "~hacks"[4] and optimizing ~(l)-type programs, all that is needed is the motion optimizations. This, therefore, is a description of
what some of what goes on at the lower levels of this screen
package. The descriptions assume a certain amount of familiarity with programming problems and some finer points of
C. None of it is terribly difficult, but you should be
forewarned.
~.~.
Terminal Infotmation
In order to use a terminal's features to the best of a
program's abilities, it must first know what they are[S].
The /~termcap database describes these, but a certain
amount of decoding is necessary, and there are, of course,
both efficient and inefficient ways of reading them in. The
algorithm that the uses is taken from ~ and is hideously
efficient.
It reads them in a tight loop into a set of
variables whose names are two uppercase letters with some
mnemonic value. For example, .H.Q is a string which moves the
[2] Actually, addch() is really a "#define" macro with
arguments, as are most of the "functions" which deal with
stdsct as a default.
[3] ~ actually uses these functions, ~ does not.
[4] Graphics programs designed to run on characteroriented terminals. I could name many, but they come and
go, so the list would be quickly out of date. Recently,
there have been programs such astocket and .9.Wl.
E-234
Screen Package
cursor to the "horne" position[61. As there are two types of
variables involving ttys, there are two routines. The
first, gettmode(), sets some variables based upon the tty
modes accessed by ~(2) and ~(2) The second, setterm(),
a larger task by reading in the descriptions from the
/~termcap
database.
This is the way these routines are
used by initscr():
.if (isatty(0)} {
gettmode () ;
.if (sp=getenv{"TERM"»
setterm(sp} ;
}
.e.J..ae
setterm{Def_term) ;
_puts (TI) ;
_puts (VS) ;
isatty() checks to see if file descriptor 0 is a terminal[8]. If it is, gettmode() sets the terminal description'
modes from a ~(2) geteny() is then called to get the name
of the terminal, and that value (if there is one) is passed
to setterm(}, which reads in the variables from /~termcap
associated with that terminal.
(geteny() returns a pointer
to a string containing the name of the terminal, which we
save in the character pointer ~.)
If isatty()
returns
false, the default terminal Def term is used. The.n and .ys
sequences initialize the terminal ( puts() is a macro which
uses tputs{}
(see termcap(3)} to put out a string). It is
these things which endwin() undoes.
~.z.
Moyement Optimizations,
~,
Getting
~
Yonder
Now that we have all this useful information, it would
be nice to do something with it[91.
The most difficult
[5] If this comes as any surprise to you, there's this
tower in Paris they're thinking of junking that I can let
you have for a song.
[7] These names are identical to those variables used in
the /~termcap database to describe each capability. See
Appendix A for a complete list of those read, and termcap(5)
for a full description.
[8] isatty() is defined in the default C library function
routines. It does a ~(2) on the descriptor and checks
the return value.
[9] Actually, it ~ be emotionally fulfilling just to
get the information. This is usually only true, however, if
you have the social life of a kumquat.
£-235
Screen Package
thing to do properly is motion optimization. When you consider how many different features various terminals have
(tabs, backtabs, non-destructive space, home sequences, absolute tabs, ••••• ) you can see that deciding how to get
from here to there can be a decidedly non-trivial task. The
editor ~ uses many of these features, and the routines it
uses to do this take up many pages of code. Fortunately, I
was able to liberate them with the author's permission, and
use them here.
After using gettmode() and setterm() to get the terminal descriptions, the function mvcur() deals with this task.
It usage is simple: you simply tell it where you are now and
where you want to go. For example
mvcur(O, 0, LINES/2, COLS/2)
would move the cursor from the home position (0, 0) to the
middle of the screen.
If you wish to force absolute addressing, you can use the function tgoto() from the termlih(7) routines, or you can tell mvcur() that you are impossibly far away, like Cleveland. For example, to absolutely
address the lower left hand corner of the screen from anywhere just claim that you are in the upper right hand
corner:
mvcur(O, COLS-I, LINES-I, 0)
~.
~
Functions
In the following definitions, "[*]" means that the
"function" is really a "idefine" macro with arguments. This
means that it will not show up in stack traces in the debugger, or, in the case of such functions as addch(), it
will show up as it's "li" counterpart.
The arguments are
given to show the order and type of each. Their names are
not mandatory, just suggestive.
~.~.
Output Functions
addch(~)
char
[*]
ch;
waddch(ldn, ~)
WINDOW
*ldn.;
~
~;
Add the character ~ on the window. at the current
(y, x) co-ordinates.
If the character is a newline
8-236
Screen Package
(18) the line will be cleared to
the end, and the
current (y, x) co-ordinates will be changed to the beginning off the next line if newline mapping is on, or
to the next line at the same x co-ordinate if it is
off. A return (II) will move to the beginning of the
line on the window. Tabs (II) will be expanded into
spaces in the normal tabstop positions of every eight
characters.
This returns ERR if it would cause the
screen to scroll illegally.
[*]
addstr{~)
~
*~;
waddstr(~, ~)
*~;
WINDOW
~
*~;
Add the string pOinted to by ~ on the window at the
current (y, x) co-ordinates.
This returns ERR if it
would cause the screen to scroll illegally.
In this
case, it will put on as much as it can.
hQx (~, n..tl., hQI.)
WINDOW
*ld.n.;
~
~,
hQI.;
Draws a box around the window using ~ as the character for drawing the vertical sides, and hQI. 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 left blank to avoid a
scroll.
clear() [*]
wclear(~)
WINnOW
*~;
Resets the entire window to blanks.
If ld.n. is a
screen, this sets the clear flag, which will cause a
clear-screen sequence to be sent on the next refresh()
call.
This also moves the current (y, x) co-ordinates
to (8, 8).
clearok(~,
boolf) [*]
B-237
Screen Package
WINDOW
.b..w2.l
*~;
boolf;
Sets the clear flag for the screen~.
If boolf is
TRUE, this will force a clear-screen to be printed on
the next refresh(), or stop it from doing so if boolf
is FALSE.
This only works on screens, and, unlike
clear(), does not alter the contents of the screen. If
~
is curscr, the next refresh() call will cause a
clear-screen, even if the window passed to refresh() is
not a screen.
clrtobot () [*]
wclrtobot(ldn)
WINDOW
*~;
Wipes the window clear from the current (y, x) coordinates to the bottom. This does not force a clearscreen sequence on the next refresh under any circumstances. This has no associated "mv" command.
clrtoeolO [*]
wclrtoeol(ldn)
WINnOW
*~;
Wipes the window clear from the current (y, x) coordinates to the end of the line. This has no associated "mv n command.
delch( )
wdelch(ldn)
WINnOW
*~;
Delete the character at the current
(y, x)
coordinates.
Each character after it on the line shifts
to the left, and the last character becomes blank.
deleteln ()
wdeleteln(ldn)
WINnOW
*~;
£-238
Screen Package
Delete the current line. Every line below the current
one will move up, and the bottom line will become
blank. The current (y, x) co-ordinates will remain unchanged.
erase() [*]
werase(!d.in)
WINDOW
*!d.ini
Erases the window to blanks without setting the clear
flag.
This is analagous to clear(), except that it
never causes a clear-screen sequence to be generated on
a refresh(). This has no associated Rmv R command.
insch<'~)
~
s:.i
winsch(!d.in, s:.)
WINDOW
s:.hll
*nni
s:.1·
Insert s:. at the current (y, x) co-ordinates Each character after it shifts to the right, and the last character disappears. This returns ERR if it would cause
the screen to scroll illegally.
insertln ()
winsertln(!d.in)
WINnow
*!d.ini
Insert a line above the current one. Every line below
the current line will be shifted down, and the bottom
line will disappear.
The current line will become
blank, and the current (y, x) co-ordinates will remain
unchanged. This returns ERR if it would cause the
screen to scroll illegally.
~(:lo, x)
:int.
[*]
:lo, X;
wmoye (!d.in, :lo,
WINnow
:int.
x)
*!d.ini
:lo, X;
B-239
Screen Package
Change the current (y, x) co-ordinates of the window to
(~, X).
This returns ERR if it would cause the screen
to scroll illegally.
overlay(~, ~)
*~, *~;
WINDOW
Overlay ~ on~. The contents of ~, insofar as
they fit, are placed on ~ at their starting (y, x)
co-ordinates. This is done non-destructively, ~.e.,
blanks on ~ leave the contents of the space on ~
untouched.
oyerwrite(~,
WINDOW
~)
*~,
*~;
Overwrite ~ on~. The contents of~, insofar
as they fit, are placed on ~ at their starting
(y, x) co-ordinates. This is done destructively, i.e.,
blanks on ~ become blank on ~.
printw(fmt,
~
~,
~,
••• )
~,
~,
*.fm.t;
fmt,
*liin;
*.fm.t;
wprintw(~,
WINDOW
~
••• )
Performs a printf() on the window starting at the
current (y, x) co-ordinates. It uses addstr() to add
the string on the window. It is often advisable to use
the field width options of printf() to avoid leaving
things on the window from earlier calls. This returns
ERR if it would cause the screen to scroll illegally.
refresh() [*]
wrefresh(l'Lin)
*liin;
WINDOW
Synchronize the terminal screen with the desired window.
If the window is not a screen, only that part
covered by it is updated. This returns ERR if it would
cause the screen to scroll illegally. In this case, it
will update whatever it can without causing the scroll.
£-241
Screen Package .
standout ( ) [ *]
wstandout(ldn)
WINDOW
*ldn;
standend ()
[ *]
wstandend(ldn)
WINPOW
*ld.n;
Start and stop putting characters onto xin in standout
mode.
standout{) causes any characters added to the
window to be put in standout mode on the terminal (if
it has that capability). standend() stops this. The
sequences
and S£ (or US and ll£ if they are not defined) are used (see Appendix A).
ao
~.~.
Input Functions
crmode ()
[*]
noc rmode ()
[*]
Set or unset the terminal to/from cbreak mode.
~()
[*]
noecho ()
[*]
Sets the terminal to echo or not echo characters.
getch()
[*]
wgetch(ldn)
WINDOW
*ld.n;
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 noecho has been set,
then the window is left unaltered. In order to retain
control of the terminal, it is necessary to have one of
noecho, cbreak, or rawmode set. If you do not set one,
whatever routine you call to read characters will set
cbreak for you, and then reset to the original mode
when finished.
E-241
Screen Package
getstr (.a.tI.) [*]
*.a.tI.;
~
wgetstr(~,
.a.tI.)
*ld.n;
WINDOW
~
*.a.tI.;
Get a string through the window and put it in the location pOinted to by.a.tI., which is assumed to be large
enough to handle it. It sets tty modes if necessary,
and then calls getch()
(or wgetch(ld,n» to get the
characters needed to fill in the string until a newline
or EOF is encountered. The newline stripped off the
string. This returns ERR if it would cause the screen
to scroll illegally.
[*]
u.w()
noraw ()
[*]
Set or unset the terminal to/from raw mode. On version
7 DElX[li] this also turns of newline mapping tsee
n.lO).
scanw (.fmt., AI.Sll" AIS.2"
*.fmt.;
••• )
wscanw(ld,n, .fmt., AI.Sll"
AL92, ••• )
~
*ld.n;
WINDOW
~
*.fmt.~
Perform a scanf() through the window using.fmt..
It
does
this
using
consecutive
getch() 's
(or
wgetch(ld,n) IS). This returns ERR if it would cause the
screen to scroll illegally.
5.1.
Miscellaneous Functions
delwin(ld,n)
WINDOW
*ld.n;
Deletes the window from existence. All resources are
freed for future use bycalloc(3). If a window has a
[10]
mux.
is a trademark of Bell Laboratories.
£-242
Screen Package
subwin() allocated window inside of it, deleting the
outer window the subwindow is not affected, even though
this does invalidate it. Therefore, subwindows should
be deleted before their outer windows are.
endwin ()
Finish up window routines before exit.
This restores
the terminal to the state it was before initscr() (or
gettmode() and setterm(» was called. It should always
be called before exiting. It does not exit. This is
especially useful for resetting tty stats when trapping
rubouts via signal(2).
~,
X} [*]
WINDOW
getyx(xin,
*ldn;
.in.t
~,
X;
Puts the current (y, x) co-ordinates of xin in the
variables ~ and X. Since it is a macro, not a function, you do not pass the address of ~ and X•
.iD&h(} [*]
winch(xin) [*]
WINDOW
*ldni
Returns the character at the current (y, x)
coordinates on the given window. This does not make any
changes to the window. This has no associated Rmv R
command.
initscr ()
Initialize the screen routines. This must be called
before any of the screen routines are used. It initializes the terminal-type data and such, and without
it, none of the routines can operate. If standard input is not a tty, it sets the specifications to the
terminal whose name is pOinted to by Def term (initialy
Rdumb R). If the boolean My term is true, Det term is
always used.
B-243
Screen Package
leayeok(~, boolf)
*~;
WINDOW
hQQl
[*]
boolf;
Sets the boolean flag for leaving the cursor after the
last change. If boolf is TRUE, the cursor will be left
'after the last update on the terminal, and the current
(y, x) co-ordinates for ~ will be changed accordingly. If it is FALSE, it will be moved to the current
(y, x) co-ordinates.
This flag (initialy FALSE) retains its value until changed by the user.
longname(termbuf, ~)
*termbuf, *~;
~
Fills in ~ with the long (full) name of the terminal
described by the termcap entry in termbuf. It is generally of little use, but is nice for telling the user
in a readable format what terminal we think he has.
This is available in the global variable ttytype.
Tetmbuf
is
usually set via the termlib routine
tgetent() •
mvwin (lfin, :/., x)
WI NPOW
*lfin;
.int
:/., X;
Move the home position of the window lfin from its
current starting coordinates to (:/., X). If that would
put part or all of the window off the edge of the terminal screen, mywin() returns ERR and does not change
anything.
WINPOW *
newwin(lines, ~, begin y, begin x)
int
lines, ~, begin y, begin x;
Create a new window with lines lines and ~ columns
starting at position (begin y, begin x).
If either
lines or ~ is 9 (zero), that dimension will be set
to (LINES - begin y) or (~ - begin x) respectively.
Thus, to get a new window of dimensions LINES x ~,
use newwin(~, ~, ~, ~) •
.nlO [*]
Screen Package
.ruml. ()
[*]
Set or unset the terminal to/from nl mode,
i.e.,
start/stop the system from mapping to <~
~>.
If the mapping is not done,
refresh()
can do
more optimization, so it is recommended, but not required, to turn it off.
scrollok (ldn, boolf)
WINDOW
*ldn;
~
boolf;
[*]
Set the scroll flag for the given window. If boolf is
FALSE, scrolling is not allowed. This is its default
setting.
touchwin(ldn)
WINDOW
*n,n;
Make it appear that the every location on the window
has been changed. This is usually only needed for refreshes with overlapping windows.
WINDOW *
subwin(ldn, lines, ~, begin y, begin x)
WINDOW
*nn.;
int
lines, ~, begin y, begin x;
Create a new window with lines lines and ~ columns
starting at position (begin y, begin x) in the middle
of the window~. This means that any change made to
either window in the area covered by the subwindow will
be made on both windows. begin y, begin x are specified relative to the overall screen, not the relative
(0, 0) of~. If either lines or ~ is 0 (zero),
that dimension will be set to (LINES - begin y) or
(~ - begin x) respectively.
uDctrl (.c..h)
~
[*]
.c..h;
This is actually a debug function for the library, but
it is of general usefulness. It returns a string which
is a representation of.c..h. Control characters become
their upper-case equivalents preceded by a nAn
Other
E-245
Screen Package
letters stay just as they are. To use unctrl(),
must have iinclude in your file •
.5. •.i.
you
Details
gettmode ()
Get the tty stats.
itscr () •
This
is
normally
called
by
in=
mycur(lasty, lastx, ~, ~)
int
lasty, lastx, ~, ~;
Moves the
terminal's cursor from (lasty, lastx) to
in an approximation of optimal fashion.
This routine uses the functions borrowed from ~ version 2.6.
It is possible to use this optimization
without the benefit of the screen routines.
with the
screen routines, this should not be called by the user.
lIUlY.e. () and refresb () should be used to move the cursor
position, so that the routines know what's going on.
(~,~)
scroll(ldn)
WINPOW
*ldn;
Scroll the window upward one line.
not used by the user.
This
is
normally
sayetty() [*]
resetty () [ *]
sayetty() saves the current tty characteristic flags.
resetty() restores them to what sayetty() stored.
These functions are performed automatically by in=
itscr() and endwin().
setterm(~)
~
*~;
Set the terminal characteristics to be those of the
terminal named~.
This is normally called by in=
itscr () •
£-246
Screen Package
If the new ~(4) driver is in use, this function will
save the current tty state and then put the process to
sleep. When the process gets restarted, it restores
the tty state and then calls wrefresh(curscr) to redraw
the screen. initscr() sets the signal SIGTSTP to trap
to this routine.
£-247
Appendix A
1.
Capabilities
1.1.
~
termcap
Disclaimer
The description of terminals is a difficult business,
and we only attempt to summarize the capabilities here: for
a full description see the paper describing termcap.
Overview
Capabilities from termcap are of 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 now.
Intelligent terminals often 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 ~
at the front of their comment. This normally is a number of
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 ~».
In some cases, the pad is
better computed as some number of milliseconds times the
number of affected lines (to the bottom of the screen usually, except when terminals have insert modes which will shift
several lines.) This is specified as, e.g., ll*. before the
capability, to say 12 milliseconds per affected whatever
(currently always line).
Capabilities where this makes
sense say .f*.
l.~.
Variables
~ ~
setterm()
variables set by setterm()
Type
char
bool
char
bool
char
bool
char
char
char
char
char
char
char
*
*
*
*
*
*
**
*
*
Name
Pad
Description
AL
AM
p*
Add new blank Line
Automatic Margins
Back Cursor movement
BackSpace works
Back Tab
Cursor Addressable
Clear to end of Display
Clear to End of line
CLear screen
Cursor Motion
Delete Character
Delete Line sequence
Delete Mode (enter)
BC
BS
BT
CA
CD
CE
CL
CM
DC
DL
DM
P
p*
P
p*
P
p*
p*
B-248
Appendix A
variables set by setterm()
Type
char
char
bool
char
char
bool
char
bool
char
char
char
char
bool
bool
char
bool
char
char
char
char
char
char
char
char
char
char
bool
char
char
char
char
char
bool
Name
*
*
DO
ED
EO
EI
HO
HZ
IC
IN
IM
IP
LL
*
*
*
*
*
*
*
Pad
P
p*
MA
MI
NC
*
NO
*
*
*
*
*
*
*
*
*
*
*
*
*
*
OS
PC
SE
SF
SO
SR
TA
TE
TI
UC
UE
UL
UP
US
VB
VE
VS
XN
P
P
P
Description
DOwn line sequence
End Delete mode
can Erase Overstrikes with ' ,
End Insert mode
HOme cursor
HaZeltine - braindamage
Insert Character
Insert-Null blessing
enter Insert Mode (IC usually set, too)
Pad after char Inserted using IM+IE
quick to Last Line, column 0
ctrl character MAp for cmd mode
can Move in Insert mode
No Cr: sends then eats
Non-Destructive space
OverStrike works
Pad Character
Standout End (may leave space)
Scroll Forwards
Stand Out begin (may leave space)
Scroll in Reverse
TAb (not AI or with padding)
Terminal address enable Ending sequence
Terminal address enable Initialization
Underline a single Character
Underline Ending sequence
UnderLining works even though lOS
UPline
Underline Starting sequence[ll]
Visible Bell
Visual End sequence
Visual Start sequence
a Newline gets eaten after wrap
Names starting with X are
glitches
~.~.
variables
~ ~
reserved
for
severely
nauseous
gettmode()
variables set by gettmode()
type
name
description
bool
NONL
Term can't hack linefeeds doing a CR
[11] US and UE, if they do not exist in the
try, are copied from SO and SE in setterm()
B-249
termcap
en-
Agpendix A
variables set by gettIDode()
type
name
description
bool
bool
GT
Gtty indicates Tabs
Terminal generates only uppercase letters
UPPERCASE
£-258
Appendix
:a
~.
~
WINDOW structure
The WINDOW structure is defined as follows:
# define
WINDOW
struct _win_st {
short
short
short
short
bool
bool
bool
_cury, _curx;
_maxy, ~axx;
_begy, _begx;
_flags;
_clear;
_leave;
_scroll;
**-y;
*_firstch;
*_lastch;
~
short
short
};
#
i
#
#
#
define
define
define
define
define
_SUBWIN
_ENDLINE
_FULLWIN
_SCROLLWIN
_STANDOUT
91
92
94
919
9299
cury and curx are the current (y, x) co-ordinates for
the window. New characters added to the screen are added at
this point.
maxy and maxx are the maximum values allowed
for (cury, curx).
begy and begx are the starting (y, x)
co-ordinates on the terminal for the window, i.e., the
window's home.
cury, curx, maxy, and maxx are measured
relative to (begy, begx), not the terminal's home.
clear tells if a clear-screen sequence is to be generated on the next refresh() call. This is only meaningful
for screens. The initial clear-screen for the first ~
fresh() call is generated by initially setting clear to be
TRUE for curscr, which always generates a clear-screen if
set, irrelevant of the dimensions of the window involved.
leave is TRUE if the current (y, x) co-ordinates and the
cursor are to be left after the last character changed on
the terminal, or not moved if there is no change.
scroll
is TRUE if scrolling is allowed.
-y is a pointer to an array of lines which describe the
terminal. Thus:
is a pointer to the
~th
line, and
_y[i] [j]
is the ith character on the
~th
£-251
line.
Appendix B
flags can have one or more values or'd into it.
SUBWIN means that the window is a subwindow, which indicates to delwin() that the space for the lines is not to be
freed.
ENDLINE says that the end of the line for this window is also the end of a screen.
FULLWIN says that this
window is a screen.
SCROLLWIN indicates that the last
character of this screen is at the lower right-hand corner
of the terminal 1 .i.~., if a character was put there, the
terminal would scroll.
STANPOUT says that all characters
added to the screen are in standout mode.
£-252
Appendix C
~.
Examples
Here we present a few examples of how to use the package.
They
attempt to be representative, though not
comprehensive.
~.
Screen Updating
The following examples are intended to demonstrate the
basic structure of a program using the screen updating sections of the package. Several of the programs require cal.culational sections which are irrelevant of to the example,
and are therefore usually not included. It is hoped that
the data structure definitions give enough of an idea to allow understanding of what the relevant portions do.
The
rest is left as an exercise to the reader, and will not be
on the final •
Twinkle
.2..~.
This is a moderately simple program which prints pretty
patterns on the screen that might even hold your interest
for 3~ seconds or more. It switches between patterns of asteriSKS, putting them on one by one in random order, and
then taking them off in the same fashion. It is more efficient to write this using only the motion optimization, as
is demonstrated below.
include
#
# include
/*
*
*
~ ~ ~ ~ program ~ ~ product ~ ~ imagination
~ Schoens.
~ responsible ~ minds lQat ~ stolen.
*/
# define
# define
NCOLS
8~
NLINES
24
MAX PATTERNS
# define
struct locs {
~
y, Xi
};
typedef struct locs
LaCS;
£-253
4
Qf
Appendix e
Loes
1*
1*
1*
current pattern number *1
number Qf stars in pattern */
1*
initialize random seguence
Layout[NeOLS * NLINES];
Pattern,
Numstars;
current board laYQut
*1
mainmain () {
*getenv() ;
die () ;
srand (getpid () ) ;
*1
initscr () ;
signal (SIGINT, die);
noecho() ;
nonl () ;
leaveok(stdscr, TRUE);
scrollok(stdscr, FALSE);
.f.Q.t. (;;)
{
1*
1*
1*
makeboard () ;
puton ( I * I) ;
puton (I I);
~ .the. board
ml.t .QIl 1*1,a
u.tJJ
*1
cover .lm lti.th
I
}
}
1*
* Qn program ~, ~ .the. cursor tQ .the. lower ~ corner ~
* direct addreseing, eince current location ia nQt guaranteed.
* ~ .l..i..e .Qn.d ~ ~ ~ tQ ~ .at. .the. upper right corner .t.o. guarantee
* abeolute addreeeing.
*1
diedie () {
signal (SIGINT, SIG_IGN);
mvcur(0, eOLS-l, LINES-I, 0);
endwin() ;
exit(0);
}
1*
* ~ .the. current board eetUp. ~ picke ~ random pattern And
* calle ,.U,Qn() tQ determine .if .the. character I I .Q.n ;that.. pattern
* .Q..t.
*1
nQt.
makeboardmakeboard() {
reg .in..t
reg LOeS
y, x;
*lp;
E-254
l,a
Appendix C
Pattern = rand() % MAXPATTERNS;
1p = Layout;
~ (y = 9; y < NLINES; y++)
~ (x = 9; x < NCOLS; x++)
.if. (ison (y, x» {
1p->y = y;
1p++->x = x;
}
Numstars = 1p - Layout;
}
/*
* Return IRllS.i.f. (~, X)
*/
isonison(y, x)
reg int
y, x; {
alrlit~ll
~
~
~ ~ ~
current pattern.
(Pattern) {
9:
/* altet:nating linea */
t:etIJt:n ! (y & 91) ;
1:
/* h.Qx. */
.i.f. (x >= LINES && Y >= NCOLS)
t:etIJt:n FALSE;
3)
.i.f. (y < 3 II y >= NLINES
t:etIJt:n TRUE;
3) ;
t:etIJt:n (x < 3 II x >= NCOLS
-
-
~
~
/* ~ Pattet:n! */
t:etIJt:n «x + y) & 91);
3:
/* ~ act:osa centet: */
t:etIJt:n (y >= 9 && Y <= 15);
2:
}
/* NOTREACHED */
}
putonputon(ch)
reg &b.a.I.
reg LOCS
regint
reg LOCS
LOCS
*lp;
r;
*end;
temp;
end = &Layout[Numstars];
(lp = Layout; lp < end; Ip++) {
r = rand() % Numstars;
temp = *lp;
*lp = Layout[r];
Layout[r] = temp;
~
}
~
(lp = Layout; 1p < end; 1p++) {
mvaddch(lp->y, Ip->x, ch);
refresh () ;
}
}
£-255
Appendix C
This program plays the famous computer pattern game of
life (Scientific American, May, 1974). The calculational
routines create a linked list of structures defining where
each piece is.
Nothing here claims to be optimal, merely
demonstrative. This program, however, is a very good place
to use the screen updating routines, as it allows them to
worry about what the last position looked like, so you don't
have to. It also demonstrates some of the input routines.
# include
# include
/*
*
RYn 4 ~~. ~
* ~ Screen Updating section ~
*/
struct lst_st {
int
y,
struct lst_st
x:
~ A demonstration program ~
~ -lcurses cursor package.
/* linked l..i...a..t. element */
"
/* (~, X) position ~
.next, *last;/* doubly linked */
~
b
typedef struct lst_st
""LIST
LIST;
/*
*Head:
~ ~
linked .l.i.at. */
mainmain(ac, av)
int
ac:
~
*av[]; {
int
die () :
evalargs(ac,"av) ;
/* evaluate arguments */
initscr () ;
signal(SIGINT, die);
/* initialize screen packag
" /* .a.e.t .tQ resto re ~ stats
crmode() ;
noecho() ;
nonl () :
/* .a.e.t ~ ~-hY-~ */
/*
/* .f.Q.I. optimization */
getstart () ;
.f.Q.I. (;;)
/*
~
starting position */
{
prboard () ;
update () ;
/* print ~ current board
/* update board position */
}
}
E-256
Appendix e
/*
* lhiA ~ ~ routine which ~ called ~ rubout ~
* ~ resets ~ ~ stats ~ their original values.
* ia ~ normal ~ ~ leaving ~ program~
~.
~
*/
diedie () {
/* ignore rubouts */
signal(SIGINT, SIG_IGN);
mvcur(0, eOLS-l, LINES-I, 0) ; /* SQ ~ bottom ~ screen */
/* ~ terminal ~ initial state
endwin () ;
exit(0);
}
/*
* ~ ~ starting position ~ ~~. ~ ~ ~, ~, ~, i, ~,
* m, " And • ~ ~ ~ moving their relative directions ~ ~
* k~. ~, ~ ~ diagonally YR ~ ~~, , moves directly ~,
*~.
X places A piece At ~ current position, " " takes ~ ~.
* ~ input ~ ~ he .f..r.wn .a~. ~.l.at. ~ built after ~
* board setup ~ ready.
*/
getstartgetstart() {
c;
x, y;
reg ~
reg ..i..n.t
/* ~ in ~ screen */
/* ~ ~ upper ~ corner */
box(stdscr, 'I', '_');
move(l,I);
.dQ{
refresh() ;
i f «c=getch(» ==
break;
switch (c) {
~ , u' :
~
~
~
I
q' )
, i' :
'0' :
•j , :
I' :
'm I :
~
I
~
, , '..
~
/* print current position */
. adjustyx(c);
.
~
,
I.
~
If':
break;
~
mvaddstr(0, 0, "File name: ");
getstr(buf);
readfile(buf);
break;
'x':
addch( 'X') ;
break;
B-257
Appendix C .
, '.
addch (' ');
break;
}
}
i t (Head 1= NULL)
dellist(Head);
Head = malloc(sizeof (LIST»;
/*
*
/* start
~
through ~ screen looking ~ 'X'~,
* element ~ ~ ~
*/
~ (y = 1; y < LINES - 1; y++)
~ (x = 1; x < COLS - 1; x++) {
move(y, x);
i t (inc h ( ) == 'x')
addlist(y, x);
lUll'l
.JJJ
~ ~ ~ ~
}
}
/*
*
~
Print QUt
current board position !LQm
~
linked
~
*/
prboardprboard() {
reg LIST
*hp;
erase () ;
box(stdscr, , I
/*
*
*
I
through ~
blank board
gQ
*/
~
,
(hp
I
/* clear ~ ~ positiol
/* ~ in ~ screen */
- ,
').
~
adding
~
piece
~ ~
= Head;
hp; hp = hp->next)
mvaddch(hp->y, hp->x, 'X');
refresh () ;
}
l.
Motion optimization
The following example shows how motion optimization is
written on its own. Programs which flit from one place to
another without regard for what is already there usually do
not need the overhead of both space and time associated with
screen updating. They should instead use motion optimization.
l . .l.
Twinkle
The twinkle program is a good candidate for simple motion optimization.
Here is how it could be written (only
the routines that have been changed are shown):
R-:25R
newly
Appendix C
mainmain() {
reg
*sp;
*getenv() ;
_putchar (), die () ;
~
~
.in.t.
srand(getpid(» ;
/* initialize random seguence */
.if (isatty(0»
{
gettmode () ;
.if. (sp=getenv( "TERM"»
setterm(sp) ;
signal (SIGINT, die);
}
~{
printf(nNeed a terminal on %d0, _tty_ch);
exit(l) ;
}
_puts(TI);
_puts(VS);
noecho() ;
nonl () ;
tputs(CL, NLINES, _putchar);
.f.Q.t. (;;)
{
makeboard() ;
puton( '*');
puton (' ');
/* ~ ~ board setup */
/* lW.t .QIl '*'.a. */
/* coyer ~ ~ , '.a. */
}
}
/*
* putchar defined
*/
_putchar_putchar(c)
reg ~
.f.Q.t.
tputs()
(And
puts(»
c; {
putchar(c);
}
putonputon(ch)
ch; {
~
static .in.t.
reg LOCS
reg .in.t.
reg LOCS
LOCS
lasty, lastx;
*lp;
r;
*end;
temp;
end = &Layout[Numitars];
(lp = Layout; Ip < end; Ip++) {
r = rand() % Numstars;
temp = *lp;
*lp = Layout[r];
Layout[r] = temp;
.f.Q.t.
}
£-259
Appendix C
(lp = Layout; Ip < end; Ip++)
/* prevent scrolling */
(lAM I I (lp->y < NLINES - 1 I I Ip->x < NCOLS - 1» {
rnvcur(lasty, lastx, Ip->y, Ip->x);
putchar(ch) ;
lasty = Ip->y;
~ «lastx = Ip->x + 1) >= NCOLS)
~ (AM) {
lastx = 9;
lasty++;
~
~
lastx = NCOLS - 1;
}
}
£-268
ALms 586 AlII) ACS 8611 COBP~R SYS'rEII XEBIX DEVELOPllElftI SYSTBII
PROGRAIUIER· S REFERERCE GUIDE
READER COMMENT FORM
Altos Computer Systems
2641 Orchard Park Way
San Jose, CA 95134
This document has been prepared for use with your Altos Computer
System. Should you find any errors or problems in the manual, or
have any suggestions for improvement, please return this form to
the ALTOS PUBLICATIONS DEPARTMENT. Do include page numbers or
section numbers, where applicable.
System Model Number _____________________
Serial Number ________________
Document Title______________________________________________________
Revision Number _________________________Date _______________________
Name ________________________________________________________________
Company Name ________________________________________________________
Address ______________________________________________________________
Source Exif Data:
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
Create Date : 2017:08:05 09:40:56-08:00
Modify Date : 2017:08:05 10:21:23-07:00
Metadata Date : 2017:08:05 10:21:23-07:00
Producer : Adobe Acrobat 9.0 Paper Capture Plug-in
Format : application/pdf
Document ID : uuid:55c3a778-31d2-094c-8f6e-a35c75738d0e
Instance ID : uuid:0c820d22-6f65-8447-82a9-741b56a74e7d
Page Layout : SinglePage
Page Mode : UseNone
Page Count : 494
EXIF Metadata provided by EXIF.tools
.