800 1295 04A_Commands_Reference_Manual_198609 04A Commands Reference Manual 198609

800-1295-04A_Commands_Reference_Manual_198609 manual pdf -FilePursuit

800-1295-04A_Commands_Reference_Manual_198609 800-1295-04A_Commands_Reference_Manual_198609

User Manual: 800-1295-04A_Commands_Reference_Manual_198609

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

Download
Open PDF In Browser	View PDF

6sun®
•

microsystems

Comlllands Reference Manual

Sun Microsystems, Inc.

• 2550 Garcia Avenue

• Mountain View, CA 94043

• 415-960-1300

Credits and Trademarks

Sun Workstation® is a registered trademark of Sun Microsystems, Inc.
SunStation®, Sun Microsystems®, SunCore®, SunWindows®, DVMA®, and the combination of Sun
with a numeric suffix are trademarks of Sun Microsystems, Inc.
UNIX, UNIXI32V, UNIX

System III, and UNIX System V are trademarks of AT&T Bell Laboratories.

Intel ® and Multibus® are registered trademarks of Intel Corporation.
DEC®, PDP®, VT®, and VAX® are registered trademarks of Digital Equipment Corporation.

Copyright © 1986 by Sun Microsystems.
This publication is protected by Federal Copyright Law, with all rights reserved. No part of this publication may be reproduced, stored in a retrieval system, translated, transcribed, or transmitted, in any fonn, or
by any means manual, electric, electronic, electro-magnetic, mechanical, chemical, optical, or otherwise,
without prior explicit written pennission from Sun Microsystems.

INTRO( 1)

USER COMMANDS

INTRO(I)

NAME

intro - introduction to commands
DESCRIPTION

This section describes publicly accessible commands in alphabetic order. Certain distinctions of purpose
are made in the headings:
(1)

Commands of general utility, many with enhancements from 4.3 BSD. Wherever possible, we
have incorporated System V versions of commands and utilities into our standard UNIX release.
Where a command has both a System V and a BSD version, and it has been possible to merge
them, we have done so. In some cases, where the System V version was compatible with BSD
and offered significant added value, we adopted that version as our standard.

(IC)

Commands for communication with other systems.

(10)

Commands used primarily for graphics and computer-aided design.

(1 V)

Optionally installed commands from System V, or commands with versions from System V.
These commands either depend upon System V functionality, or have incompatibities with the
corresponding BSD version. They are included in the System V Software installation option.
Once installed, they can be found in the directory lusrl5bin.
In most cases, versions that differed were similar enough so that only the differences for the System V version needed to be noted on the manual page. In a few cases, however, a different
manual page for each version was required.

SEE ALSO

Section 6 in this manual for computer games.
Section 7 in this manual for descriptions of publicly available files and macro packages for document preparation.
Section 8 in this manual for system administration procedures, system maintenance and operation
commands, local daemons, and network-services servers.
Getting Started With UNIX: Beginner's Guide
Setting Up Your UNIX Environment: Beginner's Guide
Windows and Window-Based Tools: Beginner's Guide
Using the Network: Beginner's Guide
Programming Utilities/or the Sun Workstation
DIAGNOSTICS

Upon termination each command returns two bytes of status, one supplied by the system giving the cause
for termination, and (in the case of 'normal' termination) one supplied by the program, see wait and
exit (2). The former byte is 0 for normal termination, the latter is customarily 0 for successful execution,
nonzero to indicate troubles such as erroneous parameters, bad or inaccessible data, or other inability to
cope with the task at hand. It is called variously "exit code," "exit status" or "return code," and is described
only where special conventions are involved.

Sun Release 3.2

Last change: 26 March 1986

1

ADB( 1)

USER COMMANDS

ADB(l)

NAME

adb - debugger
SYNOPSIS

adb [ -w] [ -k] [ -I dir] [ obffil [ corfil ] ]
DESCRIPTION

adb is an interactive, general-purpose debugger. It can be used to examine files and provides a controlled
environment for the execution of UNIX programs.
obffil is normally an executable program file, preferably containing a symbol table. If the file does not contain a symbol table, it can still be examined, but the symbolic features of adb cannot be used. The default
for objfil is a.out. corfil is assumed to be a core image file produced after executing obffil. The default for
corfil is core.
OPTIONS
-w

Create both objfil and corfil if necessary and open them for reading and writing so that files can be
modified using adb.

-k

Do UNIX kernel memory mapping; should be used when core is a UNIX crash dump or /dev/mem.

-I

specifies a directory where files to be read with $< or $« (see below) will be sought; the default
is lusrllibladb.

USAGE

Refer to adb in Debugging Tools for the Sun Workstation for more complete information on how to use
adb. (Note: Some commands require that you compile progams to be debugged with the -go compiler
flag; see cc(lV) for details.)
Commands

adb reads commands from the standard input and displays responses on the standard output. It ignores the
QUIT signal. INTERRUPT invokes the next adb command adb generally recognizes command input of the

form:
[ address] [, count] command [ ; ]
address and count (if supplied) are expressions that result, respectively, in a new current address, and a
repetition count. command is composed of a verb followed by a modifier or list of modifiers.
The symbol. represents the current location. It is initially zero. The default count is 1.
Verbs

?
I

=

@

$r
$R
$x
$X
>
RETURN

Print locations starting at address in obffil.
Print locations starting at address in corfil.
Print the value of address itself.
Interpret address as a source address. Print locations in objfil or lines of source, as appropriate.
Manage a subprocess.
Print names and contents of CPU registers.
Print names and contents of MC68881 registers, if any.
Print the names and contents ofFPA registers 0 through 15, if any.
Print the names and contents ofFPA registers 16 through 31, if any.
Assign a value to a variable or register.
Repeat the previous command with a count of 1. Increment.
Shell escape.

Modifiers

Modifiers specify the format of command output Each modifier consists of a letter, preceded by an integer
repeat count.

2

Last change: 27 February 1986

Sun Release 3.2

ADB (1)

USER COMMANDS

ADB(1 )

Format Modifiers

The following format modifiers apply to the commands ?, I, @, and =. To specify a format, follow the
command with an optional repeat count, and the desired format letter or letters:
[ v] [ [r]f . .. ]

where v is one of these four command verbs, r is a repeat count, and f is one of the format letters listed
below:
(. increment: 2) Print 2 bytes in octal.
o
(4) Print 4 bytes in octal.
q
(2) Print in signed octal.
(4) Print long signed octal.
Q
(2) Print in decimal.
d
D
(4) Print long decimal.
x
(2) Print 2 bytes in hexadecimal.
X
(4) Print 4 bytes in hexadecimal.
(2) Print as an unsigned decimal number.
u
(4) Print long unsigned decimal.
U
f
(4) Print a single-precision floating-point number.
F
(8) Print a double-precision floating-point number.
eE
(12) Print a 96-bit MC68881 extended-precision floating-point number.
(1) Print the addressed byte in octal.
b
(1) Print the addressed character.
c
(1) Print the addressed character using escape convention.
C
s
(n) Print the addressed string.
(n) Print a string using the escape convention.
S
y
(4) Print 4 bytes in date format.
(n) Print as machine instructions.
z
(n) Print with MC68010 machine instruction timings.
I
(0) Print the source text line specified by •
(0) Print the value of • in symbolic form.
a
Print the addressed value in symbolic form.
(4)
P
A
(0) Print the value of . in source-symbol form.
(4) Print the addressed value in source-symbolform.
P
(0) Tab to the next appropriate tab stop.
t
(0) Print a space.
r
(0) Print a newline.
n
, ,
(0) Print the enclosed string.
(0) Decrement.
(0) Increment.
+
(0) Decrement. by 1

o

A

A

Modifiers/or? and I Only

I value mask
L value mask
w value
W value
m b1 e1 f1[?1]

Apply mask and compare for value; move. to matching location.
Apply mask and compare for 4-byte value; move. to matching location.
Write the 2-byte value to address.
Write the 4-byte value to address.
Map new values for bl, el ,fl. If the '?' or 'I' is followed by * then the second segment
(b2 ,e2 ,[2) of the address mapping is changed.

: Modifiers

be
Be
d
D
r

Sun Release 3.2

Set breakpoint, execute e when reached
Set breakpoint using source address, execute e when reached
Delete bre~oint
Delete bre~int at source address
Run objfil as a subprocess

Last change: 27 February 1986

3

ADB( 1)

cs

ss
Ss

t
k

$ Modifiers
file
?
r

x
b

c
C
d

e
w

s
o
q
v
m
f
p
p

i
W

USER COMMANDS

ADB (1)

The subprocess is continued with signal s
Single-step the subprocess with signal s
Single-step the subprocess with signal s using source lines
Add the signal specified by address to the list of signals passed directly to the subprocess
Remove the signal specified by address from the list implicitly passed to the subprocess.
Terminate the current subprocess, if any.
Read commands from the file file.
Similar to <, but can be used in a file of commands without closing the file.
Append output to file, which is created if it does not exist
Print process id, the signal which stopped the subprocess, and the registers.
Print the general registers and the instruction addressed by pc.
If a MC68881 is present, print its registers.
Print all breakpoints and their associated counts and commands.
C stack backtrace.
C stack backtracea with names and (32 bit) values of all automatic and static variables for
each active function.
Set the default radix to address and report the new value. Note that address is interpreted in
the (old) current radix. Thus "ql0$d" never changes the default radix.
Print the names and values of external variables.
Set the page width for output to address (default 80).
Set the limit for symbol matches to address (default 255).
All integers input are regarded as octal.
Exit from adb.
Print all non zero variables in octal.
Print the address map.
Print a list of known source filenames.
Print a list of known procedure names.
(Kernel debugging) Change the current kernel memory mapping to map the designated user
structure to the address given by _u, (the address of the user's proc structure).
Show which signals are passed to the subprocess with the minimum of adb interference.
Reopen objfil and cor/lie for writing, as though the -w command-line argument had been
given.

Variables
Named variables are set initially by adb but are not used subsequently.
o
The last value printed.
1
The last offset part of an instruction source.
2
The previous value of variable 1.
9
The count on the last $< or $« command.

On entry the following are set from the system header in the corfil or objfil as appropriate.
b
The base address of the data segment.
B
The number of an address register that points to the FPA page.
d
The data segment size.
e
The entry point
F
A value of '1' indicates FPA disassembly.
m
The 'magic' number (0407,0410 or 0413).
s
The stack segment size.
t
The text segment size.
Expressions
+

4

The value of dot.
The value of dot incremented by the current increment.
The value of dot decremented by the current increment.

Last change: 27 February 1986

Sun Release 3.2

ADB(l)

USER COMMANDS

ADB(l)

&
integer

The last address typed. (Used to be "tI".)
A number. The prefixes 00 and 00 indicate octal; Ot and OT, decimal; Ox and OX, hexadecimal (the default).
int.frac
A floating-point number.
ASCII value of up to 4 characters.
'ecce'
The value of name, which is either a variable name or a register name.

 ::=

RELEASE NUMBER I a

The character a in the list is equivalent to specifying all releases for the named sees file.
D

10

The delta(l) command creates a 'null' delta in each release (if any) being skipped when a delta is
made in a new release. For example, releases 3 and 4 are skipped when making delta 5.1 after
delta 2.7. These null deltas serve as 'anchor points' so that branch deltas may be created from
them later. If the D flag is absent from the sees file, skipped releases will be non-existent in the
sees file, preventing branch deltas from being created from them in the future.

Last change: 1 February 1985

Sun Release 3.2

ADMIN ( 1)

q text

USER COMMANDS

ADMIN(l)

Text is defined by the user. The text is substituted for all occurrences of the %Q% keyword in

sees file text retrieved by get(1).
mmodule
Module name of the sees file substituted for all occurrences of the %M% keyword in sees file
text retrieved by get(l). If the m flag is not specified, the value assigned is the name of the sees
file with the leading s. removed.

t type

Type of module in the sees file substituted for all occurrences of %Y% keyword in sees file text
retrieved by get(l).

v [program]

Validity checking program: delta(l) prompts for Modification Request (MR) numbers as the reason for creating a delta. The optional pro gram specifies the name of an MR number validity
checking program (see delta(l». If this flag is set when creating an sees file, the -m option must
also be used even if its value is null.
FILES

The last component of all sees file names must be of the form sJile-name. New sees files are given mode
444 (see chmod(l V». Write permission in the pertinent directory is, of course, required to create a file.
All writing done by admin is to a temporary x-file, called xJile-name, (see get(l», created with mode 444
if the admin command is creating a new sees file, or with the same mode as the sees file if it exists.
After successful execution of admin, the sees file is removed (if it exists), and the x-file is renamed with
the name of the sees file. This ensures that changes are made to the sees file only if no errors occurred.
It is recommended that directories containing sees files be mode 755 and that sees files themselves be
mode 444. The mode of the directories allows only the owner to modify sees files contained in the directories. The mode of the sees files prevents any modification at all except by sees commands.
If it should be necessary to patch an sees file for any reason, the mode may be changed to 644 by the
owner allowing use of a text editor. "Care must be taken!" The edited file should always be processed by
an admin -b to check for corruption followed by an admin -z to generate a proper check-sum. Another
admin -b is recommended to ensure the sees file is valid.

Admin also uses a transient lock file (called z.file-name), to prevent simultaneous updates to the sees file
by different users. See get(l) for further information.
SEE ALSO

sces(l), delta(l), ed(1), get(l), help(l), prs(l), what(l), sccsfile(5).

Programming Utilities/or the Sun Workstation.
DIAGNOSTICS

Use help (1) for explanations.

Sun Release 3.2

Last change: 1 February 1985

11

AR(I)

USER COMMANDS

AR(I)

NAME

ar - archive and library maintainer
SYNOPSIS

ar dim Ipi q I r I t Ix [ ab position-name] [ cilouv ] archive file-entry . ..
DESCRIPTION
ar maintains library archives. A library is a set of files that have been combined into a single archive file
(see ar(5». ar is normally used to create and update library files used by the link editor Id(l), but can be

used for any similar purpose.
archive is the archive file. file-entry is a file contained in the archive.
OPTIONS

You must indicate one of: d, m, p, q, r, t, or x, which may be followed by one or more of the modifiers
abcilouv.
d

Delete the named files from the archive file.

m

Move the named files to the end of the archive.

p

Display the named files in the archive.

q

Quick append Append the named files to the end of the archive file without searching the archive
for duplicate names. Useful only to avoid quadratic behavior when creating a large archive
piece-by-piece.

r

Replace the named files in the archive.

t

Display a table of contents of the archive file. If no names are given, all files in the archive are
listed; if names are given, only those files are listed

x

Extract the named files. If no names are given, all files in the archive are extracted. In neither
case does x alter the archive file.

MODIFIERS

a

Place new files after posname (posname argument must be present). Applies only to the r and m
options.

b

Place new files before posname (posname argument must be present). Applies only to the r and m
options.

c

Normally ar creates archive when it needs to, and displays a message to this effect. The c
modifier suppresses this message.
Identical to the b modifier.
Local. Ar places its temporary files in the directory Itmp. The I modifier places them in the local
directory instead.

o

Old date. When files are extracted with the x option,
recorded in the archive.

u

Replace only those files that have changed since they were put in the archive. Used with the r
option.

v

Verbose. Give a file-by-file description of the creation of a new archive file from the old archive
and the constituent files. When used with t, it gives a long listing of information about the files.
When used with p, it precedes each file with a name.

0

sets the "last modified" date to the date

EXAMPLES

Creating a new archive:
orpheus% ar rcv archive file.o
a - file.o
Adding to an archive:
orpheus% ar rav file.o archive next.c

12

Last change: 19 May 1986

Sun Release 3.2

AR(1 )

USER COMMANDS

AR(I)

a - nextc
Extracting from an archive:
orpheus% ar xv archive file.o
x - file.o
orpheus% Is file.o
file.o
Seeing the table of contents:
orpheus% ar t archive
file.o
next.c
FILES
Itmplv*

temporaries

SEE ALSO
lorder(l), Id(I), ranlib(I), ar(5)
BUGS

If the same file is mentioned twice in an argument list, it is put in the archive twice.
The "last-modified" date of a file will not be altered by the
the extracted file or the superuser.

Sun Release 3.2

0

option unless the user is either the owner of

Last change: 19 May 1986

13

ARCH(l)

USER COMMANDS

ARCH(1)

NAME

arch - display the Sun WoIkstation architecture of the current host
SYNOPSIS

arch
DESCRIPTION
The arch command displays the architecture of the current Sun host.
SEE ALSO
rnach(1),rnachid(l)

14

Last change: 29 May 1986

Sun Release 3.2

AS(l)

USER COMMANDS

AS(l)

NAME

as - Sun-I, Sun-2 and Sun-3 assembler
SYNOPSIS

as [ -d2] [ -e] [ -b] [ -j ] [ -J] [ -L] [ -mc68010 ] [ -mc68020] [ -0 objfile] [ -0]
[-R ]jilename
DESCRIPTION
as translates assembly code in the namedjilename into executable object code in the specified objfile.

All undefined symbols in the assembly are treated as global.
The output of the assembly is left in the file objjile.
OPTIONS

-d2

Specifies that instruction offsets involving forward or external references and having sizes
unspecified in the assembly language are two bytes long. The default is four bytes. See also the -j
option.

-e

Allows control sections to begin on any two-byte boundary, rather than only four-byte boundaries.

-b

Suppress span-dependent instruction calculations and force all branches to be of medium length,
but all calls to take the most general form. This is used when assembly must be minimized, while
program size and run-time are unimportant. This option results in a smaller and faster program
than that produced by the -J option, but some very large programs may not be able to use it
because of the limits of the medium-length branches.

-j

Use short (pc-relative) branches to resolve jump's andjsr's to externals. This is for compact programs which cannot use the -d2 flag because of large program relocation.

-J

Suppress span-dependent instruction calculations and force all branches and calls to take the most
general form. This is used when assembly time must be minimized, but program size and run time
are not important.

-L

Save defined labels beginning with an 'L', which are normally discarded to save space in the
resultant symbol table. The compilers generate such temporary labels.

-mc68010
Accept only MC68010 instructions and addressing modes, and put the MC68010 machine-type
tag in the object file. This is the default on Sun-2's.
-mc68020
Accept the full MC68020, MC6888 1 and the Sun FPA instruction sets and addressing modes, and
put the MC68020 machine-type tag in the object file. This is the default on Sun 3's.
-0

The next argument is taken as the name of the object file to be produced. If the -0 flag isn't used,
the objfile is named a.out.

-0

Perform span-dependent instruction resolution over entire files rather than just over individual
procedures.

-R

Make initialized data segments read-only by concatenating them to the text segments. This eliminates the need to run editor scripts on assembly code to make initialized data read-only and
shared.

FILES

ItmplaS*

default temporary file

SEE ALSO

Id(I), nm(I), adb(1), dbx(l), a.out(5)
Assembly Language Reference Manual

Sun Release 3.2

Last change: 20 March 1986

15

AS( 1)

USER COMMANDS

AS(I)

BUGS

The Pascal compiler, pc, qualifies a nested procedure name by chaining the names of the enclosing procedures. This sometimes results in names long enough to abort the assembler, which currently limits
identifiers to 512 characters.

16

Last change: 20 March 1986

Sun Release 3.2

AT( 1)

USER COMMANDS

AT(l)

NAME

at - execute commands at a later time
SYNOPSIS

at [ -csm ] time [ date] [week] [script ]
DESCRIPTION

at spools a copy of the named script for execution at a later date or time. script is the name of a file to be
used as command input for the Bourne shell, sh(1), the C-Shell, csh(l), or an arbitrary shell specified by
the SHELL environment variable.
The time argument consists of 1 to 4 digits, followed by an optional 'A' or 'P' for AM or PM (if no letters
follow the digits, a 24-hour clock is assumed). One- and two-digit numbers are taken to be hours; three
and four digits specify hours and minutes. An optional colon (':') may be used to separate the hour and
minute fields. Alternatively, 'N' or 'M', optionally preceded by '12', '1200', or '12:00', may be used to
specify noon or midnight.
The optional date argument is either the name of a month, followed by a day-of-the-month number, or a
named day-of-the-week; if the keyword week follows, execution is moved out by seven days. Names of
months and days can be abbreviated, as long as the abbreviation is unambiguous.
If script is omitted, command input is accepted from the standard input.
The spool file includes a four-line header that indicates the owner of the job, the name of the script the
shell is to use, and whether mail is to be sent.
This header is followed by a cd command to the current directory (from which at was called) and a umask
command to set the modes on any files created by the job. at also copies all relevant environment variables
to the spool file.

script is run with the user and group IDs of whoever created the spool file (the user who invoked the at
command).
at jobs are started by periodic execution of the command lusrlIib/atrun from cron (8). The precise timing
of each at job depends upon the how often atrun is executed.
OPTIONS

-c

C-Shell. csh(l) is used to execute script.

-s

Standard (Bourne) shell. sh(l) is used to execute the job.

If neither -c, nor -s is specified, at uses the value of the SHELL environment variable to determine which
shell to use.
-m

Mail. Send mail after the job has been run. If errors occur during execution of the script, then
resulting error messages are included in the mail message. When -m is omitted, error output is
lost (unless redirected within the script itself).

EXAMPLES

at8amjan 24
at -s 1200n week
at -c -m 1530 fr week
DIAGNOSTICS

Complains about various syntax errors and times that are out of range.
FILES

lusrlspool/at
lusrlspool/atlyy.ddd.hhhh.*
lusrlspool/atlpast
Iusrlspool/atllasttimedone
Iusrlliblatrun

Sun Release 3.2

spooling area
job file
directory where jobs are executed from
last time atrun was run
job initiator (run by cron(8»

Last change: 17 July 1986

17

AT(1)

USER COMMANDS

AT(1)

SEE ALSO
atq(1), atrm(1), cron(8)
BUGS

Due to the granularity of the execution of lusrlIib/atrun, there may be bugs in scheduling jobs almost
exactly 24 hours ahead.

If the system crashes, mail stating that the job was not completed is not sent to the user.
Sometimes old spool files are not removed from the directory lusrlspooIlatlpast. This is usually due to a
system crash, and requires that these files be removed by hand.
Shell interpreter specifiers (e.g., #!/binlcsh ) in the beginning of script are ignored.

18

Last change: 17 July 1986

Sun Release 3.2

ATQ(l)

USER COMMANDS

ATQ( 1)

NAME

atq - print the queue of jobs waiting to be run
SYNOPSIS

atq [ -c ] [ -0 ] username ...
DESCRIPTION
atq prints the queue of jobs, created with the at(l) command, that are waiting to be run at later date.

With no flags, the queue is sorted in chronological order of execution.

If no usemames are specified, the entire queue is displayed; otherwise, only those jobs belonging to the
named users are displayed.
OPTIONS

-c

By creation time. Sorted the queue by the time that the at(l) command was given, the most
recently created job first.

-0

Number of jobs. Print the total number of jobs currently in the queue. Do not list them.

FILES

lusrlspoollat

spool area

SEE ALSO
at(1), atrm(1), cron(8)

Sun Release 3.2

Last change: 17 July 1986

19

ATRM( 1)

USER COMMANDS

ATRM(I)

NAME

atrm - remove jobs spooled by at
SYNOPSIS
atrm [ -6] [ - ] [job-number ] ... [username] ...
DESCRIPTION
atrm removes delayed-execution jobs that were created with the at(l) command. The list of jobs can be
displayed by atq(I).

atrm removes each job-number you specify, and/or all jobs belonging to username, provided that you own
the indicated jobs.
Jobs belonging to other users can only be removed by the super-user.
OPTIONS
-f

-i

Force. All information regarding the removal of the specified jobs is suppressed.
Interactive. atrm asks if a job should be removed; a response of 'y' verifies that the job is to be
removed.
Remove jobs that were queued by the current user. If invoked by the super-user, the entire queue
will be flushed

FILES

lusrlspool/at

spool area

SEE ALSO
at(l), atq(I), cron(8)

20

Last change: 17 July 1986

Sun Release 3.2

AWK(I)

USER COMMANDS

AWK(I)

NAME

awk - pattern scanning and processing language
SYNOPSIS

awk [-f programyle] [ -Fc] [program] [variable=value ... ] [file ... ]
DESCRIPTION

Awk scans each of its input file s for lines that match any of a set of patterns specified in pro gram. The
inputfiles are read in order; the standard input is read if there are no files. The filename - means the standard input.
The set of patterns may either appear literally on the command line as program, or, by using the -f option,
the set of patterns may be in a pro gramyle; a pro gramyle of - means the standard input. If the pro gram
is specified on the command line, it should be enclosed in single quotes (') to protect it from the shell.
awk variables may be set on the command line using arguments of the form variable=value. This causes
the awk variable variable to be set to the value value before the first record of the next file argument that
follows the variable=value argument is read.
With each pattern in program there can be an associated action that will be performed when a line of afile
matches the pattern. See the discussion below for the format of input lines and the awk language. Each
line in each inputfile is matched against the pattern portion of every pattern-action statement; the associated action is performed for each matched pattern.
OPTIONS
-f programyle

Use the contents of programJile as the source for the program.

-F c

Use the character c as the field separator (FS) character. See the discussion ofFS below.

LINES, STATEMENTS, AND THE AWK LANGUAGE

Input Lines
An input line is made up of fields separated by white space. The field separator can be changed by using
FS - see below. Fields are denoted $1, $2, •••, up to $9; $0 refers to the entire line.
Pattern-action Statements
A pattern-action statement has the form
pattern { action}
A missing action means copy the line to the output; a missing pattern always matches.
An action is a sequence of statements. A statement can be one of the following:

if ( conditional) statement [ else statement]
while (conditional) statement
for ( expression ; conditional; expression) statement
break
continue
{ [ statement] ••• }
variable =expression
print [ expression-list] [ >expression ]
printf format [ , expression-list] [ >expression ]
next
# skip remaining patterns on this input line
exit
# skip the rest of the input

Format of the Awk Language
Statements are terminated by semicolons, new lines or right braces. An empty expression-list stands for the
whole line.
Expressions take on string or numeric values as appropriate, and are built using the operators +, -, *, /, %,
and concatenation (indicated by a blank). The C operators ++ , - , += , -= , *= , /= , and %= are also
available in expressions.

Sun Release 3.2

Last change: 1 February 1985

21

AWK(I)

USER COMMANDS

AWK(I)

Variables may be scalars, array elements (denoted x [ i]) or fields. Variables are initialized to the null
string. Array subscripts may be any string, not necessarily numeric, providing a form of associative
memory. String constants are quoted "•••".
The print statement prints its arguments on the standard output (or on a file if >file is present), separated by
the current output field separator, and terminated by the output record separator. The printf statement formats its expression list according to the format template format (see print/(3S) for a description of the formatting control characters).

Built In Functions
The built-in function length returns the length of its argument taken as a string, or of the whole line if no
argument There are also built-in functions exp, log, sqrt, and int, where int truncates its argument to an
integer. substr(s, m, n) returns the n-character substring of s that begins at position m.
sprintf'(format, expr, expr, ••• ) formats the expressions according to the print/(3S) format given by format
and returns the resulting string.

Patterns

Patterns are arbitrary Boolean combinations ( !, II, &&, and parentheses) of regular expressions and relational expressions. Regular expressions must be surrounded by slashes and are as in egrep. Isolated regular expressions in a pattern apply to the entire line. Regular expressions may also occur in relational
expressions.
A pattern may consist of two patterns separated by a comma; in this case, the action is performed for all
lines between an occurrence of the first pattern and the next occurrence of the second.
A relational expression is one of the following:

expression matehop regular-expression
expression relop expression
where a relop is any of the six relational operators in C, and a matehop is either - (for "contains") or !(for Hdoes not contain"). A conditional is an arithmetic expression, a relational expression, or a Boolean
combination of these.
The special pattern BEGIN may be used to capture control before the first input line is read, in which case
BEGIN must be the first pattern. The special pattern END may be used to capture control after the last
input line is read, in which case END must be the last pattern.
Special Variable Names
A single character e may be used to separate the fields by starting the program with
BEGIN { FS = "e" }
or by using the -Fe option.
Other variable names with special meanings include NF, the number of fields in the current record; NR, the
ordinal number of the current record; FILENAME, the name of the current input file; OFS, the output field
separator (default blank); ORS, the output record separator (default newline); and OFMT, the output format for numbers (default %.6g).
EXAMPLES
Print lines longer than 72 characters:

length> 72
Print first two fields in opposite order:
{print $2, $1 }
Add up first column, print sum and average:
END

22

{s += $1 }
{ print" sum is", s, " average is", S/NR }

Last change: 1 February 1985

Sun Release 3.2

AWK(l)

USER COMMANDS

AWK( 1)

Print fields in reverse order:
{ for (i = NF; i > 0; -i) print $i }
Print all lines between start/stop pairs:
fstart!, fstopf

Print all lines whose first field is different from previous one:
$1 != prev {print; prev = $1 }
SEE ALSO

Using UNIX Text Utilities on the Sun Workstation
sed(1V), grep(1V), lex(1)
BUGS

Input white space is not preserved on output if fields are involved.
There are no explicit conversions between numbers and strings. To force an expression to be treated as a
number add 0 to it; to force it to be treated as a string concatenate the null string (" ") to it

Syntax errors result in the cryptic message ttawk: bailing out near line 1.tt

Sun Release 3.2

Last change: 1 February 1985

23

BANNER ( I)

USER COMMANDS

BANNER(I)

NAME

banner - make posters
SYNOPSIS

lusr/5binlbanner strings
DESCRIPTION
Note:

Optional Software (System V Option). Refer to Installing UNIX on the Sun Workstation for information on how to install this command.

banner prints its arguments (each up to 10 characters long) in large letters on the standard output.
SEE ALSO
echo(lV)

24

Last change: 17 April 1986

Sun Release 3.2

BASENAME ( 1 )

USER COMMANDS

BASENAME ( 1 )

NAME

basename, dirname - deliver portions of path names
SYNOPSIS
base name string [ suffix ]
dirname string
DESCRIPTION
basename deletes any prefix ending in I and the suffix, if present in string. It directs the result to the standard output, and is normally used inside substitution marks C ') within shell procedures.

dirname delivers all but the last level of the path name in string.
EXAMPLES
This shell procedure invoked with the argument lusrlsre/binleat.e compiles the named file and moves the
output to cat in the current directory:

ee$l
mv a.out'basename $l.e'
The following example will set the shell variable NAME to lusrlsrdemd:
NAME='dirname lusrlsrdemdleat.e'
SEE ALSO
sh(l)

Sun Release 3.2

Last change: 13 March 1986

25

BC( 1)

USER COMMANDS

BC(l )

NAME

bc - arbitrary-precision arithmetic language
SYNOPSIS

be [ -e ] [ -I ] [ file ••• ]
DESCRIPTION
Be is an interactive processor for a language which resembles C but provides unlimited precision arithmetic. Be takes input from any files given, then reads the standard input. The syntax for be programs is as
follows; L means letter a-z, E means expression, S means statement.

Comments
are enclosed in 1* and *1.
Names
simple variables: L
array elements: L [ E ]
The words 'ibase', 'obase', and 'scale'
Other operands
arbitrarily long numbers with optional sign and decimal point
(E)
sqrt (E)
length (E)

scale (E)
L(E, ••• ,E)

number of significant decimal digits
number of digits right of decimal point

Operators

+ _ * I % (% is remainder; is power)
++ (prefix and postfix; apply to names)
A

A

== <= >= != < >
= += _= *= 1= %= =
A

Statements

E
{S; ..• ;S}
if(E)S
while (E) S
for ( E ; E ; E ) S
null statement
break
quit
Function definitions
define L ( L ,•.•, L ) {
auto L, ••• ,L
S; ••• S
return (E)
}

Functions in -I math library
s(x)
sine
c(x)
cosine
e(x)
exponential
l(x)
log
a(x)
arctangent
j(n,x) Bessel function

26

Last change: 1 April 1981

Sun Release 3.2

BC( 1)

USER COMMANDS

BC(1 )

All function arguments are passed by value.
The value of a statement that is an expression is printed unless the main operator is an assignment. Either
semicolons or newlines may separate statements. Assignment to seale influences the number of digits to be
retained on arithmetic operations in the manner of de (1). Assignments to ibase or obase set the input and
output number radix respectively.
The same letter may be used as an array, a function, and a simple variable simultaneously. All variables
are global to the program. 'Auto' variables are pushed down during function calls. When using arrays as
function arguments or defining them as automatic variables empty square brackets must follow the array
name.
EXAMPLES
Define a function to compute an approximate value of the exponential function:
scale = 20
define e(x){
auto a, b, c, i, s
a=1
b=1
s=1
for(i=l; 1==1; i++){
a= a*x
b = b*i
c = alb
if(c == 0) return(s)
s = s+C
}
}

Print approximate values of the exponential function of the first ten integers:
for(i=l; k=10; i++) e(i)
OPTIONS
-I

-c

is the name of an arbitrary precision math library.
Compile only: be is actually a preprocessor for de(l), which it invokes automatically, unless the

-c (compile only) option is present. In this case the de input is sent to the standard output instead.
FILES

lusr/lib/lib.b mathematical library
dc( 1)
desk calculator proper
SEE ALSO
dc(l)

Games, Demos and Other Pursuites: Beginner's Guide
BUGS

For statement must have all three E' s.
Quit is interpreted when read, not when executed.

Sun Release 3.2

Last change: 1 April 1981

27

BIFF( 1)

USER COMMANDS

BIFF( 1)

NAME

biff - mail alarm
SYNOPSIS

birr [yin]
DESCRIPTION

bifj informs the system whether you want to be notified when mail arrives during the current terminal session. The command:

biffy
enables notification; the command:

biffn
disables it; finally, the command:

biff
on its own tells you whether the notification is y or n. When mail notification is enabled, the header and
first few lines of the message are printed on your screen whenever mail arrives. A biffy command is often
included in the file .login or .profile to be executed at each login.
bifjoperates asynchronously. For synchronous notification use the MAIL variable of sh or the mail variable
of csh.
SEE ALSO

csh(I), sh(I), mail(I), comsat(8)

28

Last change: 23 September 1985

Sun Release 3.2

BINMAIL( 1)

USER COMMANDS

BINMAIL(l)

NAME

binmail- send or receive mail among users
SYNOPSIS
tbin/maD [ -i] [ -p ] [ -q ] [ -f filename ]
tbin/maD address . ..
DESCRIPTION
Note: This is the old version 7 UNIX system mail program. The default nuzil command is described in
mail(l), and its binary is in the directory lusrlucb.

Ibinlmail with no address prints a user's mail, message-by-message in last-in, first-out order. Ibinlmail
accepts commands from the standard input to direct disposition messages.
When addresses are named, Ibinlnuzil takes the standard input up to an end-of-file (or a line with just' .')
and adds it to each person's 'mail' file. The message is preceded by the sender's name and a postmark.
Lines that look like postmarks are prepended with '>'. A person is usually a user name recognized by
login, or a network address (see aliases (5».

If there is any pending mail, login tells you there is mail when you log in. It is also possible to have the CShell, or the daemon bifftell you about mail that arrives while you are logged in.
To forward mail automatically, add the addresses of additional recipients to the forward file in your home
directory. Note that forwarding addresses must be valid, or the messages will "bounce." (You cannot, for
instance, reroute your mail to a new host by forwarding it to your new address if it is not yet listed in the
yP aliases domain.)
OPTIONS
Printing Mail

-i

continue after interrupts - an interrupt normally terminates the Ibinlnuzil accepts the following
interactive commands when printing messages.

-p

print messages without prompting for commands. Exit immediately upon receiving an interrupt.

-q

quit immediately upon interrupt.

-rfilename
use filename as if it were the mail file.
Sending Mail

-d

deliver mail directly, don't route the message through sendmail. This option is often used by pro-

grams that send mail.
-i

continue after interrupts mail file unchanged

an interrupt normally terminates the Ibinlnuzil command and leaves the

-rname
specify a string to appear as the name of the sender.
COMMANDS

?
print a command summary.
EOT (control-D)
put unexamined mail back in the mail file and quit.

!command
escape to the Shell to do command.
go back to previous message.
+

go on to next message.

newline go on to next message.
d

Sun Release 3.2

delete message and go on to the next.

Last change: 23 September 1985

29

BINMAIL( 1)

dq

USER COMMANDS

BINMAIL( 1)

delete message and quit

m [person ] _.

mail the message to the named persons (yourself is default).
n

go on to next message.

p

print message (again).

q

same as EOT.

s rJile] ...
save the message in the named files ('mbox' default). If saved successfully, remove it from the
list and go on to the next message.
W

[file] •••

save the message, without a header, in the named files ('mbox' default). If saved successfully,
remove it from the list and go on to the next message.
x

exit without changing the mail file.

FILES

letc/passwd

to identify sender and locate address
incoming mail for user *
mbox
saved mail
Itmplma*
temp file
lusrlspoollmaill* .lock lock for mail directory
dead.letter unmailable text is saved here
$HOMElJorward
list of forwarding recipients

lusrlspoollmaill*

SEE ALSO

mail(l), biff(l), write(l), uucp(lC), uux(IC), xsend(I), sendmail(8), aliases(5), csh(l)
BUGS

Race conditions sometimes result in a failure to remove a lock file.
The superuser can read your mail, unless it is encrypted by des, encrypt, or xsend. Even if you encrypt it,
the superuser can delete it.

30

Last change: 23 September 1985

Sun Release 3.2

CAL( 1)

USER COMMANDS

CAL ( 1)

NAME

cal - display calendar
SYNOPSIS

cal [ [ month] year ]
DESCRIPTION
Cal displays a calendar for the specified year. If a month is also specified, a calendar for that month only is
displayed. H neither is specified, a calendar for the present month is printed.

Year can be between 1 and 9999. Be aware that 'cal 78' refers to the early Christian era, not the 20th century. Also, the year is always considered to start in January, even though this is historically naive.
month is a number between 1 and 12.
The calendar produced is that for England and her colonies.
Try September 1752.

Sun Release 3.2

Last change: 17 February 1986

31

CALENDAR ( 1 )

USER COMMANDS

CALENDAR ( 1 )

NAME

calendar - reminder service
SYNOPSIS

calendar [ - ]
DESCRIPTION
Calendar consults the file calendar in the current directory and displays lines that contain today's or

tomorrow's date anywhere in the line. Most reasonable month-day dates - such as 'Dec. 7,' 'december
7,' and '1217' - are recognized, but '7 December' or '7/12' are not. If you give the month as "*" with a
date - for example, "* 1" - that day in any month will do. On weekends 'tomorrow' extends through
Monday.
When the optional - argument is present, calendar does its job for every user who has a file calendar in
his login directory and sends him any positive results by mail(l). Normally this is done daily in the wee
hours under control of cron (8).
The file calendar is first run through the C preprocessor, Iliblcpp, to include any other calendar files
specified with the usual "#include" syntax. Included calendars are usually shared by all users, and maintained by the system administrator.
FILES

-/calendar
lusrllib/calendar to figure out today's and tomorrow's dates
letclpasswd
Itmplcal*
llib/cpp subprocess

lusrlbin/egrep
subprocess
Ibin/sed subprocess
Ibin/mail
subprocess
SEE ALSO

at(I), cron(8), mail(l)

BUGS
Calendar's extended idea of 'tomorrow' doesn't account for holidays.

32

Last change: 17 February 1986

Sun Release 3.2

CAT ( IV)

USER COMMANDS

CAT ( IV)

NAME

cat - concatenate and display
SYNOPSIS

cat [ -u ] [ -0] [ -b] [ -s ] [ -v] [ -e ] [ -t ] [ - ] [filename . .. ]
SYSTEM V SYNOPSIS
cat [ -u ] [ -s] [ -y ] [ -e ] [ -t] [ - ] [filename . .. ]
DESCRIPTION
cat reads eachfile in sequence and displays it on the standard output Thus

% cat goodies
displays the contents of goodies on the standard output, and

% cat filel file2 >file3
concatenates the first two files and places the result on the third.
If no filename argument is given, or if the argument '-' is given, cat reads from the standard input If the
standard input is a terminal, input is terminated by an EOF signal, usually AD.
OPTIONS
-u

Unbuffered. If -u is not used, output is buffered in blocks, or line-buffered if standard output is a
tenninal.

-0

precedes each line output with its line number.

-b

numbers the lines, as -0, but omits the line numbers from blank lines.

-s

substitutes a single blank line for multiple adjacent blank lines.

-v

displays non-printing characters (with the exception of tabs and newlines) so that they are visible.
Control characters print like AX for Control-X; the DEL character (octal 0177) prints as A? NonASCII characters (with the high bit set) are displayed as M-x where M- stands for' 'meta" and x
is the character specified by the seven low order bits.

-e

displays non-printing characters, as -v, and in addition displays a $ character at the end of each
line.

-t

displays non-printing characters, as -v, and in addition displays tab characters as "I.

SYSTEM V OPTIONS
-s
suppresses messages about files which can't be opened.
-y

displays non-printing character (with the exception of tabs, newlines, and formfeeds) so that they
are visible.

-e

if the -v option is specified, displays a $ character at the end of each line.

-t

if the -v option is specified, displays tab characters as AI and formfeeds as AL.

SEE ALSO
cP(I), ex(I), more(I), pr(IV), pg(IV), tail(l)
BUGS

Beware of 'cat a b >a' and 'cat a b >b', which destroy the input files before reading them.

Sun Release 3.2

Last change: 24 April 1986

33

CB( 1)

USER COMMANDS

CB(1)

NAME

cb - C program beautifier
SYNOPSIS

cb [ -s] [ -j ] [ -Ileng ] [filename . .. ]
DESCRIPTION

cb reads C programs either from its arguments or from the standard input and writes them on the standard
output with spacing and indentation that displays the structure of the code.
indent(1) is preferred.
OPTIONS

With no options, cb preserves all user NEWUNES.
-s

Standard C style. Canonicalizes the code to the style of Kernighan and Ritchie in The C Programming Language.

-j

Split lines are put back together.

-Ileng Split lines longer than leng.
SEE ALSO

indent(l)
BUGS

Punctuation hidden in preprocessor statements can cause indentation errors.

34

Last change: 16 April 1986

Sun Release 3.2

CC( IV)

USER COMMANDS

CC( IV)

NAME

cc - C compiler
SYNOPSIS

cc [-a] [-align _block] [ -c] [-C] [-dryrun] [-Dname[=de!]] [-E] [float_option]
[ -fsingle] [ -g] [ -go] [ -belp] [ -Ipathname] [ -J] [ -Ilib]
[ -Ldir [ -M ] [ - i ) ouljile] [ -0 ] [ -p ] [ -pg] [ -pipe] [ -P ]
[ -Qoption prog opt] [ -Qpatb pathname ] [ -Qproduce sourcetype] [ -R ] [ -s ]
[ -temp=dir] [ -time] [ -Uname ] [ -v ] [ -w] sourcefile ...
SYSTEM V SYNOPSIS

/usr/Sbinlcc arguments
Note:

arguments to lusrl5binlcc are identical to those listed above.

DESCRIPTION

cc is the C compiler. It translates programs written in the C programming language into executable load
modules, or into relocatable binary programs for subsequent loading with the ld(l) linker.
In addition to the many options, cc accepts several types of filename arguments. For instance, files with
names ending in .c are taken to be C source programs. They are compiled, and each resulting object program is placed in the current directory. The object file is named after its source file - the suffix .0 replacing .c in the name of the object. In the same way, files whose names end with .s are taken to be assembly
source programs. They are assembled, and produce .0 file. Filenames ending in .iI are taken to be inline
expansion code template files; these are used to expand calls to selected routines in-line when the -0 option
is in effect. See FILES, below for a complete list of compiler-related filename suffixes.
Other arguments refer to assembler or loader options, object programs, or object libraries. Unless -c, -S,
-E -P or -Qproduce is specified, these programs and libraries, together with the results of any specified
compilations or assemblies, are loaded (in the order given) to produce an output file named a .out. You can
specify a name for the executable by using the -0 option.
If a single C program is compiled and loaded all at once, the intermediate file is deleted.
OPTIONS

See ld(l) for link-time options.
-a

Insert code to count how many times each basic block is executed. Creates a .d file for
every .f file compiled. The.d file accumulates execution data for the corresponding
source file. The tcov(l) utility can then be run on the source file to generate statistics
about the program.

-align _block

Cause the global symbol block to be page-aligned: its size is increased to a whole number
of pages, and its first byte is placed at the beginning of a page.

-c

Suppress linking with ld(l) and produce a .0 file for each source file. A single object file
can be named explicitly using the -0 option.

-C

Prevent the C preprocessor, cpp(l), from removing comments.

-dryrun

Show but do not execute the commands constructed by the compilation driver.

-Dname[=def] Define a symbol name to the C preprocessor (cpp(l». Equivalent to a #define directive
in the source. If no de! is given, name is defined as '1'.
-E

Run the source file through cpp(l), the C preprocessor, only. Sends the output to the
standard output, or to a file named with the -0 option. Includes the cpp line numbering
information. (See also, the -P option.)

float_option

Floating-point code generation option. Can be one of:

-f68881
Generate in-line code for Motorola MC68881 floating-point processor (supported only on Sun-3 systems).

Sun Release 3.2

Last change: 20 August 1986

35

CC( IV)

USER COMMANDS

CC(IV)

-ffpa

Generate in-line code for Sun Floating Point Accelerator (supported only on
Sun-3 systems).

-fsky

Generate in-line code for Sky floating-point processor (supported only on Sun2).

-fsoft

Generate software floating-point calls (this is the default).

-fswitch
Run-time-switched floating-point calls. The compiled object code is linked at
runtime to routines that support one of the above types of floating point code.
This was the default in previous releases. Only for use with programs that are
floating-point intensive, and must be portable to machines with various
floating-point hardware options.

-fsingle

Use single-precision arithmetic in computations involving only 80at expressions - that
is, do not convert everything to double, which is the default. Note that floating-point
parameters are still converted to double precision, and functions returning values still
return double-precision values.
Although not standard C, certain programs run much faster using this option. Be aware
that some significance can be lost due to lower-precision intermediate values.

-g

Produce additional symbol table information for dbx(l) and dbxtool(l) and pass the -Ig
flag to ld(l). When this option is given, the -0 and -R options are suppressed.

-go

Produce additional symbol table information for adb(l). When this option is given, the
-0 and -R options are suppressed.

-help

Display helpful information about cc.

-Ipathname

Add pathname to the list of directories in which to search for #include files with relative
filenames (not beginning with slash I). The preprocessor first searches for #include files
in the directory containing sourcefile, then in directories named with -I options (if any),
and finally, in lusr/include .

-J

Generate 32-bit offsets in switch statement labels.

-IUb

Link with object library lib (for ld(1».

-Ldir

Add dir to the list of directories containing object-library routines (for linking using
ld(l).

-M

Run only the macro preprocessor on the named C programs, requesting that it generate
makefile dependencies and send the result to the standard output (see make(l) for details
about makefiles and dependencies).

-ooutfile

Name the output file outfile. outfile must have the appropriate suffix for the type of file to
be produced by the compilation (see FILES, below). outfile cannot be the same as
sourcefile (the compiler will not overwrite the source file).

-0

Optimize the object code. Ignored when either --g or -go is used

-p

Prepare the object code to collect data for profiling with prof(l). Invokes a run-time
recording mechanism that produces a mon.out file (at normal termination).

-pg

Prepare the object code to collect data for profiling with gprof(l). Invokes a run-time
recording mechanism that produces a gmon.out file (at normal termination).

-pipe

Use pipes, rather than intermediate files, between compilation stages. (Very cpuintensive.)

-P

Run the source file through cpp(l), the C preprocessor, only. Puts the output in a file
with a .i suffix. Does not include cpp -type line number information in the output

-Qoption prog opt

36

Last change: 20 August 1986

Sun Release 3.2

CC( IV)

USER COMMANDS

CC( IV)

Pass the option opt to the program pro g. The option must be appropriate to that program
and may begin with a minus sign. prog can be one of: as, cpp, inline, or Id.
-Qpath pathname
Insert a directory pathname into the compilation search path (to use alternate versions of
programs invoked during compilation).
-Qproduce sourcetype
Produce source code of the type sourcetype. sourcetype can be one of:
.c
C source (from bb_count) .
.i
Preprocessed C source from cpp (1) .
•0
Object file from as (I) .
.s
Assembler source (from ccom, in line or c2).
-R

Merge data segment with text segment for asCI). Data initialized in the object file produced by this compilation is read-only, and (unless linked with Id -N) is shared between
processes. Ignored when either -g or -go is used.

-s

Do not assemble the program but produce an assembly source file.

-temp=dir

Set directory for temporary files to be dir.

-time

Report execution times for the various compilation passes.

-Uname

Remove any initial definition of the cpp(l) symbol name. (Inverse of the -D option.)

-v

Verbose. Print the version number of the compiler and the name of each program it executes.

-w

Do not print warnings.

ENVIRONMENT
FLOAT_OPTION When no floating-point option is specified, the compiler uses the value of this environ-

ment variable (if set). Recognized values are: f68881, ffpa, fsky, fswitch and fsoft.
FILES
a.out
file.a
file.c
file.d
filej
file .f
file.F
file .iI
file .0
file .p
file .r
file .s
file .S
file.tcov
lliblc2
Iliblccom
lliblcompile
lliblcpp
lliblcrtO.o
lliblFcrtl.o
lliblgcrtO.o
Ilibllibc .a
lliblmcrtO.o
lliblMcrtl.o

Sun Release 3.2

executable output file
library of object files
C source file
tcov(l) test coverage input file
C source file after preprocessing with cpp(1)
FORTRAN 77 source file
FORTRAN 77 source file for cpp(1)
inline expansion file
object file
Pascal source file
Ratfor source file
assembler source file
assembler source for cpp (1)
output from tcov (1)
object code optimizer
compiler
compiler command-line processing driver
macro preprocessor
runtime startoff
startup code for -fsoft option
startofffor profiling with gprof(l)
standard library, see intro (3)
startofffor profiling withprof(l) intro(3)
startup code for -f68881 option

Last change: 20 August 1986

37

CC( IV)

lliblScrtl.o
IliblWcrtl.o
lusrlinclu.tk
lusrlliblbb count
lusrlliblbb link.o
lusrllibllibc y.a
lusrllibllibF77.a
lusrlliblimine
IusrllibllibI77.a
lusrllibllibm.a
lusrllibllibU77.a
lusrl5libllibc.a
lusrl5libllibcy.a
Itmpl*
mon.out
gmon.out

USER COMMANDS

CC(IV)

startup code for -fsky option
startup code for -ffpa option
standard directory for #include files
block counting preprocessor
basic block counting routine
profiling library, see gprof( I) or prof( 1)
FORTRAN 77 library
inline expander of library calls
FORTRAN 77 library
math library
FORTRAN 77 library
System V standard compatibility library, see intro(3V)
System V profiling library, see gprof( 1) or prof( I)
compiler temporary files
file produced for analysis by prof(l)
file produced for analysis by gpro/(l)

SEE ALSO

monitor(3), prof(l), gprof(I), tcov(l), adb(l), ar(I), ld(l), dbx(l), as(I), cpp(l), make(1)
B. W. Kernighan and D. M. Ritchie, The C Programming Language, Prentice-Hall, 1978
UNIX Programming in Programming Utilities for the Sun Workstation

Floating-Point Programmer's Guide/or the Sun Workstation
UNIX Interface Overview

DIAGNOSTICS

The diagnostics produced by C itself are intended to be self-explanatory. Occasional obscure messages
may be produced by the preprocessor, assembler, or loader.
BUGS

The program context given in syntax error messages is taken from the input text after the C preprocessor
has performed substitutions. Therefore, error messages involving syntax errors in or near macro references
or manifest constants may be misleading.

38

Last change: 20 August 1986

Sun Release 3.2

CD( 1)

USER COMMANDS

CD(l)

NAME

cd - change working directory
SYNOPSIS

cd [ directory ]
DESCRIPTION

Directory becomes the new working directory. The process must have execute (search) permission in
directory. If cd is used without arguments, it returns you to your login directory. In csh(l) you may
specify a list of directories in which directory is to be sought as a subdirectory if it is not a subdirectory of
the current directory; see the description of the cdpath variable in csh(l).
SEE ALSO

csh(l), sh(l), pwd(l)

Sun Release 3.2

Last change: 26 April 1983

39

CDC(l)

USER COMMANDS

CDC(I)

NAME

cdc - change the delta commentary of an sees delta
SYNOPSIS
lusr/ucb/sccslcdc -rSID [ -m [ mr/ist ] ] [ -y [ comment] ] filename ...
DESCRIPTION
cdc changes the delta commentary, for the SID specified by the -r option, of each named sees filename.

Delta commentary is defined to be the Modification Request (MR) and comment information normally
specified via the delta command (-m and -y options).
If a directory is named, cdc behaves as though each file in the directory were specified as a narned
filename, except that non-Sees files (last component of the path name does not begin with s.) and unreadable files are silently ignored. If a name of - is given, the standard input is read (see WARNINGS); each line
of the standard input is taken to be the name of an sees file to be processed.
Arguments to cdc, which may appear in any order, consist of options and file names.
OPTIONS
All the described options apply independently to each named file:

-rSID

Specifies the Sees IDentification (SID) string of a delta for which the delta commentary is to
be changed.

-m [mrlist] If the sees file has the v flag set (see admin(l», a list of MR numbers to be added and/or
deleted in the delta commentary of the SID specified by the -r option may be supplied. A null
MR list has no effect.
MR entries are added to the list of MRs in the same manner as that of delta. In order to delete
an MR, precede the MR number with the character! (see EXAMPLES). If the MR to be
deleted is currently in the list of MRs, it is removed and changed into a "comment" line. A
list of all deleted MRs is placed in the comment section of the delta commentary and preceded
by a comment line stating that they were deleted.

If -m is not used and the standard input is a terminal, the prompt MRs? is issued on the standard output before the standard input is read; if the standard input is not a terminal, no prompt
is issued. The MRs? prompt always precedes the comments? prompt (see -yoption).
MRs in a list are separated by blanks and/or tab characters. An unescaped new-line character
terminates the MR list.
Note that if the v flag has a value (see admin(I», it is taken to be the name of a program (or
shell procedure) which validates the correctness of the MR numbers. If a non-zero exit status
is returned from the MR number validation program, cdc terminates and the delta commentary remains unchanged.
-y [comment]
Arbitrary text used to replace the comment(s) already existing for the delta specified by the-r
option. The previous comments are kept and preceded by a comment line stating that they
were changed. A null comment has no effect.

If -y is not specified and the standard input is a terminal, the prompt comments? is issued on
the standard output before the standard input is read; if the standard input is not a terminal, no
prompt is issued. An unescaped new-line character terminates the comment text
The exact permissions necessary to modify the sees file are documented in Source Code Control System.
Simply stated, they are either (1) if you made the delta, you can change its delta commentary; or (2) if you
own the file and directory you can modify the delta commentary.
EXAMPLES

40

Last change: 23 September 1985

Sun Release 3.2

CDC(I)

USER COMMANDS

CDC(I)

tutoria1% cdc -rl.6 -m"bI78-12345 !bI77-S4321 bI79-00001" -ytrouble s.file
adds bI78-12345 and bI79-00001 to the MR list, removes b177-54321 from the MR list, and adds the comment trouble to delta 1.6 of s.file.
tutoria1% cdc -rl.6 s.ftle
MRs? !bI77-S4321 bI78-12345 bl79-00001
comments? trouble
does the same thing.
WARNINGS

If sees file names are supplied to the cdc command via the standard input (- on the command line), then
the -m and -y options must also be used.
FILES

x-file
z-file

(see delta(l»
(see delta(1»

SEE ALSO
admin(I), comb(l), delta(I), get(I), help(I), prs(I), sccs(I), sccsdiff(I), sccsfile(5), va1(I), what(l)

Programming Utilities/or the Sun Workstation.
DIAGNOSTICS
Use help for explanations.

Sun Release 3.2

Last change: 23 September 1985

41

CFLOW( 1)

USER COMMANDS

CFLOW(I )

NAME

cflow- generate C flow graph
SYNOPSIS
cHow [-r] [-ix] [-i_] [ - is printed.
As an example, given the following infile.c:
int
i;

rnainO
{
fO;
gO;
fO;
}

fO
{

i= ho;
}
the command:
cflow -ix file.c
produces the output
1
main: intO, 
2
f: intO, 
3
h:<>
4
i: int, 
5
g:<>
When the nesting level becomes too deep, the -e option of pr(lV) can be used to compress the tab expansion to something less than every eight spaces.
SYSTEM V DESCRIPTION
The System V version of "cflow" in lusrlShin/cHow makes the C preprocessor cpp(l) search in
lusrlSinclude for include files before it searches in lusr/include.
OPTIONS

The following options are interpreted by cjlow:
-r

42

Reverse the "caller:callee" relationship producing an inverted listing showing the callers of each

Last change: 10 April 1986

Sun Release 3.2

CFLOW(I)

USER COMMANDS

CFLOW(I)

function. The listing is also sorted in lexicographical order by callee.

-ix
-i

Include external and static data symbols. The default is to include only functions in the flowgraph.
Include names that begin with an underscore. The default is to exclude these functions (and data if

-ix is used).
-dnurn The num decimal integer indicates the depth at which the flowgraph is cut off. By default this is a
very large number. Attempts to set the cutoff depth to a nonpositive integer will be met with contempt.
DIAGNOSTICS

Complains about bad options. Complains about multiple definitions and only believes the first. Other messages may come from the various programs used (e.g., the C-preprocessor).
SEE ALSO
as(I), cc(1V), cpP(I), lex(I), lint(lV), nm(I), pr(IV), yacc(I).
BUGS

Files produced by lex(l) and yacc(l) cause the reordering of line number declarations which can confuse
cflow. To get proper results, feed cflow the yacc or lex input.

Sun Release 3.2

Last change: 10 April 1986

43

CHECKNR(I)

USER COMMANDS

CHECKNR(I)

NAME

checknr - check nroff/troff files
SYNOPSIS

checknr [ -s] [ -f] [ -8 .xl.yl.x2.y2 ... .xn.yn] [ -c .xl.x2.x3 ... .xn ] [filename .•. J
DESCRIPTION

Checknr checks a list of nroff(l) or troff(l) input files for certain kinds of errors involving mismatched
opening and closing delimiters and unknown commands. If no files are specified, checknr checks the standard input. Delimiters checked are:
(I)

Font changes using \fx ... \tp.

(2)

Size changes using \sx ... \sO.

(3)

Macros that come in open ••• close forms, for example, the .TS and .TE macros which must
always come in pairs.

Checknr knows about the ms(7) and me (7) macro packages.
Checknr is intended to be used on documents that are prepared with checknr in mind. It expects a certain
document writing style for \f and \s commands, in that each \fx must be terminated with \tp and each \sx
must be terminated with \sO. While it will work to directly go into the next font or explicitly specify the
original font or point size, and many existing documents actually do this, such a practice will produce complaints from checknr. Since it is probably better to use the \tP and \sO forms anyway, you should think of
this as a contribution to your document preparation style.
OPTIONS
-s

Ignore \s size changes.

-f

Ignore \f font changes.

-8

Add pairs of macros to the list The pairs of macros are assumed to be those (such as .DS and
.DE) that should be checked for balance. The -8 option must be followed by groups of six characters, each group defining a pair of macros. The six characters are a period, the first macro name,
another period, and the second macro name. For example, to define a pair .BS and .ES, use
-8.BS.ES

-c

define commands which checknr would otherwise complain about as undefined.

SEE ALSO
nrofI(I), troff(I), ms(7), me(7), checkeq(l)
BUGS

There is no way to define a 1 character macro name using -8

44

Last change: 13 March 1984

Sun Release 3.2

CHGRP(l)

USER COMMANDS

CHGRP(l)

NAME

chgrp - change group
SYNOPSIS
cbgrp [ -r] [ -R ] group filename ...
DESCRIPTION
chgrp changes the group-ID of the filename(s) given as arguments to group. The group may be either a
decimal GID or a group name found in the group-ID file,/etc/group.

You must belong to the specified group and be the owner of the file, or be the superuser.
OPTIONS

-r

Force. Do not report errors.

-R

Recursive. chgrp descends through diretories supplied as arguments, setting the specified groupID as it proceeds. When symbolic links are encountered, their group is changed, but they are not
traversed.

FILES

tetc/group
SEE ALSO
chown(2), passwd(5), group(5)

Sun Release 3.2

Last change: 25 July 1986

45

CHMOD( IV)

USER COMMANDS

CHMOD( IV)

NAME

chmod - change mode
SYNOPSIS
chmod [ -tR ] mode filename •••
DESCRIPTION

Change the permissions, or mode, of a file or files. Only the owner of a file (or the superuser) may change
its mode.
The mode of each narned file is changed according to mode, which may be absolute or symbolic.
Absolute Modes
An absolute mode is an octal number constructed from the OR of the following modes:
400
read by owner

200
100

write by owner
execute (search in directory) by owner

040
020
010

read by group
write by group
execute (search) by group
read by others
write by others
execute (search) by others

004
002
001
4000
2000
1000

set user ID on execution
set group ID on execution
sticky bit, (see chmod (2) for more information)

Symbolic Modes
A symbolic mode has the form:

[ who ] op permission [ op permission ]•••
who is a combination of:
u
user's permissions
g
group permissions
o
others
a
all, or ugo

If who is omitted, the default is a, but the setting of the file creation mask (see umask in sh(l) or
csh(l) for more information) is taken into account. When who is omitted, chmod will not override
the restrictions of your user mask.
opis one of:
+
to add the permission
to remove the permission
to assign the permission explicitly (all other bits for that category, owner, group, or others, will be reset).

=

permission is any combination of:
r
read
w
write
x
execute
X
give execute permission if the file is a directory or if there is execute permission for one of the other user
s
set owner- or group-ID. This is only useful with u or g.
t
set the sticky bit to save program text between processes.

The letters u, g, or
class.

0

indicate that permission is to be taken from the current mode for the user-

Omitting permission is only useful with =, to take away all permissions.

46

Last change: 25 July 1986

Sun Release 3.2

CHMOD( IV)

USER COMMANDS

CHMOD(IV)

Multiple symbolic modes, separated by commas, may be given. Operations are performed in the order
specified.
SYSTEM V DESCRIPTION
If who is omitted in a symbolic mode, it does not take the file creation mask into account, but acts as if who
werea.
OPTIONS
-f

-R

Force. chmod will not complain if it fails to change the mode of a file.
recursively descend through directory arguments, setting the mode for each file as described
above. When symbolic links are encountered, their mode is not changed and they are not
traversed.

EXAMPLES
The first example denies write permission to others, the second makes a file executable by all if it is executable by anyone:

chmod o-w file
chmod +X file
SEE ALSO
Is(IV), sh(l), csh(l), chmod(2), chown(8)

Sun Release 3.2

Last change: 25 July 1986

47

CHSH( I)

USER COMMANDS

CHSH(I)

NAME

chsh - change default login shell
SYNOPSIS

chsh usernarne [ shell ]
DESCRIPTION
Chsh changes the login shell field of the user's password file entry. If no shell is specified, the shell reverts
to the default login shell/binlsh. To specify a shell other than Ibinlcsh, you must be the super-user.
EXAMPLES

angel% chsb billlbinlcsb
SEE ALSO
csh(l), passwd(I), passwd(5)

48

Last change: 22 December 1983

Sun Release 3.2

CLEAR ( 1)

USER COMMANDS

CLEAR(I)

NAME
clear - clear screen

SYNOPSIS
clear

DESCRIPTION
Clear clears your screen if this is possible. It looks in the environment for the terminal type and then in
letcltermcap to figure out how to clear the screen.

FILES
letcltermcap

Sun Release 3.2

terminal capability data base

Last change: 12 February 1985

49

USER COMMANDS

NAME

clear_colormap - clear the color map
SYNOPSIS

clear_colormap
DESCRIPTION

Clear_colormap clears your hardware colormap.

50

Last change: 21 August 1985

Sun Release 3.2

USER COMMANDS

CLEAR_FUNCTIONS ( 1 )

NAME

clear functions - reset state of selection service
SYNOPSIS

clear functions
DESCRIPTION

clearJunctions instructs the selection service that no function keys are currently depressed. It is useful in
cases where erroneous programs have reported a key press but not the corresponding release. The usual
symptom for this situation is that all selections are secondary (underscored rather than inverted), even
though no function keys are down.
FILES

lusrlbinlselection svc
SEE ALSO

Editing and the Text Facility, in Windows and Window-Based Tools, Beginner's Guide

Sun Release 3.2

Last change: April 4 1986

51

CLICK ( 1)

USER COMMANDS

CLICK(I)

NAME

click - control the keyboard keystroke click sound
SYNOPSIS
click [ -y ] [ -0

] [

-d keyboard device]

DESCRIPTION
Change the setting of the audible keyboard click. The default is no keyboard click. If you want to turn
clicking on then a good place to do it is in letclrc.local.

Only keyboards that support a clicker respond to this command. At the time of this writing, the only keyboard known to have a clicker is the Sun 3 keyboard
OPTIONS

-y

Yes, enable clicking.

-0

No, disable clicking.

-d keyboard device
Specify the keyboard device being set. The default is Idevlkbd.
SEE ALSO
kb(4S)
DIAGNOSTICS
A short help message is printed if an unknown flag is specified or if the -d switch is used and the keyboard
device name is not supplied. A diagnostic is printed if the keyboard device name can't be opened or is not
a keyboard type device.
BUGS

There is no way to determine the state of the keyboard click setting.

52

Last change: 18 December 1985

Sun Release 3.2

CLOCK ( 1)

USER COMMANDS

CLOCK ( 1)

NAME

clock, clocktool- display the time in a window
SYNOPSIS
clock [ -s] [ -t ] [ -r ] [ -d mdyaw] [ -f]
DESCRIPTION
clock is a standard tool provided with the SunView environment.

clock displays the current time in its own window. In its open state, clock shows the date and time textual
form. In its closed state, clock appears as a clock face which keeps time.
Note: In previous releases clock was known as clocktool. In the current release, clocktool is retained as a
symbolic link to clock.
OPTIONS
-r

-d

causes clock to use a square face with roman numerals in the iconic state. This replaces the
default round clock face.
display date information in a small area just below the clock face. The date information to be
displayed may include:
m
d
Y
a
w

the month,
the day of the month (1-31),
the year,
the string AM or PM, as appropriate,
the day of the week (Sun-Sat).

There is only room for 3 of these, but any 3 may be displayed in any sequence.

-f

Display the date and day of week on the clock face.

-s

start clock with the seconds turned on. By default, the clock starts with seconds turned off, and
updates every minute. With seconds turned on, it updates every second, and, if iconic, displays a
second hand.

-t

Test mode - ignore the real time, and instead run in a loop continuously incrementing the time by
one minute and displaying it.

clock also accepts all of the generic tool arguments discussed in suntoo1s(I).
When open, clock listens for keyboard input, toggling its state on four characters:
s or S

toggles the display of seconds.

torT

toggles the 'test' mode.

SEE ALSO
suntools(I), date(l)
FILES

lusrllib/fontslfixedwidthfonts/sail.r.6

BUGS
If you reset the system time, clock will not reflect the new time until you change its state closed, close it if open. To reset the system time, see date(I).

open it if

The date display doesn't go well with the round clock face.
The clock sometimes freezes. Bringing up the Frame Menu will unstick it.

Sun Release 3.2

Last change: 29 May 1986

53

CMDTOOL(I)

USER COMMANDS

CMDTOOL(l)

NAME

cmdtool - Run a shell (or other program) from the SunView text facility
SYNOPSIS

cmdtool [ -C] [-P n] [program [args] ]
DESCRIPTION
cmdtool is a standard tool provided with the SunView environment.

When invoked, cmdtool runs a program (usually a shell) in a text-based command subwindow. Typed
characters are inserted at the caret. If this program is a shell, it accepts commands and runs programs in
the usual way. (See BUGS below).
Text can be edited anywhere on the command line the same way as in any other text subwindow. Commands and their output are kept in a log which can be scrolled using the scrollbar. The log file can also be
edited, or even saved using the Save command in the text facility's pop-up menu. The Split command, also
in the pop-up menu, can be used to create two or more independently scrolling views of the log.
DEFAULTS OPTIONS

trty/Append_only-.log
TRUE is the standard default; it means that only the command line may be editted. FALSE permits editting of the entire log. See the descripton of Enable Edit below.
trtyllnsert_makes_caret_visible
This entry describes how hard the command subwindow should try to keep the caret visible.
Same_as_for_text
Is the standard default; it means that the setting for
Insert_makes_caret_visible will be taken from the Text category instead
of Tty when a command subwindow is created
If auto scroll
If the caret is showing, and an inserted newline would position it below the
bottom of the screen as determined by trextlLower_context, the text is
scrolled to keep it showing. The amount scrolled is controlled by
lTextlAuto_scroltby. See textedit (1) for more information.
Always
Upon any input action, if the caret is positioned off the screen, it is scrolled
back into view.
trty/Checkpoint_frequency
ois the standard default; it means that no checkpointing will take place. For a value n greater than
zero, checkpointing will take place after every nth edit Each character typed, each Get, and each
Delete counts as an edit If the transcript file is named Itmpltty.txt.OOOxxx, at each checkpoint, an
updated copy of the transcript will be saved in Itmpltty.txt.OOOxxx%%.
trextlEdit back char
Set the character for deleting the character preceding the caret Note: Stty erase has no effect; text
based tools only refer to the defaults database. The standard default is the DEL key.
trextlEdit back word
Set the character for deleting the word preceding the caret Note: Stty werase has no effect; text
based tools only refer to the defaults database. The standard default is CfRL-W.
lTextlEdit back line
Set the character for deleting from the newline preceding the caret to the caret Note: Stty kill has
no effect; text based tools only refer to the defaults database. The standard default is CTRL-U.
COMMANDLINE OPTIONS

54

-C

Redirect system console output to this instance of the cmdtool. This will prevent system error
messages from being printed in unexpected places on the screen. Moreover, since a cmdtool window is scrollable, messages that go off the top of the window can be scrolled back for reexamination.

-p n

Set the checkPoint frequency to n.

Last change: 30 September 1985

Sun Release 3.2

CMDTOOL(l)

USER COMMANDS

CMDTOOL(I)

cmdtool also takes generic tool arguments; see suntools (1) for a list of these arguments.
program [ args]
If a program argument is present, cmdtool executes it Subsequent arguments will be assumed to
be arguments of the program argument, .and will be passed to it for execution. If there are no
arguments, cmdtool runs the program corresponding to the SHELL environment variable. If this
environment variable is not available, then cmdtool runs !bin/she
THE COMMAND SUBWINDOW

The subwindow of cmdtool is a command sub window, which is also found in dbxtool and potentially in
other tools as well. The command subwindow is based on the text facility. For more information about the
text facility, see Windows and Window-Based Tools: Beginner's Guide. The pop-up menu associated with
command subwindow is the same as that for the text facility (see tutedit (1», with one additional item,
Enable Edit. The generic text menu items will not be described here except for Put, then Get, as it
approximates the functionality of StutT in shelltool (1), and is also implemented for shelltool.
Put, then Get
When there is a selection, this item reads Put, then Get. It causes the selection to be copied both
to the shelf and to the caret.
Put, then Get
When there is no selection but there is text on the shelf, Put, then is grayed out, though Get
remains active. Selecting this item causes the contents of the shelf to be copied to the caret. When
there is no selection and nothing is on the shelf, this item is inactive.

Enable Edit
If the defaults entry Append_onlyJog is set to TRUE, but at some point you want to edit the log,
selecting this menu item makes editting the log possible. When the log is editable, this item reads
Disable Edit, and selecting it makes the log read-only before the start of the command line.
Certain text facility accelerators that are especially useful in command subwindows are described here. See
tutedit (1) for more infonnation.
CTRL·RErUR.N

Holding down the control key while typing newline (carriage return) positions the caret at the bottom and scrolls it into view, as detennined by the defaults option ffextILower_context.
CfRL·P is an accelerator for the Put, then Get menu item described above.

CAPS-lock
Bound to F1, it causes subsequent keyboard input to be uppercase. This key is a toggle; striking it
a second time undoes the effect of the first strike.
FILES
Itmpltty .txlnnnnnn

-I.textswrc
SEE ALSO

shelltool(l), suntools( 1), textedit( 1), defaultsedit( 1),
Windows and Window-Based Tools: Beginner's Guide

BUGS
Full terminal emulation is not yet supported. Programs that use CBREAK or RAW mode, NO ECHO, or curses
do not work as expected. Some examples of manifestations of this deficiency include:
To send a command to more other than newline, the desired command must be followed by CfRL-D.
vi comes up in open mode.

The Mh command in mail doesn't work.
The password to su is echoed.

Sun Release 3.2

Last change: 30 September 1985

55

CMDTOOL(I)

CTRL-C

USER COMMANDS

CMDTOOL(I)

from a cmdtool running su but not started from a shell owned by root doesn't work.

•

The select system call never notices input on stdin.

•

rlogin double echos andCTRL-D kills rlogin, not just the program running from iL

Occasionally the program run from cmdtool unexplainably hangs.

56

Last change: 30 September 1985

Sun Release 3.2

USER COMMANDS

CMP( I)

CMP( I)

NAME

cmp - compare two files
SYNOPSIS

cmp [ -I] [ -s ] filel file2
DESCRIPTION
Cmp compares filel andfile2. If filel is '-', cmp reads from the standard input. Under default options,
cmp makes no comment if the files are the same; if they differ, it announces the byte and line number at
which the difference occurred. If one file is an initial subsequence of the other, that fact is noted
OPTIONS
-I

-s

Print the byte number (decimal) and the differing bytes (octal) for each difference.
Print nothing for differing files; return codes only.

SEE ALSO
diff(l), comm(l)
DIAGNOSTICS
Exit code 0 is returned for identical files, I for different files, and 2 for an inaccessible or missing argument

Sun Release 3.2

Last change: 29 April 1983

57

COL { IV)

USER COMMANDS

COL { IV)

NAME

col - filter reverse paper motions
SYNOPSIS

col [-bfbp]
SYSTEM V SYNOPSIS

lusr/5binlcol [ -bfpx ]
DESCRIPTION
col copies the standard input to the standard output and performs line overlays implied by reverse line
feeds (ESc-7 in ASCII) and by forward and reverse half line feeds (Esc-9 and Esc-8). col is particularly use-

ful for filtering multicolurnn output made with the .rt command of nroff and output resulting from use of
the tbl preprocessor.
The control characters SO (ASCII code '017"), and SI (016) are assumed to start and end text in an alternate
character set The character set (primary or alternate) associated with each printing character read is
remembered; on output, so and SI characters are generated where necessary to maintain the correct treatment of each character.
All control characters are removed from the input except space, backspace, tab, return, newline, ESC (033)
followed by one of 7, 8, 9, SI, SO, and vr (013). This last character is an alternate form of full reverse line
feed, for compatibility with some other hardware conventions. All other non-printing characters are
ignored.
SYSTEM V DESCRIPTION

The System V version of col converts spaces to tabs by default
OPTIONS

-b

col assumes that the output device in use is not capable of backspacing. In this case, if several
characters are to appear in the same place, only the last one read will be taken.

-f

Fine. Although col accepts half line motions in its input, it normally does not produce them on
output Instead, text that would appear between lines is moved to the next lower full-line boundary. The -f option suppresses this treatment - in this case the output from col may contain forward half line feeds (Esc-9), but will still never contain either kind of reverse line motion.

-b

Convert strings of blanks to tabs to decrease the printing time.

-p

Pass escape-sequences that col does not know about to the output, rather than stripping them out.
This option is highly discouraged unless you are fully aware of the position of the escape
sequences within the text

SYSTEM V OPTIONS

The -b, -f, and -p options are described above.
-x

Suppress converting spaces to tabs.

SEE ALSO

troff(1), tbl{l)
BUGS

col can't back up more than 128 lines.
At most 1600 characters, including backspaces, are allowed on a line.
Local vertical motions that would result in backing up over the first line of the document are ignored. As a
result, the first line must not have any superscripts.

58

Last change: 29 March 1986

Sun Release 3.2

COLCRT(l)

USER COMMANDS

COLCRT(l)

NAME

colcrt - filter nroff output for CRT previewing
SYNOPSIS

colert [ - ] [ -2 ] [filename ... ]
DESCRIPTION

Colert provides virtual half-line and reverse line feed sequences for terminals without such capability, and
on which overstriking is destructive. Half-line characters and underlining (changed to dashing '-') are
placed on new lines in between the normal output lines.
OPTIONS

Suppress all underlining - especially useful for previewing allboxed tables from tbl(l).
-2

Print all half-lines, effectively double spacing the output Normally, a minimal space output format is used which suppresses empty lines. Colert never suppresses two consecutive empty lines,
however. The -2 option is useful for sending output to the line printer when the output contains
superscripts and subscripts which would otherwise be invisible.

EXAMPLE

A typical use of eolert would be
tbl exum2.n 1 nroff -ms 1 colcrt - 1 more
SEE ALSO

nroff(l), troff(1), col(1V), more(l), ul(1)
BUGS

Can't back up more than 102 lines.
General overstriking is lost; as a special case 'I' overstruck with '-' or underline becomes' +'.
Lines are trimmed to 132 characters.
Some provision should be made for processing superscripts and subscripts in documents which are already
double-spaced.

Sun Release 3.2

Last change: 13 April 1983

59

COLRM(I)

USER COMMANDS

COLRM(I)

NAME

colrm - remove columns from a file
SYNOPSIS

colrm [starteol [endeol ] ]
DESCRIPTION

Colrm removes selected columns from a text file. The text is is taken from standard input and copied to the
standard output with the specified columns removed.
If only starteol is specified, the columns of each line are removed starting with starteol and extending to
the end of the line. If both starteol and endeol are specified, all columns between starteol and endeol,
inclusive, are removed.
Column numbering starts with column 1.
SEE ALSO

expand(l)

60

Last change: 13 April 1983

Sun Release 3.2

COMB(l)

USER COMMANDS

COMB(l)

NAME

comb - combine sees deltas
SYNOPSIS

lusrlsccslcomb [ -0 ] [ --s ] [ -p SID] [ -c list] filename ...
DESCRIPTION

Comb generates a shell procedure (see sh(l» which, when run, will reconstruct the given sees files. If a
directory is named, comb behaves as though each file in the directory were specified as a named file,
except that non-sees files Oast component of the path name does not begin with s.) and unreadable files
are silently ignored. If a name of - is given, the standard input is read; each line of the standard input is
taken to be the name of an sees file to be processed; non-sees files and unreadable files are silently
ignored. The generated shell procedure is written on the standard output.
OPTIONS

Options are explained as though only one named file is to be processed, but the effects of any option apply
independently to each named file.
-p SID The sees IDentification string (SID) of the oldest delta to be preserved. All older deltas are discarded in the reconstructed file.

-c list

A list of deltas to be preserved. All other deltas are discarded. See get(1) for the syntax of a list.

-0

For each get --e generated, the reconstructed file is accessed at the release of the delta to be
created. In the absence of the -0 option, the reconstructed file is accessed at the most recent
ancestor. Use of the -0 option may decrease the size of the reconstructed sees file. It may also
alter the shape of the delta tree of the original file.

--s

Generate a shell procedure which, when run, will produce a report giving, for each file: the file
name, size (in blocks) after combining, original size (also in blocks), and percentage change computed by:
100-.-(original---combinedfr original
It is recommended that before any sees files are actually combined, you should use this option to
determine exactly how much space is saved by the combining process.

If no options are specified, comb preserves only leaf deltas and the minimal number of ancestors needed to
preserve the tree.
FILES
s.COMB

comb?????

The name of the reconstructed sees file.
Temporary.

SEE ALSO

sccs(l), admin(l), delta(l), get(l), help(l), prs(1), sccsfile(5).
Programming Utilities/or the Sun Workstation.
DIAGNOSTICS

Use help (1) for explanations.
BUGS

Comb may rearrange the shape of the tree of deltas. It may not save any space; in fact, it is possible for the
reconstructed file to actually be larger than the original.

Sun Release 3.2

Last change: 6 March 1984

61

COMM(l)

USER COMMANDS

COMM(l)

NAME

comm - select or reject lines common to two sorted files
SYNOPSIS
comm [ - [123] ] file1 file2
DESCRIPTION

Comm reads filel and file2, which should be ordered in ASCII collating sequence (see sort(l V», and produces a three column output: lines only infilel; lines only infile2; and lines in both files. The filenamemeans the standard input
Flags 1, 2, or 3 suppress printing of the corresponding column. Thus comm -12 prints only the lines common to the two files; comm -23 prints only lines in the first file but not in the second; comm -123 does
nothing.
SEE ALSO
cmp(l), diff(l), uniq(l)

62

Last change: 17 February 1986

Sun Release 3.2

COMPACT(I)

USER COMMANDS

COMPACT(I)

NAME

compact, uncompact, ccat - compress and uncompress files, and cat them
SYNOPSIS
compact [ filename •.• ]
uncompact [ filename. •• ]
ccat [ filename ••• ]
DESCRIPTION

Compact compresses the named files using an adaptive Huffman code. If no file names are given, the standard input is compacted to the standard output. Compact operates as an on-line algorithm. Each time a
byte is read, it is encoded immediately according to the current prefix code. This code is an optimal Huffman code for the set of frequencies seen so far. It is unnecessary to prepend a decoding tree to the
compressed file since the encoder and the decoder start in the same state and stay synchronized Furthermore, compact and uncompact can operate as filters. In particular:
.•• I compact I uncompact I •••
operates as a (very slow) no-oPe
When an argument file is given, it is compacted and the resulting file is placed infile.C; file is removed.
The first two bytes of the compacted file code the fact that the file is compacted. This code is used to
prohibit recompaction.
The amount of compression to be expected depends on the type of file being compressed. Typical values
of compression are: Text (38%), Pascal Source (43%), C Source (36%) and Binary (19%). These values
are the percentages of file bytes reduced.

Uncompact restores the original file from a file calledfile.C which was compressed by compact. If no file
names are given, the standard input is uncompacted to the standard output
Ccat cats the original file from a file compressed by compact. without uncompressing the file.
FILES

*.C

compacted file created by compact, removed by uncompact

SEE ALSO
Gallager, Robert G., 'Variations on a Theme of Huffman', I.E.E.E. Transactions on Information Theory.
vol. IT-24, no. 6, November 1978, pp. 668 - 674.

Sun Release 3.2

Last change: 1 November 1983

63

COMPRESS ( 1 )

USER COMMANDS

COMPRESS ( 1 )

NAME

compress, uncompress, zcat - compress and expand files
SYNOPSIS

compress [ -c] [ -f] [ -v ] [ -b bits] [filename . .. ]
uncompress [ -c] [ -v] [filename . .. ]
zeat [filename . .. ]
DESCRIPTION

compress reduces the size of the named files using adaptive Lernpel-Ziv coding. Whenever possible, each
file is replaced by one with the extension .Z, while keeping the same ownership modes, access and
modification times. If no files are specified, the standard input is compressed to the standard output.
The amount of compression obtained depends on the size of the input, the number of bits per code, and the

distribution of common substrings. Typically, text such as source code or English is reduced by 50-60%.
Compression is generally much better than that achieved by Huffman coding (as used in pack), or adaptive
Huffman coding (compact), and takes less time to compute. The bits parameter specified during compression is encoded within the compressed file, along with a magic number to ensure that neither decompression of random data nor recompression of compressed data is subsequently allowed.
Compressed files can be restored to their original form using uncompress.

zeat produces uncompressed output on the standard output, but leaves the compressed

.z file intact

OPTIONS

-c

Write to the standard output; no files are changed. The nondestructive behavior of zcat is identical
to that of uncompress -c.

-f

Force compression of name, even if it does not actually shrink or the corresponding name.z file
already exists.
Except when run in the background under Ibinlsh, if -f is not given and compress is run in the
foreground, the user is prompted as to whether an existing name file should be overwritten.

.z

-v

Verbose. Display the percentage reduction for each file compressed.

-b bits Set the upper limit (in bits) for common substring codes. bits must be between 9 and 16 (16 is the
default).
DIAGNOSTICS

Exit status is normally 0; if the last file was not compressed because it became larger, the status is 2. H an
error occurs, exit status is 1.
Usage: compress [-fvc] [-b maxbits] [file ...]
Invalid options were specified on the command line.
Missing maxbits Maxbits must follow -b.

file: not in compressed format
The file specified to uncompress has not been compressed.
file: compressed with xx bits, can only handle yy bits
file was compressed by a program that could deal with more bits than the compress code on this
machine. Recompress the file with smaller bits.
file: already has Z suffix -- no change
The file is assumed to be already compressed. Rename the file and try again.
file already exists; do you wish to overwrite (y or n)?
Respond "y" if you want the output file to be replaced; "n" if not.
uncompress: corrupt input
A SIGSEGV violation was detected, which usually means that the input file is corrupted.

64

Last change: 17 July 1986

Sun Release 3.2

COMPRESS ( 1 )

USER COMMANDS

COMPRESS ( 1 )

Compression: xx.xx%
Percentage of the input saved by compression. (Relevant only for -v.)
-- not a regular file: unchanged
When the input file is not a regular file, (e.g. a directory), it is left unaltered.
-- has xx other links: unchanged
The input file has links; it is left unchanged. See In (1) for more information.
-- file unchanged
No savings are achieved by compression. The input remains uncompressed.
SEE ALSO

A Technique for High Performance Data Compression, Terry A. Welch, IEEE Computer, vol. 17, no. 6
(June 1984), pp. 8-19.
compact( 1), pack( 1)

BUGS
Although compressed files are compatible between machines with large memory, -b12 should be used for
file transfer to architectures with a small process data space (64KB or less).

compress should be more flexible about the existence of the .Z suffix.

Sun Release 3.2

Last change: 17 July 1986

65

CP( 1)

USER COMMANDS

CP(I)

NAME

cp - copy files
SYNOPSIS

cp [ -i] [ -p ] filel file2
cp [ -i] [-p] [ -rR ]file ... directory
DESCRIPTION
filel is copied onto file2. The mode and owner of file2 are preserved if it already existed; the mode of the
source file, modified by the current umask, is used otherwise.

In the second form, one or more namedfiles are copied into directory with their original filenames.
cp refuses to copy a file onto itself.
OPTIONS

-i

Interactive: prompt the user with the name of the file whenever the copy would overwrite an old
file. Answering with 'y' means that cp should go ahead and copy the file. Any other answer will
prevent cp from overwriting the file.

-p

Preserve: attempt to preserve (duplicate) in its copies the modification times and modes of the
source files, ignoring the present umask.

-r
-R

Recursive: if any of the source files are directories, cp copies each subtree rooted at that name; in
this case the destination must be a directory.

EXAMPLES
To make a backup copy of goodies:
% cp goodies old.goodies

To copy an entire directory hierarchy:
% cp -r /usr/wendy/src /usr/wendylbackup

However, BEWARE of a recursive copy like this one:
% cp -r /usr/wendy/src /usr/wendy/srdbackup
which keeps copying files until it fills the entire file system.
SEE ALSO
cat(1V), pr(1V), mv(I), rcp(IC)

66

Last change: 16 February 1984

Sun Release 3.2

CPIO( 1)

USER COMMANDS

CPIO( 1)

NAME

cpio - copy file archives in and out
SYNOPSIS
cpio -0 [ aBcv ]

cpio -i [ bcdfmrsStuv6] [patterns]
cpio -p [adlmruv] directory
DESCRIPTION
cpio copies files into and out from a cpio copy archive. The archive (built by cpio -0) contains pathname
and status information, along with the contents of one or more archived files.
OPTIONS
cpio -0 Copy out as an archive. Reads the standard input for a list of pathnames, then copies the named
files to the standard output in archive form - including pathname and status information.

a

Reset the access times of input files after they have been copied.

B

Input/output is to be blocked at 5120 bytes to the record This does not apply to the pass
option. This option is only meaningful with data directed to or from raw magnetic devices, such as Idev/rmt?

c

Write header information in ASCII character form for portability.

v

Verbose option. A list of filenames is displayed When used with the t option, the table
of contents looks like the output of an Is -I command (see ls(1 V».

cpio -i Copy in an archive. Reads in an archive from the standard input and extracts files with names
matching filename substitution patterns, supplied as arguments.
patterns are similar to those in sh or csh, save that within cpio, the metacharacters ?, * and [••. ]
also match the slash (I) character. If no patterns are specified, the default is * (select all files).
b

Swap both bytes and halfwords after reading in data.

d

directories should be created as needed.

f

Copy in all files except those matching patterns.

m

Retain previous file modification time. This option is ineffective on directories that are
being copied.

r

Interactively rename files. If the user types a null line, the file is skipped.

s

Swap bytes after reading in data

S

Swap halfwords after reading in data.

t

Print a table of contents of the input archive. No files are created.

u

Copy unconditionally. Normally, an older file will not replace a newer file with the same
name.

6

Process a UNIX Version 6 file or files.

cpio -p One pass. Copies out and in in a single operation. Destination pathnames are interpreted relative
to the named directory .
Whenever possible, link files rather than copying them.
EXAMPLES
To copy the contents of a directory into an archive:

tutorial% Is I cpio -0 > Idev/mtO

Sun Release 3.2

Last change: 17 February 1986

67

CPIO( 1)

USER COMMANDS

CPIO( 1)

To duplicate the olddir directory hierarchy in the newdir directory:
tutorial% cd olddir
tutorial% find • -depth -print I cpio -pdl newdir
The trivial case
find • -depth -print

I cpio -oB

>/dev/rmtO

can be handled more efficiently by:
find. -cpio ldev/rmtlOm

cpio archive tapes from other sites may have bytes swapped within the archive. Although the s option only
swaps the data bytes and not those in the header cpio recognizes tapes like this and swaps the bytes in the
header automatically.
SEE ALSO

ar(1), find(I), cpio(5), tar(l)

BUGS
Pathnames are restricted to 128 characters. If there are too many unique linked files, cpio runs out of
memory and linking information is lost thereafter. Only the superuser can copy special files.

68

Last change: 17 February 1986

Sun Release 3.2

CPP( 1)

USER COMMANDS

CPP( 1)

NAME

cpp - the C language preprocessor
SYNOPSIS
Ilib/cpp [-P] [-c] [-M] [ -Uname ] [ -Dname ] [-Dname=def] [-T] [ -R] [ -Idir ]

[ifile [ofile ] ]
DESCRIPTION
Cpp is the C language preprocessor which is invoked as the first pass of any C compilation using the
cc(lV) command (cpp may optionally be invoked as the first pass of a FORTRAN 77 or Pascal compilation - see [17 (1) or pc (1». Thus the output of cpp is designed to be in a form acceptable as input to the
next pass of the compiler. The preferred way to invoke cpp is through the cc (1 V) command. See m4 (1 V)
for a general macro processor.

Cpp optionally accepts two file names as arguments. [file and ofile are respectively the input and output
for the preprocessor. They default to standard input and standard output if not supplied.
OPTIONS

-P

Preprocess the input without producing the line control information used by the next pass of the C
compiler.

-C

Pass all comments (except those which appear on cpp directive lines) through the preprocessor.
By default, cpp strips out C-style comments.

-M

Generate a list of makefile dependencies to the standard output. This list indicates that the object
file which would be generated from the input file depends on the input file and all the include files
referenced.

-Uname
Remove any initial definition of name, where name is a reserved symbol that is predefined by the
particular preprocessor. Following is the current list of these possibly reserved symbols. On Sun
computers, unix, m68k, and sun are defined (mc68000 is defined as well for backward compatibility). On Sun-2 computers, M68010 is also defined (mc68010 is defined as well for backward
compatibility); on Sun-3 computers, M68020 is also defined (mc68020 is defined as well for
backward compatibility).
ibm, gcos, os, tss, unix
operating system:
interdata, pdpl1, u370, u3b, u3b5, vax, m68k, M68010, M68020,
hardware:
sun
RES,RT
UNIX system variant:
tint (1 V):
lint

-Dname
Define name as 1 (one). This is the same as if a -Dname=l option appeared on the cpp command
line, or as if a #define name 1 line appeared in the source file that cpp is processing.

-Dname=def
Define name as if by a #define directive. This is the same as if a #define name de[ line
appeared in the source file that cpp is processing. The -D option has lower precedence than the
-U option. That is, if the same name is used in both a -U option and a -D option, the name will
be undefined regardless of the order of the options.
-T

Use only the first eight characters for distinguishing different preprocessor names. This option is
include for backward compatibility with systems which always use only the first eight characters.

-Idir

Change the algorithm for searching for #include files whose names do not begin with / to look in
dir before looking in the directories on the standard list. Thus, #include files whose names are
enclosed in " " will be searched for first in the directory of the current source file, then in directories named in -I options, and last in directories on a standard list. For #include files whose
names are enclosed in <>, the directory of the ifile argument is not searched. See the section entitled DETAILS below, for exact details of the search order.

Sun Release 3.2

Last change: 20 February 1986

69

CPP(I)

USER COMMANDS

-R

CPP( 1)

Allow recursive macros.

DIRECTIVES
All cpp directives start with lines begun by #. White space (blanks or tabs) can appear after the #. The

directives are:
#define nam£ token-string
Replace subsequent instances of nam£ with token-string.
#define nam£ ( arg, •••, arg) token-string
There can be no space between nam£ and the '('. Replace subsequent instances of nam£ followed
by a '(', a list of comma-separated tokens, and a '(' by token-string where each occurrence of an
arg in the token-string is replaced by the corresponding token in the comma-separated list.
#Undefnam£
Forget the definition of nam£ (if any) from now on.
#include "filenam£"
#include 
Include at this point the contents of filenam£ (which is then run through cpp). When the
 notation is used, filename is only searched for in the standard places. See DETAILS
below.
#line integer-constant ''filenam£''
Generate line control information for the next pass of the C compiler. Integer-constant is interpreted as the line number of the next line and filenam£ is interpreted as the file where it comes
from. If ''filenam£'' is not given, the current filename is unchanged.
#endif comment
Ends a section of lines begun by a test directive (#if, #ifdef, or #ifndef). Each test directive must
have a matching #endif. The comm£nt can be used to associate the #endif with its opening #if.
#ifdef nam£
The lines following will appear in the output if and only if nam£ has been the subject of a previous
#define or a -D option without being the subject of an intervening #Undef.
#ifndef nam£
The lines following will not appear in the output if and only if name has been the subject of a previous #define or a -D option without being the subject of an intervening #Undef.
#if constant-expression
Lines following will appear in the output if and only if the constant-expression evaluates to
nonzero. All binary non-assignment C operators, including &&, II, and " are legal in constantexpression. The?: operator, and the unary -, !, and - operators, are also legal in constantexpression. The precedence of the operators is the same as defined by the C language. There is
also a unary operator defined, which can be used in constant-expression in these two forms:
defined ( nam£ ) or defined nam£. This allows the effect of #ifdef and lifndef in a #if directive.
Only these operators, integer constants, and names which are known by cpp should be used in
constant-expression. In particular, the sizeof operator is not available.
#else cOmm£ntary
Reverses for the following lines the notion of the test directive currently in effect. So if lines previous to this directive are ignored, the following lines will appear in the output, and vice versa.
The cOmm£ntary can be used to associate the #else with its opening #if.

The test directives and corresponding #else directives can be nested.
DETAILS

Directory search order for #include files is:
1. the directory of the file which contains the #include request (that is, #include is relative to the file
being scanned when the request is made)

70

Last change: 20 February 1986

Sun Release 3.2

CPP( 1)

USER COMMANDS

CPP( 1)

2. the directories specified by -I options, in left-to-right order.
3. the standard directory(s) (/usr/include on UNIX systems).

Special Names: Two special names are understood by

cpp. The name __LINE__ is defined as the
current line number (a decimal integer) as known by cpp, and __FILE__ is defined as the current
filename (a C string) as known by cpp. They can be used anywhere (including in macros) just as any other
defined name.

A newline terminates a character constant or quoted string.
An escaped newline (that is, a backslash immediately followed by a newline) may be used in the body
of a #define statement to continue the definition onto the next line. The escaped newline is not included in
the macro body.

Comments are removed (unless the -C option is used on the command line). Comments are also
ignored, except that a comment terminates a token.
Macro formal parameters are recognized in #define bodies even inside character constants and quoted
strings. The output from:
#define abc(a) '\a'
abc (xyz)
is the seven characters '\xyz' (space, single-quote, escape character, x, y, z, single-quote). Macro names
are not recognized inside character constants or quoted strings during the regular scan. Thus:
#define abc xyz
printf(" abc");
does not expand 'abc' in the second line, because it is inside a quoted string which is not part of a #define
macro definition.

Macros are not expanded while processing a #define or #Undef. Thus:
#define abc bletch
#define xyz abc
#Undefabc
xyz
produces 'abc'. The token appearing immediately after a #ifdef or #ifndef is not expanded.

Macros are not expanded during the scan which determines the actual parameters to another macro
call. Thus:
#define reverse(first,second)second first
#define greeting hello
reverse~eeting,

#define greeting goodbye
)

produces' goodbye' (and warns about the redefinition of 'greeting').

Output consists of a copy of the input file, with modifications, plus lines of the form:
# lineno "filename" "level" -

indicating the original source line number and filename of the following
output line and whether this is the first such line after an include file has been entered (level=1), the first
such line after an include file has been exited (level=2), or any other such line (level is empty).

FILES
lusrlinclude

standard directory for #include files

SEE ALSO

cc(lV), m4(lV), t77(1), pc(l).
DIAGNOSTICS
The error messages produced by cpp are intended to be self-explanatory. The line number and filename
where the error occurred are printed along with the diagnostic.

Sun Release 3.2

Last change: 20 February 1986

71

CPP( 1)

USER COMMANDS

CPP( 1)

NOTES

When newline characters were found in argument lists for macros to be expanded, some previous versions
of cpp put out the newlines as they were found and expanded. The current version of cpp replaces these
newlines with blanks.

72

Last change: 20 February 1986

Sun Release 3.2

CRYPf(l)

USER COMMANDS

CRYPf( 1)

NAME

crypt - encode/decode
SYNOPSIS

crypt [password]
DESCRIPTION
crypt encrypts and decrypts the contents of a file. crypt reads from the standard input and writes on the
standard output The password is a key that selects a particular transformation. If no password is given,
crypt demands a key from the terminal and turns off printing while the key is being typed in. crypt

encrypts and decrypts with the same key:
tutorial% crypt key encrypted.file
tutorial% crypt key  ( and) form separate words; if paired, the pairs form single words. These shell metacharacters
can be made part of other words, and their special meaning can be suppressed by preceding them with a
backslash (\). A NEWLINE preceded by a \ is equivalent to a SPACE.

In addition, a string enclosed in matched pairs of single-quotes ( , ), double-quotes (" ), or backquotes ( .. ),
forms a partial word; metacharacters in such a string, including any SPACE or TAB characters, do not form
separate words. Within pairs of backquote ( .. ) or double-quote ( " ) characters, a NEWLINE preceded by a
backslash (\) gives a true NEWLINE character. Additional functions of each type of quote are described,
below, under Variable Substitution. Command Substitution. and Filename Substitution.
When the shell's input is not a terminal, the character # introduces a comment that continues to the end of
the input line. Its special meaning is suppressed when preceded by a \ or enclosed in matching quotes.
Command Line Parsing
A simple command is composed of a sequence of words. The first word (that is not part of an 110 redirection) specifies the command to be executed. A simple command, or a set of simple commands separated by
I or 1& characters, forms a pipeline. With I, the standard output of the preceding command is redirected to
the standard input of the command that follows. With I &, both the standard error and the standard output
are redirected through the pipeline.

Pipelines can be separated by semicolons ( ; ), in which case they are executed sequentially. Pipelines that
are separated by && or II form conditional sequences in which the execution of pipelines on the right
depends upon the success or failure, respectively, of the pipeline on the left.
A pipeline or sequence can be enclosed within parentheses "( )" to form a simple command that can be a
component in a pipeline or sequence.
A sequence of pipelines can be executed asynchronously, or "in the background" by appending an &;
rather than waiting for the sequence to finish before issuing a prompt, the shell displays the job number
(see Job Control. below) and associated process IDs, and prompts immediately.
History Substitution
History substitution allows you to use words from previous command lines in the command line you are
typing. This simplifies spelling corrections and the repetition of complicated commands or arguments.
Command lines are saved in the history list, the size of which is controlled by the history variable. The
most recent command is retained in any case. A history substitution begins with a ! (although you can
change this with the bistchars variable) and may occur anywhere on the command line; history substitutions do not nest. The! can be escaped with \ to suppress its special meaning.

Input lines containing history substitutions are echoed on the terminal after being expanded, but before any
other substititions take place or the command gets executed.
Event Designators
An event designator is a reference to a command-line entry in the history list
!
Start a history subsititution, except when followed by a SPACE, TAB, NEWLINE,

=

or (.
Refer to the previous command By itself, this substitution repeats the previous command.
!n
Refer to command-line n. !-n Refer to the current command-line minus n.
!str
Refer to the most recent command starting with str.
!?str[?] Refer to the most recent command containing str.
!{...}
insulate a history reference from adjacent characters (if necessary).

!!

Word Designators

A : separates the event specification from the word designator. It can be omitted if the word designator
begins with a A, $, *, - or %.
#
The entire command line typed so far.
The first input word (command).
n
The n 'th argument

o

76

Last change: 24 July 1986

Sun Release 3.2

CSH( 1)

USER COMMANDS

$
%

x-y

*
x*
x-

CSH( 1)

The first argument, that is, 1.
The last argument
The word matched by (the most recent) ?s search.
A range of words; -y Abbreviates O-y.
All the arguments, or a null value if there is just one word in the event.
Abbreviates x-So
Like x* but omitting word $.

Modifiers

After the optional word designator, you can add a sequence of one or more of the following modifiers, each
preceded by a :.
Remove a trailing pathname component, leaving the head.
Remove a trailing suffix of the form" .xxx" , leaving the basename.
Remove all but the suffix.
e
s1l/r[1] Substitute r for l.
Remove all leading pathname components, leaving the tail.
t
Repeat the previous substitution.
&
Apply the change globally, prefixing the above, for example, 'g&'.
g
Print the new command but do not execute it.
p
Quote the substituted words, escaping further substitutions.
q
Like q, but break into words at each SPACE, TAB or NEWLINE.
x
h
r

Unless preceded by a g the modification is applied only to the first string that matches l; an error results if
no string matches.
The left-hand side of substitutions are not regular expressions, but character strings. Any character can be
used as the delimiter in place of I. A backslash quotes the delimiter character. The character &, in the
right hand side, is replaced by the text from the left-hand-side. The & can be quoted with a backslash. A
null I uses the previous string either from a I or from a contextual scan string s from !?s. You can omit the
rightmost delimiter if a NEWLINE immediately follows r; the rightmost? in a context scan can similarly be

omitted.
Without an event specification, a history reference refers either to the previous command, or to a previous
history reference on the command line (if any).
Quick Substitution
Al Ar[A] This is equivalent to the history substitution: !:sAIAr[A].
Aliases

The C-Shell maintains a list of aliases that you can create, display, and modify using the alias and unalias
commands. The shell checks the first word in each command to see if it matches the name of an existing
alias. If it does, the command is reprocessed with the alias definition replacing its name; the history substitution mechanism is made available as though that command were the previous input line. This allows history substitutions, escaped with a backslash in the definition, to be replaced with actual command-line
arguments when the alias is used. If no history substitution is called for, the arguments remain unchanged.
Aliases can be nested. That is, an alias definition can contain the name of another alias. Nested aliases are
expanded before any history substitutions is applied. This is useful in pipelines such as
alias 1m 1s -1 \!* I more'
which when called, pipes the output of Is(IV) through more (1).
Execpt for the first word, the name of the alias may not appear in its definition, nor in any alias referred to
by its definition. Such loops are detected, and cause an error message.
1/0 Redirection

The following metacharacters indicate that the subsequent word is the name of a file to which the
command's standard input, standard output, or standard error is redirected; this word is variable, command,
and filename expanded separately from the rest of the command.

Sun Release 3.2

Last change: 24 July 1986

77

CSH( 1)

USER COMMANDS

<

CSH(1 )

Redirect the standard input

«word
Read the standard input, up to a line that is identical with word, and place the resulting lines in a
temporary file. Unless word is escaped or quoted, variable and command substitutions are performed on these lines. Then, invoke the pipeline with the temporary file as it's standard input
word is not subjected to variable, filename or command substitution, and each line is compared to
it before any substitutions are performed by the shell.

>

>!

>& >&!
Redirect the standard output to a file. If the file does not exist, it is created. If it does exist, it is
overwritten; its previous contents are lost.
When set, the variable noclobber prevents destruction of existing files. It also prevents redirection to terminals and Idevlnull, unless one of the! forms is used. The & forms redirect both standard output and the the standard error (diagnostic output) to the file.

»

»&

»!

»&!

Append the standard output Like >, but places output at the end of the file rather than overwriting
it If noclobber is set, it is an error for the file not to exist, unless one of the ! forms is used The
& forms append both the standard error and standard output to the file.
Variable Substitution
After an input line is aliased and parsed, and before each command is executed, variable substitution is performed 110 redirections are recognized before variable expansion is applied, and are variable-expanded
separately. Strings enclosed in backquotes (" ), even when they contain variable references, are interpreted
later (see Command Substitution). Otherwise, variable substitution is performed on the command name
and argument list together.
The C-Shell maintains a set of variables, each of which is composed of a name and a value. A variable
name consists of up to 20 letters and digits, and starts with a letter (the underscore is considered a letter).
A variable's value is a space-separated list of zero or more words. A references to a variable starts with a
$, and is replaced the words of that variable's value, by selected words from the value, or by information
about the variable, as described below. Braces can be used to insulate the reference from subsequent characters, which might otherwise be interpreted as part of it
Variable substitution can be suppressed by preceding the $ with a \, except within double-quotes where it
always occurs. Within single-quotes, variable substitution is suppressed. A $ is escaped if followed by a
SPACE, TAB orNEWUNE.
Variables can be created, displayed, or destroyed using the set and unset commands. Some variables are
maintained or used by the shell. For instance, the argv variable contains an image of the shell's argument
list Of the variables used by the shell, a number are toggles; the shell does not care what their value is,
only whether they are set or not
Numerical values can be operated on as numbers (as with the @ builtin). With numeric operations, an
empty value is considered to be zero; the second and subsequent words of multiword values are ignored.
For instance, when the verbose variable is set to any value (including an empty value), command input is
echoed on the terminal.
Command and filename substitution is subsequently applied to the words that result from the variable substitution, except when suppressed by double-quotes, when noglob is set (suppressing filename substitution), or when the reference is quoted with the :q modifier. Within double-quotes, a reference is expanded
to form (a portion of) a quoted string; multiword values are expanded to a string with embedded SPACEs.
When the :q modifier is applied to the reference, it is expanded to a list of SPACE-separated words, each of
which is quoted to prevent subsequent command or filename substitutions.
Except as noted below, it is an error to refer to a variable that is not set

$var
${var} These

78

are replaced by words from the value of var, each separated by a SPACE. If var is an
Last change: 24 July 1986

Sun Release 3.2

CSH( 1)

USER COMMANDS

CSH( 1)

environment variable, its value is returned (but : modifiers and the other forms given below are
not available).
$var [index]
${var [index]}

These select only the indicated words from the value of var. Variable substitution is applied to
index, which may consist of (or result in) a either single number, two numbers separated by a-,
or an asterisk. Words are indexed starting from '1'; a * selects all words. If the first number of a
range is omitted (as with '$argv[-2]'), it defaults to '1'. If the last number of a range is omitted
(as with '$argv[1-]'), it defaults to $#var (the word count). It is not an error for a range to be
empty if the second argument is omitted (or within range).

$#name
${#name}

These give the number of words in the variable.
$0

This substitutes the name of the file from which command input is being read. An error occurs if
the name is not known.

$n

${n} Equivalent to $argv[n].

$*

Equivalent to $argv[ *].

The modifiers :b, :t, :r, :q and :x can be applied (see History Substitution), as can :gb, :gt and :gr. If
braces ( { } ) are used, then the modifiers must appear within the braces. The current implementation allows
only one such modifier per expansion.
The following references may not be modified with: modifiers.
$?var
${?var} Substitutes the string' l' if var is set or '0' if it is not set

$?O

Substitutes' l' if the current input filename is known, or '0' if it is not

$$

Substitute the process number of the (parent) shell.

$<

Substitutes a line from the standard input, with no further interpretation thereafter. It can be used
to read from the keyboard in a C-Shell script

Command and Filename Substitutions
Command and filename substitutions are applied selectively to the arguments of builtin commands. Portions of expressions that are not evaluated are not expanded. For non-builtin commands, filename expansion of the command name is done separately from that of the argument list; expansion occurs in a subshell, after I/O redirection is performed
Command Substitution
A command enclosed by backquotes (' ... ' ) is performed by a subshell. Its standard output is broken into
separate words at each SPACE, TAB and NEWUNE; null words are discarded This text replaces the
backquoted string on the current command line. Within double-quotes, only NEWLINES force new words;
SPACE and TAB characters are preserved. However, a final NEWLINE is ignored. It is therefore possible
for a command substitution to yield a partial word.
Filename Substitution
Unquoted words containing any of the characters *, ?, [, or {, or that begin with -, are expanded (also
known as globbing) to an alphabetically sorted list of filenames, as follows:

*

Match any (zero or more) characters.

?

Match any single character.

[ ... ]

Match any single character in the enclosed list(s) or range(s). A list is a string of characters. A
range is two characters separated by a minus-sign (-), and includes all the characters in between
in the ASCII collating sequence (see ascii(7».

Sun Release 3.2

Last change: 24 July 1986

79

CSH( 1)

USER COMMANDS

CSH( 1)

{Sir ,sir ,...}

Expand to each string (or filename-matching pattern) in the comma-separated list. Unlike the
pattern-matching expressions above, the expansion of this construct is not sorted. For instance,
"{b,a}" expands to 'b' 'a', (not 'a' 'b'). As special cases, the characters { and }, along with the
string {}, are passed undisturbed.
Your home directory, as indicated by the value of the variable home, or that of user, as indicated
by the password entry for user.
Only the patterns. ? and [...] imply pattern matching; an error results if no filename matches a pattern
that contains them. The dot character (.), when it is the first character in a filename or patbname component, must be matched explicitly. The slash (I) must also be matched explicitly.
Expressions and Operators

A number of C-Shell builtin commands accept expressions, in which the operators are similar to those of C
and have the same precedence. These expressions typically appear in the @, exit, if, set and while commands, and are often used to regulate the flow of control for executing commands. Components of an
expression are separated by white space.
Null or missing values are considered '0'. The result of all expressions are strings, which may represent
decimal numbers.

The following C-Shell operators are grouped in order of precedence:
( ... )

~uping

one's complement
logical negation

• I %
multiplication, division, remainder (These are right associative, which can lead to unexpected
results. Group combinations explicitly with parentheses.)
+ addition, subtraction (also right associative)
« » bitwise shift left, bitwise shift right
< > <= >=
less than, greater than, less than or equal to, greater than or equal to
== != =- !equal to, not equal to, filename-substitution pattern match (described below), filename-substitution
pattern mismatch
&
bitwise AND
bitwise XOR (exclusive or)
I
bitwise inclusive OR
&&
logical AND
II
logical OR
The operators: ==, !=, =-, and !- compare their arguments as strings; other operators use numbers. The
oprators =- and !- each check whether or not a string to the left matches a filename substitution pattern on
the right. This reduces the need for switch statements when pattern-matching between strings is all that is
required.
Also available are file inquiries:
-r file
Returns true, or '1' if the user has read access. Otherwise it returns false, or '0' .
-w file
True if the user has write access.
-x file
True if the user has execute access.
-e file
True if file exists.
-0 file
True if the user owns file.
-zfile
True iffile is of zero length (empty).
-f file
True if file is a plain file.
-dfile
True iffile is a directory.

80

Last change: 24 July 1986

Sun Release 3.2

CSH( 1)

USER COMMANDS

CSH( I}

If file does not exist or is inaccessible, then all inquiries return false.
An inquiry as to the success of a command is also available:

{cmd}

If cmd runs successfully, the espression evaluates to true, '1'. Otherwise it evaluates
to false '0'. (Note that, conversely, cmd itself typically returns '0' when it runs successfully, or some other value if it encounters a problem. If you want to get at the
status directly, use the value of the status variable rather than this expression).

Control Flow
The shell contains a number of commands to regulate the flow of control in scripts, and within limits, from
the terminal. These commands operate by forcing the shell either to reread input (to loop), or to skip input
under certain conditions (to branch).

Each occurrence of a foreach, switch, while, if... then and else builtin must appear as the first word on its
own input line.
If the shell's input is not seekable and a loop is being rea~ that input is buffered. The shell performs seeks
within the internal buffer to accomplish the rereading implied by the loop. (To the extent that this allows,
backward goto commands will succeed on nonseekable inputs.)
Command Execution
If the command is a C-Shell builtin, the shell executes it directly. Otherwise, the shell searches for a file by
that name with execute access. If the command-name contains a /, the shell takes it as a pathname, and
searches for it If the command-name does not contain a /, the shell attempts to resolve it to a pathname,
searching each directory in the path variable for the command. To speed the search, the shell uses its hash
table (see the rehash builtin) to eliminate directories that have no applicable files. This hashing can be disabled with the -c or -t, options, or the unhash builtin.

As a special case, if there is no / in the in the name of the script and there is an alias for the word shell, the
expansion of the shell alias is prepended (without modification), to the command line. The system attempts
to execute the first word of this special (late-occurring) alias, which should be a full pathname. Remaining
words of the alias's definition, along with the text of the input line, are treated as arguments.
When a pathnarne is found that has proper execute permissions, the shell forks a new process and passes it,
along with its arguments to the kernel (using the execve(2) system call). The kernel then attempts to overlay the new process with the desired program. If the file is an executable binary (in a.out(5), the kernel
succeeds, and begins executing the new process. If the file is a text file, and the first line begins with #!, the
next word is taken to be the pathname of a shell (or command) to interpret that script. Subsequent words
on the first line are taken as options for that shell. The kernel invokes (overlays) the indicated shell, using
the name of the script as an argument

If neither of the above conditions holds, the kernel cannot overlay the file (the execve(2) call fails); the CShell then attempts to execute the file by spawning a new shell, as follows:

If the first character of the file is a #, a C-Shell is invoked.
Otherwise, a standard (Bourne) shell is invoked.
Signal Handling
The shell normally ignores QUIT signals. Background jobs are immune to signals generated from the keyboar~ including hangups. Other signals have the values that the C-Shell inherited from its environment.
The shell's handling of interrupt and terminate signals within scripts can be controlled by the onintr builtin. Login shells catch the TERM signal; otherwise this signal is passed on to child processes. In no case
are interrupts allowed when a login shell is reading the .logout file.
Job Control
The shell associates a numbered job with each command sequence, to keep track of those commands that
are running in the background or have been stopped with TSTP signals (typically "'z or "'Y). When a comman~ or command sequence (semicolon separated list), is started in the background using the & metacharacter, the shell displays a line with the job number in brackets, and a list of associated process numbers:

Sun Release 3.2

Last change: 24 July 1986

81

CSH( 1)

USER COMMANDS

CSH(I)

[1] 1234
To see the current list of jobs, use the jobs builtin command. The job most recendy stopped (or put into the
background if none are stopped) is referred to as the current job, and is indicated with a +. The previous
job is indicated with a -; when the current job is terminated or moved to the foreground, this job takes its
place (becomes the new current job).
To manipulate jobs, refer to the bg, fg, kill, stop and % builtins.
A reference to a job begins with a %. By itself, the percent-sign refers to the current job.
%

%+ %%
The current job.
%The previous job.
%j
Refer to job j as in: kill -9 %j. j can be a job number, or a string that uniquely specifies the
command-line by which it was started; rg %vi might bring a stopped vi job to the foreground, for
instance.
%?string
Specify the job for which the command-line uniquely contains string.
A job running in the background stops when it attempts to read from the terminal. Background jobs can
normally produce output, but this can be suppressed using the stty tostop command.

Status Reporting
While running interactively, the shell tracks the status of each job and reports whenever a finishes or
becomes blocked. It normally displays a message to this effect as it issues a prompt, so as to avoid disturbing the appearance of your input. When set, the notiry variable indicates that the shell is to report status
changes immediately. By default, the notiry command marks the current process; after starting a background job, type notify to mark it.
Builtin Commands
Builtin commands are executed within the C-Shell. If a builtin command occurs
pipeline except the last, it is executed in a subshell.

as any component of a

Null command. This command is interpreted, but perfonns no action.
alias [name [def] ]
Assign def to the alias name. def is a list of words that may contain escaped historysubstitution metasyntax. name is not allowed to be alias or unalias. If de! is omitted, the alias
name is displayed along with its current definition. If both name and del are omitted, all
aliases are displayed.
bg [%job] ...
Run the current or specified jobs in the background
break

Resume execution after the end of the nearest enclosingforeach or while loop. The remaining
commands on the current line are executed. This allows multilevel breaks to be written as a
list of break commands, all on one line.

breaksw

Break from a switch, resuming after the endsw.

case label: A label in a switch statement.
cd [dir]
chdir [dir] Change the shell's working directory to directory dire If no argument is given, change to the
home directory of the user. If dir is a relative pathname not found in the current directory,
check for it in those directories listed in the cdpath variable. If dir is the name of a shell variable whose value starts with a /, change to the directory named by that value.

82

continue

Continue execution of the nearest enclosing while or roreach.

default:

Labels the default case in a switch statement. The default should come after all case labels.
Any remaining commands on the command line are first executed.

Last change: 24 July 1986

Sun Release 3.2

CSH( 1)

USER COMMANDS

CSH( 1)

dirs [-I]
Print the directory stack, most recent to the left; the first directory shown is the current directory. With the -I argument, produce an unabbreviated printout; use of the - notation is
suppressed.
echo [ -n] list
The words in list are written to the shell's standard output, separated by spaces. The output is
terminated with a NEWLINE unless the -n option is used.
eval arg ... Reads the arguments as input to the shell, and executes the resulting command(s). This is usually used to execute commands generated as the result of command or variable substitution,
since parsing occurs before these substitutions. See tset(l) for an example of how to use eval.
exec command
Execute command in place of the current shell, which terminates.
exit [(expr)]
The shell exits, either with the value of the status variable, or with the value of the specified
by the expression expr.
fg % Uob] Bring the current or specified job into the foreground.
foreach var (wordlist)
end

The variable var is successively set to each member of wordlist. The sequence of commands
between this command and the matching end is executed for each new value of var. (Both
foreach and end must appear alone on separate lines.)
The builtin command continue may be used to continue the loop prematurely and the builtin
command break to terminate it prematurely. When this command is read from the terminal,
the loop is read up once prompting with '1' before any statements in the loop are executed.

glob wordlist
Perform filename expansion on wordlist. Like echo, but no \ escapes are recognized. Words
are delimited by null characters in the output.
goto label The specified label is filename and command expanded to yield a label. The shell rewinds its
input as much as possible and searches for a line of the form label: possibly preceded by
SPACE or TAB characters. Execution continues after the indicated line.
hashstat

Print a statistics line indicating how effective the internal hash table has been at locating commands (and avoiding execs). An exec is attempted for each component of the path where the
hash function indicates a possible hit, and in each component that does not begin with a '/'.

history [-hr] [n]
Display the history list; if n is given, display only the n most recent events.
-r
-h

Reverse the order of printout to be most recent first rather than oldest first.
display the history list without leading numbers. This is used to produce files suitable
for sourcing using the -h option to source.

if (expr) command
If the specified expression evaluates to true, the single command with arguments is executed.
Variable substitution on command happens early, at the same time it does for the rest of the if
command. command must be a simple command, not a pipeline, a command list, or a
parenthesized command list Note that I/O redirection occurs even if expr is false, when command is not executed (this is a bug).
if (expr) then
else if (expr2) then

Sun Release 3.2

Last change: 24 July 1986

83

CSH( 1)

USER COMMANDS

CSH( 1)

else
endif

If expr is true, commands up to the fi~st else are executed. Otherwise, if expr2 is true, the
commands between the else if and the second else are executed. Otherwise, commands
between the else and the endif are executed. Any number of else if pairs are allowed, but only
one else. Only one endif is needed, but it is required. The words else and endif must be the
first nonwhite characters on a line. The if must appear alone on its input line or after an else.)

jobs [-I]

List the active jobs under job control.
-I

List process ids, in addition to the normal information.

kill [-sig] [Pid] [%job ] ...
kill -I
Send the TERM (terminate) signal, by default, or the signal specified, to the specified process
id, the job indicated, or the current job. Signals are either given by number or by name. There
is no default Typing 'kill' does not send a signal to the current job. If the signal being sent is
TERM (terminate) or HUP (hang up), then the job or process is sent a CONT (continue) signal as
well.
-I

List the signal names that can be sent.

limit [-b] [resource [max-use]]
Limit the consumption by the current process or any process it spawns, each not to exceed
max-use on the specified resource. If max-use is omitted, print the current limit; if resource is
omitted, display all limits.
-b

Use hard limits instead of the current limits. Hard limits impose a ceiling on the
values of the current limits. Only the superuser may raise the hard limits.

resource is one of:
cputime
file size
datasize
stacksize
coredumpsize

Maximum CPU seconds per process.
Largest single file allowed.
Maximum data size (including stack) for the process.
Maximum stack size for the process.
Maximum size of a core dump (file).

max-use is a number, with an optional scaling factor, as follows:
nb
nk
nm
mm:ss

Hours (for cputime).
n kilobytes. This is the default for all but cputime.
n megabytes or minutes (for cputime).
Minutes and seconds (for cputime).

login

Terminate a login shell and invoke login(l). The .logout file is not processed.

logout

Terminate a login shell.

nice [+n I-n] [command]
Increment the nice value for the shell or for command by n. The higher the nice value, the
lower the priority of a process, and the slower it runs. When given, command is always run in
a subshell, and the restrictions placed on commands in simple if commands apply. If command is omitted, nice increments the value for the current shell. If no increment is specified,
nice sets the nice value to 4. The range of nice values is from -20 to 20. Values of n outside
this range set the value to the lower, or to the higher boundary, respectively.

+n

-n

Increment the nice value by n.
Decrement by n. This argument can be used only by the super-user.

nobup [command]
Run command with hang ups ignored. With no arguments, ignore hangups throughout the
remainder of a script When given, command is always run in a subshell, and the restrictions
placed on commands in simple if commands apply. All processes detached with & are

84

Last change: 24 July 1986

Sun Release 3.2

CSH( 1)

USER COMMANDS

CSH( 1)

effectively nohup'ed.
notify [%job] .•.
Notify the user asynchronously when the status of the current, or of specified jobs, changes.
onintr [ - I label]
Control the action of the shell on interrupts. With no arguments, onintr restores the default
action of the shell on interrupts. (The shell terminates shell scripts and returns to the terminal
command input level). With the - argument, the shell ignores all interrupts. With a label
argument, the shell executes a goto label when an interrupt is received or a child process terminates because it was interrupted
popd [+n]
Pops the directory stack, and cds to the new top directory. The elements of the directory stack
are numbered from 0 starting at the top.
+n

Discard the n'th entry in the stack.

pushd [+n I dir]
Push a directory onto the directory stack. With no arguments, exchange the top two elements.
+n
dir

rehash

Rotate the n'th entry to the top of the stack and cd to it
push the current working directory onto the stack and change to dir.

Recompute the internal hash table of the contents of directories listed in the path variable to
account for new commands added.

repeatcountconunand
Repeat conunand count times command is subject to the same restrictions as with the one-line
if statement.

set [var [= value] ]
set var [n] word
With no arguments, set displays the values of all shell variables. Multiword values are
displayed as a parenthesized list. With the var argument alone, set assigns an empty (null)
value to the variable var. With arguments of the form var = value set assigns value to var,
where value is one of:

=

word
(wordlist)

A single word (or quoted string).
A space-separated list of words enclosed in parentheses.

Values are command and filename expanded before being assigned. The form set var[n]
word replaces the n 'th word in a multiword value with word.

=

setenv [var [ word] ]
,
With no arguments, setenv displays all environment variables. With the var argument sets the
environment variable var to have an empty (null) value. (By convention, environment variables are normally given upper-case names.) With both var and word arguments setenv sets
the environment variable name to the value word, which must be either a single word or a
quoted string. The most commonly used environment variables, USER, TERM and PATH, are
automatically imported to and exported from the csh variables user, term, and path; there is no
need to use setenv for these. In addition, the shell sets the PWD environment variable from the
csh variable cwd whenever the latter changes.
shift [variable]
The components of argv, or variable, if supplied, are shifted to the left, discarding the first
component. It is an error for the variable not to be set, or to have a null value.
source [-h] name
Reads commands from name. source commands may be nested, but if they are nested too deeply the shell may run out of file descriptors. An error in a sourced file at any level terminates
all nested SOU1Ce commands.

Sun Release 3.2

Last change: 24 July 1986

85

CSH(I)

USER COMMANDS

-h

CSH( 1)

Place commands from the the file name on the history list without executing them.

stop [%job] ...
Stop the current or specified background job.
suspend

Stops the shell in its tracks, much as if it had been sent a stop signal with AZ. This is most
often used to stop shells started by suo

switch (string)
case label:
breaksw
default:
breaksw
endsw

Each label is successively matched, against the specified string, which is first command and
filename expanded The file metacharacters *, ? and [ ... ] may be used in the case labels,
which are variable expanded. If none of the labels match before a 'default' label is found, execution begins after the default label. Each case statement and the default statement must
appear at the beginning of a line. The command breaksw continues execution after the
endsw. Otherwise control falls through subsequent case and default statements as with C. If
no label matches and there is no default, execution continues after the endsw.

time [command]
With no argument, print a summary of time used by this C-Shell and its children. With an
optional command, execute command and print a summary of the time it uses.
umask [value]
Display the file creation mask. With value set the file creation mask. value is given in octal,
and is XORed with the permissions of 666 for files and 777 for directories to arrive at the permissions for new files. Common values include 002, giving complete access to the group, and
read (and directory search) access to others, or 022, giving read (and directory search) but not
write permission to the group and others.
unalias pattern
Discard aliases that match (filename substitution) pattern. All aliases are removed by
unalias*.
unhash

Disable the internal hash table.

unlimit [-h] [resource]
Remove a limitation on resource. If no resource is specified, then all resource limitations are
removed. See the description of the limit command for the list of resource names.
-h

Remove corresponding hard limits. Only the super-user may do this.

unset pattern
Remove variables whose names match (filename substitution) pattern. All variables are
removed by unset *; this has noticeably distasteful side-effects.
unsetenv variable
Removes variable from the environment Pattern matching, as with unset is not performed.
wait

Wait for background jobs to finish (or for an interrupt) before prompting.

while (expr)
end

86

While exp~ is true (evaluates to non-zero), repeat commands between the while and the matching end statement. break and continue may be used to terminate or continue the loop prematurely. The while and end must appear alone on their input lines. If the shell's input is a

Last change: 24 July 1986

Sun Release 3.2

CSH(1)

USER COMMANDS

CSH( 1)

terminal, it prompts for commands with a question-mark until the end command is entered and
then perfonns the commands in the loop.
%Uob] [&]

Bring the current or indicated job to the foreground With the ampersand, continue running
job in the background.
@ [var =expr ]
@ [var[n] =expr

With no arguments, display the values for all shell variables. With arguments, the variable
var, or the n'th word in the value of var, to the value that expr evaluates to. (If [n] is supplied,
both var and its n 'th component must already exist)
If the expression contains the characters >, <, & or
placed within parentheses.

I, then at least this

part of expr must be

The operators *=, +=, etc., are available as in C. The space separating the name from the
assignment operator is optional. Spaces are, however, mandatory in separating components of
expr that would otherwise be single words.
Special postfix operators, + + and -- increment or decrement name, respectively.
Environment Variables and Predefined Shell Variables

Unlike the standard shell, the C-Shell maintains a distinction between environment variables, which are
automatically exported to processes it invokes, and shell variables, which aren't. Both types of variables
are treated similarly under variable substitution. The shell sets the variables argv, cwd, home, path,
prompt, sheD, and status upon initialization. The shell copies the environment variable USER into the shell
variable user, TERM into term, and HOME into borne, and copies each back into the respective environment variable whenever the shell variables are reset. PATH and path are similarly handled. You need only
set path once in the .cshrc or .login file. The environment variable PWD is set from cwd whenever the
latter changes. The following shell variables have predefined meanings:

argv

Argument list. Contains the list of command line arguments supplied to the current invocation
of the shell. This variable determines the value of the positional parameters $1, $2, and so on.

cdpath

Contains a list of directories to be searched by the cd, chdir, and popd commands, if the directory argument each accepts is not a subdirectory of the current directory.

cwd

The full pathname of the current directory.

echo

Echo commands (after substitutions), just before execution.

fignore

A list of filename suffixes to ignore when attempting filename completion. Typically the single word' .0'.

filec

Enable filename completion, in which case the EDT character CD) and the ESC character have
, special significance when typed in at the end of a terminal input line:
EDT
ESC

Print a list of all filenames that start with the preceding string.
Replace the preceding string with the longest unambiguous extension.

hardpaths If set, pathnames in the directory stack are resolved to contain no symbolic-link components.
histchars

A two-character string. The first character replaces! as the history-substitution character. The
second replaces the carat (A) for quick substitutions.

history

The number of lines saved in the history list. A very large number may use up all of the CShell's memory. If not set, the C-Shell saves only the most recent command

home

The user's home directory. The filename expansion of - refers to the value of this variable.

ignoreeor If set, the shell ignores end-of-file from terminals. This protects against accidentally killing a
C-Shell by typing a AD.
mail

Sun Release 3.2

A list of files where the C-Shell checks for mail. If the first word of the value is a number, it

Last change: 24 July 1986

87

CSH( 1)

USER COMMANDS

CSH(1 )

specifies a mail checking interval in seconds (default 5 minutes).
nobeep

Suppresses the bell during command completion when you ask the C-Shell to extend an ambiguous filename.

noclobber Restricts output redirection so that existing files are not destroyed by accident> redirections
can only be made to new files. »redirections can only be made to existing files.
noglob

Inhibit filename substitution. This is most useful in shell scripts once filenames (if any) are
obtained and no further expansion is desired.

nonomateh
Returns the filename substitution pattern, rather than an error, if the pattern is not matched.
Malformed patterns still result in errors.
notify

If set, the shell notifies you immediately as jobs are completed, rather than waiting until just
before issuing a prompt.

path

The list of directories in which to search for commands. path is initialized from the environment variable PATH, which the C-Shell updates whenever path changes. A null word
specifies the current directory. The default is typically: (. Insr/neb Ibin /nsr/bin). If path
becomes unset only full pathnames will execute. An interactive C-Shell will normally hash the
contents of the directories listed after reading .cshrc, and whenever path is reset. If new commands are added, use the rehash command to update the table.

prompt

The string an interactive C-Shell prompts with. Noninteractive shells leave the prompt variable unset. Aliases and other commands in the .cshrc file that are only useful interactively, can
be placed after the following test: if (S?prompt
0) exit, to reduce startup time for noninteractive shells. A! in the prompt string is replaced by the current event number. The default
prompt is hostname % for mere mortals, or hostname# for the super-user.

==

savehist

The number of lines from the history list that are saved in -I.history when the user logs out.
Large values for savehist slow down the C-Shell during startup.

shell

The file in which the C-Shell resides. This is used in forking shells to interpret files that have
execute bits set, but that are not executable by the system.

status

The status returned by the most recent command. If that command terminated abnormally,
0200 is added to the status. Builtin commands that fail return exit status '1', all other builtin
commands set status to '0'.

time

Controls automatic timing of commands. Can be supplied with one or two values. The first is
the reporting threshold in CPU seconds. The second is a string of tags and text indicating
which resources to report on. A tag is a percent sign (%) followed by a single upper-case
letter (unrecognized tags print as text):
%D
Average amount of unshared data space used in Kilobytes.
%E
Elapsed (wallclock) time for the command.
%F
Page faults.
%1
Number of block input operations.
%K
Average amount of unshared stack space used in Kilobytes.
%M
Maximum real memory used during execution of the process.
%0
Number of block output operations.
%P
Total CPU time - U (user) plus S (system) - as a percentage of E
(elapsed) time.
%S
Number of seconds of CPU time consumed by the kernel on behalf of the
user's process.
%U
Number of seconds of CPU time devoted to the user's process.
%W
Number of swaps.
%X
Average amount of shared memory used in Kilobytes.
The default summary display outputs from the %U, %S, %E, %P, %X, %D, %1, %0, %F

88

Last change: 24 July 1986

Sun Release 3.2

CSH( 1)

USER COMMANDS

CSH( 1)

and % W tags, in that order.
verbose

Display each command after history substitution takes place.

DIAGNOSTICS
You have stopped jobs.
You attempted to exit the C-Shell with stopped jobs under job control. An immediate second
attempt to exit will succeed, terminating the stopped jobs.
FILES

-I.cshrc
-/.login
-I.logout
-I. history
Ibinlsh
Itmplsh.
letclpasswd

Read at beginning of execution by each shell.
Read by login shells after' .cshrc' at login.
Read by login shells at logout.
Saved history for use at next login.
Standard shell, for shell scripts not starting with a '#'.
Temporary file for' «' .
Source of home directories for ,-name' .

LIMITATIONS
Words can be no longer than 1024 characters. The system limits argument lists to 10240 characters. The
number of arguments to a command which involves filename expansion is limited to 1/6'th the number of
characters allowed in an argument list. Command substitutions may substitute no more characters than are
allowed in an argument list. To detect looping, the shell restricts the number of alias substitutions on a single line to 20.
SEE ALSO
sh(l), printenv(I), access(2), execve(2), fork(2), pipe(2), tty(4), environ(5V)

Getting Started With UNIX: Beginner's Guide
Doing More With UNIX: Beginner's Guide
BUGS

When a command is restarted from a stop, the shell prints the directory it started in if this is different from
the current directory; this can be misleading (that is, wrong) as the job may have changed directories internally.
Shell builtin functions are not stoppablelrestartable. Command sequences of the form a ; b ; c are also not
handled gracefully when stopping is attempted If you suspend b, the shell never executes c. This is especially noticeable if the expansion results from an alias. It can be avoided by placing the sequence in
parentheses to force it into a subshell.
Control over terminal output after processes are started is primitive; use the Sun Window system if you
need better output control.
Shell procedures, as with the standard shell, should be provided.
Commands within loops, prompted for by ?, are not placed in the history list.
Control structures should be parsed rather than being recognized as builtin commands. This would allow
control commands to be placed anywhere, to be combined with I, and to be used with & and ; metasyntax.

It should be possible to use the : modifiers on the output of command substitutions. There are two problems with: modifier usage on variable substitutions: not all of the modifiers are available, and only one
modifier per substitution is allowed.
Quoting conventions are contradictory and confusing.
Symbolic links can fool the shell. Setting the hardpaths variable alleviates this.

set path should remove duplicate pathnames from the patbname list. These often occur because a shell
script or a .cshrc file does something like set path=(/usr/local lusrlhosts Spath) to ensure that the named
directories are in the pathname list.

Sun Release 3.2

Last change: 24 July 1986

89

CSH(I)

USER COMMANDS

CSH( 1)

The only way to direct the standard output and standard error separately is by invoking a subshell, as follows:
tutorial% ( command> outfile) >& errorflle
Although robust enough for general use, adventures into the esoteric periphery of the C-Shell may reveal
unexpected quirks.

90

Last change: 24 July 1986

Sun Release 3.2

CSPLIT(l)

USER COMMANDS

CSPLIT( 1)

NAME

csplit - context split
SYNOPSIS

csplit [ -f prefix] [ -k] [ -s ]ftlename argl [ ... argn]
DESCRIPTION

csplit reads the file whose name is filename and separates it into n+ 1 sections, defined by the arguments
argl through argn. H the filename argument is a -, the standard input is used. By default the sections are

placed in files named xxOO through xxn. n may not be greater than 99. These sections receive the following portions of the file:

xxOO
xxOI:

From the start of filename up to (but not including) the line indicated by argl (see OPTIONS
below for an explanation of these arguments.)
From the line indicated by argl up to the line indicated by arg2.

xxn:

From the line referenced by argn to the end offile.

csplit prints the character counts for each file created, and removes any files it creates if an error occurs.
OPTIONS
-f prefix

name the created files prefix 00 through prefixn.

-k

suppress removal of created files when an error occurs.

-s

suppress printing of character counts.

The arguments argl through argn can be a combination of the following selection operators:
Irexpl

A file is to be created for the section from the current line up to (but not including) the line containing the regular expression rexp. The current line then becomes the line containing rexp.
This argument may be followed by an optional + or - some number of lines (e.g., !Page/-S).

%rexp %

This argument is the same as Irexp I, except that no file is created for the selected section.

lineno

A file is to be created from the current line up to (but not including) lineno. The current line
becomes lineno.

{num}

Repeat argument. This argument may follow any of the above arguments. H it follows a rexp
type argument, that argument is applied num more times. If it follows lineno, the file will be
split every lineno lines (num times) from that point.

Enclose all rexp type arguments that contain blanks or other characters meaningful to the shell in the
appropriate quotes. Regular expressions may not contain embedded new-lines.
EXAMPLES

This example splits the file at every 100 lines, up to 10,000 lines.
csplit -k file

100

{99}

Assuming that prog.c follows the normal C coding convention of ending routines with a } at the beginning
of the line, this example will create a file containing each separate C routine (up to 21) in prog.c.
csplit -k prog.c

'%main(%'

'/"'}/+1'

{20}

SEE ALSO

ed(l), sh(I), regexp(3)
DIAGNOSTICS

Self-explanatory except for:
arg - out of range

Sun Release 3.2

Last change: 28 March 1986

91

CSPLIT( 1)

USER COMMANDS

CSPLIT(l)

which means that the given argument did not refer to a line between the current position and the end of the
file.

92

Last change: 28 March 1986

Sun Release 3.2

CTAGS(l)

USER COMMANDS

CTAGS(l)

NAME

ctags - create a tags file
SYNOPSIS
ctags [ -aBFtuvwx] [ -f tagsfile ] file . ..
DESCRIPTION
ctags makes a tags file for ex(1) from the specified C, Pascal, FORTRAN, YACC, and LEX sources. A tags
file gives the locations of specified objects (in this case functions and typedefs) in a group of files. Each
line of the tags file contains the object name, the file in which it is defined, and an address specification for
the object definition. Functions are searched with a pattern, typedefs with a line number. Specifiers are
given in separate fields on the line, separated by blanks or tabs. Using the tags file, ex can quickly find
these objects definitions.

Normally ctags places the tag descriptions in a file called tags; this may be overridden with the -f option.
Files with names ending in .c or .h are assumed to be C source files and are searched for C routine and
macro definitions. Files with names ending in .y are assumed to be YACC source files. Files with names
ending in .1 are assumed to be LEX files. Others are first examined to see if they contain any Pascal or FORTRAN routine definitions; if not, they are processed again looking for C definitions.
The tag main is treated specially in C programs. The tag formed is created by prepending M to the name of
the file, with a trailing .c removed, if any, and leading pathname components also removed. This makes use
of ctags practical in directories with more than one program.
OPTIONS

-a

append output to an existing tags file.

-B

use backward searching patterns (1 ... ?).

-F

use forward searching patterns (/ ...1) (default).

-x

produce a list of object names, the line number and file name on which each is defined, as well as
the text of that line and prints this on the standard output. This is a simple index which can be
printed out as an off-line readable function index.

-t

create tags for typedefs.

-v

produce on the standard output an index of the form expected by vgrind(l). This listing contains
the function name, file name, and page number (assuming 64 line pages). Since the output will be
sorted into lexicographic order, it may be desired to run the output through sort -f. Sample use:
ctags -v files I sort -f > index
vgrind -x index

-w

suppress warning diagnostics.

-u

update the specified files in tags, that is, all references to them are deleted, and the new values are
appended to the file. Beware: this option is implemented in a way which is rather slow; it is usually faster to simply rebuild the tags file.

FILES

tags

output tags file

SEE ALSO
ex(1), vgrind(l), vi(l)

BUGS
Recognition of functions, subroutines and procedures for FORTRAN and Pascal is done is a very simpleminded way. No attempt is made to deal with block structure; if you have two Pascal procedures in different blocks with the same name you lose.
The method of deciding whether to look for C or Pascal and FORTRAN functions is a hack.

Sun Release 3.2

Last change: 17 July 1986

93

CTAGS( 1)

USER COMMANDS

CTAGS(1 )

Does not know about #ifdefs.
Should know about Pascal types. Relies on the input being well formed to detect typedefs. Use of-tx
shows only the last line of typedefs.

94

Last change: 17 July 1986

Sun Release 3.2

CTRACE(1)

USER COMMANDS

CTRACE(1)

NAME

ctrace - C program execution trace
SYNOPSIS
ctrace [ -r functions] [ -v functions] [ ~ ] [ -x] [ -u] [ -e] [ -I n ] [ -s ] [ -t n] [ -P] [ -b ] [ -p 's' ]
[ -r f] [file]
DESCRIPTION

ctrace allows you to follow the execution of a C program, statement by statement. The effect is similar to
executing a shell procedure with the -x option. ctrace reads the C program in file (or from standard input
if you do not specify file), inserts statements to print the text of each executable statement and the values of
all variables referenced or modified, and writes the modified program to the standard output. You must put
the output of ctrace into a temporary file because the cc(1V) command does not allow the use of a pipe.
You then compile and execute this file.
As each statement in the program executes it will be listed at the terminal, followed by the name and value
of any variables referenced or modified in the statement, followed by any output from the statement.
Loops in the trace output are detected and tracing is stopped until the loop is exited or a different sequence
of statements within the loop is executed.
A warning message is printed every 1000 times through the loop to help you detect infinite loops. The
trace output goes to the standard output so you can put it into a file for examination with an editor or the
bfs(1) or tail(1) commands.
OPTIONS
The only options you will commonly use are:
-f functions Trace only these functions.
-v functions Trace all but thesefunctions.

You may want to add to the default formats for printing variables. long and pointer variables are always
printed as signed integers. Pointers to character arrays are also printed as strings if appropriate. char,
short, and int variables are also printed as signed integers and, if appropriate, as characters. double variables are printed as floating point numbers in scientific notation. You can request that variables be printed
in additional formats, if appropriate, with these options:
~

Octal.
Hexadecimal.
Unsigned.
Floating point.

-x
-u
-e

These options are used only in special circumstances:
-I n

-s

-t n

-P

Check n consecutively executed statements for looping trace output, instead of the default
of20. Use 0 to get all the trace output from loops.
Suppress redundant trace output from simple assignment statements and string copy function calls. This option can hide a bug caused by use of the = operator in place of the ==
operator.
Trace n variables per statement instead of the default of 10 (the maximum number is 20).
The DIAGNOSTICS section explains when to use this option.
Run the C preprocessor on the input before tracing it. You can also use the -D, -I, and-U
cc (1 V) options.

These options are used to tailor the run-time trace package when the traced program will run in a non-UNIX
system environment:
-b

-p s'
J

Sun Release 3.2

Use only basic functions in the trace code, that is, those in ctype(3), print/(3S), and
string (3). These are often available even in cross-compilers for microprocessors. In particular, this option is needed when the traced program runs under an operating system that
does not have signal(3),ffiush(3S), longjmp(3), or setjmp(3).
Change the trace print function from the default of 'printf('. For example, 'fprintf(stderr,'

Last change: 11 April 1986

95

CTRACE(I)

USER COMMANDS

CTRACE(I)

would send the trace to the standard error output.
Use file/in place of the runtime.c trace function package. This lets you change the entire
print function, instead of just the name and leading arguments (see the -p option).

-r r
EXAMPLE

If the file Ic.c contains this C program:
1 #include 
/* count lines in input */
2 mainO
3{
4
int c, nl;

5
6

7
8
9

10

nl =0;
while «c = getcharO) != EOP)
if (c = '\n')
++nl;
printf("%d\n", nl);

11 }
and you enter these commands and test data:
cc lc.c
a.out
1
CfRL-D,

the program will be compiled and executed. The output of the program will be the number 2, which is not
correct because there is only one line in the test data. The error in this program is common, but subtle. If
you invoke ctrace with these commands:
ctrace lc.c >temp.c
cc ternp.c
a.out
the output will be:
2 mainO
6
nl = 0;
/* nl == 0 */
7
while «c = getcharO) != EOF)
The program is now waiting for input If you enter the same test data as before, the output will be:
/* c == 49 or '1' */
8
if (c = '\n')
/* c == 10 or '\n' */
9
++nl;
/* nl == 1 */
7
while « c = getcharO) != EOF)
/* c == 10 or '\n' */
8
if (c = '\n')
/* c == 10 or '\n' */
9
++nl;
/* nl == 2 */
/* repeating */
If you now enter an end of file character (cntl-d) the final output will be:
/* repeated <1 time */
7
while c = getcharO) ! = EOF)
/* c == -1 */
10
printfC'%d\n", nl);
/* nl == 2 *12
/* return */

«

96

Last change: 11 April 1986

Sun Release 3.2

CTRACE(I)

USER COMMANDS

CTRACE(I)

Program output is printed at the end of the trace line for the nl variable. Also note the return comment
added by ctrace at the end of the trace output. This shows the implicit return at the terminating brace in the
function.
The trace output shows that variable c is assigned the value '1' in line 7, but in line 8 it has the value '\n'.
Once your attention is drawn to this if statement, you will probably realize that you used the assignment
You can easily miss this error during code reading.
operator in place of the equal operator

=

==.

USAGE
Execution-Time Trace Control
The default operation for ctrace is to trace the entire program file, unless you use the -f or -v options to
trace specific functions. This does not give you statement by statement control of the tracing, nor does it let
you turn the tracing off and on when executing the traced program.

You can do both of these by adding ctroffO and ctronO function calls to your program to tum the tracing
off and on, respectively, at execution time. Thus, you can code arbitrarily complex criteria for trace control with if statements, and you can even conditionally include this code because ctrace defines the
CTRACE preprocessor variable. For example:
#ifdef CTRACE
if (c == '!' && i > 1000)
cttonO;
#endif
You can also call these functions from dbx(l) if you compile with the -g option. For example, to trace all
but lines 7 to 10 in the primary source file, enter:
dbx a.out
when at 7 {call ctroffO; cont; }
when at 11 { call ctronO; cont; }

run
You can also turn the trace off and on by setting the static variable tr_ct_ to 0 and 1, respectively. This is
useful if you are using a debugger that cannot call these functions directly, such as adb(I).
DIAGNOSTICS
This section contains diagnostic messages from both ctrace and cc(1 V), since the traced code often gets
some cc warning messages. You can get cc error messages in some rare cases, all of which can be
avoided.
ctrace Diagnostics

warning: some variables are not traced in this statement
Only 10 variables are traced in a statement to prevent the C compiler "out of tree space; simplify
expression" error. Use the -t option to increase this number.
warning: statement too long to trace
This statement is over 400 characters long. Make sure that you are using tabs to indent your code,
not spaces.
cannot handle preprocessor code, use -P option
This is usually caused by #ifdef/#endif preprocessor statements in the middle of a C statement, or
by a semicolon at the end of a #define preprocessor statement.

'if ... else if

sequence too long
Split the sequence by removing an else from the middle.

possible syntax error, try -P option
Use the -P option to preprocess the ctrace input, along with any appropriate -D, -I, and -U
preprocessor options. If you still get the error message, check the WARNINGS section below.

Sun Release 3.2

Last change: 11 Apri11986

97

CTRACE(I)

USER COMMANDS

CTRACE( 1)

Cc Diagnostics

warning: floating point not implemented
warning: illegal combination of pointer and integer
warning: statement not reached
warning: sizeof returns 0
Ignore these messages.
compiler takes size offunction
See the ctrace "possible syntax error" message above.
yacc stack overflow
See the ctrace '''if ... else if sequence too long" message above.
out of tree space .. simplify expression
Use the -t option to reduce the number of traced variables per statement from the default of 10.
Ignore the "ctrace: too many variables to trace" warnings you will now get.
redeclaration of signal
Either correct this declaration of signal (3), or remove it and #include .
Warnings

You will get a ctrace syntax error if you omit the semicolon at the end of the last element declaration in a
structure or union, just before the right brace (}). This is optional in some C compilers.
Defining a function with the same name as a system function may cause a syntax. error if the number of
arguments is changed. Just use a different name.
ctrace assumes that BADMAG is a preprocessor macro, and that EOP and NULL are #defined constants.
Declaring any of these to be variables, e.g. "int EOP;", will cause a syntax error.

BUGS
ctrace does not know about the components of aggregates like structures, unions, and arrays. It cannot
choose a format to print all the components of an aggregate when an assignment is made to the entire
aggregate. ctrace may choose to print the address of an aggregate or use the wrong format (e.g., %e for a
structure with two integer members) when printing the value of an aggregate.

Pointer values are always treated as pointers to character strings.
The loop trace output elimination is done separately for each file of a multi-file program. This can result in
functions called from a loop still being traced, or the elimination of trace output from one function in a file
until another in the same file is called.
FILES

runtime.c

run-time trace package

SEE ALSO

signal(3), ctype(3), ffiush(3S), longjmp(3), printf(3S), setjmp(3), string(3)

98

Last change: 11 April 1986

Sun Release 3.2

CUT ( 1)

USER COMMANDS

CUT(I)

NAME
cut - remove selected fields from each line of a file
SYNOPSIS

cut -c list [filename . .. ]
cut -f list [ -de] [ -s ] [filename . .. ]
DESCRIPTION
Use cut to cut out columns from a table or fields from each line of a file; in data base parlance, it implements the projection of a relation. The fields as specified by list can be of fixed length, i.e., character positions as on a punched card, or of variable length can vary from line to line and be marked with a field delimiter character like tab (-r option). Cut can be used as a filter; if no files are given, the standard input is
used.
OPTIONS
-clist

-f list

By character position. list is a comma-separated list of integer field numbers (in increasing order),
with an optional- to indicate ranges:
1,4,7
characters 1, 4 and 7
1-3,8 characters 1 through 3, and 8
-5,10 characters (1) through 5, and 10
3characters 3 through (last)
By field position. Instead of character positions, list specifies fields that are separated a delimiter
(normally a TAB):

1,4,7

fields 1,4 and 7

Lines with no field delimiters are normally passed through intact (to allow for subheadings).
-de

Set the field delimiter to c. The default is a TAB. SPACE, or a character with special meaning to
the shell must be quoted.

-s

Suppress lines with no delimiter characters.

EXAMPLES
cut -d: -f1,5 /etc/passwd

name=who am i
DIAGNOSTICS
line too long
bad list lor ell option

no fields
SEE ALSO
grep(1 V), paste(I).

Sun Release 3.2

mapping of user IDs to names

cut -f 1 -d" " to set name to the current login name.
A line can have no more than 1023 characters or fields.
Missing -c or -f option or incorrectly specified list. No error occurs if a line
has fewer fields than the list calls for.
The list is empty.

Last change: 28 March 1986

99

CXREF( 1)

USER COMMANDS

CXREF(l)

NAME

cxref - generate C program cross-reference
SYNOPSIS
cxrer [ -c] [ -w[num] ] [ -ofile] [ -t ]files
DESCRIPTION
cxre/ analyzes a collection of C files and attempts to build a cross-reference table. cxref utilizes a special
option of cpp to include #define'd information in its symbol table. It produces a listing on standard output
of all symbols (auto, static, and global) in each file separately, or with the -c option, in combination. Each
symbol contains an asterisk (*) before the declaring reference.
SYSTEM V DESCRIPTION
The System V version of cxre/, run as /usr/Sbinicxrer, makes the C preprocessor search for include files in
/usr/Sinclnde before searching for them in /nsr/include.
OPTIONS
In addition to the -D, -I and -U options (which are identical to their interpretation by
cc(1 V»,thefollowingoptionsare cxre/:

-c

Print a combined cross-reference of all input files.

-w[num]
Width option which formats output no wider than num (decimal) columns. This option will
default to 80 if num is not specified or is less than 51.
-0 file

Direct output to namedfile.

-s

Operate silently; does not print input file names.

-t

Format listing for 80-column width.

SEE ALSO
cc(lV)
DIAGNOSTICS
Error messages are unusually cryptic, but usually mean that you cannot compile these files, anyway.
BUGS

cxre/ considers a formal argument in a #define macro definition to be a declaration of that symbol. For
example, a program that #includes ctype.h, will contain many declarations of the variable c.

100

Last change: 10 April 1986

Sun Release 3.2

DATE(lV)

USER COMMANDS

DATE(lV)

NAME
date - display or set the date
SYNOPSIS

date [ -u] [ -a [-]sssJ1J] [yynunddhhmm[.ss] ] [ +format]
SYSTEM V SYNOPSIS

date [ -u ] [ -a [-]sssJ1J] [ nunddhhmmfyy] ] [ +format]
DESCRIPTION
DESCRIPTION
If no argument is given, or if the argument begins with +, date displays the current date and time. Otherwise, the current date is set. Only the super-user may set the date.

yy is the last two digits of the year; the first mm is the month number; dd is the day number in the month; hh
is the hour number (24 hour system); the second mm is the minute number; .ss (optional) specifies seconds.
The year, month and day may be omitted; the current values are supplied as defaults.
If the argument begins with +, the output of date is under the control of the user. The format for the output
is similar to that of the first argument to print/(3S). All output fields are of fixed size (zero padded if necessary). Each field descriptor is preceded by % and will be replaced in the output by its corresponding value.
A single % is encoded by % %. All other characters are copied to the output without change. The string is
always terminated with a new-line character.
Field Descriptors:
n
insert a new-line character
t
insert a tab character
m
month of year - 01 to 12
day of month - 01 to 31
d
last 2 digits of year - 00 to 99
y
D
date as mrnIddlyy
hour - 00 to 23
H
M
minute - 00 to 59
S
second - 00 to 59
T
time as HH:MM:SS
j
day of year - 001 to 366
w
day of week - Sunday = 0
a
abbreviated weekday - Sun to Sat
h
abbreviated month - Jan to Dec
r
time in AMIPM notation
SYSTEM V SYNOPSIS
When setting the date, the first mm is the month number; dd is the day number in the month; hh is the hour
number (24 hour system); the second mm is the minute number; yy is the last 2 digits of the year number
and is optional. The current year is the default if no year is mentioned.
OPTIONS
-u
Display the date in GMT (universal time). The system operates in GMT; date normally takes
care of the conversion to and from local standard and daylight time. -u may also be used to
set GMT time.
-a [-]sssJff Using the adjtime(2) system call, tell the system to slowly adjust the time by ssslffseconds
(fff represents fractions of a second). This adjustment can be positive or negative. The
system's clock will be sped up or slowed down until it has drifted by the number of seconds
specified.
EXAMPLES
date 10080045
would set the date to Oct 8, 12:45 AM.

Sun Release 3.2

Last change: 16 July 1983

101

USER COMMANDS

DATE(IV)

DATE(IV)

If the year were 1986, and the date were so set,
date'+DATE: %m/%dI%y%nTIM:E: %H:%M:%S'

would generate as output:
DATE: 08/01/86
TIME: 14:45:05
FILES

lusr/adm!wtmp

to record time-setting

SEE ALSO

printf(3S), utmp(5)
DIAGNOSTICS

date: Failed to set date: Not owner
if you try to change the date but are not the super-user.
date: bad format character
if the field descriptor is not recognizable.

102

Last change: 16 July 1983

Sun Release 3.2

DBX( 1)

USER COMMANDS

DBX( 1)

NAME

dbx - source-level debugger for C, FORTRAN 77 and Pascal programs
SYNOPSIS

dbx [ -r] [ -i] [ -I dir] [ -k] [ -kbd] [obffile [ corefile] ]
DESCRIPTION

dbx is a utility for source-level debugging and execution of programs written in C, FORTRAN 77 and Pascal.
It accepts the same commands as dbxtool (1), using a standard terminal interface rather than the window
system.
obffile is an object file produced by cc(1 V),j77(1) or pc (1) (or a combination of them) with the appropriate
flag (-g) specified to produce symbol information in the object file.
If no obffile is specified, use the debug command to specify the program to be debugged The object file
contains a symbol table which includes the names of all the source files translated by the compiler to create
it These files are available for perusal while using the debugger.
If a file named corefile exists in the current directory or a corefile is specified, dbx can be used to examine
the state of the program when it faulted
Debugger commands in the file .dbxinit are executed immediately after the symbolic information is read, if
that file exists in the current directory, or in the user's home directory if .dbxinit doesn't exist in the current
directory.
OPTIONS

-r

Executes obifile immediately. Parameters follow the object file name (redirection is handled properly). If the program terminates successfully, dbx exits. Otherwise, dbxreports the reason for termination and waits for user response. dbx reads from /dev/tty when -r is specified and standard
input is a file or pipe.

-i

Forces dbx to act as though standard input is a terminal or terminal emulator.

-I dir

Adds dir to the list of directories that are searched when looking for a source file. Normally dbx
looks for source files in the current directory and in the directory where obifile is located. The
directory search path can also be set with the use command.

-k

Kernel debugging.

-kbd

Debugs a program that sets the keyboard into up/down translation mode. This flag is necessary if
the program you are debugging uses up/down encoding.

USAGE

Refer to dbx in Program Debugging Tools/or the Sun Workstation.
The most useful basic commands to know about are run to run the program being debugged, where to
obtain a stack trace with line numbers, print for displaying variables, and stop for setting breakpoints.
Filenames

Filenames within dbx may include shell metacharacters. The shell used for pattern matching is determined
by the SHELL environment variable.
Expressions

dbx expressions are combinations of variables, constants, procedure calls, and operators. Hexadecimal
constants must be preceded by a 'Ox' and octal constants by a '0'. Character constants must be enclosed in
single quotes. Expressions cannot involve strings, structures, or arrays, although elements of structures or
arrays may be used

Sun Release 3.2

Last change: 23 July 1986

103

DBX(I)

USER COMMANDS

DBX(I)

Operators

+-*/div%

add, subtract, multiply, divide, integer division, and remainder
«

»

&

1left shift, right shift, bitwise AND, bitwise OR, and bitwise complement

&

*

address of operator and contents of operator

< > <= >= == != !
less than, greater than, less than or equal, greater than or equal, equal to, not equal to, and
not
&&

II

logical AND, logical OR

sizeof (cast)

size of variable or type, and type cast

• ->

Field reference, pointed-to field reference (dot works for both in dbx).

Precedence and associativity of operators are the same as in C, and parentheses can be used for grouping.
If there is no corefile file, only expressions containing constants are available. Procedure calls require an

active child process.
Scope Rules

dbx uses the variables file and func to resovle scope conflicts. Their values are updated as files and functions are entered and exited during execution. You can also change them explicitly. When func is
changed, file is updated along with it, but not vice versa.
Execution and Tracing Commands

Stop the program being debugged and enter dbx.
run [ args ] [ < infile ] [> I »outfile ]
Start executing objfile, reading in any new information from it. With no args, use the argument list from the previous run command
args
Pass args as command-line arguments to the program.
< I> I»
Redirect input or output, or append output to a file.
rerun [ args ] [ < infile ] [ > I »outfile]
Like the run command, except that when args are omitted, none are passed to the program.
cont [ at source line ] [ sig signal]
Continue execution from where it stopped.
at sourceline Start from source line
sig signal
Continue as if signal had occurred. signal may be a number or a name as with
catch.
trace [ injunction] [if condition ]
trace sourceline [ if condition ]
trace function [ if condition ]
trace expression at sourceline [ if condition ]
trace variable [infunction ] [if condition]
Display tracing information. If no argument is specified, each source line is displayed before
execution. Tracing is turned off when the function or procedure is exited.
Display tracing information only while executing the function or procedure
in function

INTERRUPT

function.

if condition
sourceline
function

Display tracing information only if condition is true.
Display the line immediately prior to executing it. Source line-numbers from
another file are written as "filename" :n.
Display the routine and source line called from, parameters passed in, and
return value.

expression at sourceline
variable

104

Display the value of expression whenever sourceline is reached.
Display the name and value whenever variable changes.

Last change: 23 July 1986

Sun Release 3.2

DBX( 1)

USER COMMANDS

DBX(l)

stop at source line [ if condition ]
stop infunction [if condition]
stop variable [ if condition ]
stop if condition
Stop execution when the sourceline is reached, function is called, variable is changed, or condition becomes true.
when infunction { command ; [ command; ] ... }
when at sOUTceline { command ; [ command; ] ... }
when condition {command ; [ command; ] ... }
Execute the dbx command(s) when function is called, sourceline is reached, or condition is
true.
status [> filename ]
Display active trace, stop and when commands, and associated command numbers.
delete all
delete cmd-no [ ,cmd-no ] ...
Remove all traces, stops and whens, or those corresponding to each dbx cmd-no (as
displayed by status).
clear [ so urce line ]
Clear all breakpoints at the current stopping point, or at sourceline .
catch [ signal [ , signal] ... ]
Display all signals currently being caught, or catch signal before it is sent to the program
being debugged A signal can be specified either by name (with the SIG prefix omitted, as
with kill(l» or number. Initially all signals are caught except SIGHUP, SIGEMT, SIGFPE,
SIGKILL, SIGALRM, SIGTSfP, SIGCONT, SIGCHLD, and SIGWINCH.
ignore [ signal [ , signal] ... ]
Display all signals currently being ignored, or stop catching signal, which may be specified
by name or number as with catch.
step [ n ]
Execute the next n source lines. If omitted, n is taken to be '1'. Steps into functions.
next [ n ]
Execute the next n source lines. If omitted, n is taken to be '1'. Steps past functions.
Naming, Printing and Displaying Data

Variables from another function or procedure with the same name as one in the current block must be
qualified as follows:

r sourcefile ']function' variable
For Pascal variables there may be more than one function or procedure name, each separated by a
backquote.
print expression [ ,expression ] ...
Print the value of each expression, which may involve function calls. Program execution
halts when a breakpoint is reached, and dbx resumes.
display [ expression [ , expression ] ... ]
Print a list of the expressions currently being displayed, or display the value of each expression whenever execution stops.
undisplay [ expression [ , expression ] ... ]
Stop displaying the value of each expression whenever execution stops. If expression is a
constant, it refers shown by the display command with no arguments.
whatis identifier
whatis type Print the declaration of the given identifier or type. types are useful to print all the members
of a structure, union, or enumerated type.
which identifier
Print the fully-qualified name of the given identifier.
where is identifier
Print the fully qualified name of all symbols matching identifier.

Sun Release 3.2

Last change: 23 July 1986

105

DBX(I)

USER COMMANDS

assign variable

DBX(I)

=expression

set variable =expression

Assign the value of expression to variable. There is no type conversion for operands of differing type.
set81fpreg=wordl word2 word3
Treat the concatenation of word1 word2 word3 as a 96-bit, IEEE floating-point value and
assign it to the MC68881 floating-point register fpreg. (Supported only on Sun-3).
califunction (parameters )
Execute the named function. Arguments are passed according to the rules for the sourcelanguage of function.
where [n] List all, or the top n, active functions on the stack.
dump [function]
Display the names and values of local variables and parameters in the current or specified
function.

up [n]
down [ n ]

Move up (towards "main") or down the call stack, one or n levels.

File Access Commands

edit [filename lfunction ]
Edit the current source file, or the given filename or the file that contains function.
file [filename ]
Print the name of the current source file, or change the current source file to filename.
fune [function I program lobjfile
Print the name of the current function, or change to the given function, program, or objfile.
Also changes the current scope.
list [ startline [ , endline ] ]
list function List the next ten lines from current source file, list from startline through endline, or and list
from five lines above, to five lines below the first line offunction.
use [ directory-list ]
Print or set the list of directories in which to search for source files.
cd [ directory ]
Change the current working directory for dbx to directory (or to the value of the HOME
environment variable).
pwd
Print the current working directory for dbx.
Ireg-ap[/]
?reg-exp [ ? ]
Search the current file for the regular expression reg-exp, from the next {previous} line to the
end (top). The matching line becomes the new current line.
Miscellaneous Commands

sh command-line
Pass the command line to the shell for execution. The SHELL environment variable determines which shell is used.
alias new-command-name character-sequence
Respond to new-command-name as though it were character-sequence. Special characters
occurring in character-sequence must be enclosed in quotation marks. Alias substitution as
with the C-Shell (csh (1» also occurs.
help [ command ]
Display a synopsis of dbx commands, or print a short message explaining command.
make
Invoke make (l) with the name of the program as its argument. Any arguments set using
dbxenv makeargs are also passed as arguments.
source filename
Read and execute dbx commands fromfilename. Useful when thefilename has been created
by redirecting an earlier status command
quit
Exit dbx.

106

Last change: 23 July 1986

Sun Release 3.2

DBX( 1)

USER COMMANDS

DBX(I)

dbxenv
dbxenv case sensitive I insensitive
dbxenv fpaasm on I off
dbxenv fpabase a[0-7] I off
dbxenv makeargs string
dbxenv stringlen num
dbxenv speed seconds
Display dbx attributes or set the named attribute:
case
Controls whether upper- and lower-case characters are treated as different
values. The default is sensitive.
fpaasm
Controls FPA instruction disassembly. The default is on.
Sets the base register for FPA instruction disassembly. The default is off.
fpabase
makeargs
Sets arguments to pass to make (1). The default is "CC=cc -g".
Set the interval between execution during tracing. The default is 0.5 seconds.
speed
stringlen
Controls the maximum number of characters printed for a "char *" variable
in a C program. The default is 512.
debug [ -k ] [ objfile [ corefile I pid ] ]
With no arguments, print the name of the current program. With arguments, stop debugging
the current program and begin debugging objfile having either corefile or the current process
ID pid.
-k
Kernel debugging.
Stop debugging of the current program, but be ready to debug another.
kill
Detach the current program (process) from dbx. dbx will be unable to access or modify its
detach
state.
proc [pid] For kernel debugging. Display which process is mapped into the user area, or map pid to the
user area.
Machine-Level Commands
tracei [ address] [if condition ]
tracei [ variable ] [at address] [ if condition ]
Trace execution of a specific machine-instruction address.
stopi [ variable ] [ if condition ]
stopi [at address] [if condition]
Set a breakpoint at a machine instruction address.
stepi
nexti
Single step as in step or next, but do a single machine instruction rather than a source line.

address ,address I [mode ]
address I [count] [mode ]
Display the contents of memory starting at the first (or current) address up to the second
address, or until count items have been displayed. The initial display mode is X. The following modes are supported:
i
the machine instruction
d
word in decimal
D
longword in decimal
o
word in octal
long word in octal
x
word in hexadecimal
X
long word in hexadecimal
b
byte in octal
c
byte as a character
s
strings as characters terminated by a null
f
single precision real number
F
double-precision real number
E
extended-precision real number

o

Sun Release 3.2

Last change: 23 July 1986

107

DBX(l)

USER COMMANDS

DBX(l)

An address can be specified as an item from the following list, or as and expression made up
of other addresses and the operators' +', '-', '*', and indirection (unary '*').
&name
symbolic address
$d[0-7]
data registers
$a [0-7]
address registers
$fp
frame pointer, equivalent to register a6
stack pointer, equivalent to register a7
$pc
program counter
$ps
program status
$fp[O-7]
MC68881 data registers
$fpc
MC68881 control register
$fps
MC68881 status register
$fpi
MC68881 instruction address register
$fpf
MC68881 flags register (unused, idle, busy)
$fpg
MC68881 floating-point signal type
double-precision interpretation of FPA registers.
$fpa[0-31]
$sfpa[0-31] single-precision interpretation of FPA registers.

ssp

address = [mode ]
Display the value of the address.
ENVIRONMENT
dbx checks the environment variable EDITOR for the name of the text editor to use with the edit command.
FILES

core
-I.dbxinit

default core file
initial commands

SEE ALSO
cc(1V), 07(1), pc(l)

Debugging Tools/or the Sun Workstation
BUGS

dbx does not correctly handle C variables that are local to compound statements. When printing these variables it often gives incorrect results.
dbx does not handle FORTRAN entry points well- it treats them as if they were independent routines.
dbx does not handle assigning to FORTRAN complex types correctly (see the assign/set command).
Some operations behave differently in dbx than in C:

dbx has two division operators - / always yields a floating-point result and div always
yields an integral result.
An array or function name does not signify the address of the array or function in dbx.
An array name signifies the entire array, and a function name signifies a call to the function with no arguments. The address of an array can be obtained by taking the address of
its first element, and the address of a function can be obtained by taking the address of its
name.

Casts do not work with FORTRAN 77 or Pascal.
Executable code incorporated into a source file using an #include preprocessor directive confuses dbx.

dbx is confused by the output of program generators such as yacc and lex.

108

Last change: 23 July 1986

Sun Release 3.2

DBXTOOL(l)

USER COMMANDS

DBXTOOL(I)

NAME

dbxtool- window- and mouse-based source-level debugger for C, FORTRAN 77, and Pascal programs
SYNOPSIS

dbxtool [ -i ] [ -I dir] [ -k] [ -kbd ] [objfile [ corefile ] ]
DESCRIPTION

dbxtool, a source-level debugger for C, Pascal and FORTRAN 77 programs, is a standard tool that runs
within the SunView environment It accepts the same commands as dbx, but provides a more convenient
user interface.

You can use the mouse to set breakpoints, examine the values of variables, control execution, peruse
source files, and so on. dbxtool has separate sub windows for viewing source code, entering commands and
other uses.
objfile is an object file produced by cc(1V),j77(1), or pc(l) (or a combination of them) with the appropriate flag (-g) specified to produce symbol information in the object file. IMPORTANT: every stage of the
compilation process, including the linking phase, must include the -g option. If no objfile is specified, you
can use the debug command to specify the program to be debugged The object file contains a symbol
table which includes the names of all the source files translated by the compiler to create it. These files are
available for perusal while using the debugger.
If a file named core exists in the current directory or a corefile is specified, dbxtool can be used to examine
the state of the program when it faulted

Debugger commands in the file .dbxinit are executed immediately after the symbolic information is read, if
that file exists in the current directory, or in the user's home directory if .dbxinit doesn't exist in the current
directory.
OPTIONS

-i

Force dbxtool to act as though standard input were a terminal.

-I dir

Add dir to the list of directories that are searched when looking for a source file. Normally
dbxtool looks for source files in the current directory and then in the directory where objfile is
located The directory search path can also be set with the use command. Multiple -I options
may be given.

-k

Kernel debugging.

-kbd

Debugs a program that sets the keyboard into up/down translation mode. This flag is necessary if
you are debugging a program that uses up/down encoding.

USAGE

Refer to dbx(l) for a summary of dbx commands, or Program Debugging Tools for the Sun Workstation
for more complete information on using dbxtool.
FILES

a.out
core

default object file
default core file

SEE ALSO

dbx(l), cc(l V), 07(1), pc(l)
Debugging Toolsfor the Sun Workstation
The SunView Application Programmer's Guide
BUGS

The bugs for dbx(l) apply to dbxtool as well.
The interaction between scrolling in the source subwindow and dbx 's regular expression search commands
is wrong. Scrolling should affect where the next search begins, but it does not.

Sun Release 3.2

Last change: 29 April 1986

109

DC(!)

USER COMMANDS

DC(l)

NAME

de - desk calculator
SYNOPSIS
de [file]
DESCRIPTION
Dc is an arbitrary precision arithmetic package. Ordinarily it operates on decimal integers, but one may
specify an input base, output base, and a number of fractional digits to be maintained. The overall structure
of de is a stacking (reverse Polish) calculator. If an argument is given, input is taken from that file until its
end, then from the standard input The following constructions are recognized:

number
The value of the number is pushed on the stack. A number is an unbroken string of the digits 0-9.
It may be preceded by an underscore _ to input a negative number. Numbers may contain decimal
points.

+ _/

*

%
The top two values on the stack are added (+), subtracted (-), multiplied (*), divided (/), remaindered (%), or exponentiated C). The two entries are popped off the stack; the result is pushed on
the stack in their place. Any fractional part of an exponent is ignored.
A

sx

The top of the stack is popped and stored into a register named x, where x may be any character. If
the s is capitalized, x is treated as a stack and the value is pushed on it.

h

The value in register x is pushed on the stack. The register x is not altered. All registers start with
zero value. If the I is capitalized, register x is treated as a stack and its top value is popped onto the
main stack.

d

The top value on the stack is duplicated.

p

The top value on the stack is printed The top value remains unchanged P interprets the top of the
stack as an ascii string, removes it, and prints it

f

All values on the stack and in registers are printed.

q

exits the program. If executing a string, the recursion level is popped by two. If q is capitalized,
the top value on the stack is popped and the string execution level is popped by that value.

x

treats the top element of the stack as a character string and executes it as a string of de commands.

X

replaces the number on the top of the stack with its scale factor.

[ ••• ]

puts the bracketed ascii string onto the top of the stack.

x

=X

The top two elements of the stack are popped and compared. Register x is executed if they obey the
stated relation.
v

replaces the top element on the stack by its square root Any existing fractional part of the argument is taken into account, but otherwise the scale factor is ignored.
interprets the rest of the line as a UNIX command.

e

All values on the stack are popped.
The top value on the stack is popped and used as the number radix for further input I pushes the
input base on the top of the stack.

110

o

The top value on the stack is popped and used as the number radix for further output.

o

pushes the output base on the top of the stack.

k

the top of the stack is popped, and that value is used as a non-negative scale factor: the appropriate
number of plac~s are printed on output, and maintained during multiplication, division, and
exponentiation. The interaction of scale factor, input base, and output base will be reasonable if all

Last change: 2 June 1983

Sun Release 3.2

DC(1 )

USER COMMANDS

DC(I)

are changed together.

z

The stack level is pushed onto the stack.

z

replaces the number on the top of the stack with its length.

?

A line of input is taken from the input source (usually the terminal) and executed.

,.

are used by be for array operations.

EXAMPLE
Print the first ten values of n!

[lal+dsa*plalO>y]sy
Osal
lyx
SEE ALSO
bc(I), which is a preprocessor for de providing infix notation and a C-like syntax which implements functions and reasonable control structures for programs.
DIAGNOSTICS
'x is unimplemented' where x is an octal number.
'stack empty' for not enough elements on the stack to do what was asked.
'Out of space' when the free list is exhausted (too many digits).
'Out of headers' for too many numbers being kept around.
'Out of pushdown' for too many items on the stack.
'Nesting Depth' for too many levels of nested execution.

Sun Release 3.2

Last change: 2 June 1983

111

DD(I)

USER COMMANDS

DD(I)

NAME

dd - convert and copy a file
SYNOPSIS
dd [option=value] ...
DESCRIPTION

dd copies a specified input file to a specified output with possible conversions. The standard input and output are used by default. The input and output block size may be specified to take advantage of raw physical I/O.
OPTION

VALUES

u=name

input file is taken from fUlme; standard input is default

of=name

output file is taken from name; standard output is default Note that tid creates an explicit output file; therefore the seek option is usually useless with explicit output except in
special cases such as using magnetic tape or raw disk files.

ibs=n

input block size n bytes (default 512).

obs=n

output block size n bytes (default 512).

bs=n

set both input and output block size, superseding ibs and obs; also, if no conversion is
specified, it is particularly efficient since no copy need be done

cbs=n

conversion buffer size

skip=n

skip n input records before starting copy

files=n

copy n input files before terminating (makes sense only when input is a magtape or similar device).

seek=n

seek n records from beginning of output file before copying. This option generally only
works with magnetic tapes and raw disk files and is otherwise usually useless if the
explicit output file was named with the of option.

count=n
conv=ascii
ebcdic
ibm
block
unblock
lcase
ucase
swab
noeTTor
sync
... , ...

copy only n input records
convert EBCDIC to ASCII
convert ASCII to EBCDIC
slightly different map of ASCII to EBCDIC
convert variable length records to fixed length
convert fixed length records to variable length
map alphabetics to lower case
map alphabetics to upper case
swap every pair of bytes
do not stop processing on an error
pad every input record to ibs
several comma-separated conversions

Where sizes are specified, a number of bytes is expected A number may end with k (kilobytes) to specify
multiplication by 1024, b (blocks of 512 bytes) to specify multiplication by 512, or w (words) to specify
multiplication by 4; a pair of numbers may be separated by x to indicate a product.
Cbs is used only if ascii, unblock, ebcdic, ibm, or block conversion is specified. In the first two cases, cbs
characters are placed into the conversion buffer, any specified character mapping is done, trailing blanks
trimmed and new-line added before sending the line to the output In the latter three cases, characters are
read into the conversion buffer, and blanks added to make up an output record of size cbs.
After completion, dd reports the number of whole and partial input and output blocks.
EXAMPLE

112

Last change: 23 September 1985

Sun Release 3.2

DD(l)

USER COMMANDS

DD(l)

To read an EBCDIC tape blocked ten 80-byte EBCDIC card images per record into the ASCII file x:
tutorial% dd if=/dev/rmtO or=x ibs=800 cbs=80 conv=ascii,lcase
Note the use of raw magtape: dd is especially suited to I/O on the raw physical devices because it allows
reading and writing in arbitrary record sizes.
SEE ALSO
cP(l), tr(l V)
DIAGNOSTICS
f+p records in(out): numbers of full and partial records read(written)
BUGS
The ASCII/EBCDIC conversion tables are taken from the 256 character standard in the CACM Nov, 1968.
The ibm conversion, while less blessed as a standard, corresponds better to certain IBM print train conventions. There is no universal solution.
The block and unblock options cannot be combined with the ascii, ebcdic or ibm. Invalid combinations
silently ignore all but the last mutually-exclusive keyword

Sun Release 3.2

Last change: 23 September 1985

113

DEFAULTSEDIT ( 1 )

USER COMMANDS

DEFAULTSEDIT( 1)

NAME

defaultsedit,
defaults merge,
defaults from input
defaults to indentpro,
defaults to maitrc,
indentpro_ to_defaults, IOckscreen_default, tiailrc_to_defaults, scrolldefaults - window- and mouse-based
default parameters editor
SYNOPSIS

deraultsedit
DESCRIPTION

defaultsedit is a standard tool provided with the SunView environment.
defaultsedit presents a convenient user interface for inspecting and setting default parameters. It can be
viewed as a replacement for the traditional UNIX defaultsedit to manipulate options to the programs
indent, mail and mailtool, stty, and defaultsedit, as well as the menu, scrollbar, text subwindow and tty
subwindow packages and the SunView environment.

Any program or package which a user can customize by setting or changing a parameter could be written
such that it gets its options from the database manipulated through defaultsedit. For information on how to
do this see the chapter on the Defaults Database in the SunView System Programmer' s Guide.
OPTIONS

defaultsedit accepts all of the generic tool arguments discussed in suntools(1).
SUBWINDOWS

defaultsedit consists of four subwindows. From top to bottom they are:

control

contains the name of the category currently displayed, and buttons labeled SAVB, QUIT,
RESET, and EDIT ITEM. To change the category, click on the word CATEGORY with the
left mouse button, or use the menu that pops up when you click with the right mouse button.

message

a small text subwindow where messages from defaultsedit are displayed.

parameters

shows all current default parameter names with corresponding values. Clicking the left
mouse button over a parameter displays a help string in the message sub window.

edit

a small text subwindow which enables text editing of parameter values. This is useful for
very long text values, such as a long mailing list

USING DEFAULTS EDIT

SAVE

Saves the current values for all categories in your private database file in your home directory.

that is, the .defaults

QUIT

exits without saving any changes.

RESET

resets the default parameters of the current category to the values in your private database.
This is useful if you change some values, then change your mind and want to restore the original values.

EDIT ITEM Pressing the right mouse button over the EDIT ITEM button brings up a menu with three
choices: COpy ITEM, DELETE ITEM and EDIT LABEL. Only text or numeric items can
be edited. Also, note that edits made using this menu will appear only in your private
defaults database, not in the master database. The three editing operations are described
below.
COpy ITEM Selecting COpy ITEM causes the current item to be duplicated. You can then edit both the
label and the value of the the newly created item. Only items with text or numeric values
can be copied in this way. COpy ITEM is useful when you want to change the number of
instances of a certain type of item - for example, to insert a new mail alias into your
defaults database.
DELETE ITEM
Selecting DELETE ITEM will delete the current item from your private database. It cannot
be permanently deleted if the corresponding node is present in the master database.

114

Last change: 29 May 1986

Sun Release 3.2

DEFAULTSEDIT( 1)

USER COMMANDS

DEFAULTSEDIT( 1)

However, you can make it behave like an undefined node by giving it the special value

\255Undefined\255.
EDIT LABEL
Selecting EDIT LABEL allows you to edit the label of the current item. When you select
EDIT LABEL, the label of the current item changes from bold to normal face. Then you
can select the label and edit it as a normal panel text item.
FILES

-I.defaults
lusrllib/defaults/* .d
Note: A performance optirnzation may be enabled by setting the Private_only parameter in the Defaults
category. If this is set to True, only the user's private defaults file is consulted.
SEE ALSO
Windows and Window-Based Tools: Beginner's Guide

The SunView System Programmer's Guide
BUGS

Editing of choice items or categories is not supported by defaultsedit. Neither is editing of the master
defaults database - to add a new program to the master defaults database, you have to edit a master
defaults textfile.
Switching between certain categories may cause the database to be reread and over-write any changed
values. Therefore, using the "Save" button for each category changed is recommended.

Sun Release 3.2

Last change: 29 May 1986

115

DELTA ( 1)

USER COMMANDS

DELTA(I)

NAME

delta - make a delta (change) to an sees file
SYNOPSIS

lusrlsccs/delta [ -r SID] [ -s] [ -n ] [ -g list] [ -m [mrlist] ] [ -y [ comment]] [ -p ] file •••
DESCRIPTION
Delta permanently introduces into the named sees file changes that were made to the file retrieved by
get(1) (called the g-file, or generated file).

Delta makes a delta to each named sees file. If a directory is named, delta behaves as though each file in
the directory were specified as a named file, except that non-sees files (last component of the path name
does not begin with s.) and unreadable files are silently ignored. If a name of - is given, the standard input
is read (see WARNINGS); each line of the standard input is taken to be the name of an sees file to be processed.
Delta may issue prompts on the standard output depending upon certain options specified and flags (see
admin (1» that may be present in the sees file (see -m and -y options below).
OPTIONS

Options apply independently to each named file.
-r SID Uniquely identifies which delta is to be made to the sees file. The use of this option is necessary
only if two or more outstanding get's for editing (get -e) on the same sees file were done by the
same person (login name). The SID value specified with the -r option can be either the SID
specified on the get command line or the SID to be made as reported by the get command (see
get (1». A diagnostic results if the specified SID is ambiguous, or, if necessary and omitted on the
command line.

-s

Do not display the created delta's SID, number of lines inserted, deleted and unchanged in the
sees file.

-n

Retain the edited g-file which is normally removed at completion of delta processing.

-g list

Specifies a list of deltas to be ignored when the file is accessed at the change level (SID) created
by this delta. See get(l) for the definition of list.

-m [mrlist]

If the sees file has the v flag set (see admin(l», a Modification Request (MR) number must be
supplied as the reason for creating the new delta.
If -m is not used and the standard input is a terminal, the prompt MRs? is issued on the standard
output before the standard input is read; if the standard input is not a terminal, no prompt is issued.
The MRs? prompt always precedes the comments? prompt (see -y option).
MRs in a list are separated by blanks and/or tab characters. An unescaped new-line character terminates the MR list
Note that if the v flag has a value (see admin(1», it is taken to be the name of a program (or shell
procedure) which will validate the correctness of the MR numbers. If a non-zero exit status is
returned from MR number validation program, delta terminates (it is assumed that the MR
numbers were not all valid).
-y [comment]
Arbitrary text to describe the reason for making the delta. A null string is considered a valid comment.

If -y is not specified and the standard input is a terminal, the prompt comments? is issued on the
standard output before the standard input is read; if the standard input is not a terminal, no prompt
is issued. An unescaped new-line character terminates the comment text.
-p

116

Display (on the standard output) the sees file differences before and after the delta is applied in a
diff( 1) format

Last change: 6 March 1984

Sun Release 3.2

DELTA(I)

USER COMMANDS

DELTA(I)

FILES

All files of the form ?-file are explained in the Source Code Control System User's Guide. The naming
convention for these files is also described there.
g-file
p-file
q-file
x-file
z-file
d-file
Ibinldiff

Existed before the execution of delta; removed after completion of delta.
Existed before the execution of delta; may exist after completion of delta.
Created during the execution of delta; removed after completion of delta.
Created during the execution of delta; renamed to sees file after completion of delta.
Created during the execution of delta; removed during the execution of delta.
Created during the execution of delta; removed after completion of delta.
Program to compute differences between the "gotten" file and the g-file.

WARNINGS

Lines beginning with an SOH Asell character (binary 001) cannot be placed in the sees file unless the
SOH is escaped This character has special meaning to secs (see sccsfile(5» and will cause an error.
A get of many sees files, followed by a delta of those files, should be avoided when the get generates a
large amount of data Instead, multiple get/delta sequences should be used
If the standard input (-) is specified on the delta command line, the -m (if necessary) and -y options must
also be present. Omission of these options is an error.
SEE ALSO

sccs(I), admin(I), get(I), help(I), prs(l), sccsfile(5).

Programming Utilities/or the Sun Workstation.
DIAGNOSTICS

Use help(l) for explanations.

Sun Release 3.2

Last change: 6 March 1984

117

DEROFF(l)

USER COMMANDS

DEROFF(l)

NAME

deroff - remove nroff, troff, tbl and eqn constructs
SYNOPSIS
deroff [ -w ] file •••
DESCRIPTION
Deroff reads each file in sequence and removes all nroff and troff command lines, backslash constructions,
macro definitions, eqn constructs (between' .EQ' and' .EN' lines or between delimiters), and table descriptions and writes the remainder on the standard output Deroff follows chains of included files (' .so' and
'.nx' commands); if a file has already been included, a '.so' is ignored and a '.nx' terminates execution. If
no input file is given, deroff reads from the standard input file.
OPTIONS

-w

Generate a word list, one word per line. A 'word' is a string of letters, digits, and apostrophes,
beginning with a letter; apostrophes are removed. All other characters are ignored.

SEE ALSO

troff(l), eqn(l), tbl(l)
BUGS

Deroff is not a complete troff interpreter, so it can be confused by subtle constructs. Most errors result in
too much rather than too little output.
Deroff does not work well with files that use .so to source in the standard macro package files.

118

Last change: 1 February 1985

Sun Release 3.2

DES ( 1)

USER COMMANDS

DES(l)

NAME

des - encrypt/decrypt with Data Encryption Standard
SYNOPSIS
des-e l-d [-b] [-f] [-kkey] [-s] [infile [ou¢le]]
DESCRIPTION
des encrypts and decrypts data using the NBS Data Encryption Standard algorithm. One of -e (for encrypt)

or -d (for decrypt) must be specified
The des command is provided to promote secure exchange of data in a standard fashion.
OPTIONS

-b

Select ECB (eight bytes at a time) encryption mode.

-f

Suppress warning message when software implementation is used

-k key Use the encryption key specified.

-s

Selects software implementation for the encryption algorithm.

Two standard encryption modes are supported by the des program, Cipher Block Chaining (CBC - the
default) and Electronic Code Book (ECB - specified with -b). CBC mode treats an entire file as a unit of
encryption, i.e., if insertions or deletions are made to the encrypted file then decryption will not succeed.
CBC mode also ensures that regularities in clear data do not appear in the encrypted data. ECB mode
treats each 8 bytes as units of encryptions, so if parts of the encrypted file are modified then other parts may
still be decrypted. Identical values of clear text encrypt to identical values of cipher text
The key used for the DES algorithm is obtained by prompting the user unless the -k key option is given. If
the key is an argument to the des command, it is potentially visible to users executing ps(l) or a derivative.
To minimize this possibility, des takes care to destroy the key argument immediately upon entry.
The des command attempts to use DES hardware for its job, but will use a software implementation of the
DES algorithm if the hardware is unavailable. Normally, a warning message is printed if the DES
hardware is unavailable since the software is only about lIS0th as fast However, the -f option will
suppress the warning. The -s option may be used to force use of software instead of hardware DES.
The des command reads from standard input unless infile is specified and writes to standard output unless
ou¢le is given.
The following sections give information required to implement compatible facilities in other environments.
Since the CBC and ECB modes of DES require units of 8 bytes to be encrypted, files being encrypted by
the des command have 1 to 8 bytes appended to them to cause them to be a multiple of 8 bytes. The last
byte, when decrypted, gives the number of bytes (0 to 7) which are to be saved of the last 8 bytes. The
other bytes of those appended to the input are randomized before encryption. If, when decrypting, the last
byte is not in the range of 0 to 7 then either the encrypted file has been corrupted or an incorrect key was
provided for decryption and an error message is printed.
The DES algorithm requires an 8 byte key whose low order bits are assumed to be odd-parity bits. The
ASCII key supplied by the user is zero padded to 8 bytes and the high order bits are set to be odd-parity
bits. The DES algorithm then ignores the low bit of each ASCII character, but that bit's information has
been preserved in the high bit due to the parity.
The CBC mode of operation always uses an initial value of all zeros for the initialization vector, so the first
8 bytes of a file are encrypted the same whether in CBC or ECB mode.
FILES

/dev/des?
BUGS

It would be better to use a real 56-bit key rather than an ASCTI-based 56-bit pattern. Knowing that the key
was derived from ASCII radically reduces the time necessary for a brute-force crytographic attack.

Sun Release 3.2

Last change: 23 September 1985

119

DES(l)

USER COMMANDS

DES ( 1)

RESTRICTIONS

This program is not available on software shipped outside the U.S.

120

Last change: 23 September 1985

Sun Release 3.2

DF( 1)

USER COMMANDS

DF(1)

NAME

df - report free disk space on file systems
SYNOPSIS
df [ -i] [ -t type ] [filesystem ... ] [filename ... ]
DESCRIPTION
df displays the amount of disk space occupied by currently mounted file systems, the amount of used and
available space, and how much of the file system's total capacity has been used. Used without arguments,
dfreports on all mounted file systems, producing something like:

tutorial% df
Filesystem kbytes
Idev/ipOa
7445
Idev/ipOg
42277

used avail capacity
4714 1986 70%
35291 2758 93%

Mounted on
I

lusr

Note that used+avail is less than the amount of space in the file system (kbytes); this is because the system
reserves a fraction of the space in the file system to allow its file system allocation routines to work well.
The amount reserved is typically about 10%; this may be adjusted using tunefs. When all the space on a
file system except for this reserve is in use, only the super-user can allocate new files and data blocks to
existing files. When a file system is overallocated in this way, df may report that the file system is more
than 100% utilized.
If arguments to df are disk partitions (for example, /devlipOa) or UNIX path names, df produces a report on
the file system containing the named file. Thus "df ." shows the amount of space on the file system containing the current directory.
OPTIONS

-i

Report the number of used and free inodes.

-t type Report on filesystems of a given type (for example, nfs or 4.2).

FILES

letc/mtab

list of currently mounted filesystems

SEE ALSO
du(1V), mtab(5), quot(8), tunefs(8)

Sun Release 3.2

Last change: 23 September 1985

121

DIFF( 1)

USER COMMANDS

DIFF( 1)

NAME

diff - show differences between the contents of files or directories
SYNOPSIS

diff [-biwt] [-e[#] l-e I-f I-n I-b] filename! filename2
difT [ -biwt] [ -Dstring] filename! filename2
difT [ -biwt] [ -e[#] l-e I-f I-n I-b] [ -I] [ -r] [ -s] [ -Sname] dir! dir2
DESCRIPTION
diff is a differential file comparator. When run on regular files, and when comparing text files that differ
during directory comparison (see the notes below on comparing directories), difftells what lines must be
changed in the files to bring them into agreement. Except in rare circumstances, diJ! finds a smallest
sufficient set of differences. If neither filename! nor filename2 is a directory, either may be given as -, in
which case the standard input is used. If filename! is a directory, a file in that directory whose filename is
the same as the filename offilename2 is used (and vice versa).

There are several options for output format; the default output format contains lines of these forms:
nl a n3,n4
nl,n2 dnJ
nl ,n2 c nJ ,n4

These lines resemble ed commands to convert filename! intofilename2. The numbers after the letters pertain to filename2. In fact, by exchanging a for d and reading backward one may ascertain equally how to
convertfilename2 intofilenamel. As in ed, identical pairs, where n! = n2 or n3 = n4, are abbreviated as a
single number.
Following each of these lines come all the lines that are affected in the first file flagged by <, then all the
lines that are affected in the second file flagged by>.
If both arguments are directories, diff sorts the contents of the directories by name, and then runs the regular file diJ! program as described above on text files which are different Binary files which differ, common
subdirectories, and files which appear in only one directory are listed.
OPTIONS

-b

ignore trailing blanks (spaces and tabs) and treat all other strings of blanks as equivalent.

-w

ignore all blanks (spaces and tabs); e.g., "if ( a == b )" will compare equal to "if(a==b)" .

-i

ignore the case of letters; e.g., "A" will compare equal to "a".

-t

expand tabs in output lines. Normal or -e output adds character(s) to the front of each line which
may screw up the indentation of the original source lines and make the output listing difficult to
intetpret This option will preserve the original source's indentation.

The following four options are mutually exclusive:
-e[#]

produces a listing of differences with lines of context. The default is to present 3 lines of context
and may be changed, (to 10, for example), by -elO. With -e the output format is modified
slightly: output begins with identification of the files involved and their creation dates, then each
change is separated by a line with a dozen *s. The lines removed fromfilenamel are marked with
- ; those added to filename2 are marked +. Lines which are changed from one file to the other are
marked in both files with! .
Changes which lie within  lines of each other are grouped together on output (This is a
change from the previous "diff -c" but the resulting output is usually much easier to intetpret.)

-e

122

produce a script of 8, c, and d commands for the editor ed, which will recreate filename2 from
filenamel.
In connection with -e, the following shell program may help maintain multiple versions of a file.
Only an ancestral file ($1) and a chain of version-ta-version ed scripts ($2,$3, ... ) made by diff
need be on hand. A 'latest version' appears on the standard output

Last change: 23 September 1985

Sun Release 3.2

DIFF( 1)

USER COMMANDS

DIFF( 1)

(shift; cat $*; echo '1,$p')I ed - $1
Extra commands are added to the output when comparing directories with --e, so that the result is
a sh script for converting text files which are common to the two directories from their state in
dir1 to their state in dir2.
-r

produce a script similar to that of --e, not useful with ed, which is in the opposite order.

-0

produce a script similar to that of -e, but in the opposite order and with a count of changed lines
on each insert or delete command.

-b

does a fast, half-hearted job. It works only when changed stretches are short and well separated,
but does work on files of unlimited length.

Options for the second form of diff are as follows:
-Dstring
create a merged version of filename] and filename2 on the standard output, with C preprocessor
controls included so that a compilation of the result without defining string is equivalent to compilingfilenamel, while defining string will yield filename2 .

Options when comparing directories are:
-I

long output format; each text file diff is piped through pr to paginate it, other differences are
remembered and summarized after all text file differences are reported.

-r

apply diff recursively to common subdirectories encountered.

-s

report files which are the same, which are otherwise not mentioned. -

-Sname

starts a directory diffin the middle, beginning with file name.
FILES

Itmpld?????
lusr/lib/difth for -b
Ibin/diff for directory diffs
lusrlbinlpr
SEE ALSO

cmp(I), comm(I), cpp(I), diff3(IV), ed(l)
DIAGNOSTICS

Exit status is 0 for no differences, 1 for some differences, 2 for trouble.
BUGS

Editing scripts produced under the --e or -r option are naive about creating lines consisting of a single'.'.
When comparing directories with the -b, -w, or -i options specified, diff first compares the files (as in
cmp), and then runs the regular diff algorithm if they are not equal. This may cause a small amount of
spurious output if the files then turn out to be identical because the only differences are insignificant blank
string or case differences.
The -D option ignores existing preprocessor controls in the source files, and can generate #irders's with
overlapping scope. The output should be checked by hand, or run through cc -E and then diffed with the
original source files. Discrpancies revealed should be corrected before compilation.
WARNINGS
Missing newline at end offile X

indicates that the last line of file X did not have a new-line. If the lines are different, they will be
flagged and output, although the output will seem to indicate they are the same.

Sun Release 3.2

Last change: 23 September 1985

123

USER COMMANDS

DIFF3( IV)

DIFF3( IV)

NAME

diff3 - 3-way differential file comparison
SYNOPSIS
difT3 [ -exEX3 ] file 1 file2 file3
SYSTEM V SYNOPSIS

lusrlSbinldifT3 [ -ex3 ] filel file2 file3
DESCRIPTION
diff3 compares three versions of a file, and publishes disagreeing ranges of text flagged with these codes:

all three files differ
==== 1

filel is different

====2

file2 is different

====3

file3 is different

The types of differences between a given range within the given files is indicated in one of these ways:

f:nl a

Text is to be appended after line number nl in file f, where f = 1, 2, or 3.

f:nl,n2c Text is to be changed in the range line nl to line n2. IT nl = n2, the range may be abbreviated to
nl.
The original contents of the range follows immediately after a c indication. When the contents of two files
are identical, the contents of the lower-numbered file is suppressed.
OPTIONS
The options to diff3 instruct it to produce a script for the editor ed, rather than a list of differences. This
script will incorporate some or all of the differences between file2 and file3 into filel. This script will not
include a w or q command at the end, so that it will not write out the changed file.

-e

Produce a script that will incorporate all changes betweenfile2 andfile3, i.e. the changes that normally would be fiagged "====" and "====3".

-x

Produce a script that will incorporate only changes flagged "====".

-3

Produce a script that will incorporate only changes fiagged "====3".

-E

Produce a script that will incorporate aU changes between file2 and file3, but treat overlapping
changes (i.e., changes that would be flagged with "====" in the normal listing) differently. The
overlapping lines from both files will be inserted by the edit script, bracketed by "«««" and
"»»»" lines.

-x

Produce a script that will incorporate only changes flagged ====, but treat these changes in the
manner of the -E option.

For example, suppose lines 7-8 are changed in both filel and file2. Applying the edit script generated by
the command
difO -E filel file2 file3
to file 1 results in the file:
lines 1-6
of file 1

«««< filel
lines 7-8
of file 1
lines 7-8
offile3
»»»> file3

124

Last change: 17 July 1986

Sun Release 3.2

DIFF3( tV)

USER COMMANDS

DIFF3( tV)

rest of filel
SYSTEM V OPTIONS
The System V version of diff3 does not support the -E and -x options. The script produced by the -e, -x,
and -3 options does include a wand q command at the end, so that it will write out the changedfile.
EXAMPLES
The following command will incorporate all the changes between file2 and file3 into filel , and print the
resulting file to the standard output If the System V version of difj3 , is used, filel will be replaced with the
resulting file.

(diff3 -e filet file2 file3; echo '1,$p') I ed - filel
FILES

Itmpld3?????
lusrllibldiff3
lusrl5libldifj3prog
SEE ALSO
diff(l)

BUGS
Text lines that consist of a single. will defeat -e.

Sun Release 3.2

Lastchange: 17 July 1986

125

DIFFMK( I)

USER COMMANDS

DIFFMK(I)

NAME

diffmk: - mark differences between document files
SYNOPSIS

difTmk oldfile changedfile markedfile
DESCRIPTION
diffmk compares two versions of a file and creates a third file that includes "change mark" commands for
troff(I). name} and name2 are the old and new versions of the file. diffmk generates name3, which, contains the text from name2 with troff(l) "change mark" requests (.me) inserted where changedfile differs
from oldfile. When name3 is formatted, changed or inserted text is shown by I at the right margin of each
line. The position of deleted text is shown by a single *.

diffmk can also be used to produce listings of C (or other) programs with changes marked. A typical command line for such use is:
diffrnk old.c new.c tmp; nroff reqs tmp I pr
where the file reqs contains the commands:
.pl 1
.II 77
.nf
.eo
.nc
The .ll request might specify a different line length, depending on the nature of the program being printed.
The .eo and .De requests are probably needed only for C programs.
If the characters
them.

I and * are inappropriate,

you might run marked/tie through sed(lV) to globally change

SEE ALSO
diff(I), nroff(I), sed(IV)

BUGS
Aesthetic considerations may dictate manual adjustment of some output. File differences involving only
formatting requests may produce undesirable output, i.e., replacing .sp by .sp 2 will produce a "change
mark" on the preceding or following line of output.

126

Last change: 9 April 1986

Sun Release 3.2

DIRCMP(lV)

USER COMMANDS

DIRCMP(lV)

NAME

dircmp - directory comparison
SYNOPSIS

lusrlSbinldircmp [ -d ] [ -S ] [ -wn ] dirl dir2
DESCRIPTION
Note:

OPTIONS
-d

Optional Software (System V Option). Refer to Installing UNIX on the Sun Workstation for information on how to install this command. dircmp examines dir1 and dir2 and generates various
tabulated information about the contents of the directories. Listings of files that are unique to each
directory are generated for all the options. If no option is entered, a list is output indicating
whether the filenames common to both directories have the same contents.
Compare the contents of files with the same name in both directories and output a list telling what
must be changed in the two files to bring them into agreement. The list format is described in
diff(I).

-s

Suppress messages about identical files.

-wn

Change the width of the output line to n characters. The default width is 72.

SEE ALSO
cmp(I), diff( 1)

Sun Release 3.2

Last change: 17 July 1986

127

DOMAINNAME ( 1 )

USER COMMANDS

DOMAINNAME ( 1 )

NAME

domainname - set or display name of current domain system
SYNOPSIS

domainname [ nameo/domain ]
DESCRIPTION
Without an argument, domainname displays the name of the current domain. Only the super-user can set
the domainname by giving an argument; this is usually done in the startup script letclrc.local. Currently,
domains are only used by the yellow pages, to refer collectively to a group of hosts.
SEE ALSO
ypinit(8)

128

Last change: 23 September 1985

Sun Release 3.2

DU( IV)

USER COMMANDS

DU( IV)

NAME

du - summarize disk usage
SYNOPSIS

du [ -s] [ -a ] [ name 1
SYSTEM V SYNOPSIS

du [ -s] [ -a ] [ -r ] [ name 1
DESCRIPTION
du gives the number of kilobytes contained in all files and, recursively, directories within each specified
directory or file name. If name is missing, • (the current directory) is used.

A file which has multiple links to it is only counted once.
SYSTEM V DESCRIPTION
The System V version of du gives the number of 512-byte blocks rather than the number of kilobytes.
OPTIONS

-s

Only display the grand total for each of the specified name s.

-a

Generate an entry for each file.

Entries are generated only for each directory in the absence of options.
SYSTEM V OPTIONS
-r
The System V version of du is normally silent about directories that cannot be read, files that cannot be opened, etc. The -r option will cause du to generate messages in such instances.
EXAMPLE
Here is an example of using du in a directory. We used the pwd command to identify the directory, then
used du to show the usage of all the subdirectories in that directory. The grand total for the directory is the
last entry in the display:
%pwd

lusrlhenry/misc
%du

5
33

44
217
401

144
80
388
93
15
1211
%

Jjokes
Jsquash
Jtech.papers/lpr.document
Jtech.papers/new.manager
Jtech.papers
Jmemos
Jletters
Jwindow
Jmessages
Juseful.news

SEE ALSO
df(I), quot(8)

BUGS
Filename arguments that are not directory names are ignored, unless you use -a .
If there are too many distinct linked files, du will count the excess files more than once.

Sun Release 3.2

Last change: 10 April 1986

129

ECHO ( IV)

USER COMMANDS

ECHO ( IV)

NAME

echo - echo arguments
SYNOPSIS

echo [ -n ] [argument ••• ]
SYSTEM V SYNOPSIS

echo argument •••
DESCRIPTION
echo writes its arguments on the standard output. Arguments must be separated by spaces or tabs, and terminated by a newline.

echo is useful for producing diagnostics in shell programs and for writing constant data on pipes. If you
are using the Bourne Shell (sh (1», you can send diagnostics to the standard error file by typing:
echo ••• 1>&
SYSTEM V DESCRIPTION
Note: If lusrl5bin is ahead of lusrlbin in the Bourne shell's search path, its built-in echo command mimics the System V version of echo as described here.

echo also understands C-like escape conventions; beware of conflicts with the shell's use of \:

\b

\c
\f
\n
\r
\t
\v
\\

\n

backspace
print line without new-line
form-feed
new-line
carriage return
tab
vertical tab
backslash
the 8-bit character whose ASCII code is the 1-,2- or 3-digit octal number n, which must
start with a zero.

OPTIONS
-0

Don't add the newline to the output.

SEE ALSO
sh(l)

130

Last change: 16 April 1986

Sun Release 3.2

ED( 1)

USER COMMANDS

ED(1 )

NAME

ed - text editor
SYNOPSIS
ed [ - ] [ -x] [filename ]
DESCRIPTION
ed is the basic line editor in the UNIX system. Although superseded by ex and vi for most purposes, ed is
still used by system utilities such as sees.
You can tell ed to perform various operations on the lines you specify. (see Line Addressing, below, for a
discussion of how to·form line-addresses for ed). You can print (display) lines, change lines, insert new
lines into the buffer, delete existing lines, you can move or copy lines to a different place in the buffer, or
you can substitute character strings within lines. (See List of Operations, below, for a guide. Also, see
Regular Expressions for string-matching metacharacters.)

ed does not operate directly on the contents of a file - when editing a file, ed reads the contents of the file
into a buffer or seratehpad. All changes made during an editing session are made on the contents of the
buffer. The copy must be 'saved' or 'written' - using the w (write) command - to save changes.
The command-line shown in the synopsis above invokes ed. If filename is given, ed reads a copy of
filename into its buffer so that it can be edited (simulates an e operation onfilename).

ed commands have a simple and regular structure: commands consist of an optional line-address, or two
optional line-addresses separated by a comma, then a single letter operation, optionally followed by some
other parameter:
[line-address [,line-address ] ] operation [parameter]
For example, '1,10p' means 'print (display) lines 1 through 10' (two line-addresses), '5a' means 'append
after line 5' (one line-address), and d means 'delete the current line' (no line-address with the current line
used as default). Parameter varies for each operation - for the move and transfer operations, for example, it is the line that the addressed lines are to be moved or transferred after. These operations actually
have three line-addresses. For reading and writing a file, parameter specifies the name of the file that is to
be read.

ed is extremely terse in its interaction with the user -

ed's normal response to just about any problem is
simply a question mark? You get this response when, for instance, ed can't find a specified line in the
buffer, or if a search for a regular expression fails in a substitute (s) operation.

OPTIONS
Don't display character counts normally given by the e, r, and w operations the standard input is an editor script.
-x

can be used when

Simulate an x operation on the named file before reading it into the buffer, to handle encryption.

LINE ADDRESSING
The format of ed operations above shows that an operation can be preceded by one or two line-addresses,
both of which are optional. If only one line-address is specified, operations are performed on that specific
line. If two line-addresses are supplied, ed operates on the inclusive range of lines between them.
Line-addresses are usually separated from each other by a comma 1,10p
prints (displays) lines 1 thru 10.

for instance:

Line addresses may also be separated by a semicolon. Whereas the starting position for line-addresses
separated by a comma is the same place in the buffer, when a line-address is followed by a semicolon, the
current line is set to the line-address preceding the semicolon before any subsequent line-addresses are
interpreted. For example:
IDomaine Chandon! ;//p
sets the current line to the first occurrence of the string 'Domaine Chandon' before starting the search for
the second occurrence. This feature can be used to determine the starting line for forward and backward

Sun Release 3.2

Last change: 5 December 1985

131

ED( 1)

USER COMMANDS

ED(I)

searches ('I', '?').
Lines can be accessed (addressed, in ed terminology) in several ways, but the most easily understood way
of addressing lines is by line number. Line numbers in ed are relative to the start of the buffer. In practice,
addressing lines by number proves to be the most awkward to use, so ed provides other mechanisms for
line-addressing. Note that the line numbers associated with lines in the buffer are not physically present
with the text of the lines - they are just an addressing mechanism.
While ed is working on the buffer, it keeps track of the line on which you last performed some operation.
This line is called the 'current line'. As described below, you can indicate the current line by typing a
period character (.).
If you don't specify a line for an operation to operate on, most ed operations work on the line addressed by
the current line.

When ed starts working on a file, the current line is positioned at the last line in the buffer. Thereafter, the
current line usually changes when any operation is performed. In general, the current line sits at the last
line affected by whatever ed operation you used. For instance, if you print lines 1 through 10 of the buffer,
after the lines are displayed, the current line will be positioned at line 10.
Line-addresses are constructed from elements as shown in the list below. Some special characters are used
as a shorthand for certain line-addresses:
('dot') addresses the current line.

$

addresses the last line of the buffer.

nnn

A decimal number nnn addresses the nnn -th line of the buffer.

'x

addresses the line marked with the name x, which must be a lower-case letter. Mark lines with the
k operation described below.

Iregular expressionl
A regular expression enclosed in slashes 'I' searches forward from the current line and stops at
the first line containing a string that matches the regular expression. If necessary, the search
wraps around to the beginning of the buffer.
?regular expression?
A regular expression enclosed in question marks'?, searches backward from the current line and
stops at the first line containing a string that matches the regular expression. If necessary the
search wraps around to the end of the buffer.
address±nnn
An address followed by a plus sign '+' or a minus sign '-' followed by a decimal number
specifies that line-address plus or minus the indicated number of lines. Plus is assumed if no signs
are given.
±address
An address beginning with '+' or '-' is taken relative to the current line; in other words, '-5' is
understood to mean '.-5'.
address±
An address ending with '+' or '-', adds or subtracts 1. As a consequence of this rule and the previous rule, the line-address '-' refers to the line before the current line. Moreover, trailing' +' and
'-' characters have cumulative effect, so '--' refers to the current line less 2.
To maintain compatibility with earlier versions of ed, the character 'A' in line-addresses is
equivalent to '-'.
ed operations do not necessarily use line-addresses; they may use one or two. Operations which don't use
line-addresses regard the presence of a line-address as an error. Operations which accept one or two lineaddresses assume default line-addresses if these are not specified. If more line-addresses are given than
such an operation requires, the last one or two (depending on what is accepted) are used. The second line-

132

Last change: 5 December 1985

Sun Release 3.2

ED(I)

USER COMMANDS

address of any two-address sequence must be greater than the first line-address must follow the first line in the buffer.

ED(1 )

that is, the second line

LIST OF OPERATIONS
ed operates in one of two major modes: command mode and text input mode. ed always starts up in commandmode.

While you are typing commands at ed, you are in command mode. Some commands - a for append, c for
change, and i for insert - provide for adding new text to the buffer. While ed is accepting new text, you
are in text input mode. You exit from text input mode by typing a period '.' alone at the beginning of a
line. ed then reverts to command mode. For example, here is a very short illustration of command mode
versus text mode:
tutorial% ed winelist
(tell ed to edit a file called winelist)
42
(ed states there are 42 characters in the file)
l,$p
(in command mode-tell ed to print all lines)
1978 Chateau Chunder
1979 Redeye Canyon
a
(in command mode-tell ed to append text)
(text input mode-add a new line)
1980 Doomsday Special
(period ends text input mode)
(back
in command mode- print last line entered)
P
1980 Doomsday Special
w
(command mode - write the file)
(ed displays the number of characters written)
65
q
(command mode-quit the edit session)
(back in the Shell)
tutorial%

If you interrupt ed, it displays '?interrupted' and returns to command mode.

a Append Text.
Reads the text entered in input mode and appends it to the buffer after the addressed line. a
accepts one line-address - default line-address is the current line. The new current line is the last
line input, or at the addressed line if no text is entered Address '0' is a valid place to append text,
in which case text is placed at the beginning of the buffer.
c

Change Lines.
Deletes the addressed lines, then accepts input text which replaces these lines. c accepts two
line-addresses - default line-address is the current line. The current line is left on the last line
input, or at the line preceding the deleted lines if no text is entered

d

Delete Lines.
Delete the addressed lines from the buffer. d accepts two line-addresses - default line-address is
the current line. The line originally after the last line deleted becomes the current line; if the lines
deleted were originally at the end, the new last line becomes the current line.

e filename Edit a file.
Deletes the entire contents of the buffer, and then reads in the named file. e sets the current line to
the last line of the buffer, and reports the number of characters read into the buffer. e remembers
filename for possible use as a default file name in a subsequent r or w operations. If no filename is
given, the remembered filename is used. e displays a ? if the buffer has not been written out since
the last change made - a second e operation says you really mean it.

Efilename
Same as e, but will silently allow you to quit an editing session without warning you if you have
not written your file. e, on the other hand, reminds you to save your changes if you have altered
the buffer at all.
f filename Display Remembered Filename.
Display the currently 'remembered filename'. If filename is given, the currently 'remembered

Sun Release 3.2

Last change: 5 December 1985

133

ED(I)

USER COMMANDS

ED(I)

filename' is changed to filename .

glregular expression/operation list
This is the global operation: perform operation list on all lines in the range of line-addresses containing regular expression. g accepts two line-addresses - default is all lines in the buffer. Also
see the v operation, which inverts the sense of regular expression.
If your operation list actually takes up more than a single line, you must end every line except the
last (the true 'end' of the global operation) with an escape character, '\'. For example, if you want
to substitute 'jimjams' for 'frarnrnis', then append several lines of text to every line containing the
string 'widget' and print those lines, you would type this sequence:
g/widgetls/frarnrnisljimjarnsl\
a\
new line of text\
another new line of text\
\
P
Note that the a, i, and c operations, which put ed in input mode, are permitted in the operation list;
the final • terminating input may be omitted if it is the last line of the operation list. The g and v
operations are not permitted in the operation list.

.

Insert Text
Insert lines of text into the buffer before the addressed line. i accepts one line-address - default
line-address is the current line. The current line is placed at the last line input; if no text is input, the
current line is left at the line before the addressed line. i differs from a only in the placement of the
text.

j

kx

Join Lines.
Joins the addressed lines into a single line; intermediate newlines simply disappear. j accepts two
line-addresses - default is the current line and the following line. The current line is placed at the
resulting line.
Mark Line.
Marks the addressed line with name x (the name must be a lower-case letter). The line-address form
'x then addresses this line. k accepts one line-address - default line-address is the current line.

I Display Non-printing Characters.
Displays non-graphic characters in the addressed lines such that they are displayed in two-digit octal,
and long lines are folded. I accepts two line-addresses - default line-address is the current line. I
may be placed on the same line after any non-I/O operation.

maddress Move lines.
Reposition the addressed lines after the line-addressed by address. m accepts two line-addresses to
specify the range of lines to be moved - default line-address is the current line. The last of the
moved lines becomes the current line.
p

P
q

Q

134

Print (display) Lines.
Displays the addressed lines. p accepts two line-addresses - default line-address is the current line.
The current line is placed at the last line printed. p may be placed on the same line after any non-I/O
operation.
Synonym for p.
Quit Edit Session.
Exit from the editing session. Note, however, that the buffer is not automatically written out (do a
'w' to write if you want to save your changes). ed warns you once if you haven't saved your filea second q says you really mean it
Same as q, but you don't get any warning if you haven't previously written out the buffer.

Last change: 5 December 1985

Sun Release 3.2

ED(l)

USER COMMANDS

ED(l)

r filename Read from file.
Reads the contents of filename into the buffer after the addressed line. If filename is not given, the
'remembered filename', if any, is used (see e and I). r accepts one line-address - default lineaddress is $. If line-address '0' is used, r reads the file in at the beginning of the buffer. If the read
is successful, r displays the number of characters read in. The current line is left at the last line read
in from the file.

s/regular expression/replacement string lor,
s/regular expression/replacement string Ig
Substitute the replacement string for the first occurrence of regular expression on each line where
the regular expression occurs. In the first form of the s operation, only the first occurrence of the
matched string on each line is replaced. If you use the g (global) suffix, all occurrences of the regular expression are replaced in the line. Keep the g suffix of the s operation distinct from the g operation itself - they are completely different. s accepts two line-addresses to delimit the range of lines
within which the substitutions should be done - default line-address is the current line. The current
line is left at the last line substituted.
Special Characters:
Any punctuation character may be used instead of 'I' to delimit the regular expression and
the replacement string.
An ampersand' &' appearing in the replacement string is replaced by the string matching
the regular expression. The special meaning of '&' in this context may be suppressed by
preceding it by '\'.
The characters \n where n is a digit, are replaced by the text-matched by the n-th regular
subexpression enclosed between '\(' and '\)'. When nested, parenthesized subexpressions
are present, n is determined by counting occurrences of '\(' starting from the left. Lines
may be split by substituting new-line characters into them. The new-line in the replacement
string must be escaped by preceding it by '\'.
taddress Transfer Lines.
Transfers a copy of the addressed lines to after line address. transfer is like move, but it makes
copies of the lines, leaving the original text where it was. t accepts two line-addresses preceeding
the operation letter - default line-address is default. The current line is left on the last line of the
copy. '0' is a legal line-address for the destination.
u

Undo. Undo previous substitute.
undo undoes the effect of the the last substitute operation, providing that the current line has not
been moved since the substitute operation.

v/regular expressiOn/operation list
Like a negative of the global operation, g: perform operation list on all lines except those containing
regular expression. v accepts two line-addresses - default is all lines in the file.
w

Write Lines.
Write the addressed lines from the buffer into the file specified by the 'remembered filename'. w
accepts two line-addresses - default is all lines in the file. The current line is unchanged. If the
write is successful, ed displays the number of characters written.

w filename

Write Lines.
Write the addressed lines into filename. Filename is created if it does not already exist. Filename
becomes the 'remembered filename' (see the e and r operations). w accepts two line-addresses default is all lines in the file. The current line is unchanged. If the write is successful, ed displays
the number of characters written.

W filename
Same as w, but appends the addressed lines to the named file instead of overwriting the file. W
accepts two line-addresses - default is all lines in the file.
x

Encrypt File.

Sun Release 3.2

Last change: 5 December 1985

135

ED(I)

USER COMMANDS

ED(I)

When x is used, ed demands a key string from the standard input. Later r, e, and w operations will
encrypt and decrypt the text with this key by the algorithm of crypt. An explicitly empty key turns
off encryption.

= Display Line Number.

Display the line number of the addressed line. = accepts one line-address - default line-address is
$. The current line is unchanged by this operation.

!

The remainder of the line after the '!' is sent to sh to be interpreted as a shell command. The current
line is unchanged.
address

Display the addressed line. If you type a line-address and type RETURN, ed displays the addressed
line. If you simply type RETURN, the line following the current line is displayed (equivalent to
'.+lp'). This is useful for stepping through text
REGULAR EXPRESSIONS
ed supports a limited form of regular expression notation. A regular expression (also known as a pattern)

specifies a set of strings of characters - such as 'any string containing digits 5 through 9' or 'only lines
containing uppercase letters'. A member of this set of strings is said to be matched by the regular expression. Regular expressions or patterns are used to address lines in the buffer (see Line Addressing, above),
and also for selecting strings to be substituted in the s (substitute) operation described previously.
An empty regular expression, indicated by two regular expression delimiters in a row, stands for a copy of
the last regular expression encountered.
Any given regular expression matches the the longest among the leftmost matches in a line.
In the following specification for regular expressions, the notation

c stands for any single ordinary charac-

ter, where a character is anything except a newline character.

c

any ordinary character except a special character matches itself. Special characters are the delimiters that actually surround the regular expression, plus \ (the escape character), [ (the opening
bracket for a character class as described below), • (period which matches any single character),
and sometimes the * (closure) and $ characters. If you want a literal occurrence of one of these
special characters you must escape them with the \ character.
A

at the very start of the regular expression constrains the match to the beginning of the line. A
match of this type is called an 'anchored match' because it is 'anchored' to a specific place in the
line. The character loses its special meaning if it appears in any position other than at the very
start of the regular expression.
A

$

at the very end of the regular expression constrains the match to the end of the line. A match of
this type is called an 'anchored match' because it is 'anchored' to a specific place in the line. The
$ character loses its special meaning if it appears in any position other than at the very end of the
regular expression.
(period) matches any single character except a newline character.

[string] A string of characters enclosed in brackets matches anyone of the characters in the brackets. For
example, [abcxyz] matches any single character from the set 'abcxyz'. If the first character inside
the bracket is a A, the string matches any character not inside the brackets. For instance,
[,,456787] matches any character except '45678'. You can use a shorthand notation to refer to an
inclusive range of characters: a-b. Such a bracketed string of characters is known as a character

class.

136

xy

When two regular expressions are concatenated, they match the leftmost and then the longest possible string that can be divided with the first part of the string matching the first regular expression,
followed by the second string matching the second regular expression.

*

Any regular expression followed by

* matches

a sequence of 0 or more matches of the regular

Last change: 5 December 1985

Sun Release 3.2

ED(I)

USER COMMANDS

ED(I)

expression. Such a pattern is called a closure. For example: [a-z] [ a-z ]. matches any string
of one or more lower case letters.
\( regular expression \)
The regular expression within the \( and \) brackets essentially 'remembers' whatever the regular
expression matches. This provides a mechanism for extracting parts of strings. There can be up
to nine such partial matches in a string. Parenthesized regular expressions can be nested.

\n

where n is in the range 1 thru 9, matches a copy of the string that the bracketed regular expression
beginning with the nth \( matched, as described in the previous paragraph on matching parts of
strings. When nested, parenthesized subexpressions are present, n is determined by counting
occurrences of \( starting from the left

Regular expressions are used in line-addresses to specify lines and in one operation (see s for substitute
above) to specify a portion of a line which is to be replaced. If it is desired to use one of the regular
expression metacharacters as an ordinary character, that character may be preceded by '\'. This also
applies to the character bounding the regular expression (often '/') and to '\' itself.
FILES

Ittnple*
edhup: work is saved here if telephone hangs up
SEE ALSO

crypt(l)
ex(l)
sed(IV)
vi(l)

encode and decode
extended line editor (part of vi)
stream editor
visual (display) editor

Editing Text Files on the Sun Workstation.

BUGS
The I operation mishandles DEL.
The undo operation removes marks from affected lines.
Because 0 is an illegal line-address for a w operation, it is not possible to create an empty file with ed. Use
cat (1 V) to create an empty file.
RESTRICTIONS

Some size limitations: 512 characters per line, 256 characters per global command list, 64 characters per
file name, and 128K characters in the temporary file. Since each line uses two bytes of memory, the limit
on the number of lines should not be exceeded in practice.
When reading a file, ed discards ASCII NUL characters and all charac.ters after the last newline. ed refuses to
read files containing non-ASCII characters.
The encryption facilities of ed are not available on software shipped outside the U.S.

Sun Release 3.2

Last change: 5 December 1985

137

ED(IV)

USER COMMANDS

EO( IV)

NAME

ed, red - line editor
SYSTEM V SYNOPSIS
ed [ - ] [ -p string] [ -x] [filename]
SYSTEM V DESCRIPTION
Ed is the standard System V line editor. If the filename argument is given, ed reads the named file into the

buffer for editing.
Ed operates on a copy of the file it is editing; changes made to the copy have no effect on the file until a w
(write) command is given. The copy being edited resides in a temporary file called the buffer. There is
only one buffer.
Red is a restricted version of ed. It will only allow editing of files in the current directory, and prohibits
executing shell commands with the! command Attempts to bypass these restrictions result in an error
message (restricted shell).
OPTIONS

Suppress printing of character counts (bye, r, and w commands), diagnostics (bye and q commands), and the ! prompt (after a! command).
-p string
Specify a prompt string.

-x

Edit an encrypted file (see crypt(l) for details.

USAGE
Command Structure
ed commands have a simple and regular structure: zero, one, or two addresses are followed by a singlecharacter command, which may be followed by parameters for that command.

[address [,address ]]command[parameter]

A single address specifies a single line in the buffer. A pair specifies an inclusive range. Commands that
requires an address uses certain addresses by default (typically the address of the current line).
In general, only one command can appear on a line. Certain commands allow you to insert or add text,
which is placed in the appropriate location in the buffer. While accepting text, ed is said to be in input
mode. In this mode, no commands are recognized; all input is added or inserted into the buffer. To exit
input mode, type a period ( .) by itself on a line.
Addresses

Generally speaking, the current line is the last line affected by a command. Explicit addresses are constructes as follows:
Addresses the current line.

138

S

Addresses the last line of the buffer.

n

A decimal number n addresses the n 'th line in the buffer.

'x

addresses the line marked with the mark character x, which must be a lower-case letter. (Lines
are marked with the k command).

IREI

An RE is a regular expression, as described below. When enclosed by slashes, it addresses the
first line found by searching for a string that it matches. The search proceeds forward from the line
following the current line. If necessary, the search wraps around to the beginning of the buffer
and continues up to and including the current line, so that the entire buffer is searched

?RE?

An RE enclosed in question marks addresses the first line containing a match found by searching
backward from the line preceding the current line. If necessary, the search wraps around to the
end of the buffer and continues up to and including the current line.

Last change: 25 July 1986

Sun Release 3.2

ED( IV)

USER COMMANDS

ED( IV)

addr+n
addr-n An address followed by a plus sign (+) or a minus sign (-), followed by a decimal number,

specifies that base address plus or minus the indicated number of lines. (The plus sign may be
omitted) If addr is omitted, the current line is used as the base. For instance, 31-3 addresses the
28'th line in the buffer.
If an address ends with + or -, then '1' is added to or subtracted from the base address, respectively. The address - refers to the line preceding the current line. (To maintain compatibility with
earlier versions of the editor, the character in addresses is equivalent to -.) Trailing + and characters have a cumulative effect, so - refers to the current line, less 2.
A

For convenience, a comma (,) stands for the address pair 1,$, while a semicolon (;) stands for the
pair .,$.
Regular Expressions
Ed supports a limited form of "regular expression" notation, which can be used in an address to specify
lines by their contents. A regular expression (RE) specifies a set of character strings to match. These
strings are built up from the following "single-character" RE's:
c

Any ordinary character not listed below. An ordinary character matches itself.

\

Backslash. When followed by a special character, the RE matches the special character itself.
Period (or "dot"). Matches any single character.
As the leftmost character, a carat (or circumflex) constrains the RE to the leftmost segment of a
line.

$

As the rightmost character, a dollar-sign (or currency symbol) constrains the RE to the rightmost
segment of a line.

The construction ARE $

*

When it follows any RE that matches a single-character, an asterisk (or "star") matches a string
composed of zero or more occurrences of the RE.

d

The delimiting character for the RE.

[c .. . J

A nonempty string of characters, enclosed in square brackets, matches any single character in the
string. When the first character of the string is a carat (), then the RE matches any character
except those in the remainder of the string. A carat in any other position is taken as an ordinary
character. The right square bracket doesn't terminate the enclosed string if it is the first character
(after an initial A, if any).

[1-rJ

The minus sign, between two characters, indicates a range of consecutive ASCII characters to
match. For instance, the range [0-9] is equivalent to the string [0123456789]. The - is treated as
an ordinary character if it occurs first (or first after an initial A) or last in the string.

d

The character used to delimit an RE is special for that RE (for example, see how I is used in the g
command, below).

The following rules and special characters allow for constructing RE's from single-character RE's:
The concatenation of RE's matches the concatenation of text strings, each of which is matched by
a component RE.
*

A one-character RE, followed by an asterisk (*) matches zero or more occurrences of the onecharacter RE. If there is a choice, the longest leftmost string that permits a match is chosen.

\{m\}

\{m,\}
\{m,n\} A one-character RE followed by \{m\}, \{m,\}, or \{m,n\} is an RE that matches a range of
occurrences of the one-character RE. The values of m and n must be nonnegative integers less
than 256; \{m\} matches exactly m occurrences; \{m,\} matches at least m occurrences; \{m,n\}

Sun Release 3.2

Last change: 25 July 1986

139

ED(IV)

USER COMMANDS

ED( IV)

matches any number of occurrences between m and n inclusive. Whenever a choice exists, the RE
matches as many occurrences as possible.
\(...\)

An RE enclosed between the character sequences \( and \) matches whatever the unadorned RE
matches. The expression \n matches the same string of characters as was matched by an expression enclosed between \( and \) earlier in the same RE. Here n is a digit; the subexpression
specified is that beginning with the n-th occurrence of \( counting from the left. For example, the
expression A\(.*\)\I$ matches a line consisting of two repeated appearances of the same string.
constrains the entire RE to match the entire line.

II

The null RE (II) is equivalent to the last RE encountered.

Commands

Commands may require zero, one, or two addresses. Commands that require no addresses regard the presence of an address as an error. Commands that accept one or two addresses assume default addresses when
an insufficient number of addresses is given; if more addresses are given than such a command requires,
the last one(s) are used.
Typically, addresses are separated from each other by a comma (,). They may also be separated by a semicolon (;). In the latter case, the current line (.) is set to the first address, and only then is the second
address calculated. This feature can be used to determine the starting line for forward and backward
searches. The second address of any two-address sequence must correspond to a line that follows, in the
buffer, the line corresponding to the first address.
In the following list of ed commands, the default addresses are shown in parentheses. The parentheses are
not part of the address; they show that the given addresses are the default
It is generally illegal for more than one command to appear on a line. However, any command (except e, r,
r, or w) may be suffixed by I, D, or p in which case the current line is either listed, numbered or printed,
respectively).
(·)a

text
Read the given text and append it after the addressed line; • is left at the last inserted line, or, if
there were none, at the addressed line. Address 0 is legal for this command: it causes the
"appended" text to be placed at the beginning of the buffer. The maximum number of characters
that may be entered from a terminal is 256 per line (including the NEWLINE
character).
(·)c

text
The change command deletes the addressed lines, then accepts input text that replaces those lines;
• is left at the last line input, or, if there were none, at the first line that was not deleted.

140

(·'·)d

The delete command deletes the addressed lines from the buffer. The line after the last line
deleted becomes the current line; if the lines deleted were originally at the end of the buffer, the
new last line becomes the current line.

e file

The edit command causes the entire contents of the buffer to be deleted, and then the named file to
be read in; • is set to the last line of the buffer. If no filename is given, the currently-remembered
filename, if any, is used (see the r command). The number of characters read is typed; file is
remembered for possible use as a default filename in subsequent e, r, and w commands. Iffile is
replaced by!, the rest of the line is taken to be a shell (sh(l» command from which output is read.
Such a shell command is not remembered as the current filename. See also DIAGNOSl'ICS below.

E file

The Edit command is like e, except that the editor does not check to see if any changes have been
made to the buffer since the last w command.

rfile

Iffile is given, the/ile command changes the currently-remembered filename tofile; otherwise, it
prints the currently-remembered filename.

Last change: 25 July 1986

Sun Release 3.2

ED( tV)

USER COMMANDS

ED( IV)

( I, $) glREIcommand-list

In the global command, the first step is to mark every line that matches the given RE. Then, for
every such line, the given command-list is executed with. initially set to that line. A single command or the first of a list of commands appears on the same line as the global command. All lines
of a multiline list, except the last line, must end with a \; a, i, and c commands and associated
input are permitted. The. terminating input mode may be omitted if it would be the last line of the
command-list. An empty command-list is equivalent to the p command. The g, G, v, and V commands are not permitted in the command-list. See also BUGS.
(1,$)GIREI
In the interactive Global command, the first step is to mark every line that matches the given RE.
Then, every such line is printed, • is changed to that line, and anyone command (other than one of
the a, c, i, g, G, v, and V commands) can be typed in for execution. After the execution of that
command, the next marked line is printed, and so on; a NEWLINE acts as a null command; an &
causes the reexecution of the most recent command executed within the current invocation of G.
Note that the commands input as part of the execution of the G command may address and affect
any lines in the buffer. The G command can be terminated by an interrupt signal (ASCII DEL or
BREAK).

h

The help command gives a short error message that explains the reason for the most recent? diagnostic.

H

The Help command alternates between automatic diagnostic message, or the normal mode of
diagnositcs on request It will also explain the previous ? if there was one.

( ·)i

text
The insert command inserts the given text before the addressed line; • is left at the last inserted
line, or, if there were none, at the addressed line. This command differs from the a command in
the placement of the input text Address 0 is not legal for this command. The maximum number
of characters that may be entered from a terminal is 256 per line (including the NEWLINE character).
(., .+1) j

The join command joins contiguous lines by removing the appropriate NEWLINE characters. If
exactly one address is given, this command does nothing.
The mark command marks the addressed line with name c, which must be a lower-case letter.
The address 'c then addresses this line; • is unchanged.

(.,.) I

The list command prints the addressed lines in an unambiguous way: a few nonprinting characters,
such as TAB and BACKSPACE are represented by (hopefully) mnemonic overstrikes. All other
nonprinting characters are printed in octal, and long lines are folded An I command may be
appended to any command other than e, f, r, or w.

(·'·)ma

The move command repositions the addressed line(s) after the line addressed by a. Address 0 is
legal for a and causes the addressed line(s) to be moved to the beginning of the file. It is an error
if address a falls within the range of moved lines; • is left at the last line moved.
(.,.) n

The number command prints the addressed lines, preceding each line by its line number and a
TAB character; • is left at the last line printed The n command may be appended to any command
other than e, f, r, or w.

(. ,.) p

The print command prints the addressed lines; • is left at the last line printed. The p command
may be appended to any command other than e, f, r, or w. For example, dp deletes the current
line and prints the new current line.

P

The editor prompts with a * for all subsequent commands. The P command alternately turns this
mode on and off; it is initially off.

Sun Release 3.2

Last change: 25 July 1986

141

ED(IV)

USER COMMANDS

ED(IV)

q

The quit command. ed exits. No automatic write of a file is done, but if changes have been made
since the last time the buffer was written, ed warns you (unless the - option is in effect) by printing a ? diagnostic. A second q exits, destroying the buffer's contents.

Q

The editor exits without checking for changes since the last w command.

($)r file

The read command reads in the given file after the addressed line. If no file is named, the
currently-remembered filename, if any, is used (see e and r commands). The currentlyremembered filename is not changed unless file is the very first filename mentioned since ed was
invoked. Address 0 is legal for r and causes the file to be read at the beginning of the buffer. If
the read is successful, the number of characters read is typed; • is set to the last line read in. If file
is replaced by!, the rest of the line is taken to be a shell (sh(I» command whose output is to be
read. For example, $r !Is appends current directory to the end of the file being edited. A shell
command is not remembered as the current filename.
(·'·)slRElreplacementl[gln]
The substitute command searches each addressed line for an occurrence of the specified RE. In
each line for which a match is found, all (non-overlapped) matched strings are replaced by the
replacement if the global replacement indicator g appears after the command. If the global indicator does not appear, only the first occurrence of the matched string is replaced If a number n
appears after the command, only the n'th occurrence of the matched string on each addressed line
is replaced. It is an error for the substitution to fail on all addressed lines. Any character other
than SPACE or NEWLINE can be used instead of I to delimit the RE and the replacement string. •
is left at the last line on which a substitution occurred.

An ampersand ( & ) appearing in the replacement is replaced by the string matching the RE on the
current line. The special meaning of & in this context may be suppressed by preceding it by \. As
a more general feature, the characters \n, where n is a digit, are replaced by the text matched by
the n'th regular subexpression of the specified RE enclosed between \( and \). When nested
parenthesized subexpressions are present, n is determined by counting occurrences of \( starting
from the left When the character % is the only character in the replacement, the replacement
used in the most recent substitute command is used as the replacement in the current substitute
command The % loses its special meaning when it is in a replacement string of more than one
character or is preceded by a backslash.
A line may be split by substituting a NEWLINE character into it The NEWliNE in the replacement must be escaped by preceding it by \. Such substitution cannot be done as part of a g or v
command-list
(·,·)t

a
This command acts just like the m command, except that a copy of the addressed lines is placed
after address a (which may be '0'); • is left at the last line of the copy.

u

The undo command nullifies the effect of the most recent command that modified anything in the
buffer, namely the most recent a, c, d, g, i, j, m, r, S, t, v, G, or V command.

(1,$)v/RElcommand-list
This command is the same as the global command g except that the command-list is executed with
• initially set to every line that does not match the RE.
(1,$)VIREI

This command is the same as the interactive global command G except that the lines that are
marked during the first step are those that do not match the RE.
(1 ,$)w file
The write command writes the addressed lines into the named file. If the file does not exist, it is
created with mode 666 (readable and writable by everyone), unless your umask setting (see
sh(l» dictates otherwise. The currently-remembered filename is not changed unless file is the
very first filename mentioned since ed was invoked If no filename is given, the currently-

142

Last change: 25 July 1986

Sun Release 3.2

ED( IV)

USER COMMANDS

ED( IV)

remembered filename, if any, is used (see e and/commands); • is unchanged. If the command is
successful, the number of characters written is typed If file is replaced by!, the rest of the line is
taken to be a shell (sh(l» command for which the standard input is the addressed lines. Such a
shell command is not remembered as the current filename.

x

A key string is demanded from the standard input Subsequent e, r, and w commands encrypt and
decrypt the text with this key by the algorithm of crypt(l). An explicitly empty key turns off
encryption.

The line number of the addressed line is typed; • is unchanged by this command.

!shell-command
The remainder of the line after the! is sent to the UNIX system shell (sh(l» to be interpreted as a
command Within the text of that command, the unescaped character % is replaced with the
remembered filename; if a ! appears as the first character of the shell command, it is replaced with
the text of the previous shell command. Thus,!! will repeat the last shell command. If any expansion is performed, the expanded line is echoed; • is unchanged.
(.+1)

NEWLINE

An address, alone on a line, prints the addressed line. A NEWLINE alone is equivalent to .+lp,
which is useful for stepping forward through the buffer.

If an interrupt signal (ASCII DEL or BREAK) is sent, ed prints a ? and returns to its command level.
File Format Specification Support
Both ed and red support the/spec(4) formatting capability. After including a format specification as the
first line of filename and invoking ed with your terminal in stty -tabs or stty tab3 mode (see stty( 1V), the
tab stops specified are used when displaying lines. For example, if the first line of a file contained:

<:15,10,15 s72:>
tab stops would be set at columns 5, 10, and 15, and a maximum line length of 72 would be imposed.
While inserting text, however, tab characters are expanded to every eighth column.
LIMITATIONS
The following limitations apply:

512 characters per line.
256 characters per global command-list
64 characters per filename.
128K characters in the buffer.
The limit on the number of lines depends on the amount of user memory:
each line takes 1 word.
When reading a file, ed discards ASCII NUL characters and all characters after the last NEWLINE. Files (like
a.out) that contain characters not in the ASCII set (bit 8 on) cannot be edited by ed.
If the closing delimiter of an RE or of a replacement string (such as I) would be the last character before a
NEWLINE, that delimiter may be omitted, in which case the addressed line is printed. The following pairs
of commands are equivalent:
sis 1/s2
sIs 1/s2/p
glsl
glsl/p

?sl

?sl?

FILES
/tmp/e#

ed.hup
DIAGNOSTICS
?

?file

Sun Release 3.2

temporary; # is the process number.
work is saved here if the terminal is hung up.
For command errors.
For an inaccessible file (use the help and Help commands for detailed explanations).

Last change: 25 July 1986

143

ED( IV)

USER COMMANDS

ED(IV)

If changes have been made in the buffer since the last w command that wrote the entire buffer, ed warns
the user if an attempt is made to destroyed's buffer via the e or q commands. It prints ? and allows one to
continue editing. A second e or q command at this point will take effect. The - command-line option inhibits this feature.
SEE ALSO
ed( 1), crypt( 1), grep( 1V), sed( 1V), sh( 1), stty( 1V), fspec(4), regexp( 5)
CAVEATS AND BUGS
A ! command cannot be subject to a g or a v command.

The ! command and the ! escape from the e, r, and w commands cannot be used if the the editor is invoked
from a restricted shell (see sh(I».
The sequence \n in an RE does not match a NEWLINE character.
The I command mishandles DEL.
Files encrypted directly with the crypt(l) command with the null key cannot be edited.
Characters are masked to 7 bits on input.
If the editor input is coming from a command file, the editor exits at the first failure of a command in that
file.

144

Last change: 25 July 1986

Sun Release 3.2

ENV(l)

USER COMMANDS

ENV(l)

NAME

env - obtain or alter environment variables for command execution
SYNOPSIS

env [ - ] [ name =value . .. ] [ command ]
DESCRIPTION

env obtains the current environment, modifies it according to its arguments, and executes the command
with the modified environment that results.
OPTIONS

Ignore the environment that would otherwise be inherited from the current shell. Restricts the
environment for command to that specified by the arguments.
name=value
Set the environment variable name to value and add it to the environment
If no command is specified, the resulting environment is displayed.
SEE ALSO

sh(l), exec(2), profile(4), environ(5V)

Sun Release 3.2

Last change: 21 February 1986

145

EQN( 1)

USER COMMANDS

EQN(l )

NAME

eqn, neqn, checkeq - typeset mathematics
SYNOPSIS
eqn [ -dxy] [ -pn] [ -sn] [ -fn] [filename] ...
neqn [filename ] ...
checkeq [filename] ...
DESCRIPTION
Eqn (and neqn) are language processor~ to assist in describing equations. Eqn is a preprocessor for troff(l)
and is intended for devices that can print troffs output. Neqn is a preprocessor for nroff(l) and is intended
for use with terminals. Usage is almost always:
tutorial% eqnfile ... 1 troff
tutorial% neqnfile ... 1 nrotT

If no file s are specified, eqn and neqn read from the standard input. A line beginning with '.EQ' marks the
start of an equation; the end of an equation is marked by a line beginning with' .EN'. Neither of these lines
is altered, so they may be defined in macro packages to get centering, numbering, etc. It is also possible to
set two characters as 'delimiters'; subsequent text between delimiters is also treated as eqn input.

Checkeq reports missing or unbalanced delimiters and .EQ/.EN pairs.
OPTIONS

-dxy

Set equation delimiters set to characters x and y with the command-line argument. The more
common way to do this is with 'delim xy' between .EQ and .EN. The left and right delimiters
may be identical. Delimiters are turned off by 'delim off' appearing in the text. All text that is
neither between delimiters nor between .EQ and .EN is passed through untouched.

-p n

Reduce subscripts and superscripts by n point sizes from the previous size. In the absence of the
-p option, subscripts and superscripts are reduced by 3 point sizes from the previous size.

-sn

Change point size to n globally in the document. The point size can also be changed globally in
the body of the document by using the gsize directive.

-fn

Change font to n globally in the document. The font can also be changed globally in the body of
the document by using the gfont directive.

EQN LANGUAGE
Tokens within eqn are separated by spaces, tabs, newlines, braces, double quotes, tildes or circumflexes.
Braces {} are used for grouping; generally speaking, anywhere a single character like x could appear, a
complicated construction enclosed in braces may be used instead. Tilde C) represents a full space in the
output, circumflex C) half as much.

Subscripts and superscripts are produced with the keywords sub and sup. Thus x sub i makes
x1 y1
sup 2 produces a?, and e sup (x sup 2 + y sup 2) gives e +

Xi'

a sub i

Fractions are made with over: a over b yields ~.
sqrt makes square roots: lover sqrt {ax sup 2 +hx+c} results in...j

1
.
ax 2+bx+c
n

The keywords from and to introduce lower and upper limits on arbitrary things: lim Lxi is made with lim
n-';OO

0

from {n- > inf} sum from 0 to n x sub i.
Left and right brackets, braces, etc., of the right height are made with left and right: left [ x sup 2 + y sup 2

over alpha right 1 -=-1 produces

r'+f]

= 1.

The right clause is optional. Legal characters after left

and right are braces, brackets, bars, c and f for ceiling and floor, and "" for nothing at all (useful for a
right-side-only bracket).

146

Last change: 1 February 1985

Sun Release 3.2

EQN( 1)

USER COMMANDS

EQN (1)

a
Vertical piles of things are made with pile, lpile, cpile, and rpile: pile {a above b above c} produces b.
c

There can be an arbitrary number of elements in a pile. lpile left-justifies, pile and cpile center, with different vertical spacing, and rpile right justifies.
Xi

Matrices are made with matrix: matrix { lcol (x sub i above y sub 2) ccol ( 1 above 2) } produces

Y2

1

2.

In addition, there is rcol for a right-justified column.
Diacritical marks are made with dot, dotdot, hat, tilde, bar, vec, dyad, and under: x dot = f(t) bar is
x=! (t), y dotdot bar -=- n under is = n, and x vec -=-y dyad is x=)1.

y

Sizes and font can be changed with size n or size ±n, roman, italic, bold, and font n. Size and fonts can
be changed globally in a document by gsize n and gfont n, or by the command-line arguments -sn and -fn.
Successive display arguments can be lined up. Place mark before the desired lineup point in the first equation; place lineup at the place that is to line up vertically in subsequent equations.
Shorthands may be defined or existing keywords redefined with define:
define thing % replacement %
defines a new token called thing which will be replaced by replacement whenever it appears thereafter.
The % may be any character that does not occur in replacement.
Keywords like sum (~), int (f), in! (00), and shorthands like >= (~), -> (~), and != (*) are recognized.
Greek letters are spelled out in the desired case, as in alpha or GAMMA. Mathematical words like sin, cos,
log are made Roman automatically. troff( 1) four -character escapes like \(bu (.) can be used anywhere.
are passed through untouched; this permits keywords to be entered
Strings enclosed in double quotes
as text, and can be used to communicate with troffwhen all else fails.
II ••• "

SEE ALSO

Formatting Documents on the Sun Workstation
troff(l), tbl(I), ms(7), eqnchar(7)
BUGS

To embolden digits, parens, etc., it is necessary to quote them, as in 'bold "12.3'''.

Sun Release 3.2

Last Change: 1 February 1985

147

ERROR ( 1)

USER COMMANDS

ERROR ( 1)

NAME

error - analyze and disperse compiler error messages
SYNOPSIS

error [ -n] [ -s ] [ -q ] [ -v ] [ -t suffixlist] [ -I ignore/tie] [name]
DESCRIPTION

Error analyzes error messages produced by a number of compilers and language processors. It replaces
the painful, traditional methods of scribbling abbreviations of errors on paper, and permits error messages
and source code to be viewed simultaneously.
Error looks at error messages, either from the specified file name or from the standard input, and:

• Determines which language processor produced each error message,
• Determines the file name and line number of the erroneous line, and,
• Inserts the error message into the source file immediately preceding the erroneous line.
Error messages which can't be categorized by language processor or content are not inserted into any file,
but are sent to the standard output. Error touches source files only after all input has been read.
Options are explained later on in this manual entry.
Error is intended to be run with its standard input connected via a pipe to the error message source. Some
language processors put error messages on their standard error file; others put their messages on the standard output. Hence, both error sources should be piped together into error. For example, when using the
csh syntax,
tutorial% make -s lint I & error -q -v

will analyze all the error messages produced by whatever programs make runs when making lint.
Error knows about the error messages produced by: make, cc, cpp, ccom, as, ld, lint, pi, pc, and [77. For
all languages except Pascal, error messages are restricted to one line. Some error messages refer to more
than one line in more than one file, in which case error duplicates the error message and inserts it at all of
the places referenced.
Error does one of six things with error messages.
synchronize
Some language processors produce short errors describing which file they are processing. Error
uses these to determine the file name for languages that don't include the file name in each error
message. These synchronization messages are consumed entirely by error.
discard Error messages from lint that refer to one of the two lint libraries, lusrlliblllib-lc and lusrlliblllibport are discarded, to prevent accidently touching these libraries. Again, these error messages are
consumed entirely by error.
nullify

Error messages from lint can be nullified if they refer to a specific function, which is known to
generate diagnostics which are not interesting. Nullified error messages are not inserted into the
source file, but are written to the standard output. The names of functions to ignore are taken from
either the file named .errorrc in the user's home directory, or from the file named by the -I
option. If the file does not exist, no error messages are nullified. If the file does exist, there must
be one function name per line.

not file specific
Error messages that can't be intuited are grouped together, and written to the standard output
before any files are touched. They are not inserted into any source file.
file specific
Error messages that refer to a specific file but to no specific line are written to the standard output
when that file is touched.
true errors

148

Last change: 13 March 1984

Sun Release 3.2

ERROR ( 1)

USER COMMANDS

ERROR ( 1)

Error messages that can be intuited are candidates for insertion into the file to which they refer.
Only true error messages are inserted into source files. Other error messages are consumed entirely by
error or are written to the standard output. Error inserts the error messages into the source file on the line
preceeding the line number in the error message. Each error message is turned into a one line comment for
the language, and is internally flagged with the string '###' at the beginning of the error, and '%%%' at the
end of the error. This makes pattern searching for errors easier with an editor, and allows the messages to
be easily removed. In addition, each error message contains the source line number for the line the message refers to. A reasonably formatted source program can be recompiled with the error messages still in
it, without having the error messages themselves cause future errors. For poorly formatted source programs in free format languages, such as C or Pascal, it is possible to insert a comment into another comment, which can wreak havoc with a future compilation. To avoid this, format the source program so there
are no language statements on the same line as the end of a comment.
OPTIONS

-n

Do not touch any files; all error messages are sent to the standard output.

-q

Error asks whether the file should be touched. A 'y' or 'n' to the question'ais necessary to continue.
Absence of the -q option implies that all referenced files (except those refering to discarded error
messages) are to be touched.

-v

After all files have been touched, overlay the visual editor vi with it set up to edit all files touched,
and positioned in the first touched file at the first error. If vi can't be found, try ex or ed from standard places.

Take the following argument as a suffix list. Files whose suffices do not appear in the suffix list are
not touched. The suffix list is dot seperated, and '*' wildcards work. Thus the suffix list:
" .c.y.f*.h"
allows error to touch files ending with' .c', '.y', 'J*' and' .h'.

-t

-s

Print out statistics regarding the error categorization. Not too useful.

Error catches interrupt and terminate signals, and if in the insertion phase, will orderly terminate what it is
doing.
FILES
-I.errorrc
Idev/tty

function names to ignore for lint error messages
user's teletype

BUGS

Opens the teletype directly to do user querying.
Source files with links make a new copy of the file with only one link to it.
Changing a language processor's format of error messages may cause error to not understand the error
message.
Error, since it is purely mechanical, will not filter out subsequent errors caused by 'floodgating' initiated
by one syntactically trivial error. Humans are still much better at discarding these related errors.

Pascal error messages belong after the lines affected (error puts them before). The alignment of the' I '
marking the point of error is also dis turbed by error.
Error was designed for work on CRT's at reasonably high speed. It is less pleasant on slow speed terminals, and has never been used on hardcopy tenninals.

Sun Release 3.2

Last change: 13 March 1984

149

EX(I)

USER COMMANDS

EX(l)

NAME

ex, edit, e - text editor
SYNOPSIS
ex [ - ] [ -R ] [ -r ] [ -t tag] [ +command] [ -v] [ -x ] [ -wnnn ] [ -I ] file . ..
edit [ options]
DESCRIPTION
ex, a line editor, is the root of a family of editors that includes edit, ex, and vi (the display editor). In most
cases vi is preferred for interactive use.
OPTIONS

supress all interactive feedback to the user -

useful for processing ex scripts in shell files.

-R

Read only. Do not overwrite the original file.

-r

recover the indicatedfiles after a system crash.

-t tag

edit the file containing the tag tag. A tags database must first be created using the ctags(l) command.

+ command
start the editing session by executing command.
-v

start up in display editing state using vi(l). You can achieve the same effect by simply typing the
vi command itself.

-x

prompt for a key to be used in encrypting the file being edited.

-wnnn set the default window (number of lines on your terminal) to nnn- this is useful if you are dialling into the system over a slow 'phone line.
-I

set up for editing LISP programs.

FILES

/usr/lib/ex? ?strings
/usr/lib/ex? ?recover
/usrnib/ex??preserve
/etcltermcap
-/.exrc
/tmplExnnnnn
/tmplRxnnnnn

/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), ed(I), grep(IV), sed(IV), grep(I), vi(I), termcap(5), environ(5V)

Editing Text Files on the Sun Workstation
BUGS

The undo command causes all marks to be lost on lines changed and then restored if the marked lines were
changed.

Undo never clears the buffer modified condition.
The z 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 '-' option is used.
There is no easy way to do a single scan ignoring case.
The editor does not warn if text is placed in named buffers and not used before exiting the editor.

150

Last change: 29 May 1986

Sun Release 3.2

USER COMMANDS

EX(l)

EX(l )

Null characters are discarded in input files t and cannot appear in resultant files.
The editor checks the first five lines of the text file for commands of the form "ex:command" or
"vi:command.1t This feature can result in unexpected behavior, and is not recommended in any case.
RESTRICTIONS
The encryption facilities of ex are not available on software shipped outside the U.S.

Sun Release 3.2

Last change: 29 May 1986

151

EXPAND ( 1)

USER COMMANDS

EXPAND ( 1)

NAME

expand, unexpand - expand tabs to spaces, and vice versa
SYNOPSIS

expand [ -tabstop ] [ -tab1 ,tab2, . . .,tabn] [filename ... ]
unexpand [ -a ] [filename... ]
DESCRIPTION

expand copies the named files (or the standard input) to the standard output, with tabs changed into spaces
(blanks). Backspace characters are preserved into the output and decrement the column count for tab calculations. expand is useful for pre-processing character files (before sorting, looking at specific columns,
etc.) that contain tabs.
Unexpand copies the named files (or the standard input) to the standard output, putting tabs back into the
data. By default, only leading spaces (blanks) and tabs are converted to strings of tabs, but this can be
overridden by the -a option (see the options section below).
EXPAND OPTIONS

-tabstop
Specified as a single argument sets tabs tabstop spaces apart instead of the default 8.

-tab1 ,tab2, ... ,tabn
Set tabs at the columns specified by tabl •••
UNEXPAND OPTIONS

-a

152

Insert tabs when replacing a run of two or more spaces would produce a smaller output file.

Lastchange: 17 July 1986

Sun Release 3.2

EXPR( IV)

USER COMMANDS

EXPR( IV)

NAME

expr - evaluate arguments as an expression
SYNOPSIS
expr arg ...
DESCRIPTION
expr evaluates expressions as specified by its arguments. After evaluation, the result is written on the standard output. Each token of the expression is a separate argument, so terms of the expression must be
separated by blanks. Characters special to the shell must be escaped. Note that 0 is returned to indicate a
zero value, rather than the null string. Strings containing blanks or other special characters should be
quoted. Internally, integers are treated as 32-bit, 2s complement numbers.

The operators and keywords are listed below. Characters that need to be escaped are preceded by \. The
list is in order of increasing precedence, with equal precedence operators grouped within {} symbols.

expr \ I expr
returns the first expr if it is neither null nor 0, otherwise returns the second expr.
expr \& expr
returns the first expr if neither expr is null or 0, otherwise returns O.
expr { =, \>, \>=, \<, \<=, != } expr
returns the result of an integer comparison if both arguments are integers, otherwise returns the
result of a lexical comparison.
expr { +, - } expr
addition or subtraction of integer-valued arguments.
expr { \*, /, % } expr
multiplication, division, or remainder of the integer-valued arguments.
expr: expr
match string regular-expression
The two forms of the matching operator above are synonymous. The matching operators : and
match compare the first argument with the second argument which must be a regular expression.
Regular expression syntax is the same as that of ed(I), except that all patterns are "anchored"
(i.e., begin with A) and, therefore, A is not a special character, in that context. Normally, the
matching operator returns the number of characters matched (0 on failure). Alternatively, the
\( •.. \) pattern symbols can be used to return a portion of the first argument.
substr string integer-l integer-2
extracts the subtring of string starting at position integer-l and of length integer-2 characters. If
integer-l has a value greater'than the length of string, expr returns a null string. If you try to
extract more characters than there are in string, expr returns all the remaining characters from
string. Beware of using negative values for either integer-lor integer-2 as expr tends to run forever in these cases.
index string character-list
reports the first position in string at which anyone of the characters in character-list matches a
character in string.
length string
returns the length (that is, the number of characters) of string.
SYSTEM V DESCRIPTION
Integer-valued arguments may be preceded by a unary minus sign.

The operators substr, index, and length are not supported.
EXAMPLES

Sun Release 3.2

Last change: 26 March 1984

153

EXPR( IV)

1.

USER COMMANDS

EXPR( IV)

a=' expr $a + l'
adds 1 to the shell variable a.

2.

# 'For $a equal to either "/usr/abc/file" or just "file" ,
expr $a : ' .*/\(.*\), \ I $a
returns the last segment of a path name (i.e., file). Watch out for I alone as an argument:
expr will take it as the division operator (see BUGS below).

3.

# A better representation of example 2.
expr //$a : ' .*/\(.*\)'
The addition of the II characters eliminates any ambiguity about the division operator and
simplifies the whole expression.

4.

expr $VAR :

'.*'

returns the number of characters in $VAR.
SEE ALSO

ed(I), sh(I), test(l)
EXIT CODE
Expr returns the following exit codes:

o

if the expression is neither null nor 0
if the expression is null or 0
for invalid expressions.

1
2
DIAGNOSTICS

syntax error
non-numeric argument

for operator/operand errors
if arithmetic is attempted on such a string

BUGS

After argument processing by the shell, expr cannot tell the difference between an operator and an operand
except by the value. If $a is an =, the command:
expr $a

= ,-,

looks like:
expr

=

as the arguments are passed to expr (and they will all be taken as the = operator). The following works:
expr X$a = X=
Note that the match, substr, length, and index operators cannot themselves be used as ordinary strings.
That is, the expression:
tutorial% expr index expurgatorious length
syntax error
tutorial%
generates the 'syntax error' message as shown instead of the value I as you might expect.

154

Last change: 26 March 1984

Sun Release 3.2

EYACC(l)

USER COMMANDS

EYACC( 1)

NAl\1E

eyacc - modified yacc allowing much improved error recovery
SYNOPSIS

eyacc [ -v] [grammar]
DESCRIPTION

Eyacc is a version of yacc(1), that produces tables used by the Pascal system and its error recovery routines. Eyacc fully enumerates test actions in its parser when an error token is in the look -ahead set. This
prevents the parser from making undesirable reductions when an error occurs before the error is detected.
The table format is different in eyacc than it was in the old yacc, as minor changes had been made for
efficiency reasons.
SEE ALSO

yacc(l)
Practical LR Error Recovery by Susan L. Graham, Charles B. Haley and W. N. Joy; SIGPLAN Conference
on Compiler Construction, August 1979.

BUGS
Pc and its error recovery routines should be made into a library of routines for the new yacc.

Sun Release 3.2

Last change: 25 April 1983

155

F77 ( 1)

USER COMMANDS

F77 (1 )

NAME
f77 - FORTRAN 77 compiler
SYNOPSIS

f77 [ -66 ] [ -a ] [ -align _block] [ -c ] [ -c ] [-dryrun ] [ -Dname [=def] ] [float_option]
[ -fstore ] [ -F] [ -g] [ -help] [ -i2 ] [ -i4 ]
[-Ipathname] [-llib] [-Ldir] [-m4] [-N[qxscn]nnn]
outftle ] [ -onetrip ] [ -0] [ -p ] [ -pg] [ -pipe] [ -P ] [ -Qoption prog opt]
[ -Qpath pathname ] [ -Qproduce sourcetype ] [ -s ] [-temp=dir] [ -time]
[ -u ] [ -u] [ -v ] [ -w [66]] sourcefile ...
[ -0

DESCRIPTION

[77 is the FORTRAN 77 compiler, which translates programs written in the FORTRAN 77 programming
language into executable load modules or into relocatable binary programs for subsequent linking with
Id(l). In addition to the many flag arguments (options),j77 accepts several types of files. Filenames ending in .f are taken to be FORTRAN 77 source programs; they are compiled, and each object program is left
in the file (in the current directory) whose name is that of the source with .0 substituted for .f. Filenames
ending in .F are also taken to be FORTRAN 77 source programs, but they are preprocessed by the C preprocessor (equivalent to a cc -E command) before they are compiled by the[77 compiler.
Filenames ending in .r are taken to be Ratfor source programs; these are first transformed by the ratfor(l)
preprocessor, then compiled by [77.
Filenames ending in .c or .s are taken to be C or assembly source programs and are compiled or assembled,
producing .0 files.
Filenames ending in .il are taken to be in-line expansion code template files; these are used to expand calls
to selected routines in-line when the -0 option is in effect.
OPTIONS

See Id(1) for link-time options.

-66

Report non-FORTRAN 66 constructs as errors

-a

Insert code to count how many times each basic block is executed. Creates a .d file for
every .f file compiled. The.d file accumulates execution data for the corresponding
source file. The tcov(l) utility can then be run on the source file to generate a line-byline execution profile of the program.

-align _block

Cause the global symbol whose FORTRAN name is block to be page-aligned: its size is
insreased to a whole number of pages, and its first byte is placed at the beginning of a
page.

-c

Suppress linking with Id(l) and produce a .0 file for each source file. A single object file
can be named explicitly using the -0 option.

-C

Compile code to check that subscripts are within the declared array bounds.

-dryrun

Show but do not execute the commands constructed by the compilation driver.

-Dname [=def] Define a symbol name to the C preprocessor (cpp(l». Equivalent to a #define directive
in the source. If no def is given, name is defined as '1' ( .F suffix files only).

Floating-point code generation option. Can be one of:
-f68881
Generate in-line code for the Motorola MC68881 floating-point coprocessor
(supported only on Sun-3 systems).

156

-ffpa

Generate in-line code for the Sun Floating-Point Accelerator (supported only on
Sun-3 systems).

-fsky

Generate in-line code for the Sky floating-point processor (supported only on
Sun-2 systems).

Last change: 8 April 1986

Sun Release 3.2

F77 ( 1)

USER COMMANDS

-fsoft

F77 (1)

Generate software floating-point calls (this is the default).

-fswitch
Generate run-time-switched floating-point calls. The compiled object code is
linked at runtime to routines that support one of the above types of floating-point
code. This was the default in previous releases. Only for use with programs
that are floating-point intensive and which must be portable to machines with
various floating-point options.
-fstore

Insure that expressions allocated to extended precision registers are rounded to storage
precision whenever an assignment occurs in the source code. Only has effect when
-f68881 or -ffpa, and -0 or -P are specified.

-F

Apply the C preprocessor to .F files and the Ratfor preprocessor to .r files. Put the result
in corresponding jfiles, but do not compile them. No linking is done.

-g

Produce additional symbol table information for dbx(l) and pass the -Ig flag to ld(l).

-help

Display helpful information aboutj77.

-i2

Make the default size of integer and logical constants and variables two bytes.

-i4

Make the default size of integer and logical constants and variables four bytes (this is the
default).

-Ipathname

Add pathname to the list of directories in which to search for #include files with relative
filenames (not beginning with I). The preprocessor first searches for #include files in the
directory containing sourcefile, then in directories named -with -I options (if any), and
finally in lusrlincludelj77 (applies to processing of .F suffix files only).

-llib

Link with object library lib (for ld(I».

-Ldir

Add dir to the list of directories containing object-library routines (for linking using
ld(1».

-m4

Apply the M4 preprocessor to each .r file before transforming it with the Ratfor preprocessor.

-N[qxscn]nnn

Make static tables in the compiler bigger. 177 complains if tables overflow and suggests
you apply one or more of these flags. These flags have the following meanings:
q
Maximum number of equivalenced variables. Default is 150.
x
Maximum number of external names (common block, subroutine, and function
names). Default is 200.
s
Maximum number of statement numbers. Default is 401.
c
Maximum depth of nesting for control statements (for example, DO loops).
Default is 20.
n
Maximum number of identifiers. Default is 1009.
Multiple -N options increase sizes of multiple tables.

-ooutfile

Name the output file out/tie. outfile must have the appropriate suffix for the type of file to
be produced by the compilation (see FILES, below). outfile cannot be the same as
sourcefile (the compiler will not overwrite the source file).

-onetrip

Compile DO loops so that they are performed at least once if reached. FORTRAN 77 DO
loops are not performed at all if the upper limit is smaller than the lower limit.

-0

Optimize the object code. This invokes both the global intermediate code optimizer and
the object code optimizer.

-p

Prepare the object code to collect data for profiling with prof(l). Invokes a run-time
recording mechanism that produces a mon.out file (at normal termination).

-pg

Prepare the object code to collect data for profiling with gprof(l). Invokes a run-time

Sun Release 3.2

Last change: 8 April 1986

157

F77 (1)

USER COMMANDS

F77 (1)

recording mechanism that produces a gmon.out file (at normal termination).
-pipe

-p

Use pipes, rather than intermediate files between compilation stages. Very cpu-intensive.
Partial optimization. Does a restricted set of global optimizations. Do not use -P unless

-0 results in excessive compilation time.
-Qoption pro g opt
Pass the option opt to the program pro g. The option must be appropriate to that program
and may begin with a minus sign. prog can be one of: as, c2, cg, cpp, f77passl, iropt,
inline, Id, m4, or ratfor.
-Qpath pathname
Insert directory pathname into the compilation search path (to use alternate versions of
programs invoked during compilation).
-Qproduce source type
Produce source code of the type sourcetype. sourcetype can be one of:
.f
Source file from ratfor(I) .
•0
Object file from as (l).
.s
Assembler source (from[77passl , inline c2 or cg ).

-S

Compile the named programs, and leave the assembly language output on corresponding
files suffixed .s (no .0 file is created).

-temp=dir

Set directory for temporary files to be dir.

-time

Report execution times for the various compilation passes.

-u

Make the default type of a variable 'undefined' rather than using the FORTRAN default
rules.

-u

Do not convert upper case letters to lower case. The default is to convert upper case
letters to lower case, except within character string constants.

-v

Verbose. Print the version number of the compiler and the name of each program it executes.

-w[66]

Suppress all warning messages. -w66 supresses only FORTRAN 66 compatibility warnings.

Other arguments are taken to be either linker option arguments, or j77 -compatible object programs, typically produced by an earlier run, or libraries of[77 -compatible routines. These programs, together with the
results of any compilations specified, are linked (in the order given) to produce an executable program in
the file specified by the -0 option, or in a file named a .out if the -0 option is not specified.
ENVIRONMENT
FLOAT OPTION When no floating-point option is specified, the compiler uses the value of this environment variable (if set). Recognized values are: f68881, ffpa, fsky, fswitch and fsoft.

FILES

a.out
file.a
file .c
file.d
file .f
file.F
file .il
file.o
file.p
file.r
file.s
file.S

158

executable output file
library of object files
C source file
tcov(l) test coverage input file
FORTRAN 77 source file
FORTRAN 77 source file for cpp(1)
inline expansion file
object file
Pascal source file
Ratfor source file
assembler source file
assembler source for cpp (1)

Last change: 8 April 1986

Sun Release 3.2

F77 ( 1)

USER COMMANDS

file .tcov
/lib/bin/ratjor
llib/c2
/lib/cg
/lib/compile
Ilib/cpp
llib/crtO.o
/lib/Fcrtl.o
llib/gcrtO.o
/libllibc .a
/lib/mcrtO.o
Ilib/M crtl.o
/lib/Scrtl.o
Ilib/Wcrtl.o
/ usrlincl ude/f17
/usrllib!fl7passl
/usr/Ub/libc y.a
/usrllibllibF77.a
/usrllib/inline
/usrllibllibI77.a
/usrllib/libm.a
/usrllib/ libpfc.a
/usrllib/ libU77.a
/tmp/*
mon.out
gmon.out

F77 (1)

output from tcov(I)
Ratfor preprocessor
optional optimizer
FORTRAN 77 code generator
compiler command-line processing driver
macro preprocessor
runtime startoff
startup code for -fsoft option
startoff for gprof-profiling
standard library, see intro(3)
startoff for profiling
startup code for -f68881 option
startup code for -fsky option
startup code for -ffpa option
directory searched by the FORTRAN 77 include statement
FORTRAN 77 parser
profiling library, see intro(3)
FORTRAN 77 library
inline expander of library calls
FORTRAN 77 library
math library
startup code for combined Pascal and FORTRAN 77 programs
FORTRAN 77 library
compiler temporary files
file produced for analysis by prof(I)
file produced for analysis by gprof(I)

SEE ALSO

cc( 1V), gprof( 1), Id( 1), prof( 1), ratfor( 1)
FORTRAN Programmer's Guide
Floating-Point Programmer's Guide for the Sun Workstation
DIAGNOSTICS

The diagnostics produced by [17 itself are intended to be self-explanatory. Occasional messages may be
produced by the linker.

Sun Release 3.2

Last change: 8 April 1986

159

FILE ( 1)

USER COMMANDS

FILE(1)

NAME

file - determine file type
SYNOPSIS

file [ -Lc] [ -f ffile ] [ -m mfile ] filename . ..
DESCRIPTION
file performs a series of tests on each filename in an attempt to determine what it contains. If the contents
of a file appear to be ASCII text,file examines the first 512 bytes and tries to guess its language.

file uses the file letclmagic to identify files that have some sort of magic number, that is, any file containing
a numeric or string constant that indicates its type.
OPTIONS
-f

-m
-L
-c

Get a list of filenames to identify fromffile.
Use mfile as the name of an alternate magic number file.
If a file is a symbolic link, test the file the lin~ references rather than the link itself.

Check for format errors in the magic number file. For reasons of efficiency, this validation is not
normally carried out. No file type-checking is done under -c.

EXAMPLE

The example illustrates the use of file on all the files in a specific user's directory:
%pwd
lusrlblort/mise
% file *
mc68020 demand paged executable
code:
c program text
code.c:
counts:
ascii text
roff, nroff, or eqn input text
doc:
empty. file: empty
libz:
archive random library
memos:
directory
symbolic link to /usr/project
project:
executable shell script
script:
titles:
ascii text
cpio archive
s5.stuff:
%

SEE ALSO

magic(5)

BUGS
file often makes mistakes. In particular, it often suggests that command files are C programs.

Does not recognize Pascal or LISP.

160

Last change: 29 April 1986

Sun Release 3.2

FIND ( 1)

USER COMMANDS

FIND ( I}

NAME

find - find files
SYNOPSIS
find pathname-list expression
DESCRIPTION
find recursively descends the directory hierarchy for each pathname in the pathname-list, seeking files that
match a boolean (logical) expression written in the primaries given below. In the descriptions, the argument n is used as a decimal integer where +n means more than n, -n means less than n, and n means

exactly n.

-fstype type

True if the filesystem to which the the file belongs is of type type, where type is typically
4.2 or nfs.

-name filename True if the filename argument matches the current file name. Shell argument syntax can
be used if escaped (watch out for [, ? and *).

-perm onum

True if the file permission" flags exactly match the octal number onum (see chmod(1V)}.
If onum is prefixed by a minus sign, more flag bits (017777, see chmod(l V)) become
significant and the flags are compared: (fiags&onum)==onum.

-prune

Always yields true. Has the side effect of pruning the search tree at the file. That is, if
the "current path name is a directory, find will not descend into that directory.

-type c

True if the type of the file is c, where c is one of:
b

for block special file,

c

for character special file,

d

for directory,

f

for plain file,

p

for named pipe (FIFO),
for symbolic link, or

s

for socket.

-links n

True if the file has n links.

-user uname

True if the file belongs to the user uname. If uname is numeric and does not appear as a
login name in the /etc/passwd database, it is taken as a user ID.

-nouser

True if the file belongs to a user not in the /etc/passwd database.

-group gname

True if the file belongs to group gname. If gname is numeric and does not appear as a
login name in the /etc/group database, it is taken as a group ID.

-nogroup

True if the file belongs to a group not in the /etc/group database.

-size n

True if the file is n blocks long (512 bytes per block). If n is followed by a c, the size is
in characters.

-inurn n

True if the file has inode number n.

-atirne n

True if the file has been accessed in n days. Note that the access time of directories in
path-name-list is changed by find itself.

-mtirne n

True if the file has been modified in n days.

-ctime n

True if the file has been changed in In days. "Changed" means either that the file has
been modified or some attribute of the file (its owner, its group, the number of links to it,
etc.) has been changed.

-exec command True if the executed command returns a zero value as exit status. The end of command
must be punctuated by an escaped semicolon. A command argument {} is replaced by

Sun Release 3.2

Last change: 20 June 1986

161

FIND ( 1)

USER COMMANDS

FIND ( 1)

the current pathname.
-ok command

Like -exec except that the generated command is written on the standard output, then the
standard input is read and the command executed only upon response y.

-print

Always true; the current pathname is printed.

-Is

Always true; causes current pathnameto be printed together with its associated statistics.
These include (respectively) inode number, size in kilobytes (1024 bytes), protection
mode, number of hard links, user, group, size in bytes, and modification time. If the file
is a special file the size field will instead contain the major and minor device numbers. If
the file is a symbolic link the pathname of the linked-to file is printed preceded by "->".
The format is identical to that of "Is -gilds" (note however that formatting is done internally, without executing the Is program).

-cpio device

Always true; write the current file on device in cpio(4) format (5120-byte records).

-ncpio device

Always true; write the current file on device in cpio -c format (5120-byte records).

-newer file

True if the current file has been modified more recently than the argumentfile.

-xdev

Always true; causes find not to traverse down into a file system different from the one on
which current argument pathname resides.

-depth

Always true; causes descent of the directory hierarchy to be done so that all entries in a
directory are acted on before the directory itself. This can be useful when find is used
with cpio(l) to transfer files that are contained in directories without write permission.

( expression)

True if the parenthesized expression is true (parentheses are special to the shell and must
be escaped).

!primary

True if the primary is false ('!' is the unary not operator).

primary1 [ -a] primary2
True if both primary1 and primary2 are true. The -a is not required. It is implied by the
juxtaposition of two primaries.
primary1

-0

primary2
True if either primary1 or primary2 is true (' -0' is the or operator).

EXAMPLE
In our local development system, we keep a file called TIMESTAMP in all the manual page directories.
Here is how to find all entries that have been updated since TIMESTAMP was created:
angel% find lusr/man/man2 -newer lusr/man/man2ITIMEST AMP -print
lusr/man/man2
lusr/man/man21 socket.2
lusr/man/man2/mmap.2

angel%
To find all the files called intro.ms starting from the current directory:
angel% find. -name intro.ms -print
.Imanuals/assembler/intro.ms
.Imanuals/sun.core/intro.ms
.Imanuals/driver.tutlintro.ms
.Imanuals/sys.manager/uucp.impl/intro.mss
.Isupplements/general.works/unix.introduction/intro.mss
.Isupplements/programming.tools/sccs/intro.mss
angel%
To recursively print all files names in the current directory and below, but skipping
angel% find. -name sees -prune -0 -print
angel%

162

Last change: 20 June 1986

secs directories:

Sun Release 3.2

FIND ( 1)

USER COMMANDS

FIND ( 1)

To recursively print all files names in the current directory and below, skipping the contents of sees directories, but printing out the sees directory name:
angel% find. -print -name sees -prune
angel%
To remove files beneath your home directory named 'a.out' or '*.0' that have not been accessed for a week
and that aren't mounted using NFS:
angel% cd
angel% find. \( -name a.out -0 -name '*.0' \) -atime +7 -exec rm {} \; -0 -fstype nfs -prune
FILES

letc/passwd
/etc/group
SEE ALSO

chmod(1 V), cpio(1), sh(1), test(1 V), cpio(5), fs(5)

Sun Release 3.2

Last change: 20 June 1986

163

FINGER ( 1)

USER COMMANDS

FINGER ( 1)

NAME

finger - display information about users
SYNOPSIS
finger [ options] username ...
DESCRIPTION
finger displays information about each named user, including his or her:
login name,
full name,
terminal name (prepended with a '*' if write-permission is denied),
idle time,
login time,
office location, and
phone number
if known.
A

username
may be a first and last name, or an account name.
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.
Information is presented in a multi-line format, and may
include the user's home directory and login shell, any plan
contained in the file
.plan
in the user's home directory, and a project on which they are
working described in the file
.project
(also in that directory).
Ifa
username
argument contains an at-sign, "@", then a connection
is attempted to the machine named after the at-sign, and the remote
finger daemon is queried.
OPTIONS
-m

Match arguments only on username.

-I

Force long output format.

-p

Suppress printing of the .plan files

-s

Force short output format.

FILES

letc!utmp

who is logged in

letc!passwd

for users names

lusrladmllastlog

last login times

-I.plan

plans

7.project

projects

SEE ALSO
w(I), who(l), whois(l)

164

Last change: April 29, 1985

Sun Release 3.2

FINGER ( 1)

USER COMMANDS

FINGER(l)

BUGS

Only the first line of the .project file is printed.

Sun Release 3.2

Last change: April 29, 1985

165

FMT( 1)

USER COMMANDS

FMT( 1)

NAME

fmt - simple text formatter
SYNOPSIS
fmt [ -width] [ -c ] [input-file ..• ]
DESCRIPTION
Imt is a simple text formatter. It joins and fills input lines to produce output lines of up to 72 characters by

default. Imt concatenates the input-files listed as arguments. If none are given,lmt accepts text from the
standard input.
Blank lines are preserved in the output, as is spacing between words.
Normally, if the left-hand margin of a line is indented, that indention is preserved in the output. Input lines
with differing indention aren't normally joined.
Imt is meant to format mail messages before sending, but may also be useful for other simple tasks. For
instance, while in the vi text editor, the command:
!}fmt
reformats a paragraph, making the lines reasonably even in length.
Imt does not fill lines beginning with. or From: for compatibility with nroff(1) and rnail(1).
OPTIONS

-width Fill output lines to up to width columns wide.

-c

Crown margin mode (useful for tagged paragraphs). Imt preserves the indention of the first two
lines in each paragraph. The left margin of the third and subsequent lines is aligned with that of
the second.

SEE ALSO

nroff(l), mail(l)

166

Last change: 17 February 1986

S un Release 3.2

FOLD ( 1)

USER COMMANDS

FOLD ( 1)

NAME

fold - fold long lines for finite width output device
SYNOPSIS

fold [ -width] [ file ••• ]
DESCRIPTION

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 usingfold.
SEE ALSO

expand(l)
BUGS

Folding may not work correctly if underlining is present

Sun Release 3.2

Last change: 27 April 1983

167

FONTEDIT ( 1 )

USER COMMANDS

FONTEDIT ( 1 )

NAME

fontedit - a vfont screen-font editor
SYNOPSIS

fontedit [-W[generic_tool_arg]] [font_name]
DESCRIPTION

fontedit is an editor for fixed-width fonts in vfont format whose characters are no taller than 24 pixels
(larger characters will not fit completely onto the screen). For a description of vfont format, see vfont(5).
OPTIONS

-Wgeneric_too 1_arg
fontedit accepts any generic tool argument as described in suntools(l). Otherwise, you can manipulate the tool via the Tool Manager Menu.
COMMANDS

To edit a font, type 'fontedit'. Afont_name may be supplied on the command line or may be typed into the
option sub window once the program has started. If it exists, the font_name file must be in vfont format.
When the program starts, it displays a single large window containing four subwindows. From top to bottom, the four sub windows are:
1)

The top subwindow, a message subwindow, displays messages, prompts, and warnings.

2)

The second suhwindow from the top, an option subwindow, allows you to set global parameters for
the entire font and specify operations for editing any single character. The options are:
(Load)

Load in the font specified in the file name field. The program will warn you if you try to
read over a modified font.

(Store)

Store the current font onto disk with the name in file name field.

(Quit)

Quit the program; warns you if you have modified the font.

Font name:
The name of the font
Max Width and Max Height:
The size, in pixels, of the largest character in the font. If you edit an existing font, these
parameters are set automatically; you must set them if you are creating a new font.
Changing either of these values for an existing font may alter the glyph of some characters of the font. If the glyph size of a character is larger than the new max size, then that
character is clipped to the new size (its bottom and right edges are moved in). However, if
a glyph's size is smaller than the new size, the glyph is left alone.
Caps Height and X-Height:
The distance, in pixels, between the top of a capital and lowercase letter and the baseline.
When an existing font is edited, the values of Caps Height and X-Height are estimated
by!ontedit, and may require some adjustment
Baseline:

The number of pixels from the top (i.e., the upper left corner) of the character to the baseline. For an existing font, the value of the largest baseline distance is used. For a new font,
each character will have the same baseline distance. If this value is changed, then the
baseline distance for all characters in the font will be the new value.

(Apply)

Apply the current values of Max Width, Max Height, Caps Height, X-Height, and
Baseline to the font. That is, changes made to these values do not take effect until Apply
is selected.

Operation:
This is a list of drawing and editing operations that you can perform on a character. For
drawing, the left mouse button draws in black, and the middle draws in white. Operations
are:

168

Last change: 10 October 1985

Sun Release 3.2

FONTEDIT ( 1 )

USER COMMANDS

FONTEDIT ( 1 )

Single Pt

Press a mouse button down and a grey cell will appear; move the mouse and
the cell will follow it. Releasing the the button will draw.

Pt Wipe

Pressing a button down will draw and moving with the button down will continue drawing until the button is released.

Line

Button down marks the end point of a line; moving with the button down
rubber bands a line; releasing button draws the line.

Reet

Like Line except draws a rectangle.

Cut

Button down marks one end of rectangle, and moving rubber bands the outline of the rectangle. Button up places the contents of the rectangle into a
buffer and then "cuts" (draws in white) the rectangular region from the
character. The Paste operation (below) gets the data from the buffer.

Copy

Like Cut except that the region is just copied; no change is made to the character.

Paste

Button down displays a rectangle the size of the region in the buffer. Moving
with the button down moves the rectangle. Button up pastes the contents of
the buffer into the character.
The contents of the paste buffer cannot be transferred between tools.
In Copy or Cut mode, holding down the shift key while pressing the left or
middle mouse button will perform a Paste action. For best results, after placing a region in the buffer, press down the shi(t key and hold it down, then
press down the mouse button. Release the mouse key to paste the region and
then release the shift key.

3)

The third subwindow echoes the characters in the current font as they are typed. Note that the cursor
must be in this window in order to see the characters. Your character delete key will delete the echoed
characters.

4)

The bottom subwindow, the editing subwindow, displays eight smaller squares at its top; these are
called edit buttons. The top section of each of these buttons contains a line of text in the form nnn: c,
where nnn is the hexadecimal number of the character and c is the standard ASCII character
corresponding to that number. In the lower section of the button the character of the current font, if it
exists, is displayed. Clicking once over an editing button selects its character for editing.
Just below this row of buttons is a box with the characters "0 9 A Z a z" in it. This box is called a
slider. The slider allows you to scroll around in the font and select which section of the font you want
displayed in the edit buttons. The black rectangle near" a" is an indicator which shows the section of
the font that is displayed in the buttons above. To move the indicator, select it by pressing the left or
middle mouse button down over the indicator and then move the mouse to the left or right with the
button down; the indicator will slide along with the cursor. Releasjng the button selects the new section of the font. A faster method of moving about in the font is to just press down and release the
mouse button above the area you want without bothering to drag the indicator. Another method of
scrolling through the characters of the font is to press a key on the keyboard when the cursor is in the
bottom window; that character is the first one displayed in the edit buttons.

EDITING CHARACTERS:

To edit a character, click once over the edit button where the character is displayed. When you do this, an
edit pad will appear in the bottom subwindow.
The edit pad consists of an editing area bordered by scales, a proof area, and 3 command buttons. The editing area is Max Width by Max Height when the pad opens, and displays a magnified view of the selected
character. Black squares indicate foreground pixels. The editing area is surrounded by scales which show
the current Caps Height, X-Height and Baseline in reverse video.

Sun Release 3.2

Last change: 10 October 1985

169

FONTEDIT ( 1 )

USER COMMANDS

FONTEDIT ( 1 )

Just outside the scales, on the top, right side, and bottom of the pad, are three small boxes with the capital
letters "R", "B", and "A" in them. These boxes are movable sliders that change the right edge, bottom edge,
and x-axis advance of the character respectively. In a fixed-width font, these values are usually the same
for all characters; however, in a variable-width font these controls can be used to set these properties for
each character.
To the right of the pad is the proof area where the character is displayed at normal (that is, screen) resolution and three buttons. The three buttons are:
Undo

Clicking the left or middle mouse button undoes the last operation.

Store

Stores the current representation of the character in the font.

Quit

Closes the edit pad.

In the bottom subwindow, the right mouse button displays a menu of operations. These operations are the
same as those in the option subwindow discussed above; you can select the current operation by either
picking the operation in the option subwindow or by selecting the appropriate menu with the left button of
the mouse. When the cursor is in the other subwindows, the left button displays the standard tool menu.
FILES

Iusr/liblfonts!fixedwidthfonts

Sun-supplied screen fonts

SEE ALSO

suntools(l), vfont (5), vswap(l)

BUGS
Results are unpredictable with variable-width fonts. The baseline should be greater than 0 or else the font
cannot be read in by fontedit or by suntools(I).

170

Last change: 10 October 1985

Sun Release 3.2

FPR( 1)

USER COMMANDS

FPR( 1)

NAME

fpr - print FORTRAN file
SYNOPSIS

fpr
DESCRIPTION
Ipr transforms files formatted according to FORTRAN's carriage control conventions into files formatted
according to UNIX line printer conventions.

Fpr copies its input onto its output, replacing the carriage control characters with characters that will produce the intended effects when printed using lpr(l). The first character of each line determines the vertical
spacing as follows:
(blank) one line

o

two lines

1

to first line of next page

+

no advance

A blank line (that is, an empty line) is treated as if its first character is a blank. A blank that appears as a
carriage control character is deleted. A zero is changed to a newline. A one is changed to a form feed. The
effects of a "+" are simulated using backspaces.
Note that Ipr is known as asa in UNIX System V.
EXAMPLES
a.out I fpr Ilpr

fpr < f77.output Ilpr
BUGS

Results are undefined for input lines longer than 170 characters.

Sun Release 3.2

Last change: 24 October 1983

171

FROM ( 1)

USER COMMANDS

FROM(l)

NAME

from - who is my mail from?
SYNOPSIS
from [ -ssender ] [user]
DESCRIPTION
From prints out the mail header lines in your mailbox file to show you who your mail is from. If user is
specified, then user's mailbox is examined instead of your own.
OPTIONS

-ssender
Only display headers for mail sent by sender.
FILES

lusrlspooVmaill*
SEE ALSO
biff(l), mail(l), prmail(l)

172

Last change: 27 April 1983

Sun Release 3.2

FSPLIT( 1)

USER COMMANDS

FSPLIT( 1)

NAME

fsplit - split a multi-routine FORTRAN file into individual files
SYNOPSIS

fsplit [ -e efile ] ... [file]
DESCRIPTION
F split takes as input either a file or standard input containing FORTRAN source code. It attempts to split

the input into separate routine files of the form namef, where name is the name of the program unit (function, subroutine, block data or program). The name for unnamed block data subprograms has the form
blkdtaNNNf where NNN is three digits and a file of this name does not already exist. For unnamed main
programs the name has the form mainNNNf. If there is an error in classifying a program unit, or if name f
already exists, the program unit will be put in a file of the form zzzNNNJwhere zzzNNNJdoes not already
exist.
Normally each subprogram unit is split into a separate file. When the -e option is used, only the specified
subprogram units are split into separate files. E.g.:
fsplit -e readit -e doit progJ
will split readit and doit into separate files.
DIAGNOSTICS
If names specified via the -e option are not found, a diagnostic is written to standard error.
BUGS

Fsplit assumes the subprogram name is on the first noncomment line of the subprogram unit. Nonstandard
source formats may confuse [split.

It is hard to use -e for unnamed main programs and block data subprograms since you must predict the
created file name.

Sun Release 3.2

Last change: 24 August 1983

173

FTP( lC)

USER COMMANDS

FTP(IC)

NAME

ftp - file transfer program
SYNOPSIS

rtp [ -v] [ -d] [ -i] [ -n ] [ -g ] [ -t] [host]
DESCRIPTION
ftp is the user interface to the ARPANET standard File Transfer Protocol. ftp transfers files to and from a

remote network site.
The client host with whichftp is to communicate may be specified on the command line. If this is done,/tp
immediately attempts to establish a connection to an FTP server on that host; otherwise, ftp enters its command interpreter and awaits instructions from the user. When ftp is awaiting commands from the user, it
displays the prompt "ftp>".
OPTIONS

Options may be specified at the command line, or to the command interpreter.
-v

show all responses from the remote server, as well as report on data transfer statistics. This is
turned on by default ifftp is running interactively with its input coming from the user's terminal.

-0

do not attempt "auto-login" upon initial connection. If auto-login is enabled, ftp checks the
.netrc file in the user's home directory for an entry describing an account on the remote machine.
If no entry exists, ftp uses the login name on the local machine as the user identity on the remote
machine, and prompts for a password and, optionally, an account with which to login.

-i

turn off interactive prompting during multiple file transfers.

-g

disable filename "globbing."

-d

enable debugging.

-t

enable packet tracing (unimplemented).

COMMANDS
! [command]

Run command as a shell command on the local machine. If no command is given, invoke an
interactive shell.

append local-file [ remote-file]
Append a local file to a file on the remote machine. If remote-file is left unspecified, the local file
name is used in naming the remote file. File transfer uses the current settings for' 'representation
type", "file structure", and "transfer mode".
ascii

Set the "representation type" to "network ASCII". This is the default type.

bell

Arrange that a bell be sounded after each file transfer command is completed.

binary Set the "representation type" to "image".
bye

Terminate the FTP session with the remote server and exitftp.

cd remote-directory
Change the working directory on the remote machine to remote-directory.

close

Terminate the FTP session with the remote server, and return to the command interpreter.

delete remote-file
Delete the file remote-file on the remote machine.
debug [ debug-value]
Toggle debugging mode. If an optional debug-value is specified it is used to set the debugging
level. When debugging is on, ftp prints each command sent to the remote machine, preceded by
the string" -->".
dir [ remote-directory] [ local-file]

174

Last change: 17 February 1986

S un Release 3.2

FTP( IC)

USER COMMANDS

FTP( IC)

Print a listing of the directory contents in the directory, remote-directory, and, optionally, placing
the output in local-file. If no directory is specified, the current working directory on the remote
machine is used. If no local file is specified, or local-file is -, output comes to the terminal.

form [format-name]
Set the carriage control format subtype of the "representation type" to format-name. The only
validformat-name is non-print, which corresponds to the default "non-print" subtype.
get remote-file [ local-file ]
Retrieve the remote-file and store it on the local machine. If the local file name is not specified, it
is given the same name it has on the remote machine. The current settings for "representation
type", "file structure" , and "transfer mode" are used while transferring the file.
glob

Toggle filename expansion, or "globbing", for mdelete, mget and mput. If globbing is turned off,
filenames are taken literally.
Globbing for mput is done as in csh (1). For mdelete and mget, each remote file name is
expanded separately on the remote machine, and the lists are not merged.
Expansion of a directory name is likely to be radically different from expansion of the name of an
ordinary file: the exact result depends on the remote operating system and FTP server, and can be
previewed by doing 'mls remote-files -' .

mget and mput are not meant to transfer entire directory subtrees of files. You can do this by
transferring a tar (1) archive of the subtree (using a "representation type" of "image" as set by
the binary command).
hash

Toggle hash-sign (#) printing for each data block transferred. The size of a data block is 1024
bytes.

help [ command]
Print an informative message about the meaning of command. If no argument is given,ftp prints a
list of the known commands.
led [ directory ]
Change the working directory on the local machine. If no directory is specified, the user's home
directory is used.
Is [ remote-directory] [local-file]
Print an abbreviated listing of the contents of a directory on the remote machine. If remotedirectory is left unspecified, the current working directory is used. If no local file is specified, or if
local-file is -, the output is sent to the terminal.

mdelete [ remote-files ]
Delete the remote-files on the remote machine.
mdir remote-files local-file
Like dir, except multiple remote files may be specified.
mget remote-files
Expand the remote-files on the remote machine and do a get for each file name thus produced.
See glob for details on the filename expansion. Files are transferred into the local working directory, which can be changed with 'led directory'; new local directories can be created with
'! mkdir directory'.
mkdir directory-name
Make a directory on the remote machine.
mls remote-files local-file
Like Is, except multiple remote files may be specified.

mode [ mode-name ]
Set the "transfer mode"

Sun Release 3.2

to mode-name. The only valid mode-name is stream, which

Last change: 17 February 1986

175

FTP( lC)

USER COMMANDS

FTP( lC)

corresponds to the default "stream" mode.
mput local-files
Expand wild cards in the list of local files given as arguments and do a put for each file in the
resulting list. See glob for details of filename expansion.
open host [port]
Establish a connection to the specified host FTP server. An optional port number may be supplied, in which case,ftp will attempt to contact an FTP server at that port. If the auto-login option
is on (default),ftp will also attempt to automatically log the user in to the FTP server (see below).
prompt Toggle interactive prompting. Interactive prompting occurs during multiple file transfers to allow
the user to selectively retrieve or store files. By default, prompting is turned on. If prompting is
turned off, any mget or mput will transfer all files, and any mdelete will delete all files.
put local-file [ remote-file ]
Store a local file on the remote machine. If remote-file is left unspecified, the local file name is
used in naming the remote file. File transfer uses the current settings for "representation type",
"file structure" , and "transfer mode" .
pwd

Print the name of the current working directory on the remote machine.

quit

A synonym for bye.

quote argl arg2 ...
Send the arguments specified, verbatim, to the remote FTP server. A single FfP reply code is
expected in return.
recv remote-file [ local-file]
A synonym for get.
remotehelp [command-name ]
Request help from the remote FfP server. If a command-name is specified it is supplied to the
server as well.
rename from to
Rename the file from on the remote machine to have the name to.
rmdir directory-name
Delete a directory on the remote machine.
send local-file [ rerrwte-file ]
A synonym for put.
sendport
Toggle the use of PORT commands. By default,ftp will attempt to use a PORT command when
establishing a connection for each data transfer. If the PORT command fails, ftp will use the
default data port. When the use of PORT commands is disabled, no attempt will be made to use
PORT commands for each data transfer. This is useful for certain FTP implementations which
ignore PORT commands but incorrectly indicate they've been accepted.
status

Show the current status offtp.

struct [ struct-name ]
Set the "file structure" to struct-name. The only valid struct-name is file, which corresponds to
the default' 'file" structure.
tenex

Set the "representation type" to that needed to talk to TENEX machines.

trace

Toggle packet tracing (unimplemented).

type [ type-name]
Set the "representation type" to type-name. The valid type-name s are ascii for "network
ASCII", binary or image for "image", and tenex for "local byte size" with a byte size of 8

176

Last change: 17 February 1986

Sun Release 3.2

FTP( lC)

USER COMMANDS

FfP( lC)

(used to talk to TENEX machines). If no type is specified, the current type is printed. The default
type is "network ASCII' , .
user user-name [password] [ account]
Identify yourself to the remote FfP server. If the password is not specified and the server requires
it, ftp will prompt the user for it (after disabling local echo). If an account field is not specified,
and the FTP server requires it, the user will be prompted for it. Unlessftp is invoked with "autologin" disabled, this process is done automatically on initial connection to the FTP server.
verbose Toggle verbose mode. In verbose mode, all responses from the FTP server are displayed to the
user. In addition, if verbose mode is on, when a file transfer completes, statistics regarding the
efficiency of the transfer are reported. By default, verbose mode is on ifftp's commands are coming from a terminal, and off otherwise.

? [command]
A synonym for help.
Command arguments which have embedded spaces may be quoted with quote (") marks.
If any command argument which is not indicated as being optional is not specified, ftp will prompt for that
argument.
FILE NAMING CONVENTIONS

Local files specified as arguments toftp commands are processed according to the following rules.
1)

If the file name "-" is specified, the standard input (for reading) or standard output (for writing) is

used.
2)

If the first character of the file name is "I", the remainder of the argument is interpreted as a shell

command. ftp then forks a shell, using popen(3S) with the argument supplied, and reads (writes)
from the standard output (standard input) of that shell. If the shell command includes spaces, the
argument must be quoted; e.g. ""I Is -It"". A particularly useful example of this mechanism is:
"dir Imore".
3)

Failing the above checks, if "globbing" is enabled, local file names are expanded according to the
rules used in the csh(l); c.f. the glob command.

Note that remote file names are not processed, but are passed just as they are typed, except for the mdelete,
mdir, mget, and mls commands, where they are expanded according to the rules of the remote host's
operating system, if any.
FILE TRANSFER PARAMETERS

The FTP specification specifies many parameters which may affect a file transfer.
The "representation type" may be one of "network ASCII", "EBCDIC", "image", or "local byte size"
with a specified byte size (for PDP-lO's and PDP-20's mostly). The "network ASCII" and "EBCDIC"
types have a further subtype which specifies whether vertical format control (new lines, form feeds, etc.) are
to be passed through ("non-print"), provided in TELNET format ("TELNET format controls"), or provided in ASA (FORTRAN) ("carriage control (ASA)") format. ftp supports the "network ASCII" (subtype "non-print" only) and "image" types, plus "local byte size" with a byte size of 8 for communicating with TENEX machines.
The "file structure" may be one of "file" (no record structure), "record", or "page". ftp supports only
the default value, which is "file".
The "transfer mode" may be one of "stream", "block", or "compressed". ftp supports only the default
value, which is "stream".
SEE ALSO

rcp(IC), ftpd(8C), netrc(5)

Sun Release 3.2

Last change: 17 February 1986

177

FTP(IC)

USER COMMANDS

FTP( lC)

BUGS

Many FTP server implementations do not support experimental operations such as print working directory.
V AX sites running the BBN FTP server appear to ignore the PORT command while indicating complicity;
this locks up all file transfers.

178

Last change: 17 February 1986

Sun Release 3.2

GCORE( 1)

USER COMMANDS

GCORE( 1)

NAME

gcore - get core images of running processes
SYNOPSIS

gcore process-id ...
DESCRIPTION
gcore creates a core image of each specified process. Such an image can be used with adb or dbx.

For best results, stop the process before running gcore to avoid confusion from paging activity.
FILES

core.

core images

SEE ALSO

kill(l), csh(l), adb(l), dbx(l)

Sun Release 3.2

Last change: 3 December 1985

179

GET ( 1)

USER COMMANDS

GET ( 1)

NAl\1E

get - get a version of an SCCS file
SYNOPSIS
lusrlsccs/get [ -rSID ] [ -c cutoff] [ -i list] [ -x list] [ -a seq-no. ] [ -k ] [ -e ] [ -I [p] ]
[ -p ] [ -m ] [ -n ] [ -s ] [ -b ] [ -g ] [ -Gnewname ] [ -t ] filename ...
DESCRIPTION
get generates an ASCII text file from each named secs file according to the specified option. Arguments
may be specified in any order, options apply to all named sees files. If a directory is named, get behaves

as though each file in the directory were specified as a named file, except that non-SCeS files (last component of the path name does not begin with s.) and unreadable files are silently ignored. If a name of - is
given, the standard input is read; each line of the standard input is taken to be the name of an sees file to
be processed. Again, non-SeeS files and unreadable files are silently ignored.
The generated text is normally written into a file called the g-file whose name is derived from the sees file
name by simply removing the leading s.; (see also FILES, below).
OPTIONS

Options are explained below as though only one sees file is to be processed, but the effects of any option
argument applies independently to each named file.
-r SID The Sees IDentification string (SID) of the version (delta) of an sees file to be retrieved. Table
1 below shows, for the most useful cases, what version of an sees file is retrieved (as well as the
SID of the version to be eventually created by delta if the -e option is also used), as a function of
the SID specified.
-ccutofJ
Cutoff date-time, in the form: YY[ MM[ DD[ HH[ MM[ ss ]] ] ] ]

No changes (deltas) to the sees file which were created after the specified cutoff date-time are
included in the generated ASCII text file. Units omitted from the date-time default to their maximum possible values; that is, -c7502 is equivalent to -c750228235959. Any number of nonnumeric characters may separate the various 2 digit pieces of the cutoff date-time. This feature
allows one to specify a cutofJ date in the form: -c77/2/2 9:22:25. Note that this implies that one
may use the %E% and %U% identification keywords.
-e

This get is for editing or making a change (delta) to the sees file via a subsequent use of delta. A
lusrlsccs/get -e applied to a particular version (SID) of the sees file prevents further
lusrlsccs/get -e commands on the same SID until delta is run or the j (joint edit) flag is set in the
sees file (see admin(I)). Concurrent use of lusrlsccs/get -e for different SIDs is always
allowed.
If the g-file generated by a lusrlsccs/get -e is accidentally ruined in the process of editing it, it
may be regenerated by re-running a get with the -k option in place of the -e option.

sees file protection specified via the ceiling, floor, and authorized user list stored in the sees file
(see admin(l)) are enforced when the -e option is used.
-b

U sed with the -e option to indicate that the new delta should have an SID in a new branch as
shown in Table 1. This option is ignored if the b flag is not present in the file (see admin(I)) or if
the retrieved delta is not a leaf delta. (A leaf delta is one that has no successors on the sees file
tree.)
Note: A branch delta may always be created from a non-leaf delta.

-i list

A list of deltas to be included (forced to be applied) in the creation of the generated file. The list
has the following syntax:
 ::=  I  , 
 ::= SID I SID - SID
SID, the sees Identification of a delta, may be in any form shown in the 'SID Specified' column of

180

Last change: 8 April 1986

Sun Release 3.2

GET ( 1)

USER COMMANDS

GET ( 1)

Table 1. Partial SIDs are interpreted as shown in the 'SID Retrieved' column of Table 1.
-x list

A list of deltas to be excluded (forced not to be applied) in the creation of the generated file. See
the -i option for the list format.

-k

Suppress replacement of identification keywords (see below) in the retrieved text by their value.
The -k option is implied by the -e option.

-I [p ]

Write a delta summary into an l-file. If -Ip is used, the delta summary is written on the standard
output and the l-file is not created. See FILES for the format of the I-file.

-p

Write the text retrieved from the sees file to the standard output. Nag-file is created. All output
which normally goes to the standard output goes to the standard error file instead, unless the -s
option is used, in which case it disappears.

-s

Suppress all output normally written on the standard output. However, fatal error messages
(which always go to the standard error file) remain unaffected.

-m

Precede each text line retrieved from the sees file with the SID of the delta that inserted the text
line in the sees file. The format is: SID, followed by a horizontal tab, followed by the text line.

-n

Precede each generated text line with the %M% identification keyword value (see below). The
format is: %M% value, followed by a horizontal tab, followed by the text line. When both the -m
and -n options are used, the format is: %M% value, followed by a horizontal tab, followed by the
-m option generated format.

-g

Do not actually retrieve text from the sees file. It is primarily used to generate an I-file, or to verify the existence of a particular SID.

-t

Access the most recently created ('top') delta in a given release (for example, -rI), or release and
level (for example, -rl.2).

-Gnewname
If a get is allowed on filename (filename is not writable by anyone) place the version that get produces in a file called newname.

-a seq-no.
The delta sequence number of the sees file delta (version) to be retrieved (see sccsfile(5)). This
option is used by the comb command; it is not a generally useful option, and users should not use
it. If both the -r and -a options are specified, the -a option is used. Care should be taken when
using the -a option in conj unction with the -e option, as the SID of the delta to be created may not
be what one expects. The -r option can be used with the -a and -e options to control the naming
of the SID of the delta to be created.
For each file processed, get responds (on the standard output) with the SID being accessed and with the
number of lines retrieved from the sees file.
If the --e option is used, the SID of the delta to be made appears after the SID accessed and before the
number of lines generated. If there is more than one named file or if a directory or standard input is named,
each file name is printed (preceded by a new-line) before it is processed. If the -i option is used included
deltas are listed following the notation 'Included'; if the -x option is used, excluded deltas are listed following the notation 'Excluded'.

Sun Release 3.2

Last change: 8 April 1986

181

GET ( 1)

USER COMMANDS

GET(1 )

TABLE 1. Determination of sees Identification String
SID*
Specified
none:j:

-b Option
Usedt
no

Other
Conditions
R defaults to mR

SID
Retrieved
mR.rnL

SID of Delta
to be Created
mR.(rnL+l)

none:j:
R

yes
no

R defaults to mR
R>mR

mR.rnL
mR.rnL

mR.mL.(mB+l).1
R.l***

R

no

R=mR

mR.rnL

mR.(mL+1)

yes

R>mR

mR.rnL

mR.mL.(mB + 1).1

yes

R=mR

mR.mL

mR.mL.(mB+1).1

R

R R
andR exists
No trunk succ.

R.L

yes

No trunk succ.

R.L

R.L.(mB+l).1

R.L

R.L.(mB+l).l

R.L.B

no

Trunksucc.
in release ~ R
No branch succ.

R.L.B.mS

R.L.B.(mS+l)

R.L.B
R.L.B.S

yes
no

No branch succ.
No branch succ.

R.L.B.mS
R.L.B.S

R.L.(mB+l).1
R.L.B.(S+l)

R.L.B.S

yes

No branch succ.

R.L.B.S

R.L.(mB+l).1

Branch succ.

R.L.B.S

R.L.(mB+1).1

R.L

R.L.B.S
*

**
* **
I
t
:j:

'R', 'L', 'B', and'S' are the 'release', 'level', 'branch', and 'sequence' components of the SID,
respectively; 'm' means 'maximum'. Thus, for example, 'R.mL' means 'the maximum level
number within release R'; 'R.L.(mB+l).I' means 'the first sequence number on the new branch
(that is, maximum branch number plus one) of level L within release R'. Note that if the SID
specified is of the form 'R.L', 'R.L.B', or 'R.L.B.S', each of the specified components must exist
'hR' is the highest existing release that is lower than the specified, nonexistent, release R.
Forces creation of theflrst delta in a new release.
Successor.
The -b option is effective only if the b flag (see admin(1» is present in the file. An entry ofmeans 'irrelevant'.
This case applies if the d (default SID) flag is not present in the file. If the d flag is present in the
file, the SID obtained from the d flag is interpreted as if it had been specified on the command line.
Thus, one of the other cases in this table applies.

IDENTIFICATION KEYWORDS
Identifying information is inserted into the text retrieved from the sees file by replacing identification keywords with their value wherever they occur. The following keywords may be used in the text stored in an
sees file:

Keyword Value
%M% Module name: either the value of the m flag in the file (see admin(1», or if absent, the name of
the sees file with the leading s. removed.
%1%
sees identification (SID) (%R%.%L%.%B%.%S%) of the retrieved text
% R % Release.
%L% Level.

182

Last change: 8 Apri11986

Sun Release 3.2

GET ( 1)

USER COMMANDS

GET ( 1)

%B%
%S%
%D%
%H%
%T%
%E%
%G%
%U%
%Y%
%F%
%P%
%Q%
%C%

Branch.
Sequence.
Current date (YY/MMlDD).
Current date (MM/DD/YY).
Current time (HH:MM:SS).
Date newest applied delta was created (YY/MM/DD).
Date newest applied delta was created (MMlDD/YY).
Time newest applied delta was created (HH:MM:SS).
Module type: value of the t flag in the sees file (see admin(l».
sees file name.
Fully qualified sees file name.
The value of the q flag in the file (see admin(l».
Current line number. This keyword is intended for identifying messages output by the program
such as 'this shouldn't have happened' type errors. It is not intended to be used on every line to
provide sequence numbers.
%Z% The 4-character string @(#) recognizable by what.
%W% A shorthand notation for constructing what strings for UNIX program files. %W% =
%Z%%M%%I%
%A% Another shorthand notation for constructing what strings for non-UNIX program files. %A% =
%Z%%Y% %M% %I%%Z%

FILES

Several auxiliary files may be created by get, These files are known generically as the g-file, i-file, p-file,
and z-file. The letter before the hyphen is called the tag. An auxiliary file name is formed from the sees
file name: the last component of all sees file names must be of the form s.moduie-name, the auxiliary files
are named by replacing the leading s with the tag. The g-file is an exception to this scheme: the g-file is
named by removing the s. prefix. For example, s.xyz.c, the auxiliary file names would be xyz.c, I.xyz.c,
p.xyz.c, and z.xyz.c, respectively.
The g-file, which contains the generated text, is created in the current directory (unless the -p option is
used). A g-file is created in all cases, whether or not any lines of text were generated by the get. It is
owned by the real user. If the -k option is used or implied its mode is 644; otherwise its mode is 444.
Only the real user need have write permission in the current directory.
The i-file contains a table showing which deltas were applied in generating the retrieved text. The I-file is
created in the current directory if the -I option is used; its mode is 444 and it is owned by the real user.
Only the real user need have write permission in the current directory.
Lines in the l-file have the following format:
a.
b.
c.

d.
e.
f.
g.
h.

i.

A blank character if the delta was applied;
* otherwise.
A blank character if the delta was applied or wasn't applied and ignored;
* if the delta wasn't applied and wasn't ignored.
A code indicating a 'special' reason why the delta was or was not applied:
'I': Included.
'X': Excluded.
'C': Cut off (by a -c option).
Blank.
sees identification (SID).
Tab character.
Date and time (in the form YY/MMIDD HH:MM:SS) of creation.
Blank.
Login name of person who created delta.

The comments and MR data follow on subsequent lines, indented one horizontal tab character. A
blank line terminates each entry.

Sun Release 3.2

Last change: 8 April 1986

183

GET ( 1)

USER COMMANDS

GET(1)

The p-file passes information resulting from a lusrlsccslget -e along to delta. Its contents are also used to
prevent a subsequent execution of a lusrlsccs/get -e for the same SID until delta is executed or the joint
edit flag, j, (see admin(l» is set in the sees file. The p-file is created in the directory containing the sees
file and the effective user must have write permission in that directory. Its mode is 644 and it is owned by
the effective user. The format of the p-file is: the gotten SID, followed by a blank, followed by the SID that
the new delta will have when it is made, followed by a blank, followed by the login name of the real user,
followed by a blank, followed by the date-time the get was executed, followed by a blank and the -i option
if it was present, followed by a blank and the -x option if it was present, followed by a new-line. There
can be an arbitrary number of lines in the p-file at any time; no two lines can have the same new delta SID.
The z-file serves as a lock-out mechanism against simultaneous updates. Its contents are the binary (2
bytes) process ID of the command (that is, get) that created it The z-file is created in the directory containing the sees file for the duration of get. The same protection restrictions as those for the p-file apply for
the z-file. The z-file is created mode 444.
SEE ALSO

sccs(1), admin(l), delta(1), help(1), prs(1), what(1), sccsfile(5)
Programming Utilities/or the Sun Workstation.
DIAGNOSTICS

Use help for explanations.
BUGS

If the effective user has write permission (either explicitly or implicitly) in the directory containing the
sees files, but the real user doesn't, only one file may be named when the -e option is used.

184

Last change: 8 April 1986

Sun Release 3.2

GET_SELECTION ( 1 )

USER COMMANDS

GET_SELECTION ( 1 )

NAME

get_selection - copy the contents of a SunView selection to the standard output
SYNOPSIS
get_selection [ rank] [t seconds] [ D ]
DESCRIPTION

get_selection prints the contents of the indicated selection on standard out. A selection is a collection of
objects (e.g. characters) picked with the mouse in the SunView window system.
OPTIONS

rank

indicates which selection is to be printed:
1: primary; 2: secondary; 3: the shelf.
The default is primary.

t seconds
indicates how many seconds to wait for the holder of a selection to respond to a request before
giving up. The default is currently 6 seconds.
D

debugging: inquire through a special debugging service for the selection, rather than accessing the
standard service. Useful only for debugging window applications which are clients of the selection library.

EXAMPLE
The following line in a SunView root menu file provides a menu command to print the primary selection
on the user's default printer:
"Print It"
csh -c "get_selection 1 Ilpr"
SEE ALSO

Editing and the Text Facility, in Windows and Window-Based Tools, Beginner's Guide

Sun Release 3.2

Last change: 29 April 1986

185

GETOPT( 1)

USER COMMANDS

GETOPT(I)

NAME

getopt - parse command options in shell scripts
SYNOPSIS

set -

'getopt optstring $*'

DESCRIPTION
getopt is used to break up options in command lines for easy parsing by shell scripts, and to check for legal
options. optstring is a string of option letters to recognize, (see getopt(3C»). If a letter is followed by a

colon, the option is expected to have an argument - which mayor may not be separated by white space.
(The - following set indicates that the Bourne shell is to pass arguments beginning with a dash as parameters to the script.)
If - appears on the command line that invokes the script, getopt uses it to delimit the end of options it is to
parse (see example below). If used explicitly, getopt will recognize it; otherwise, getopt will generate it at
the first arugment it encounters that has no -. In either case, getopt places it at the end of the options. The
positional parameters ($1 $2 optstring is broken out and preceded by a -, along with the argument (if any)
for each.
EXAMPLE

The following code fragment shows how one might process the arguments for a command that can take the
options a or b, as well as the option 0, which requires an argument:
:j#:! /bin/sh
set "get opt abo: $*'
if [ $? ! = 0 ]
then
echo $USAGE
exit 2
fi
for i in $*
do
case $i in
FLAG=$i; shift;;
-a I -b)
-0)
OARG=$2; shift 2;;
shift; break;;
-)
esac
done

This code will accept any of the following command lines as equivalent:

cmd -a -0 arg f1 f2
cmd -aoarg f1 f2
cmd -oarg -a f1 f2
cmd -a -oarg f1 f2
DIAGNOSTICS
getopt prints an error message on the standard error when it encounters an option letter not included in optstring.
SEE ALSO

sh(I), csh(I), getopt(3C)

186

Last change: 28 March 1986

Sun Release 3.2

GFXTOOL(l)

USER COMMANDS

GFXTOOL(l)

NAME

gfxtool- Run graphics programs in the SunWindows environment
SYNOPSIS

gfxtool [ -C] [program [arguments]]
OPTIONS

-C

Redirect system console output to this instance of gfxtool.

gfxtool also accepts all of the generic tool arguments; see suntools(l) for a list of these arguments.
If a pro gram argument is present, gfxtool runs it. If there are no arguments, gfxtool runs the program
corresponding to your SHELL environment variable. If this environment variable is not available, then
gfxtool runs Ibinlsh.
DESCRIPTION
gfxtool is a standard tool provided with Sun Windows. It allows you to run graphics programs that don't

overwrite the terminal emulator from which they run.
gfxtool has two subwindows: a terminal sub window and an empty subwindow. The terminal subwindow
contains a running shell,just like the shelltool (see shelltool(1». Programs invoked in the terminal subwindow can run in the empty subwindow. You can move the boundary between these two sub windows as
described in suntools(1) under The Tool Manager. If you wish, you can make gfxtool your console by
entering a first argument of -C.

Normally you can use the mouse and keyboard anywhere in the empty subwindow to access Tool Manager
functions. However, some graphics programs which run in this window may take over inputs directed to it.
For example, SunCore uses the mouse and keyboard for its own input. When you run such tools, access
the Tool Manager menu from the tool boundaries or namestripe.
SEE ALSO

suntools(l), shelltool(1), gfx_ demos (6)
FILES
-I.ttyswrc
lusr/binl gfxtool
lusr/binlsuntools
lusr/demol*
lusrlsrc/sun/suntooVgfxtool.c

BUGS

If more than 256 characters are input to a tenninal emulator subwindow without an intervening newline,
the tenninal emulator may hang. If this occurs, display the Tool Manager Menu; the "TTY Hung?" submenu there has one item, "Flush input", that you can invoke to correct the problem.

Sun Release 3.2

Last change: 29 March 1985

187

GPROF( 1)

USER COMMANDS

GPROF( 1)

NAME

gprof - display call-graph profile data
SYNOPSIS

gprof [ -a ] [ -b ] [ -c] [ -e name] [ -E name] [ -f name] [ -F name] [ -s ] [ -z ]
[ object-file [profile-file .. . ] ]
DESCRIPTION

GproJ produces an execution profile of C, Pascal, or FORTRAN 77 programs. The effect of called routines
is incorporated in the profile of each caller. The profile data is taken from the call graph profile file
(gmon.out default) which is created by programs compiled with the -pg option of cc, pc, and [17. That
option also links in versions of the library routines which are compiled for profiling. The symbol table in
the named object file (a.out by default) is read and correlated with the call graph profile file. If more than
one profile file is specified, the gprof output shows the sum of the profile information in the given profile
files.
First, execution times for each routines are propagated along the edges of the call graph. Cycles are
discovered, and calls into a cycle are made to share the time of the cycle. The first listing shows the functions sorted according to the time they represent, including the time of their call graph descendants. Below
each function entry is shown its (direct) call-graph children, and how their times are propagated to this
function. A similar display above the function shows how this function's time and the time of its descendants is propagated to its (direct) call-graph parents.
Cycles are also shown, with an entry for the cycle (!s a whole and a listing of the members of the cycle and
their contributions to the time and call counts of the cycle.
Next, a flat profile is given, similar to that provided by prof(I). This listing gives the total execution times
and call counts for each of the functions in the program, sorted by decreasing time. Finally, an index showing the correspondence between function names and call-graph profile index numbers.
Beware of quantization errors. The granularity of the sampling is shown, but remains statistical at best. It
is assumed that the time for each execution of a function can be expressed by the total time for the function
divided by the number of times the function is called. Thus the time propagated along the call-graph arcs
to parents of that function is directly proportional to the number of times that arc is traversed.
The profiled program must call exit(2) or return normally for the profiling information to be saved in the
gmon.out file.
OPTIONS

-a

suppress printing statically declared functions. If this option is given, all relevant information
about the static function (for instance, time samples, calls to other functions, calls from other functions) belongs to the function loaded just before the static function in the a .out file.

-b

Brief. Suppress descriptions of each field in the profile.

-c

the static call-graph of the program is discovered by a heuristic which examines the text space of
the object file. Static-only parents or children are indicated with call counts of O.

-ename
suppress printing the graph profile entry for routine name and all its descendants (unless they have
other ancestors that aren't suppressed). More than one -e option may be given. Only one name
may be given with each -e option.

-Ename
suppress printing the graph profile entry for routine name (and its descendants) as -e, above, and
also exclude the time spent in name (and its descendants) from the total and percentage time computations. More than one -E option may be given. For example, -E mcount -E mcleanup is the
default.
-fname
print the graph profile entry only for routine name and its descendants. More than one -f option

188

Last change: 22 April 1986

Sun Release 3.2

GPROF( 1)

USER COMMANDS

GPROF( 1)

may be given. Only one name may be given with each -f option.

Sun Release 3.2

Last change: 22 April 1986

189

GPROF( 1)

USER COMMANDS

GPROF( 1)

-F name
print the graph profile entry only for routine name and its descendants (as -f, above) and also use
only the times of the printed routines in total time and percentage computations. More than one
-F option may be given. Only one name may be given with each -F option. The -F option overrides the - E option.

-s

produce a profile file grrwn.sum which represents the sum of the profile information in all the
specified profile files. This summary profile file may be given to subsequent executions of gprof
(probably also with a -s) option to accumulate profile data across several runs of an a.out file.

-z

display routines which have zero usage (as indicated by call counts and accumulated time). This
is useful in conjunction with the -c option for discovering which routines were never called.

FILES

a.out
gmon.out
gmon.sum

the namelist and text space
dynamic call-graph and profile
summarized dynamic call-graph and profile

SEE ALSO

monitor(3), profil(2), cc(I), prof(1)
Graham, S.L., Kessler, P.B., McKusick, M.K., 'gprof: A Call Graph Execution Profiler', Proceedings of
the SIGPLAN '82 Symposium on Compiler Construction, SIGPLAN Notices, Vol. 17, No.6, pp. 120-126,
June 1982.
BUGS

Parents which are not themselves profiled will have the time of their profiled children propagated to them,
but they will appear to be spontaneously invoked in the call-graph listing, and will not have their time propagated further. Similarly, signal catchers, even though profiled, will appear to be spontaneous (although
for more obscure reasons). Any profiled children of signal catchers should have their times propagated
properly, unless the signal catcher was invoked during the execution of the profiling routine, in which case
all is lost.

190

Last change: 22 April 1986

Sun Release 3.2

GRAPH ( 1G)

USER COMMANDS

GRAPH ( IG)

NAME

graph - draw a graph
SYNOPSIS
graph [ -a spacing [start]] [-b] [-c string] [ -g gridstyle] [-I label]
[ -m connectmode ] [ -s] [-x [ 1 ] lower [ upper [ spacing] ] ]
[ -y [I] lower [upper [spacing]]] [ -hfraction] [-w fraction] [-r fraction]
[ -ufraction] [-t] ...
DESCRIPTION

Graph with no options takes pairs of numbers from the standard input as abscissas and ordinates of a
graph. Successive points are connected by straight lines. The graph is encoded on the standard output for
display by the plot(1G) filters.
If the coordinates of a point are followed by a nonnumeric string, that string is printed as a label beginning
on the point. Labels may be surrounded with quotes
in which case they may be empty or contain
blanks and numbers; labels never contain newlines.
tI • • • " ,

A legend indicating grid range is produced with a grid unless the -s option is present.
OPTIONS
Each option is recognized as a separate argument.

-a spacing [start]
Supply abscissas automatically (they are missing from the input); spacing is the spacing (default
1). start is the starting point for automatic abscissas (default 0 or lower limit given by -x).
-b

Break (disconnect) the graph after each label in the input.

-c string

String is the default label for each point
-g gridstyle

Gridstyle is the grid style: 0 no grid, 1 frame with ticks, 2 full grid (default).
-I

label is label for graph.

-m connectmode
is mode (style) of connecting lines: 0 disconnected, 1 connected (default). Some devices give distinguishable line styles for other small integers.

-s

Save screen, don't erase before plotting.

-x [ 1 ] lower [ upper [ spacing] ]

If 1 is present, x axis is logarithmic. lowerandupper are lower (and upper) x limits. spacing, if
present, is grid spacing on x axis. Normally these quantities are determined automatically.
-y [ 1 ] lower [ upper [ spacing] ]
If 1 is present, y axis is logarithmic. lowerandupper are lower (and upper) y limits. spacing, if
present, is grid spacing on y axis. Normally these quantities are determined automatically.

-hfraction
is fraction of space for height.
-wfraction
is fraction of space for width.
-r fraction
is fraction of space to move right before plotting.

-ufraction
is fraction of space to move up before plotting.
-t

Sun Release 3.2

Transpose horizontal and vertical axes. (Option -x now applies to the vertical axis.)

Last change: 1 June 1983

191

GRAPH ( 1G)

USER COMMANDS

GRAPH(1G)

If a specified lower limit exceeds the upper limit, the axis is reversed.
SEE ALSO

spline(1G), plot(1G)
BUGS

Graph stores all points internally and drops those for which there isn't room.
Segments that run out of bounds are dropped, not windowed.
Logarithmic axes may not be reversed.

192

Last change: 1 June 1983

Sun Release 3.2

GREP( IV)

USER COMMANDS

GREP( IV)

NAME

grep, egrep, fgrep - search a file for a pattern
SYNOPSIS

grep [ -v] [ -c ] [ -I] [ -n ] [ -b ] [ -i] [ -s ] [ -b] [ -w] [ -e ] expression [file . .. ]
egrep [ -v] [ -c ] [ -I] [ -n] [ -b ] [ -i ] [ -s ] [ -b] [ -e expression] [ -f file]
[ expression] [file ... ]

fgrep [ -v ] [ -x ] [ -c ] [ -I] [ -n ] [ -b ] [ -i] [ -s ] [ -b ]
[ -e string] [ -f file] [ string] [file . .. ]
SYSTEM V SYNOPSIS

grep [ -v] [ -c ] [ -I] [ -n ] [ -b ] [ -i] [ -s ] expression [file ... ]
DESCRIPTION
Commands of the grep family search the inputfiles (standard input default) for lines matching a pattern.
Normally, each line found is copied to the standard output. Grep patterns are limited regular expressions in
the style of ed(I). Egrep patterns are full regular expressions including alternation. Fgrep patterns are
fixed strings - no regular expression metacharacters are supported.

In general, egrep is the fastest of these programs.
Take care when using the characters $, *, [, ", I, (, ), and \ in the expression, as these characters are also
meaningful to the Shell. It is safest to enclose the entire expression argument in single quotes' ... '.
When any of the grep utilities is applied to more than one input file, the name of the file is displayed
preceding each line which matches the pattern. The filename is not displayed when processing a single file,
so if you actually want the filename to appear, use !dey/null as a second file in the list.
OPTIONS
-v

Invert the search to only display lines that do not match.

-x

Display only those lines which match exactly ifgrep only).

that is, only lines which match in their entirety

-c

Display a count of matching lines rather than displaying the lines which match.

-I

List only the names of files with matching lines (once) separated by newlines.

-n

Precede each line by its relative line number in the file.

-b

Precede each line by the block number on which it was found. This is sometimes useful in locating disk block numbers by context.

-i

Ignore the case of letters in making comparisons identical.

-s

Work silently, that is, display nothing except error messages. This is useful for checking the error
status.

-b

DOJ1ot display filenames.

-w

search for the expression as a word as if surrounded by \< and \>. grep only.

that is, upper and lower case are considered

-e expression
Same as a simple expression argument, but useful when the expression begins with a-.
-f file

Take the regular expression (egrep) or a list of strings separated by newlines ifgrep) from file .

SYSTEM V OPTIONS
The System V version of grep does not recognize the -b, -W, or -e options. The -s option indicates that
error messages for nonexistent or unreadable files should be suppressed, not that all messages should be
suppressed.

Sun Release 3.2

Last change: 8 July 1986

193

GREP( IV)

USER COMMANDS

GREP( IV)

REGULAR EXPRESSIONS
The following one-character regular expressions match a single character:

c

An ordinary character (not one of the special characters discussed below) is a one-character regular expression that matches that character.

\c

A backs lash (\) followed by any special character is a one-character regular expression that
matches the special character itself. The special characters are:
a.

., *, [, and \ (period, asterisk, left square bracket, and backslash, respectively), which are
always special, except when they appear within square brackets ([ ]).

b.

'" (caret or circumflex), which is special at the beginning of an entire regular expression, or
when it immediately follows the left of a pair of square brackets ([ D.

c.

$ (currency symbol), which is special at the end of an entire regular expression.

A period (.) is a one-character regular expression that matches any character except newline.

[string]
A non-empty string of characters enclosed in square brackets is a one-character regular expression
that matches anyone character in that string. If, however, the first character of the string is a
circumflex C), the one-character regular expression matches any character except newline and the
remaining characters in the string. The '" has this special meaning only if it occurs first in the
string. The minus (-) may be used to indicate a range of consecutive ASCII characters; for example, [0-9] is equivalent to [0123456789]. The - loses this special meaning if it occurs first (after
an initial A, if any) or last in the string. The right square bracket (D does not terminate such a
string when it is the first character within it (after an initial A, if any); e.g., []a-f] matches either a
right square bracket (]) or one of the letters a through f inclusive. The four characters ., *, [, and \
stand for themselves within such a string of characters.
The following rules may be used to construct regular expressions:
*

A one-character regular expression followed by an asterisk (*) is a regular expression that
matches zero or more occurrences of the one-character regular expression. If there is any choice,
the longest leftmost string that permits a match is chosen.

\(

A regular expression enclosed between the character sequences \( and \) matches whatever the
unadorned regular expression matches. (grep only).

\n

The expression \n matches the same string of characters as was matched by an expression
enclosed between \( and \) earlier in the same regular expression. Here n is a digit; the subexpression specified is that beginning with the n-th occurrence of \( counting from the left. For
example, the expression "'\(.*\)\1$ matches a line consisting of two repeated appearances of the
same string.

concatenation
The concatenation of regular expressions is a regular expression that matches the concatenation of
the strings matched by each component of the regular expression.

\<

The sequence \< in a regular expression constrains the one-character regular expression immediately following it only to match something at the beginning of a "word"; that is, either at the
beginning of a line, or just before a letter, digit, or underline and after a character not one of these.

\>

The sequence \> in a regular expression constrains the one-character regular expression immediately following it only to match something at the end of a "word"; that is, either at the end of a
line, or just before a character which is neither a letter, digit, nor underline.
A circumflex C) at the beginning of an entire regular expression constrains that regular expression
to match an initial segment of a line.

$

194

A currency symbol ($) at the end of an entire regular expression constrains that regular expression
to match afinal segment of a line.

Last change: 8 July 1986

Sun Release 3.2

GREP( IV)

USER COMMANDS

GREP( IV)

The construction "entire regular expression$ constrains the entire regular expression to match the entire
line.

egrep accepts regular expressions of the same sort grep does, except for \(, \), \n, \<, and \>, with the addition of:
*

A regular expression (not just a one-character regular expression) followed by an asterisk (*) is a
regular expression that matches zero or more occurrences of the one-character regular expression.
If there is any choice, the longest leftmost string that permits a match is chosen.

+

A regular expression followed by a plus sign (+) is a regular expression that matches one or more
occurrences of the one-character regular expression. If there is any choice, the longest leftmost
string that permits a match is chosen.

?

A regular expression followed by a question mark (?) is a regular expression that matches zero or
one occurrences of the one-character regular expression. If there is any choice, the longest left-

most string that permits a match is chosen.
Alternation: two regular expressions separated by I or newline match either a match for the first or
a match for the second.

o

A regular expression enclosed in parentheses matches a match for the regular expression.

The order of precedence of operators at the same parenthesis level is [ ] (character classes), then * + ? (closures), then concatenation, then I (alternation) and newline.
SYSTEM V REGULAR EXPRESSIONS
The System V version of grep does not accept \< or \> in a regular expression, and accepts the following
additional item in a regular expression:
\{m\}
\{m,\}

\{m,n\} A regular expression followed by \{m\}, \{m,\}, or \{m,n\} matches a range of occurrences of the
regular expression. The values of m and n must be non-negative integers less than 256; \{m\}
matches exactly m occurrences; \{m,\} matches at least m occurrences; \{m,n\} matches any
number of occurrences between m and n inclusive. Whenever a choice exists, the regular expression matches as many occurrences as possible.
EXAMPLES
Search a file for a fixed string usingfgrep:
tutorial% fgrep intro lusr/manlman3/*.3*
Look for character classes using grep:
tutorial% grep '[1-8]([CJMSNX])' lusr/man/manl/*.l
Look for alternative patterns using egrep:
tutorial% egrep '(SallyIFred) (SmithIJonesIParker)' telephone.Iist
To get the filename displayed when only processing a single file, use Idev/null as the second file in the list:
tutorial% grep 'Sally Parker' telephone.Iist Idev/null
SEE ALSO
visual display-oriented editor based on ex(l)
vi(l)
line-oriented text editor based on ed( 1)
ex(l)
primitive line-oriented text editor
ed(l)
stream editor
sed(1 V)
pattern scanning and text processing language
awk(l)
Bourne Shell
sh(l)
DIAGNOSTICS
Exit status is 0 if any matches are found, 1 if none, 2 for syntax errors or inaccessible files.
BUGS
Lines are limited to 1024 characters by·grep; longer lines are truncated.

Sun Release 3.2

Last change: 8 July 1986

195

GREP( 1V)

USER COMMANDS

GREP( 1V)

If there is a line with embedded nulls, grep will only match up to the first null; if it matches, it will print the
entire line.
The combination of -I and -v options does not produce a list of files in which a regular expression is not
found. To get such a list, use the C-Shell construct:
foreach file (*)
if ('grep "re" $file I wc -1' == 0) echo $file
end
Ideally there should be only one grep.

196

Last change: 8 July 1986

Sun Release 3.2

GROUPS(l)

USER COMMANDS

GROUPS(l)

NAME

groups - show group memberships
SYNOPSIS

groups
DESCRIPTION
Groups displays the groups to which you belong. Each user belongs to a group specified in the password
file fetclpasswd and possibly to other groups as specified in the file fetc/group. If you do not own a file but
belong to the group which it is owned by then you are granted group access to the file.

When a new file is created it is given the group of the containing directory.
SEE ALSO
setgroups(2)
FILES

letclpasswd, fetcfgroup

Sun Release 3.2

Last change: 20 June 1983

197

HEAD ( 1)

USER COMMANDS

. HEAD(I)

NAME

head - display first few lines of specified files
SYNOPSIS

head [ -n ] [filename . . .J
DESCRIPTION
head copies the first n lines of each filename to the standard output. If no filename is given, head copies
lines from the standard input. The default value of n is 10 lines.

When more than one file is specified, head places a marker at the start of each file which looks like:
==> filename <==

Thus, a common way to display a set of short files, identifying each one, is:
gaia% head -9999 filet file2 ••.
EXAMPLE

gaia% head -4 /usr/manlman1l{cat,head,tail}.1 *
==> lusr/manlmanllcat.lv <==
.TIl CAT IV "2 June 1983"
.SHNAME
cat - concatenate and display
.SH SYNOPSIS
==> lusr/man/man lIhead.l <==
.TH HEAD 1 "24 August 1983"
.SHNAME
head - display first few lines of specified files
.SH SYNOPSIS
==> lusr/man/manlltail.l <==
.TIl TAIL 1 "27 April 1983"
.SHNAME
tail- display the last part of a file
.SH SYNOPSIS
SEE ALSO

more(I), tail(l), cat(l V)

198

Last change: 5 May 1986

Sun Release 3.2

HELP ( 1)

USER COMMANDS

HELP(1)

NAME

help - ask for help regarding

sees

SYNOPSIS

lusrIsccslhelp [args]
DESCRIPTION
Help finds information to explain a message from a command or explain the use of a command. Zero or
more arguments may be supplied. If no arguments are given, help will prompt for one.

The arguments may be either message numbers (which normally appear in parentheses following messages) or command names, of one of the following types:
type 1

Begins with non-numerics, ends in numerics. The non-numeric prefix is usually
an abbreviation for the program or set of routines which produced the message
(for example, ge6, for message 6 from the get command).

type 2

Does not contain numerics (as a command, such as get)

type 3

Is all numeric (for example, 212)

The response of the program will be the explanatory information related to the argument, if there is any.
When all else fails, try lusrlsccs/help stuck.
FILES

/usr/lib/help

directory containing files of message text.

DIAGNOSTICS
Use help(1) for explanations.

Sun Release 3.2

Last change: 27 October 1983

199

HOSTID( 1)

USER COMMANDS

HOSTID( 1)

NAME

hostid - print identifier of current host system
SYNOPSIS

hostid
DESCRIPTION

The hostid command prints the identifier of the current host in hexadecimal. This numeric value is unique
across all Sun hosts.
SEE ALSO

gethostid(2)

200

Last change: 1 February 1985

Sun Release 3.2

HOSTNAME ( 1 )

USER COMMANDS

HOSTNAME(l)

NAME

hostname - set or print name of current host system
SYNOPSIS

hostname [ nameotbost ]
DESCRIPTION

The hostname command prints the name of the current host, as given before the "login" prompt. The
super-user can set the hostname by giving an argument; this is usually done in the startup script
I etc/rc.1ocal.
SEE ALSO

gethostname(2), sethostname(2)

Sun Release 3.2

Last change: 22 March 1983

201

ICONEDIT ( 1 )

USER COMMANDS

ICONEDIT ( 1 )

NAME

iconedit - create and edit small images for icons, cursors, panel items, etc.
SYNOPSIS

iconedit [filename ]
OPTIONS

iconedit accepts the standard SunView command-line arguments; see suntools(l) for a list
DESCRIPTION

iconedit is a standard tool provided with the SunView environment. With it you can create and edit small
images for use in icons, cursors, panel items, etc. iconedit has several subwindows:
A large drawing area or canvas (on the left).
A small proof area for previewing a life-size version of the image being edited (at the lower right).
A control panel showing the options available and their current state (at the center right).
An area for status messages (at the upper right).

An area containing instructions for the use of the mouse (above the drawing canvas).
Inside the canvas, use the left button to draw and the middle button to erase. As you draw, an enlarged version of the image appears in the canvas, while a life-sized version of the image appears in the proof area.
Use the right button to undo the previous operation.
While editing a cursor image, you can try the cursor out against different backgrounds and with different
raster operations by moving the cursor into the proof area.
CONTROL PANEL

The large control panel to the right of the canvas contains many items through which you can control
iconedit. Some items are buttons which allow you to initiate commands, some are text fields which you
type into, and some are choice items allowing you select from a range of options. Use the left button to
select items. Most items also have a menu which you can invoke with the right button.
There are three text fields: the two at the top labelled "Dir:" and "File:", and one to the right of the
"abc" labelled "Fill:". A triangular caret points to the current type-in position. Typing 
advances the caret to the next text field; you can also move the caret to a text field by selecting the field
with the left button.
Each item in the control panel is described below:
Dir

The current directory.

File

The current filename. The default is the filename given on the command line. You can request
filename completion by pressing . iconedit searches the current directory for files whose
names begin with the string you entered. If the filename search locates only one file, that file will
be loaded in. In addition, typing CTRL-L, CTRL-S, CTRL-B or CTRL-Q are equivalent to pressing the Load, Store, Browse, or Quit buttons, respectively.

Load

(Button) Load the canvas from the file named in the File field.

Store

(Button) Store the current image in the file named in the File field.

Browse (Button) Display all the images in the current directory in a popup panel. When you select an
image with the left button, it will be loaded into the canvas for editing and the browsing panel will
be hidden. Pressing browse again will cause the panel to popup again (it will come up immediately if the directory and file fields have not been modified).

202

Quit

(Button) Terminate processing. Quitting requires a confirming click of the left mouse button.

Size

Alter the canvas size. Choices are icon size (64 x 64 pixels) or cursor size (16 x 16 pixels).

Grid

Display a grid over the drawing canvas, or turn the grid off.

Clear

(Button) Clear the canvas.

Last change: 17 September 1985

Sun Release 3.2

ICONEDIT ( 1 )

USER COMMANDS

Fill

(Button) Fill canvas with current rectangular fill pattern.

Invert

(Button) Invert each pixel represented on the canvas.

ICONEDIT ( 1 )

Paintbrush
Select from among five painting modes. Instructions for each painting mode appear above the
canvas. The painting modes are:
dot

Paint a single dot at a time.

line

Draw a line. To draw a line on the canvas, point to the first endpoint of the line, and
press and hold the left mouse button. While holding the button down, drag the cursor to
the second endpoint of the line. Release the mouse button.

rectangle
Draw a rectangle. To draw a rectangle on the canvas, point to the first corner of the rectangle and press and hold the left mouse button. While holding the button down, drag the
cursor to the diagonally opposite comer of the rectangle. Release the mouse button.
In the control panel, the Fill field to the right of the rectangle indicates the current rectangle fill pattern. Any rectangles you paint on the canvas will be filled with this pattern.
circle

Draw a circle. To draw a circle on the canvas, point to the center of the circle, and press
and hold the left mouse button. While holding the button down, drag the cursor to the
desired edge of the circle. Release the mouse button.
In the control panel, the Fill field to the right of the circle indicates the current circle fill
pattern. Any circles you paint on the canvas will be filled with this pattern.

abc

Insert text. To insert text, move the painting hand to "abc" and type the desired text.
Then move the cursor to the canvas and press and hold the left mouse button. A box will
appear where the text is to go. Position the box as desired and release the mouse button.
In addition, you can choose the font in which to draw the text. Point at the Fill field to
the right of the "abc" and either click the left mouse button to cycle through the available fonts or press and hold the right mouse button to bring up a menu of fonts.

Load

This is the rasterop to be used when loading a file in from disk. (See the Pixrect Reference
Manual for details on rasterops).

Fill

This is the rasterop to be used when filling the canvas. The source for this operation is the rectangle fill pattern, and the destination is the canvas.

Proof

This is the rasterop to be used when rendering the proof image. The source for this operation is
the proof image, and the destination is the proof background.

Proof background
The proof background can be changed to allow you to preview how the image will appear against
a variety of patterns. The squares just above the proof area show the patterns available for use as
the proof background pattern. To change the proof background, point at the desired pattern and
click the left mouse button.
SEE ALSO

suntools( 1)
FILES

lusr/binliconedit

Sun Release 3.2

Last change: 17 September 1985

203

USER COMMANDS

ID( 1)

ID( 1)

NAME

id - print user and group IDs and names
SYNOPSIS

id
DESCRIPTION
id writes a message on the standard output giving the user and group IDs, and the corresponding names of
the invoking process. If the effective and real IDs do not match, both are printed.
SEE ALSO
getuid(2)

204

Last change:

Sun Release 3.2

INDENT ( 1)

USER COMMANDS

INDENT(I)

NAME

indent - indent and format C program source
SYNOPSIS

indent [ input-file [ output-file ] ] [-bad I-nbad] [-bap I-nbap] [-bbb I-nbbb] [-bc I-nbc]
[ -bl ] [ -br ] [ -bs I -nbs] [ -cn] [ -cdn] [ -cdb I -nedb ] [ -ee I -nee] [ -cin ] [ -e1in] [ -dn ]
[ -din] [ -fel I-nfel] [-in] [-ip I -nip] [ -In] [ -len] [ -Ip I -nip] [ -pes I -npes] [ -npro ]
[ -psi I -npsl] [ -se I -nse ] [ -sob I -nsob ] [ -st] [ -troff] [ -v I-nv ]
DESCRIPTION

Indent is a C program formatter. It reformats the C program in the input-file according to the switches.
The switches which can be specified are described below. They may appear before or after the file names.

NOTE: If you only specify an input-file, the formatting is done 'in-place', that is, the formatted file is written back into input-file and a backup copy of input-file is written in the current directory. If input-file is
named '/blah/blah/file', the backup file is named file.BAK.
If output-file is specified, indent checks to make sure it is different from input-file.
OPTIONS

The options listed below control the formatting style imposed by indent.
-bap,-nbap

If -bap is specified, a blank line is forced after every procedure body. Default -nbap.

-bad,-nbad

If -bad is specified, a blank line is forced after every block of declarations. Default
-nbad.

-bbb,-nbbb

If -bbb is specified, a blank line is forced before every block comment. Default
-nbbb.

-be,-nbc

If -be is specified, then a newline is forced after each comma in a declaration. -nbc
turns off this option. The default is -be.

-br,-bl

Specifying -bllines up compound statements like this:
if

( ... )

code
}

Specifying -br (the default) makes them look like this:
if

( ... )

{

code

-bs,-nbs

Enables (disables) the forcing of a blank after sizeof. Some people believe that size of
should appear as though it were a procedure call (-nbs, the default) and some people
believe that since sizeof is an operator, it should always be treated that way and should
always have a blank after it.

-en

The column in which comments on code start. The default is 33.

-edn

The column in which comments on declarations start. The default is for these comments
to start in the same column as those on code.

-cdb,-nedb

Enables (disables) the placement of comment delimiters on blank lines. With this option
enabled, comments look like this:
/*
* this is a comment
*/
Rather than like this:
/* this is a comment */
This only affects block comments, not comments to the right of code. The default is
-edb.

Sun Release 3.2

Last change: 14 June 1985

205

INDENT ( 1)

206

USER COMMANDS

INDENT ( 1)

-ee,-nee

Enables (disables) forcing 'else's to cuddle up to the immediatly preceeding '}'. The
default is -ee •

-ein

Sets the continuation indent to be n. Continuation lines will be indented that far from
the beginning of the first line of the statement Parenthesized expressions have extra
indentation added to indicate the nesting, unless -Ip is in effect -ci defaults to the same
value as -i.

-c1in

Causes case labels to be indented n tab stops to the right of the containing switch statement. -eliO.5 causes case labels to be indented half a tab stop. The default is -cliO.

-dn

Controls the placement of comments which are not to the right of code. The default -di
means that such comments are placed one indentation level to the left of code. Specifying -dO lines up these comments with the code. See the section on comment indentation
below.

-din

Specifies the indentation, in character positions, from a declaration keyword to the following identifier. The default is -di16.

-fel,-nfel

Enables (disables) the formatting of comments that start in column 1. Often, comments
whose leading 'I' is in column 1 have been carefully hand formatted by the programmer.
In such cases, -nfel should be used. The default is -fel.

-in

The number of spaces for one indentation level. The default is 4.

-ip,-nip

Enables (disables) the indentation of parameter declarations from the left margin. The
default is -ip •

-In

Maximum length of an output line. The default is 75.

-len

Sets the line length for block comments to n. It defaults to being the same as the usual
line length as specified with -I.

-Ip,-nlp

Lines up code surrounded by parenthesis in continuation lines. If a line has a left paren
which is not closed on that line, then continuation lines will be lined up to start at the
character position just after the left paren. For example, here is how a piece of continued code looks with -nIp in effect:
pI = first-procedure(second-procedure(p2, p3),
third-procedure(p4, p5»;
With -Ip in effect (the default) the code looks somewhat clearer:
pI = first-procedure(second-procedure(p2, p3),
third-procedure(p4, p5»;
Inserting a couple more newlines we get:
pI = first_procedure(second-procedure(p2,
p3) ,
third-procedure(p4,
p5) ) ;

-npro

Causes the profile files, 'J .indentpro' and '-/.indent.pro', to be ignored.

-pes ,-npes

If true (-pes) all procedure calls will have a space inserted between the name and the '(' .
The default is -npes

-psI, -npsl

If true (-psI) the names of procedures being defined are placed in column 1 - their types,
if any, will be left on the previous lines. The default is -psI

-se,-nse

Enables (disables) the placement of asterisks ('*'s) at the left edge of all comments.

-sob,-nsob

If -sob is specified, indent will swallow optional blank lines. You can use this to get rid
of blank lines after declarations. Default: -nsob

-st

Causes indent to take its input from stdin, and put its output to stdout

-Ttypename

Adds typename to the list of type keywords. Names accumulate: -T can be specified

Last change: 14 June 1985

Sun Release 3.2

INDENT ( 1)

USER COMMANDS

INDENT(1)

more than once. You need to specify all the typenames that appear in your program that
are defined by typedefs - nothing will be harmed if you miss a few, but the program
won't be formatted as nicely as it should. This sounds like a painful thing to have to do,
but it's really a symptom of a problem in C: typedef causes a syntactic change in the
laguage and indent can't find all typedefs.
-troff

Causes indent to format the program for processing by troff. It will produce a fancy
listing in much the same spirit as vgrind. If the output file is not specified, the default is
standard output, rather than formatting in place.
The usual way to get a troff'd listing is with the command
indent -troff program.c I troff -mindent

-v,-nv

-v turns on 'verbose' mode, -nv turns it off. When in verbose mode, indent reports
when it splits one line of input into two or more lines of output, and gives some size
statistics at completion. The default is -nv.

FURTHER DESCRIPTION
You may set up your own 'profile' of defaults to indent by creating a file called .indent.pro in either your
login directory or the current directory and including whatever switches you like. A '.indent.pro' in the
current directory takes precedence over the one in your login directory. If indent is run and a profile file
exists, then it is read to set up the program's defaults. Switches on the command line, though, always override profile switches. The switches should be separated by spaces, tabs or newlines.

Comments

'Box' comments. Indent assumes that any comment with a dash or star immediately after the start of comment (that is, '/*-' or '/**') is a comment surrounded by a box of stars. Each line of such a comment is
left unchanged, except that its indentation may be adjusted to account for the change in indentation of the
first line of the comment.
Straight text. All other comments are treated as straight text. Indent fits as many words (separated by
blanks, tabs, or newlines) on a line as possible. Blank lines break paragraphs.
Comment indentation
If a comment is on a line with code it is started in the 'comment column', which is set by the ---en command
line parameter. Otherwise, the comment is started at n indentation levels less than where code is currently
being placed, where n is specified by the -dn command line parameter. If the code on a line extends past
the comment column, the comment starts further to the right, and the right margin may be automatically
extended in extreme cases.

Preprocessor lines
In general, indent leaves preprocessor lines alone. The only reformmatting that it will do is to straighten up
trailing comments. It leaves imbedded comments alone. Conditional compilation (#ifdef••.#endif) is
recognized and indent attempts to correctly compensate for the syntactic peculiarites introduced.
C syntax

Indent understands a substantial amount about the syntax of C, but it has a 'forgiving' parser. It attempts to
cope with the usual sorts of incomplete and misformed syntax. In particular, the use of macros like:
*define forever for(;i)
is handled properly.
FILES
J .indent.pro
profile file
-/ .indent.pro
profile file
lusr/lib/tmac/tmac.indent Troff macro package for' 'indent -troff" output.

Sun Release 3.2

Last change: 14 June 1985

207

INDENT(l)

USER COMMANDS

INDENT(l)

BUGS
Indent has even more switches than Is.
A common mistake that often causes grief is typing:
indent *.c
to the shell in an attempt to indent all the C programs in a directory. This is probably a bug, not a feature.
The -bs option splits an excessivly fine hair.

208

Last change: 14 June 1985

Sun Release 3.2

INDXBIB (1)

USER COMMANDS

INDXBIB (1)

NAME

indxbib - make inverted index to a bibliography
SYNOPSIS
indxbib database . ..
DESCRIPTION

Indxbib makes an inverted index to the named databases (or files) for use by lookbib(l) and refer(l).
These files contain bibliographic references (or other kinds of information) separated by blank lines.
A bibliographic reference is a set of lines, constituting fields of bibliographic information. Each field starts
on a line beginning with a "%", followed by a key-letter, then a blank, and finally the contents of the field,
which may continue until the next line starting with "%".

Indxbib is a shell script that calls two programs: lusrl/iblrefer/mkey and /usrlliblreJerlinv. mkey truncates
words to 6 characters, and maps upper case to lower case. It also discards words shorter than 3 characters,
words among the 100 most common English words, and numbers (dates) < 1900 or> 2000. These parameters can be changed - see ReJer- a Bibliography System in Formatting Documents on the Sun Workstation. inv creates an entry file (.ia), a posting file (.ib), and a tag file (.ic), all in the working directory.
FILES

x .ia, x .ib, x .ic, where x is the first argument, or if these are not present, then x .ig, x
SEE ALSO
refer(l), addbib(l), sortbib(l), roftbib(l), lookbib(l)

Refer in Formatting Documents on the Sun Workstation
BUGS

Probably all dates should be indexed, since many disciplines refer to literature written in the 1800s or earlier.

S un Release 3.2

Last change: 6 April 1985

209

USER COMMANDS

NAME

input_from_defaults, defaults_from_input - update kernel state from defaults database, and vice versa
SYNOPSIS

input_from_defaults
defaults_from_ in put
DESCRIPTION

Input_from_defaults updates various parameters controlling mouse- and keyboard-processing on the
machine on which it is run. It should be used on systems which are running the SunView window system.
The parameters control the distribution of function keys on the keyboard, the assignment of buttons on the
mouse, the scaling of mouse-to-cursor motion, and the effect of two filters on mouse-motion originally provided to compensate for defective mice. The new values are taken from the defaults datbase, starting with
the file .defaults in the user's home directory.
Defaults_ from_input is the inverse operation to input_from_defaults - it updates a the user's private
defaults database (used by defaultsedit(l» to reflect the current state of kernel input parameters listed
above.
FILES

$HOME/.defaults
lusr/lib/defaults/* .d
SEE ALSO

defaultsedit( 1)
Editing and the Text Facility, in Windows and Window-Based Tools, Beginner's Guide
BUGS

Input_from_defaults should be targetable to any user's .defaults file.

210

Last change: 29 April 1986

Sun Release 3.2

INSTALL ( 1)

USER COMMANDS

INSTALL(l)

NAME

install- install files
SYNOPSIS

install [ -c] [ -m mode ] [ -0 owner] [ -g group] [ -s ] binary destination
DESCRIPTION

binary is copied to destination. If destination already exists, it is removed before binary is copied. If the
destination is a directory then binary is copied into file destination/binary.
install refuses to move a file onto itself.

Note: install has no special privileges since it simply uses cp to copy files from one place to another. The
implications of this are:
• You must have permission to read binary .
• You must have permission to copy into destination.
• You must have permission to change the modes on the final copy of the file if you want to use the -m
option to change modes.
• You must be super-user if you want to use the -0 option to change ownership.
OPTIONS

-c

Copy binary instead of moving it. In fact, install always copies the file, but the -c option is
retained for backwards compatibility with old system shell scripts which might otherwise break.

-mmode
Specifies a different mode for binary: the mode for destination is set to 755 by default.
-0

owner
Set the owner of the destination file to owner. destination is changed to owner root by default.

-g group
Set the group ownership of the destination file to group. destination is changed to group staffby
default.

-s

Strip binary files after it is installed -

only applicable to binary files in a.out(5) format.

SEE ALSO

chmod(l V), cp(l), mv(l), strip(l), chown(8)
BUGS

Should be possible to move multiple files at a time, like mv or cp.
When the destination is a directory, install simply appends the entire source file name to the directory
name, instead of using the source file name's last component like mv or cp.

Sun Release 3.2

Last change: 23 September 1985

211

IPCRM( 1)

USER COMMANDS

IPCRM(l )

NAME

ipcrm - remove a message queue, semaphore set, or shared memory id
SYNOPSIS

ipcrm [primitives]
DESCRIPTION
ipcrm removes one or several messages, semaphores, or shared memory identifiers, as specified by the following primitives:

-q msqid

removes the message queue identifier msqid from the system and destroys the message
queue and data structures associated with it

-m shmid

removes the shared memory identifier shmid from the system. The shared memory segment
and data structures associated with it are destroyed after the last detach.

-s semid

removes the semaphore identifier semid from the system and destroys the set of semaphores
and data structures associated with it.

-Q msgkey

removes the message queue identifier, created with key msgkey, from the system and destroys the message queue and data structures associated with it

-M shmkey

removes the shared memory identifier, created with key shmkey, from the system. The
shared memory segment and data structures associated with it are destroyed after the last
detach.

-8 semkey

removes the semaphore identifier, created with key semkey, from the system and destroys
the set of semaphores and data structures associated with it.

The identifiers and keys may be found by using ipcs(l).
The details of removing identifiers are described in msgctl(2), shmctl(2), and semctl(2) in the sections
detailing the IPC_RMID command.
SEE ALSO
ipcs(I), msgct1(2), msgget(2), semctl(2), semget(2), shmct1(2), shmget(2)

212

Last change: 30 April 1986

Sun Release 3.2

IPCS( 1)

USER COMMANDS

IPCS(1 }

NAME

ipcs - report interprocess communication facilities status
SYNOPSIS

ipcs [primitives]
DESCRIPTION
ipcs prints information about active interprocess communication facilities as specified by the primitives
shown below. If no primitives are given, information is printed in short format for message queues, shared

memory, and semaphores that are currently active in the system.

-q

Print information about active message queues.

-ID

Print information about active shared memory segments.

-s

Print information about active semaphores.

If any of the primitives -q, -ID, or -s are specified, information about only indicated facilities is printed. If
none of these are specified, information about all three is printed.
-b

Print the biggest allowable size information. (Maximum number of bytes in messages on queue
for message queues, size of segments for shared memory, and number of semaphores in each set
for semaphores.) See below for the meaning of columns in a listing.

-c

Print creator's login name and group name. See below.

-0

Print information on outstanding usage. (Number of messages on queue and total number of bytes
in messages on queue for message queues and number of processes attached to shared memory
segments.)

-p

Print process number information. (Process ID of last process to send a message and process ID of
last process to receive a message on message queues and process ID of creating process and process ID of last process to attach or detach on shared memory segments) See below.

-t

Print time information. (Time of the last control operation that changed the access permissions for
all facilities. Time of last msgsnd(2) and last msgrcv(2} on message queues, last shmat(2) and
last shmdt(2} on shared memory, last semop(2} on semaphores.} See below.

-3

Use all display primitive s. (This is a shorthand notation for -b, -c, -0, -p, and -t.)

-C corefile
Use the file corefile in place of Idevlkmem.

-N name list
The argument will be taken as the name of an alternate namelist (/vmunix is the default).
The column headings and the meaning of the columns in an ipcs listing are given below; the letters in
parentheses indicate the primitives that cause the corresponding heading to appear; all means that the heading always appears. Note that these primitives only determine what information is provided for each facility; they do not determine which facilities will be listed.
T

ID

KEY

MODE

Sun Release 3.2

(all) Type of the facility:
q
message queue;
m
shared memory segment;
s
semaphore.
(all) The identifier for the facility entry.
(all) The key used as an argument to msgget(2}, semget(2), or shmget(2) to create the facility entry. (Note: The key of a shared memory segment is changed to IPC _PRIVATE
when the segment has been removed until all processes attached to the segment detach
it.)
(all) The facility access modes and flags: The mode consists of 11 characters that are interpreted as follows:
The first two characters are:

Last change: 30 April 1986

213

IPCS( 1)

USER COMMANDS

R
S
D
C

IPCS (1)

if a process is waiting on a msgrcv(2);
if a process is waiting on a msgsnd(2);
if the associated shared memory segment has been removed. It will
disappear when the last process attached to the segment detaches it;
if the associated shared memory segment is to be cleared when the first
attach is executed;
if the corresponding special flag is not set.

The next 9 characters are interpreted as three sets of three bits each. The first
set refers to the owner's permissions; the next to permissions of others in the
user-group of the facility entry; and the last to all others. Within each set, the
first character indicates permission to read, the second character indicates permission to write or alter the facility entry, and the last character is currently
unused

OWNER
GROUP
CREATOR
CGROUP
CBYTES

(all)
(all)
(a,c)
(a,c)
(a,o)

QNUM
QBYTES

(a,o)
(a,b)

LSPID
LRPID
STIME
RTIME
CTIME
NATTCH
SEGSZ
CPID
LPID
ATIME
DTIME
NSEMS
OTIME

(a,p)
(a,p)
(a,t)
(a,t)
(a,t)
(a,o)
(a,b)
(a,p)
(a,p)
(a,t)
(a,t)
(a,b)
(a,t)

The permissions are indicated as follows:
r
if read permission is granted;
w
if write permission is granted;
if alter permission is granted;
a
if the indicated permission is not granted
The login name of the owner of the facility entry.
The group name of the group of the owner of the facility entry.
The login name of the creator of the facility entry.
The group name of the group of the creator of the facility entry.
The number of bytes in messages currently outstanding on the associated message
queue.
The number of messages currently outstanding on the associated message queue.
The maximum number of bytes allowed in messages outstanding on the associated
message queue.
The process ID of the last process to send a message to the associated queue.
The process ID of the last process to receive a message from the associated queue.
The time the last message was sent to the associated queue.
The time the last message was received from the associated queue.
The time when the associated entry was created or changed.
The number of processes attached to the associated shared memory segment.
The size of the associated shared memory segment.
The process ID of the creator of the shared memory entry.
The process ID of the last process to attach or detach the shared memory segment.
The time the last attach was completed to the associated shared memory segment.
The time the last detach was completed on the associated shared memory segment.
The number of semaphores in the set associated with the semaphore entry.
The time the last semaphore operation was completed on the set associated with the
semaphore entry.

FILES
Ivrnunix

system namelist
memory
letc/passwd user names
letc/group group names

Idev~mem

SEE ALSO

msgop(2), semop(2), shmop(2)

BUGS
Things can change while ipcs is running; the picture it gives is only a close approximation to reality.

214

Last change: 30 April 1986

Sun Release 3.2

JOIN (1)

USER COMMANDS

JOIN (1)

NAME

join - relational database operator
SYNOPSIS

join [ -an] [ -e string] [ -j [112] m ] [ -0 list] [ -tc ] filename 1 filename2
DESCRIPTION
join fonns, on the standard output, a join of the two relations specified by the lines of filenamel and
filename2. Iffilenamel is -t the standard input is used.

filenamel andfilename2 must be sorted in increasing ASCII collating sequence on the fields on which they
are to be joined - normally the first in each line.
There is one line in the output for each pair of lines in filenamel and filename2 that have identical join
fields. The output line normally consists of the common field, then the rest of the line fromfilenamel , then
the rest of the line fromfilename2.
The default input field separators are blank, tab t and newline. If the default input field separators are used,
multiple separators count as one field separatort and leading separators are ignored. The default output
field separator is a blank.
OPTIONS

-an

The parameter n can be one of the values:
1
produce a line for each unpairable line infilenamel .
2
produce a line for each unpairable line infilename2.
3
produce a line for each unpairable line in bothfilenamel andfilename2.
The normal output is also produced.
-e string
Replace empty output fields by string.
-j[lI2] m
The j may be immediately followed by n, which is either a '1' or a '2'. If n is missing, the join is
on the m'th field of both files. If n is present, the join is on the m'th field of file n, and the first
field of the other. Note that join counts fields from 1 instead of 0 like sort does.
-0 list Each output line comprises the fields specified in list, each element of which has the form n.m,
where n is a file number and m is a field number. The cornmon field is not printed unless
specifically requested. Note that join counts fields from 1 instead of 0 like sort does.
-tc
Use character c as a separator (tab character). Every appearance of c in a line is significant The
character c is used as the field separator for both input and output.
EXAMPLE
The following command line will join the password file and the group file, matching on the numeric group
ill, and outputting the login name, the group name and the login directory. It is assumed that the files have
been sorted in ASCII collating sequence on the group ID fields.
join -j 14 -j2 3 -0 1.1 2.1 1.6 -t: /etc/passwd /etc/group
SEE ALSO
sort(IV), comm(1), awk(I), uniq(I), look(1)
BUGS

With default field separationt the collating sequence is that of sort -b; with -t, the sequence is that of a
plain sort.
The conventions of join , sort, comm, uniq, look, and awk are wildly incongruous.
Filenames that are numeric may cause conflict when the -0 option is used right before listing filenames.

Sun Release 3.2

Last change: 17 February 1986

215

KILL(I)

USER COMMANDS

KILL ( 1)

NAME

kill- send a signal to a process, or terminate a process
SYNOPSIS
kill [ -sig ] processid
kill-I

0

0

0

DESCRIPTION
kill sends the TERM (terminate, 15) signal to the specified processes. If a signal name or number preceded
by '-' is given as first argument, that signal is sent instead of terminate. The signal names are listed by
using the -I option, and are as given in lusr/include/signal.h, stripped of the common SIG prefix.

The terminate signal will kill processes that do not catch the signal, so kill -9
is a sure kill, as the
KILL (9) signal cannot be caught. By convention, if process number 0 is specified, all members in the process group (that is, processes resulting from the current login) are signaled (but beware: this works only if
you use sh(I); not if you use csh(I).) Negative process numbers also have special meanings; see kill(2) for
details. The killed processes must belong to the current user unless he is the super-user.
0

••

To shut the system down and bring it up single user the super-user may send the initialization process a
TERM (terminate) signal by 'kill 1'; see init(8). To force init to close and open terminals according to
what is currently in letclttys use 'kill-HUP l' (sending a hangup, signal 1).
The shell reports the process number of an asynchronous process started with' &' (run in the background).
Process numbers can also be found by usingps(I).
kill is built in to csh(I); it allows job specifiers, such as kill %
for details.

o. 0, in place of kill arguments.

See csh(l)

OPTIONS

-I

Display a list of signal names.

SEE ALSO
csh(I), ps(I), kill(2), sigvec(2)

BUGS
A replacement for kill 0 for csh(l) users should be provided.

216

Last change: 17 July 1986

Sun Release 3.2

LAST ( 1)

USER COMMANDS

LAST ( 1)

NAME

last - indicate last logins of users and teletypes
SYNOPSIS

last [ -number] [ -f filename] [name ... ] [ tty ... ]
DESCRIPTION
last looks back in the wtmp file which records alllogins 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 ttyO'. 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. last displays
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, last 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 displays a record of alllogins and logouts, in reverse order.
If last is interrupted, it indicates how far the search has progressed in wtmp. If interrupted with a quit signal
(generated by a control-\) last indicates how far the search has progressed so far, and the search continues.
OPTIONS

-number
limit the number of entries displayed to that specified by number.
-ffilename
Use filename as the name of the accounting file instead of lusrladmlwtmp.
FILES

lusr/admlwtmp

login data base

SEE ALSO
utmp(5), ac(8), lastcomm(l)

Sun Release 3.2

Last change: 23 September 1985

217

LASTCOMM ( 1 )

USER COMMANDS

LASTCOMM ( 1 )

NAME

lastcomm - show last commands executed in reverse order
SYNOPSIS

lastcomm [command name] ... [user name] ... [terminal name] ...
DESCRIPTION
Lastcomm gives information on previously executed commands. Lastcomm with no arguments displays
information about all the commands recorded during the current accounting file's lifetime. If called with
arguments, lastcomm only displays accounting entries with a matching command name, user name, or terminalname.
EXAMPLES

tutorial% Iastcomm a.out root ttydO
would produce a listing of all the executions of commands named a.out, by user root while using the terminal ttydO. and
tutorial% Iastcomm root
would produce a listing of all the commands executed by user root.
For each process entry, lastcomm displays the following items of information:
The command name under which the process was called.
One or more flags indicating special information about the process. The flags have the following meanings:
F

The process performed afork but not an exec.

S

The process ran as a set-user-id program.

D The process dumped memory.
X The process was killed by some signal.
The name of the user who ran the process.
The terminal which the user was logged in on at the time (if applicable).
The amount of CPU time used by the process (in seconds).
The date and time the process exited.
FILES

lusr/admlacct

accounting file

SEE ALSO
last(I), acct(5), core(5)

218

Last change: 1 February 1985

Sun Release 3.2

LD(l )

USER COMMANDS

LD( 1)

NAME

ld - link editor
SYNOPSIS
Id [ -align datum] [ -A name] [ -d ] [ -D hex] [ -e entry] [ -Ix] [ -Ldir ] [ -M] [ -n ] [ -N ]
[ -0 name] [ -r ] [ -s ] [ -8 ] [ -t ] [ - T [text] hex] [ - Tdata hex] [ -u name] [ -x] [ -x ]
[ -ysym] [ -z ] filename ...

DESCRIPTION

ld combines several object programs into one, resolves external references, and searches libraries. In the
simplest case several objectfilenames are given, and ld combines them, producing an object module which
can either be executed or become the input for a subsequent ld run. In the latter case, the -r option must be
given to preserve the relocation bits. The output of ld is left on a file called a.out if not otherwise specified.
The output file is made executable only if no errors occurred during link editing.

Files specified by the argument filename ... are concatenated in the order specified. The entry point of the
output is the beginning of the first routine, unless the -e option is specified.
If a named file is a library, it is searched exactly once at the point it is encountered in the argument list.
Only those routines defining an unresolved external reference are loaded. If a routine from a library references another routine in the same library, and the library has not been processed by ranlib, the referenced
routine must appear after the referencing routine in the library. Thus the order of programs within libraries
may be important. The first member of a library should be a file named ' __.SYMDEF' , which is understood to be a dictionary for the library as produced by ranlib; the dictionary is searched iteratively to
satisfy as many references as possible.

The symbols _etext, _ edata and _end (etext, edata and end in C) are reserved, and if referred to, are set to
the first location above the program, the first location above initialized data, and the first location above all
data, respectively. It is erroneous to define these symbols.
OPTIONS

Options should appear before the filenames, except abbreviated library names specified by the -I option,
which can appear anywhere.
-align datum
datum (usually a FORTRAN common block) is increased in length to be a multiple of the page
size; its beginning is set at a page boundary.
-A name
Incremental loading: linking is to be done in a manner so that the resulting object may be read into
an already executing program. name is the name of a file whose symbol table is taken as a basis on
which to define additional symbols. Only newly linked material is entered into the text and data
portions of a.out, but the new symbol table will reflect all symbols defined before and after the
incremental load. This argument must appear before any other object file in the argument list.
One or both of the - T options may be used as well, and will be taken to mean that the newly
linked segment will commence at the corresponding addresses (which must be a multiple of the
page size). The default value is the old value of _end.

-d

Force definition of common storage even if the -r flag is present.

-D hex Pad the data segment with zero-valued bytes to make it hex bytes long.

-e entry
Define the entry point: the entry argument is made the name of the entry point of the loaded program.
-Ix

Sun Release 3.2

This option is an abbreviation for the library name Iibx.a, where x is a string. ld searches for
libraries first in any directories specified with -L options, then in the standard directories llib,
lusr/lib, and lusrlIocaIllib. A library is searched when its name is encountered, so the placement
of a -I is significant.

Last change: 17 July 1986

219

LD(I)

USER COMMANDS

LD(I)

-Ldir

Add dir to the list of directories in which libraries are searched for. Directories specified with-L
are searched before the standard directories rob, lusr/lib, and lusr/local/lib.

-M

Produce a primitive load map, listing the names of the files which will be loaded.

-0

Arrange (by giving the output file a 0410 'magic number') that when the output file is executed,
the text portion will be read-only and shared among all processes executing the file. This involves
moving the data areas up to the first possible segment boundary following the end of the text.

-N

Do not make the text portion read-only or sharable. (Use 'magic number' 0407.)

-0 name

Name is made the name of the ld output file, instead of a.out.
-r

Generate relocation bits in the output file so that it can be the subject of another ld run. This flag
also prevents final definitions from being given to common symbols, and suppresses the
'undefined symbol' diagnostics.

-s

Strip the output, that is, remove the symbol table and relocation bits to save space (but impair the
usefulness of the debuggers). This information can also be removed by strip(I).

-S

Strip the output by removing all symbols except locals and globals.

-t

Trace: display the name of each file as it is processed.

- T [ text] hex
Start the text segment at location hex. Specifying -Tis the same as using the - Ttext option.
-Tdata hex
Start the data segment at location hex. This option is only of use to programmers wishing to write
code for PROMs, since the resulting code cannot be executed by the UNIX system.

-uname
Enter name as an undefined symbol. This is useful for loading wholly from a library, since initially the symbol table is empty and an unresolved reference is needed to force the loading of the
first routine.
-x

Preserve only global (non- .globl) symbols in the output symbol table; only enter external symbols. This option saves some space in the output file.

-X

Record local symbols, except for those whose names begin with 'L'. This option is used by cc to
discard internally generated labels while retaining symbols local to routines.

-ysym Display each file in which sym appears, its type and whether the file defines or references it.
Many such options may be given to trace many symbols. It is usually necessary to begin sym with
an '_', as external C, FORTRAN and Pascal variables begin with underscores.

-z

Arrange for the process to be loaded on demand from the resulting executable file (0413 'magic
number') rather than preloaded. This is the default. Results in a (32-byte) header on the output
file followed by text and data segments, each of which has a multiple of page-size bytes (being
padded out with nulls in the file if necessary). With this format the first few BSS segment symbols
may actually end up in the data segment; this is to avoid wasting the space resulting from rounding the data segment size. The text is read-only and shared among all processes executing the file.

FILES

llib/lib* .a
lusr/lib/lib*.a
lusr/iocalllib/lib*.a
a.out

libraries
more libraries
still more libraries
output file

SEE ALSO
as(l), ar(l), cc(l V), ranlib(l), strip(l)

220

Last change: 17 July 1986

S un Release 3.2

LEAVE ( 1)

USER COMMANDS

LEAVE(I)

NAME

leave - remind you when you have to leave
SYNOPSIS

leave [[ + ]hhmm]
DESCRIPTION
leave sets an alarm to a time you specify and will tell you when the time is up. leave 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, and at the time. After the specified time, it reminds you every minute thereafter 10 more
times. leave disappears after you log off.
You can specify the time in on of two ways, namely as an absolute time of day in the form hhmm where hh
is a time in hours (on a 12 or 24 hour clock), or you can place a + sign in front of the time, in which case
the time is relative to the current time, that is, the specified number of hours and minutes from now. 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?". leave exits if you just type a
newline, otherwise the reply is assumed to be a time. This 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 and
its process id.
SEE ALSO

calendar( 1)
EXAMPLES

The first example sets the alarm to an absolute time of day:
manual% leave 1535
Alarm set for Wed Mar 7 15:35:07 1984
work work work work
manual% Time to leave!
The second example sets the alarm for 10 minutes in the future:
manual% leave +10
Alarm set for Wed Mar 7 15:45:24 1984
work work work work
manual% Time to leave!
work work work work
manual% You're going to be late!

Sun Release 3.2

Last change: 17 July 1986

221

LEX ( 1)

USER COMMANDS

LEX ( 1)

NAME

lex - generator of lexical analysis programs
SYNOPSIS

lex [ -tvro] [filename] ...
DESCRIPTION

lex generates programs to be used in simple lexical analyis of text. Each filename (standard input by
default) contains regular expressions to search for, and actions written in C to be executed when expressions are found.

A C source program, lex.yy.c is generated, to be compiled as follows:
cc lex.yy.c -11
This program, when run, copies unrecognized portions of the input to the output, and executes the associated C action for each regular expression that is recognized. The actual string matched is left in yytext, an
external character array.
Matching is done in order of the strings in the file. The strings may contain square braces to indicate character classes, as in [abx-z] to indicate a, b, X, y, and z; and the operators *, + and ?, which mean, respectively, any nonnegative number, any positive number, or either zero or one occurrences of the previous
character or character-class. The "dot" character (.) is the class of all ASCII characters except NEWLINE.
Parentheses for grouping and vertical bar for alternation are also supported. The notation r{d,e} in a rule
indicates instances of regular expression r. between d and e. It has a higher precedence than I, but lower
than that of *, ?, +, or concatenation. The carat character () at the beginning of an expression permits a
successful match only immediately after a NEWLINE, and the character $ at the end of an expression
requires a trailing NEWLINE.
The character I in an expression indicates trailing context; only the part of the expression up to the slash is
returned in yytext, although the remainder of the expression must follow in the input stream.
An operator character may be used as an ordinary symbol if it is within

n

symbols or preceded by \.

Three subroutines defined as macros are expected: inputO to read a character; nnput(c) to replace a character read; and output(c) to place an output character. They are defined in terms of the standard streams,
but you can override them. The program generated is named yylexO, and the library contains a maio()
which calls it. The action REJECT on the right side of the rule causes this match to be rejected and the next
suitable match executed; the function yymoreO accumulates additional characters into the same yytext; and
the function yyless(p) pushes back the portion of the string matched beginning at p, which should be
between yytext and yytext +yyleng. The macros input and output use files yyio and yyout to read from and
write to, defaulted to stdio and stdont, respectively.
In a lex program, any line beginning with a blank is assumed to contain only C text and is copied; if it precedes % % it is copied into the external definition area of the lex.yy.c file. All rules should follow a % %,
as in YACC. Lines preceding % % which begin with a nonblank character define the string on the left to be
the remainder of the line; it can be used later by surrounding it with {}. Note that curly brackets do not
imply parentheses; only string substitution is done.
The external names generated by lex all begin with the prefix yy or YY.
Certain table sizes for the resulting finite-state machine can be set in the definitions section:

222

%p n

number of positions is n (default 2000)

%0 n

number of states is n (500)

%t n

number of parse tree nodes is n (1000)

%a n

number of transitions is n (3000)

Last change: 23 July 1986

Sun Release 3.2

USER COMMANDS

LEXC 1)

LEXC 1)

The use of one or more of the above automatically implies the -v option, unless the -n option is used.
OPTIONS
-t

Place the result on the standard output instead of in file lex.yy.c.

-v
-n

Print a one-line summary of statistics of the generated analyzer.

-f

'Faster' compilation: don't bother to pack the resulting tables; limited to small programs.

Opposite of -v; -n is default.

EXAMPLES

lex lexcommands
would draw lex instructions from the file lexcommands, and place the output in lex.yy.c.
%%
[A-Z] putcharCyytext[O]+'a'-'A');
[]+$

;

[ ]+

putcharC' ');

is an example of a lex program. It converts upper case to lower, removes blanks at the end of lines, and
replaces multiple blanks by single blanks.
D
%%

if
[a-z] +
O{D}+
{D}+
"++"

"+"
"/*tI

[0-9]

printfCtlIF statement\n tl );
printf("tag, value %s\ntl ,yytext);
printf("octal number %s\ntl ,yytext);
printfCtldecimal number %s\ntl,yytext);
printf("unary op\ntl);
printfCtlbinary op\ntl);
{
loop:
while CinputO != '*');
switch CinputO)
{
case '/': break;
case '*': unputC'*');
default: go to loop;
}
}

SEE ALSO
yaccCl), sedCl V)

Lex - A Lexical Analyzer Generator, in Programming Utilities for the Sun Workstation.

Sun Release 3.2

Last change: 23 July 1986

223

LINE ( 1)

USER COMMANDS

LINE ( 1)

NAME

line - read one line
SYNOPSIS

line
DESCRIPTION

line copies one line (up to a newline) from the standard input and writes it on the standard output It
returns an exit code of 1 on EOF and always prints a newline at least. It is often used within shell scripts to
read from the user's terminal.
SEE ALSO

sh(I), read(2)

224

Last change: 21 February 1986

Sun Release 3.2

LINT ( IV)

USER COMMANDS

LINT ( IV)

NAME

lint - a C program verifier
SYNOPSIS
lint [ -abchinouvxz] [ -Dname [=def ] ] [ -D name] [ -U name ] [ -I dir] [ -0 outftle ] filename . ..
lint [ -Clib ] filename ...
SYSTEM V SYNOPSIS
/usrlSbin/Iint [ -abcghnpuvxzO ] [ -D name =def] [ -D name] [ -U name] [ -I dir] [ -0 lib ] filename
DESCRIPTION
lint attempts to detect features of the C programfiles that are likely to be bugs, non-portable, or wasteful.
lint also checks the type usage of the program more strictly than the C compiler. lint runs the C preprocessor as its first phase. The preprocessor symbol "lint" is defined, in order to allow certain questionable code
to be altered or removed for lint. Therefore, the symbol "lint" should be thought of as a reserved word for
all code that is planned to be checked by lint.

Among the things that are currently found are unreachable statements, loops not entered at the top,
automatic variables declared and not used, and logical expressions whose values are constant. Moreover,
the usage of functions is checked to find functions which return values in some places and not in others,
functions called with varying numbers of arguments, and functions whose values are not used.
Arguments whose names end with .c are taken to be C source files. Arguments whose names end with .In
are taken to be the result of an earlier invocation of lint with the -C option used. The.ln files are analogous to.o (object) files that are produced by the cc(lV) command when given a.c file as input.
lint will take all the .c,.In, and llib-Ix.In (specified by -Ix) files and process them in their command line
order. By default, lint appends the standard C lint library (llib-Ic.ln) to the end of the list of files. When
the -C option is not used, the second pass of lint checks this list of files for mutual compatibility. When
the -C option is used, the .In and the llib-Ix.ln files are ignored.

To create lint libraries, use the -C option. For example
tutorial% lint -Ccongress files ...
where files are the C sources of library congress, produces a file llib-lcongress .In in the current directory in
the correct library format suitable for lint'ing programs using -Icongress.
General Comments
The routine exit(2) and other functions which do not return are not understood; this causes various lies.

Certain conventional comments in the C source will change the behavior of lint:
/*NOTREACHED*/
at appropriate points stops comments about unreachable code. (This comment is typically placed
just after calls to functions like exit(2».
I*V ARARGSn*1
suppresses the usual checking for variable numbers of arguments in the following function
declaration. The data types of the first n arguments are checked; a missing n is taken to be O.
I*ARGSUSED*I
turns on the -v option for the next function.
1* LINTLIBRARY */
at the beginning of a file, shuts off complaints about unused functions and function arguments in
this file. This is equivalent to using the -v and -x options.
SYSTEM V DESCRIPTION
lint will take all the .c,.ln, and llib-Ix.In (specified by -Ix) files and process them in their command line
order. By default, lint appends the standard C lint library (llib-Ic.ln) to the end of the list of files. However, if the -p option is used, the portable C lint library (llib-port.In) is appended instead. When the -c

Sun Release 3.2

Last change: 17 July 1986

225

LINT ( IV)

USER COMMANDS

LINT ( IV)

option is not used, the second pass of lint checks this list of files for mutual compatibility. When the -c
option is used, the .In and the Ilib-lx.1n files are ignored.
Lint produces its first output on a per-source-file basis. Complaints regarding included files are collected
and printed after all source files have been processed. Finally, if the -c option is not used, information
gathered from all input files is collected and checked for consistency. At this point, if it is not clear
whether a complaint stems from a given source file or from one of its included files, the source file name
will be printed followed by a question mark.

The behavior of the -c and the -0 options allows for incremental use of lint on a set of C source files.
Generally, one invokes lint once for each source file with the -c option. Each of these invocations produces a .In file which corresponds to the .c file, and prints all messages that are about just that source file.
After all the source files have been separately run through lint, it is invoked once more (without the -c
option), listing all the .In files with the needed -Ix options. This will print all the inter-file inconsistencies.
This scheme works well with make (1); it allows make to be used to lint only the source files that have been
modified since the last time the set of source files were linted.
OPTIONS

-a

Report assignments of long values to variables that are not long.

-b

Report break statements that cannot be reached. This is not the default because, unfortunately,
most lex(l) and many yacc(l) outputs produce dozens of such messages.

-c

Complain about casts which have questionable portability.

-b

Apply a number of heuristic tests to attempt to intuit bugs, improve style, and reduce waste.

-i

Cause lint to produce a .In file for every .c file on the command line. These .In files are the product of lint's first pass only, and are not checked for compatibility between functions.

-n

Do not check compatibility against the standard library.

-u

Do not complain about functions and external variables used and not defined, or defined and not
used (this is suitable for running lint on a subset of files comprising part of a larger program).

-v

Suppress complaints about unused arguments in functions.

-x

Report variables referred to by extern declarations, but never used.

-z

Do not complain about structures that are never defined (for example, using a structure pointer
without knowing its contents).

-Dname=def

-Dname
Define name to the preprocessor, as if by '#define'. If no definition is given, the name is defined
as lit.
It

-Uname
Remove any initial definition of name in the preprocessor.
-Idir

'#include' files whose names do not begin with 'I' are always sought first in the directory of the
file argument, then in directories named in -I options, then in the lusrlinclude directory.

-ooutfile
Name the output file outfile. outfile cannot be the same as sourcefile (lint will not overwrite the
source file).
-CUb

create a lint library with name lib (see DESCRIPTION section).

-llib

use lint library lib from the lusrllibllint directory.

SYSTEM V OPTIONS
The sense of the -a, -b, -b, and -x options is reversed in the System V version of lint; the tests they control are performed unless the flag is specified. The -C option is not available; instead, the -c or -0 options
can be used.

226

Last change: 17 July 1986

Sun Release 3.2

LINT ( IV)

USER COMMANDS

LINT ( IV)

-p

Attempt to check portability to other dialects (IBM and GeOS) of C. Along with stricter checking,
this option causes all non-external names to be truncated to eight characters and all external names
to be truncated to six characters and one case.

-c

Cause lint to produce a .In file for every .c file on the command line. These .In files are the product of lint's first pass only, and are not checked for compatibility between functions.

-0

lib

Cause lint to create a lint library with the name IIib-llib .In. The -c option nullifies any use of the
option. The lint library produced is the input that is given to lint's second pass. The -0 option
simply causes this file to be saved in the named lint library. To produce a llib-llib.ln without
extraneous messages, use of the -x option is suggested. The -v option is useful if the source
file(s) for the lint library are just external interfaces (for example, the way the file llib-Ie is written). These option settings are also available through the use of "lint comments" (see below).

-0

-g
-0

These options are accepted but ignored. By recognizing these options, lint's behavior is closer to
that of the cc (1 V) command.

EXAMPLE

The following lint call:
tutorial% lint -b myfile.c
checks the consistency of the code in the C source file file myfile.c. The -b option indicates that unreachable break statements are to be checked for.
FILES

lusr/lib/lintllint[1 2]
lusr/lib/lintillib-l*.ln
lusr/lib/lintillib-l*
These libraries exist
-Itermeap.

programs
Various prebuilt lint libraries.
Sources of the prebuilt lint libraries.
for -Ie, -Ieore, -Ieurses, -1m, -Imp, -Ipixrect, -Isuntool, -Isunwindow, and

SYSTEM V FILES

lusr/5lib/lintllint[1 2]
programs
lusr/lib/5lintlllib-I*.1n Various prebuilt lint libraries.
Sources of the prebuilt lint libraries.
lusr/lib/5Iintlllib-l*
These libraries exist for -Ie, -1m, and -Iport.
SEE ALSO

cc(1 V), cpp(l)
Lint, a C Program Checker, in Programming Utilities/or the Sun Workstation

BUGS
There are some things you just can't get lint to shut up about.

Sun Release 3.2

Last change: 17 July 1986

227

LN( 1)

LN(l)

USER COMMANDS

NAME

In - make links
SYNOPSIS

In [ -f] [ -s ] filename [ linkname ]
In [ -f] [ -s ] filename . .. directory
DESCRIPTION

In assigns an additional name (directory entry), called a link, to a file or directory. Several links may be
assigned to a file at anyone time. The number of links does not affect other attributes such as size, protections, data, etc. There are two kinds of links: hard links and symbolic links.
A hard link, which is the default, can only be made to an existing file. Only the superuser can make a hard
link to a directory. To remove a file with more than one hard link, all such links (including the name by
which it was created) must be removed. Hard links may not span file systems.

In can also make symbolic links. A symbolic link contains the name of the file or directory to which it is
linked. The referenced file or directory is used when an open(2V) operation is performed on the link. A
stat on a symbolic link returns the linked-to file; an Istat(2) must be done to obtain information about the
link itself. The readlink(2) call may be used to read the contents of a symbolic link. Symbolic links may
span file systems and may refer to directories.
filename is the original name of the file or directory to be linked. linkname is the new name to be associated
with the file or filename. If linkname is omitted, the last component of the original pathname is used
directory is a directory in which to place the link. When a directory is specified, In uses the last component
of each original pathname as the name of each link.
OPTIONS

-f

Force a hard link to a directory, -

-s

Create symbolic links.

this option is only available to the superuser.

EXAMPLES

The commands below illustrate the effects of the different forms of the In command.
See what files we've got
tutorial% Is -F
grab
jones/
See what files there are in jones
tutorial% Is -F jones
One file
house
try to link a file in the same directory
tutorial% In grab
Sorry - can't link a file to itself
Jgrab: File exists
link a file from another directory to here
tutorial% In joneslhouse
tutorial % Is -F
grab
house jones/
link afile to another name in this directory
tutorial% In grab hold
tutorial% Is -F
grab
hold
house jones/
link files from here to jones
tutorial% In grab hold jones
tutorial% Is -F jones
grab
hold
house
tutorial%
SEE ALSO

rm(I), cp(I), mv(I), link(2), readlink(2), stat(2), symlink(2), Istat(2)

228

Last change: 23 September 1985

Sun Release 3.2

LOCKSCREEN ( 1 )

USER COMMANDS

LOCKSCREEN ( 1 )

NAME

lockscreen, lockscreen_default - maintain window context, prevent unauthorized access and reduce phosphorbum.
SYNOPSIS

lockscreen [ -b program] [ -e] [ -0] [ -r] [ -t seconds] [gfx-program] [gfx-program-args]
DESCRIPTION
Lockscreen is a standard tool provided under the SunView environment that preserves the current state of
the display while the machine is not in use. When run, the display is cleared to black and the gfx-program
is run. It is assumed that the gfx-pro gram will provide moving graphics to limit phosphor bum of the video

display that might otherwise occur from leaving the same static window configuration displayed for a long
time. If no gfx-program is provided, a suitable default program is run.
Lockscreen prevents unauthorized access by requiring the user's password before restoring the window
context. When any keyboard or mouse button is pressed, the graphics screen is replaced by a password
screen that displays the user name, a small box with a bouncing logo, and a prompt for the user's password.
If the user has no password, or if the -0 option is used, the user's window context is immediately restored.

When the password screen appears:
1)

Restore the window context by entering the user's password followed by a carriage return (this
password is not echoed on the screen) or,

2)

Point to the black box and click the left button to return to the graphics display.

If neither of the above actions is taken, gfxyrogram will resume execution after the interval specified with
the -t option, as described below.
OPTIONS
-b program

Allow an additional program to be run as a child process of lockscreen. This background process
could be a compile server or some other useful program that the user wants run while lockscreen
is running. No arguments are passed to this program.
-e

Add the Exit Desktop choice to the password screen. If pointed to and clicked, the SunView
environment is exited and the current user is logged out.

-n

Require no password to reenter the window environment.

-r

Allow the use of the user name root in the Name: field of the password screen. Normally, root is
not accepted as a valid user name.

-t seconds

After seconds seconds, clear the password screen and restart the gfx-prograrn. The default is 5
minutes (300 seconds).
[ gfx-program] [ gfx-program-args ]
Run this program after clearing the screen to black. If no pro gram argument is present, lockscreen will try to run lockscreen_default if it exists on the standard search path, otherwise a
bouncing Sun logo will appear. If gfx-program-args are specified and the gfx-program isn't then
the args are passed to lockscreen_default. Lockscreen_default is typically a life program displaying the successive generations. Lockscreen will not search for lockscreen_default if the gfxprogram is specified explicitly as ''''.
FILES

lusrlbinllockscreen_default
The default gfx-program. If a file named lockscreen_defaUlt appears earlier in the
search path, that file is used instead.
SEE ALSO

suntools(l),login(l)

Sun Release 3.2

Last change: 16 June 1986

229

LOCKSCREEN ( 1 )

USER COMMANDS

LOCKSCREEN ( 1 )

NAME

login - sign on
SYNOPSIS
login [ username ]
DESCRIPTION
login signs username on to the system initially; login may also be used at any time to change from one
userid to another.

When used with no argument, login requests a user name and password (if appropriate). Echoing is turned
off (if possible) while typing the password.
When successful, login updates accounting files, informs you of the existence of any mail, prints the message of the day, and displays the time you last logged in (unless you have a .hushlogin file in your home
directory - mainly used by nonhuman users, such as uucp).

login initializes the user and group IDs and the working directory, then starts a command interpreter shell
(usually either Ibinlsh or Ibinlcsh according to specifications found in the file letclpasswd. (Argument 0 of
the command interpreter is "-sh", or more generally, the name of the command interpreter with a leading
dash ("-") prepended.)
login also initializes the environment with information specifying home directory, command interpreter,
terminal-type (if available) and username.
If the file letclnologin exists, login prints its contents on the user's terminal and exits. This is used by shutdown(8) to stop log ins when the system is about to go down.
The login command, recognized by sh and csh, is executed directly (without forking), and terminates that
shell. To resume working, you must log in.

login times out and exits if its prompt for input is not answered within a reasonable time.
When the Bourne shell (sh) starts up, it reads a file called .profile from your home directory (that of the
usemame you use to log in). When the C-Shell (csh) starts up, it reads a file called .cshrc from your home
directory, and then reads a file called .login.
The shells read these files only if they are owned by the person logging in.
FILES

accounting
accounting
time of last login
terminal types
quota check
mail
message-of-the-day
password file
stop login, print message
makes login quieter

letclutmp
lusrladmlwtmp
lusrladmllastlog
lusrlttytype
lusrlucblquota
Iusrlspool!maill*
letclmotd
letclpasswd
letclnologin
-I.hushlo gin

SEE ALSO
init(8), getty(8), mail(l), passwd(l), passwd(5), environ(5V), shutdown(8), utmp(5)
DIAGNOSTICS
"Login incorrect," if the name or the password is bad (or mistyped).
"No Shell", "cannot open password file", "no directory": ask your system administrator for assistance.

230

Last change: 12 June 1986

Sun Release 3.2

LOGNAME(l)

USER COMMANDS

LOGNAME(l)

NAME

logname - get login name
SYNOPSIS

iogname
DESCRIPTION
logname returns the contents of the environment variable LOGNAME, which is set when a user logs into the
system.
FILES

/ etc/profile
SEE ALSO
env(l), login(I), environ(5V)

Sun Release 3.2

Last change:

231

LOOK ( 1)

USER COMMANDS

LOOK ( 1)

NAME

look - find lines in a sorted list or words in the system dictionary
SYNOPSIS

look [ -dr] string [ file]
DESCRIPTION
Look consults a sortedfile and prints all lines that begin with string.
OPTIONS
-d

-f

'Dictionary' order: only letters, digits, tabs and blanks participate in comparisons.
Fold: Upper case letters compare equal to lower case.

If no file is specified, look uses lusrldictlwords with collating sequence -dr.
FILES

lusr/diet/words
SEE ALSO
sort(1 V), grep(1 V)

232

Last change: 13 April 1983

Sun Release 3.2

LOOKBID(l)

USER COMMANDS

LOOKBIB(l)

NAME

lookbib - find references in a bibliography
SYNOPSIS
lookbib database
DESCRIPTION
A bibliographic reference is a set of lines, constituting fields of bibliographic information. Each field starts
on a line beginning with a "%", followed by a key-letter, then a blank, and finally the contents of the field,
which may continue until the next line starting with' '%" .

Lookbib uses an inverted index made by indxbib to find sets of bibliographic references. It reads keywords
typed after the ">" prompt on the terminal, and retrieves records containing all these keywords. If nothing
matches, nothing is returned except another ">" prompt.
It is possible to search multiple databases, as long as they have a common index made by indxbib. In that
case, only the first argument given to indxbib is specified to lookbib.
If lookbib does not find the index files (the .i[abc] files), it looks for a reference file with the same name as
the argument, without the suffixes. It creates a file with a '.ig' suffix, suitable for use withfgrep. Lookbib
then uses this fgrep file to find references. This method is simpler to use, but the .ig file is slower to use
than the .i[abc] files, and does not allow the use of multiple reference files.
FILES

x.ia, x.ib, x.ic, where x is the first argument, or if these are not present, then x.ig, x
SEE ALSO
refer(l), addbib(l), sortbib(l), roffbib(l), indxbib(l)

Refer in Formatting Documents on the Sun Workstation
BUGS

Probably all dates should be indexed, since many disciplines refer to literature written in the 1800s or earlier.

Sun Release 3.2

Last change: 6 April 1985

233

LORDER( 1)

USER COMMANDS

LORDER(I)

NAME

lorder - find ordering relation for an object library
SYNOPSIS

lorder file •••
DESCRIPTION

Give lorder one or more object or library archive (see ar(l» files, and it lists pairs of object file namesmeaning that the first file of the pair refers to external identifiers defined in the second - to the standard
output. Lorder's output may be processed by tsort(l) to find an ordering of a library suitable for one-pass
access by ld(l).
EXAMPLE

This brash one-liner intends to build a new library from existing.o files.
ar cr library . . lorder *.0 I tsort'
The ranlib(I), command converts an ordered archive into a randomly accessed library and makes lorder
unnecessary .
SEE ALSO

tsort(I), Id(I), ar(I), ranlib(l)

BUGS
The names of object files, in and out of libraries, must end with '.0'; otherwise, nonsense results.

234

Last change: 11 November 1983

Sun Release 3.2

USER COMMANDS

LPQ( 1)

LPQ( 1)

NAME

lpq - spool queue examination program
SYNOPSIS

Ipq [ + [ num ] ] [ -I] [ -Pprinter ] [job # ... ] [ user . .. ]
DESCRIPTION
lpq examines the spooling area used by lpd (8) for printing files on the line printer, and reports the status of

the specified jobs or all jobs associated with a user.
Ipq reports on any jobs currently in the queue when invoked without any options. Arguments supplied that
are not recognized as options are interpreted as user names or job numbers to filter out only those jobs of
interest.

For each job submitted (that is, each invocation of Ipr) Ipq reports the user's name, current rank in the
queue, the names of files comprising the job, the job identifier (a number which may be supplied to lprm
for removing a specific job), and the total size in bytes. Normally, only as much information as will fit on
one line is displayed. Job ordering is dependent on the algorithm used to scan the spooling directory and is
supposed to be FIFO (First in First Out). File names comprising a job may be unavailable (when Ipr is
used as a sink in a pipeline) in which case the file is indicated as '(standard input)'.
If lpq warns that there is no daemon present (that is, due to some malfunction), the lpe(8) command can be
used to restart the printer daemon.
OPTIONS
-Pprinter report the state of the queue to the specified printer. In the absence of the -P option, the queue
to the printer specified by the PRINTER variable in the environment is reported on. If the PRINTER variable

isn't set, the default line printer queue is reported.
-Ijob # ...

causes information about each of the files comprising the job to be printed.
+nnn

display the spool queue until it empties. Supplying a number nnn immediately after the + sign
indicates that lpq should sleep nnn seconds in between scans of the queue.

FILES

letc/termcap
letclprintcap
lusrlspooll*
lusrlspooll*/cf*
lusrlspooll *flock

for manipulating the screen for repeated display
to determine printer characteristics
the spooling directory, as determined from printcap
control files specifying jobs
the lock file to obtain the currently active job

SEE ALSO

Ipr(l), Iprm(l), Ipc(8), Ipd(8)
BUGS

The + option doesn't wait until the entire queue is empty; it only waits until the local machine's queue is
empty.
Ipq may report unreliably. The status, as reported, may not always reflect the actual state of the printer.

Output formatting is sensitive to tl-te line length of the terminal; this can result in widely-spaced columns.
Ipq is sometimes unable to open various files because the lock file is malformed.
DIAGNOSTICS

Waiting for printer to become ready (offline ?)
The daemon could not open the printer device. This can happen for a number of reasons; the most
common is that the printer is turned off-line. This message can also be generated if the printer is
out of paper, the paper is jammed, and so on. The actual reason is dependent on the meaning of
error codes returned by system device driver. Not all printers supply sufficient information to distinguish when a printer is off-line or having trouble (for example, a printer connected through a

Sun Release 3.2

Last change: 23 September 1985

235

LPQ( 1)

USER COMMANDS

LPQ(l)

serial line). Another possible cause of this message is some other process, such as an output filter,
has an exclusive open on the device. Your only recourse here is to kill off the offending
program(s) and restart the printer with lpc.

printer is ready and printing
The lpq program checks to see if a daemon process exists for printer and prints the file status. If
the daemon is hung, a super user can use lpc to abort the current daemon and start a new one.

waiting for host to come up
Indicates that there is a daemon trying to connect to the remote machine named host in order to
send the files in the local queue. If the remote machine is up, lpd on the remote machine is probably dead or hung and should be restarted as mentioned for lpr.

sending to host
The files should be in the process of being transferred to the remote host. If not, the local daemon
should be aborted and started with lpc.
Warning: printer is down
The printer has been marked as being unavailable with lpc.

Warning: no daemon present
The lpd process overseeing the spooling queue, as indicated in the "lock" file in that directory,
does not exist. This normally occurs only when the daemon has unexpectedly died. The error log
file for the printer should be checked for a diagnostic from the deceased process. To restart an
lpd, use

% /usr/etc/lpc restart printer

236

Last change: 23 September 1985

Sun Release 3.2

LPR( 1)

USER COMMANDS

LPR( 1)

NAME

lpr - off-line print
SYNOPSIS
Ipr [ -Pprinter] [ -#num ] [ -Cclass] [ - Jjob ] [ - Ttitle] [ -i [ num] ] [ -1234font]
[-wnum] [ -r ] [ -m] [ -b] [ -s] [ -filter-option] [filename ... ]
DESCRIPTION
lpr uses a spooling daemon to print the named files when facilities become available. lpr reads the stndard
input if no files are specified.
OPTIONS

-Pprinter
Force output to the named printer. Normally, the default printer is used (site dependent), or the
value of the PRINTER environment variable is used.
-#num Produce multiple copies of output, using num as the number of copies for each file named. For
example,
tutorial% Ipr -#3 new.index.c print.index.c more.c
produces three copies of the file new .index.c , followed by three copies of print .index.c , etc. On the other
hand,
tutorial% cat new.index.c print.index.c more.c Ilpr-#3
generates three copies of the concatenation of the files.
-C

Print class as the job classification on the burst page. For example,
tutorial% Ipr -C Operations new.index.c
replaces the system name (the name returned by hostname) with 'Operations' on the burst page,
and prints the file new Jndex.c .

-Jjob

Print job as the job name on the burst page. Normally, Ipr uses the first file's name.

- Ttitle Use title instead of the file name for the title used by pr.
-i[num] Indent output num spaces. If num is not given, eight spaces are used as default
-I font

-2font
-3 font
-4 font Mount the specified font on font position I, 2, 3 or 4. The daemon will construct a .railmag file in
the spool directory that indicates the mount by referencing lusrlliblvfontlfont.
-wnum Use num as the page width for pr.
-r

Remove the file upon completion of spooling.

-m

Send mail upon completion.

-b

Suppress printing the burst page.

-s

Create a symbolic link from the spool area to the data files rather than trying to copy them (so
large files can be printed). This means the data files should not be modified or removed until they
have been printed. In the absence of this option, files larger than 1 Megabyte in length are truncated. Note that the -s option only works on the local host (files sent to remote printer hosts are
copied anyway), and only with named data files - it doesn't work if Ipr is at the end of a pipeline.

filter-option
The following single letter options notify the line printer spooler that the files are not standard text
files. The spooling daemon will use the appropriate filters to print the data accordingly.
-p
-I
-t
-n

Sun Release 3.2

Use pr to format the files (lpr -p is very much like pr Ilpr).
Print control characters and suppress page breaks.
The files contain troff(cat phototypesetter) binary data.
The files contain data from ditroff(device independent troft).

Last change: 30 July 1986

237

LPR( 1)

USER COMMANDS

-d
-g
-v
-c
-f

LPR( 1)

The files contain data from tex (DVI fonnat from Stanford).
The files contain standard plot data as produced by the plot(3X) routines (see also
plot(lG) for the filters used by the printer spooler).
The files contain a raster image, see rasterfile(5).
This option currently is unassigned.
Interpret the first character of each line as a standard FORTRAN carriage control character.

If no filter-option is given, '%!' as the first two characters indicates that the file contains
Postscript commands.
FILES

/etc/passwd
/ etclprintcap
/usr/lib/lpd*
/usr/spooll*
/usr/spooll*/cf*
/usr/spooll*/df*
/usr/spooll*/tf*

personal identification
printer capabilities data base
line printer daemons
directories used for spooling
daemon control files
data files specified in "cf' files
temporary copies of "cf' files

SEE ALSO

lpq(l), lprm(l), pr(lV), printcap(5), Ipc(8), Ipd(8), rasterfile(5), screendump(l)
DIAGNOSTICS

lpr: copy file is too large
A file is determined to be too 'large' to print by copying into the spool area. Use the -s option as
defined above to make a symbolic link to the file instead of copying it. A 'large' file is approximately 1 Megabyte in this system.
Ipr: printer: unknown printer
The printer was not found in the printcap database. Usually this is a typing mistake; however, it
may indicate a missing or incorrect entry in the /etclprintcap file.
Ipr: printer: jobs queued, but cannot start daemon.
The connection to lpd on the local machine failed. This usually means the printer server started at
boot time has died or is hung. Check the local socket Idev/printer to be sure it still exists (if it
does not exist, there is no lpd process running).
lpr: printer: printer queue is disabled
This means the queue was turned off with
tutorial% lusr/etclIpc disable printer
to prevent lpr from putting files in the queue. This is nonnally done by the system manager when a printer
is going to be down for a long time. The printer can be turned back on by a super-user with lpc.
If the -f and -s flags are combined as follows:

Ipr -fs filename
copies the file to the spooling directory rather than making a symbolic link.
Placing the -s flag first, or writing each as separate arguments makes a link as expected.
BUGS

Ipr -p is not equivalent to pr Ilpr. Ipr -p puts the current date at the top of each page, rather than the date
last modified, and inserts a header page between each file printed.
The -p and -# options don't work well together; the second and subsequent copies do not include the file
name in each page's title.
Fonts for troff and tex reside on the host with the printer. It is currently not possible to use local font
libraries.

238

Last change: 30 July 1986

Sun Release 3.2

LPRM( 1)

USER COMMANDS

LPRM(I)

NAME

lprm - remove jobs from the line printer spooling queue
SYNOPSIS

Iprm [ -Pprinter ] [ - ] [job # ... ] [ username ... ]
DESCRIPTION
lprm removes a job, or jobs, from a printer's spool queue. Since the spooling directory is protected from
users, using lprm is normally the only method by which a user may remove ajob.

lprm without any arguments will delete the currently active job if it is owned by the user who invoked
lprm.
If the - flag is specified, lprm will remove all jobs which a user owns. If the super-user employs this flag,
the spool queue will be emptied entirely. The owner is determined by the user's login name and host name
on the machine where the lpr command was invoked.

Specifying a user's name, or list of user names, will cause lprm to attempt to remove any jobs queued
belonging to that user (or users). This form of invoking lprm is useful only to the super-user.
A user may dequeue an individual job by specifying its job number. This number may be obtained from
lpq. For example:
tutorial% Ipq -Pimagen
imagen is ready and printing
Rank Owner Job Files
active wendy 385 standard input
tutorial% Iprm -Pimagen 385

Total Size
35501 bytes

lprm announces the names of any files it removes and is silent if there are no jobs in the queue which match
the request list.
lprm will kill off an active daemon, if necessary, before removing any spooling files. If a daemon is killed,
a new one is automatically restarted upon completion of file removals.
The -P option may be used to specify the queue associated with a specific printer (otherwise the default
printer, or the value of the PRINTER variable in the environment is used).
FILES

letc/printcap
printer characteristics file
lusrlspooll*
spooling directories
lusrlspooll*/lock lock file used to obtain the pid of the current
daemon and the job number of the currently active job
SEE ALSO
Ipr(I), Ipq(1), Ipd(8)
DIAGNOSTICS

Iprm: printer: cannot restart printer daemon
The connection to lpd on the local machine failed. This usually means the printer server started at
boot time has died or is hung. Check the local socket !dev/printer to be sure it still exists (if it
does not exist, there is no lpd process running). Use
tutorial% ps ax I fgrep Ipd
to get a list of process identifiers of running lpd's. The lpd to kill is the one which is not listed in
any of the "lock" files (the lock file is contained in the spool directory of each printer). Kill the
master daemon using the following commands:
tutorial% su Password:
tutorial# kill pid

Sun Release 3.2

Last change: 23 September 1985

239

LPRM( 1)

USER COMMANDS

LPRM(I)

Then remove Idevlprinter and restart the daemon (and printer) with the following commands.
tutorial# rm /dev/printer
tutorial# /usr/lib/lpd
Another possibility is that the lpr program is not setuid root, setgid daemon. This can be checked
with
tutorial# Is -Ig /usr/ucblIpr

BUGS
Since there are race conditions possible in the update of the lock file, the currently active job may be
incorrectly identified.

240

Last change: 23 September 1985

Sun Release 3.2

LS( IV)

USER COMMANDS

LS( IV)

NAME

Is - list contents of directory
SYNOPSIS

Is [ -acdfgilqrstulACLFR ] filename . ..
SYSTEM V SYNOPSIS

/usr/5binlls [ -abcdfgilmnopqrstuxCLFR ] filename . ..
DESCRIPTION

For each filename which is a directory, Is lists the contents of the directory; for each filename which is a
file, Is repeats its name and any other information requested. By default, the output is sorted alphabetically.
When no argument is given, the current directory is listed. When several arguments are given, the arguments are first sorted appropriately, but file arguments are processed before directories and their contents.
In order to determine output formats for the -C, -x, and -m options, /usr/5binlls uses an environment variable, COLUMNS, to determine the number of character positions available on one output line. If this variable is not set, the terminfo database is used to determine the number of columns, based on the environment
variable TERM. If this information cannot be obtained, 80 columns are assumed.
OPTIONS

-a

List all entries; in the absence of this option, entries whose names begin with a '.' are not listed
(except for the super-user, for whom Is, but not /usr/Sbin/ls, normally prints even files that begin
with a '.').

-b

(/usr/Sbin/Is only) Force printing of non-graphic characters to be in the octal \ddd notation.

-c

Use time of last edit (or last mode change) for sorting or printing.

-d

If argument is a directory, list only its name (not its contents); often used with -I to get the status
of a directory.

-f

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

-g

For Is, show the group ownership of the file in a long output. For /usr/Sbin/Is, print a long listing,
the same as -I, except that the owner is not printed.

-i

For each file, print the i-number in the first column of the report.

-I

List in long format, giving mode, number of links, owner, size in bytes, and time of last
modification for each file. (See below.) If the file is a special file the size field will instead contain
the major and minor device numbers. If the file is a symbolic link the pathname of the linked-to
file is printed preceded by '->'. /usr/5bin/1s will print the group in addition to the owner.

-m

(/usr/5binlls only) Stream output format; the file names are printed as a list separated by commas,
with as many entries as possible printed on a line.

-n

(/usr/Sbinlls only) The same as -I, except that the owner's UID and group's GID numbers are
printed, rather than the associated character strings.

-0

(/usr/5binlls only) The same as -I, except that the group is not printed.

-p

(/usr/Sbinlls only) Put a slash (I) after each filename if that file is a directory.

-q

Display non-graphic characters in filenames as the character (?); this is the default when output is
to a terminal.

-r

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

-s

Give size of each file, including any indirect blocks used to map the file, in kilobytes (Is) or 512byte blocks (/usr/Sbin/Is).

-t

Sort by time modified (latest first) instead of by name.

Sun Release 3.2

Last change: 17 July 1986

241

LS( IV)

USER COMMANDS

LS( IV)

-u

Use time of last access instead of last modification for sorting (with the -t option) and/or printing
(with the -I option).

-x

(/usr/5binlIs only) Multi-column output with entries sorted across rather than down the page.

-1

(Is only) Force one entry per line output format; this is the default when output is not to a terminal.

-A

(Is only) Same as -3, except that'.' and ' •. ' are not listed.

-C

Force multi-column output, with entries sorted down the columns; for Is, this is the default when
output is to a terminal.

-F

Mark directories with a trailing slash (I), executable files with a trailing asterisk (*), symbolic
links with a trailing at-sign (@), and AF_UNIX domain sockets with a trailing equals sign (=).

-L

If argument is a symbolic link, list the file or directory the link: references rather than the link
itself.

-R

Recursively list subdirectories encountered.

INTERPRETATION OF LISTING
The mode printed under the -I option contains 10 characters interpreted as follows. If the first character is:
d entry is a directory;
b entry is a block-type special file;
c entry is a character-type special file;
I entry is a symbolic link;
p entry is a fifo (a.k.a. "named pipe") special file;
s entry is an AF_ UNIX domain socket, or
entry is a plain file.

The next 9 characters are interpreted as three sets of three bits each. The first set refers to owner permissions; the next refers to permissions to others in the same user-group; and the last refers 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. The permissions are indicated as follows:
r the file is readable;
w the file is writable;
x the file is executable;
the indicated permission is not granted.
The group-execute permission character is given as s if the file has the set-group-id bit set; likewise the
owner-execute permission character is given as s if the file has the set-user-id bit set.
The last character of the mode (normally x or -) is t if the 1000 bit of the mode is on. See c hmod (1 V) for
the meaning of this mode. The indications of set-ID and 1000 bits of the mode are capitalized (S and T
respectively) if the corresponding execute permission is not set
When the sizes of the files in a directory are listed, a total count of blocks, including indirect blocks is
printed.
FILES

fetclpasswd
fetc/group

to get user id's for Is -I and Is -0.
to get group id's for Is -g and lusr/5bin/Is-1.

fusrflibfterminfof*
to get terminal information for lusrISbin/ls.
BUGS

Newline and tab are considered printing characters in filenames.

242

Last change: 17 July 1986

Sun Release 3.2

LS( IV)

USER COMMANDS

LS( IV)

The output device is assumed to be 80 columns wide.
The option setting based on whether the output is a teletype is undesirable as 'Is -s' is much different than
'Is -s Ilpr'. On the other hand, not doing this setting would make old shell scripts which used Is almost
certain losers.
None of the above apply to lusr/5binlIs.
Unprintable characters in file names may confuse the columnar output options.

Sun Release 3.2

Last change: 17 July 1986

243

M4( IV)

USER COMMANDS

M4( IV)

NAME
~4-fJUacroprocessor

SYNOPSIS
m4 [filename] ...
SYSTEM V SYNOPSIS
m4 [ -es ] [ -B int] [ -H int] [ -S int] [ -Tint] '[ -Dname=val ] [ -Uname ] [filename ] ...
DESCRIPTION
m4 is a fJUacro processor intended as a front end for Ratfor, C, and other languages. Each of the argufJUent
files is processed in order; if there are no files, or if a file name is -, the standard input is read. The processed text is written on the standard output.

Macro calls have the form:

name(argJ[, arg2, ... ,] argn)
The '(' fJUust iffifJUediately follow the name of the fJUacro. If the name of a defined fJUacro is not followed by
a '(" it is interpreted as a call of the fJUacro with no argufJUents. Potential ~acro names consist of letters,
digits, and underscores L), where the first character is not a digit.
Leading unquoted blanks, tabs, and NEWLINEs are ignored while collecting argufJUents. Left and right single quotes (, ,) are used to quote strings. The value of a quoted string is the string stripped of the quotes.
When a ~acro name is recognized, its argufJUents are collected by searching for a matching right
parenthesis. If fewer arguments are supplied than are in the fJUacro definition, the trailing arguments are
taken to be null. Macro evaluation proceeds nOffJUally during the collection of the arguments, and any co~­
mas or right parentheses which happen to tum up within the value of a nested call are as effective as those
in the original input text. After argufJUent collection, the value of the fJUacro is pushed back onto the input
streafJU and rescanned.
Built-In Macros
m4 fJUakes available the following built-in fJUacros. They may be redefined, but once this is done the original fJUeaning is lost. Their values are null unless otherwise stated.

define

the second argufJUent is installed as the value of the fJUacro whose name is the first argu~ent.
Each occurrence of $n in the replacefJUent text, where n is a digit, is replaced by the n'th
argument. Argument 0 is the name of the macro; missing arguments are replaced by the
null string.

undefine

refJUoves the definition of the fJUacro named in its argument.

ifdef

if the first argufJUent is defined, the value is the second argu~ent, otherwise the third. If
there is no third argufJUent, the value is null. The word unix is predefined.

changequote change quote characters to the first and second argufJUents. cbangequote without argu~ents
restores the original values (i.e.,' ,).

244

divert

m4 fJUaintains 10 output streafJUS, numbered 0-9. The final output is the concatenation of the
streams in nUfJUerical order; initially stream 0 is the current stream. The divert fJUacro
changes the current output stream to its (digit-string) argufJUent. Output diverted to a stream
other than 0 through 9 is discarded.

undivert

causes immediate output of text frofJU diversions named as argufJUents, or all diversions if no
argument. Text fJUay be undiverted into another diversion. Undiverting discards the
diverted text.

divnum

returns the value of the current output stream.

dnl

reads and discards characters up to and including the next newline.

ifelse

has three or fJUore arguments. If the first argument is the same string as the second, then the
value is the third argument. If not, and if there are fJUore than four arguments, the process is

Last change: 17 July 1986

Sun Release 3.2

M4(lV)

USER COMMANDS

M4( IV)

repeated with arguments 4, 5, 6, 7 and so on. Otherwise, the value is either the last string
not used by the above process, or, if it is not present, null.

iner

returns the value of its argument incremented by 1. The value of the argument is calculated
by interpreting an initial digit-string as a decimal number.

eval

evaluates its argument as an arithmetic expression, using 32-bit arithmetic. Operators
include +, -, *, /, %, (exponentiation); relationals; parentheses.
A

len

returns the number of characters in its argument.

index

returns the position in its first argument where the second argument begins (zero origin), or
-1 if the second argument does not occur.

substr

returns a substring of its first argument. The second argument is a zero origin number
selecting the first character; the third argument indicates the length of the substring. A missing third argument is taken to be large enough to extend to the end of the first string.

translit

transliterates the characters in its first argument from the set given by the second argument
to the set given by the third No abbreviations are permitted.

include

returns the contents of the file named in the argument

sinclude

is similar to include, except that it says nothing if the file is inaccessible.

sysemd

executes the UNIX system command given in the first argument. No value is returned.

maketemp

fills in a string of XXXXX in its argument with the current process ID.

errprint

prints its argument on the diagnostic output file.

dumpdef

prints current names and definitions, for the named items, or for all if no arguments are
given.

SYSTEM V DESCRIPTION
In the System V version of m4, the following built-in macros have added capabilities.

define

$# is replaced by the number of arguments; $* is replaced by a list of all the arguments
separated by commas; $@ is like $*, but each argument is quoted (with the current quotes).

ehangequote change quote symbols to the first and second arguments. The symbols may be up to five
characters long.

eval

Additional operators include bitwise &, I, A, and -. Octal, decimal and hex numbers may be
specified as in C. The second argument specifies the radix for the result; the default is 10.
The third argument may be used to specify the minimum number of digits in the result

The System V version of m4 makes available the following additional built-in macros.

defn

returns the quoted definition of its argument(s). It is useful for renaming macros, especially
built-ins.

pushdef

like define, but saves any previous definition.

popdef

removes current definition of its argument(s), exposing the previous one, if any.

shift

returns all but its first argument. The other arguments are quoted and pushed back with
commas in between. The quoting nullifies the effect of the extra scan that will subsequently
be performed.

ehangeeom

change left and right comment markers from the default # and NEWLINE. With no arguments, the comment mechanism is effectively disabled. With one argument, the left marker
becomes the argument and the right marker becomes NEWLINE. With two arguments, both
markers are affected. Comment markers may be up to five characters long.

deer

returns the value of its argument decremented by 1.

sysval

is the return code from the last call to syscmd.

Sun Release 3.2

Last change: 17 July 1986

245

M4(1V)

USER COMMANDS

M4( IV)

m4exit

causes immediate exit from m4. Argument 1, if given, is the exit code; the default is O.

m4wrap

argument 1 will be pushed back at final EOF; example: m4wrap(' cleanup()')

traceon

with no arguments, turns on tracing for all macros (including built-ins). Otherwise, turns on
tracing for named macros.

traceoff

turns off trace globally and for any macros specified. Macros specifically traced by traceon
can be untraced only by specific calls to traceo!!.

SYSTEM V OPTIONS
The options and their effects are as follows:

-e

Operate interactively. Interrupts are ignored and the output is unbuffered.

-s

Enable line sync output for the C preprocessor (#line ... )

-Bint

Change the size of the push-back and argument collection buffers from the default of 4,096.

-Hint

Change the size of the symbol table hash array from the default of 199. The size should be prime.

-Sint

Change the size of the call stack from the default of 100 slots. Macros take three slots, and nonmacro arguments take one.

-Tint

Change the size of the token buffer from the default of 512 bytes.

To be effective, these flags must appear before any file names and before any -D or -U flags:

-Dname[=val]
Defines name to be valor to be null in val's absence.
-Uname
undefines name .
SEE ALSO

M4 -A Macro Processor, in Programming Utilitiesfor the Sun Workstation.

246

Last change: 17 July 1986

Sun Release 3.2

MACH ( 1)

USER COMMANDS

MACH ( 1)

NAME

mach - display the processor type of the current host
SYNOPSIS

mach
DESCRIPTION

The mach command displays the processor-type of the current Sun host
SEE ALSO

arch(l), machid(l)

Sun Release 3.2

Last change: 29 May 1986

247

MACHID( 1)

USER COMMANDS

MACHID(I)

NAME

machid, sun, iAPX286, m68k, pdp11, u3b, u3b2, u3b5, vax - provide truth value about your processor type
SYNOPSIS

sun
iAPX286
m68k
pdp11

u3b
u3b2
u3bS
vax
DESCRIPTION

The following commands will return a true value (exit code of 0) if you are on a processor that the command name indicates.
sun

True if you are on a Sun.

iAPX286
True if you are on a computer using an iAPX286 processor.
m68k True if you are on a computer using an MC68000-farnily processor.
pdp11 True if you are on a PDP-l1.

u3b

True if you are on a 3B 20S computer.

u3b2

True if you are on a 3B 2 computer.

u3b5

True if you are on a 3B 5 computer.

vax

True if you are on a VAX.

The commands that do not apply will return a false (non-zero) value. These commands are often used
within make (1) rnakefiles and shell procedures to increase portability.
SEE ALSO

arch(I), mach(I), make(I), sh(I), test(IV), true(l)

248

Last change: 6 June 1986

Sun Release 3.2

MAIL ( 1)

USER COMM:ANDS

MAIL(l)

NAME

mail, Mail- interactive message-processing system
SYNOPSIS

Mail [ -d ] [ -e ] [ -f [filename I +folder ] ] [ -H ] [ -i ] [ -n] [ -N ] [ - T file] [ -u user] [ -U] [ -v ]
Mail [ -d ] [ -F] [ -b nwnber ] [ -i ] [ -0] [ -r address] [ -s subject] [ -U ] [ -v ] recipient . ..
/usr/ueb/mail ...
DESCRIPTION

mail provides a comfortable, flexible environment for sending and receiving electronic messages. While
reading mail, mail provides commands to browse, display, save, delete, and respond to messages. While
sending mail, mail allows editing and reviewing of a message being composed, and the inclusion of text
from files or other messages.
Incoming mail is stored in a standard file for each user, called the system mailbox for that user. When mail
is called to read messages, the system mailbox is the default place to find them. As messages are read, they
are marked to be moved to a secondary file for storage (unless specific action is taken), so that the messages need not be seen again. This secondary file, called the mhox, is normally the file .mbox in the user's
home directory, but can be changed by setting the MBOX variable. Messages remain in this file until forcibly removed
OPTIONS

If no recipient is specified, mail attempts to read messages from the system mailbox.
-d

Turn on debugging output (Neither particularly interesting nor recommended.)

-e

Test for presence of mail. If there is no mail, mail prints nothing and exits (with a successful return code).

-f [filename]

Read messages from filename instead of system mailbox. If no filename is specified, the
mbox is used.

-f [ + folder]

Use the filefolder in the folder directory (same as the folder command). The name of this
directory is listed in the folder variable.

-F

Record the message in a file named after the first recipient Overrides the record variable, if set.

-b number

The number of network 'hops' made so far. This is provided for network software to
avoid infinite delivery loops.

-H

Print header summary only.

-i

Ignore interrupts (as with the ignore variable).

-n

Do not initialize from the system default MaiI.re file.

-N

Do not print initial header summary.

-r address

Pass address to network delivery software. All tilde commands are disabled.

-s subject

Set the Subject header field to subject.

- T file

Print the contents of the article-id fields of all messages that were read or deleted on file
(for the use of network news programs if available).

-u user

Read user's system mailbox. This is only effective if user's system mailbox is not read
protected.

-U

Convert uucp style addresses to Internet standards. Overrides the eonv environment variable.

-v

Pass the -v flag to sendmail (8).

Sun Release 3.2

Last change: 17 July 1986

249

MAll.. ( 1)

USER COMMANDS

MAll.. ( 1)

USAGE

Refer to Mail and Messages: Beginner's Guide for tutorial information about mail.
Starting Mail

As it starts, mail reads commands from a system-wide file (/usr/liblMaiI.re) to initialize certain variables,
then it reads from from a private start-up file called the .mailrc file (it is normally the file .mailre in your
home directory, but can be changed by setting the MAILRC environment variable) for your personal commands and variable settings. Most mail commands are legal inside start-up files. The most common uses
for this file are to set up initial display options and alias lists. The following commands are not legal in the
start-up file: !, Copy, edit, followup, Followup, hold, mail, preserve, reply, Reply, replyall, replysender,
shell, and visual. Any errors in the start-up file cause the remaining lines in that file to be ignored.
You can use the mail command to send a message directly by including names of recipients as arguments
on the command line. When no recipients appear on the mail command line, it enters command mode,
from which you can read messages sent to you. If you list no recipients and have no messages, mail prints
the message: "No mail for username" and exits.
When in command mode (while reading messages), you can send messages using the mail command.
Sending Mall

While you are composing a message to send, mail is in input mode. If no subject is specified as an argument to the command a prompt for the subject is printed. Mter entering the subject line, mail enters input
mode to accept the text of your message to send
As you type in the message, mail stores it in a temporary file. To review or modify the message, enter the
appropriate tilde escapes, listed below, at the beginning of an input line.

To indicate that the message is ready to send, type a dot (or end-of-file character, normally AD) on a line by
itself. mail submits the message to sendmail (8) for routing to each recipient.
Recipients can be local usernames, Internet addresses of the form:
name@domain
uucp(lC) addresses of the form:
. .. [host!]host!username

filenames, folders or alias groups. If the name of the recipient begins with a pipe symbol (I), the
remainder of the name is taken as a shell command to pipe the message through. This provides an
automatic interface with any program that reads the standard input, such as Ipr(l) to record outgoing mail
on paper. An alias group is the name of a list of recipients that is set by the alias command, taken from the
host's lusr/lib/aliases file, or taken from the Yellow Pages aliases domain. See addresses(5) for more
information about mail addresses and aliases.
Tllde Escapes

The following tilde escape commands can be used when composing messages to send. Each must appear
at the beginning of an input line. The escape character (-), can be changed by setting a new value for the
escape variable. The escape character can be entered as text by typing it twice.

-! [shell-command]
Escape to the shell. If present, run shell-command.
Simulate end of file (terminate message input).
-: mail-command
- mail-command
Perform the indicated mail command. Valid only when sending a message while reading mail.

250

-?

Print a summary of tilde escapes.

-A

Insert the autograph string Sign into the message.

a

Insert the autograph string sign into the message.

Last change: 17 July 1986

Sun Release 3.2

MAIL ( 1)

USER COMMANDS

MAIL(I)

-bname ...
Add the names to the blind carbon copy (Bcc) list. This is like the carbon copy (Cc) lis4 except
that the names in the Bcc list are not shown in the header of the mail message.
cname ...
Add the names to the carbon copy (Cc) list.
-dRead in the dead.letter file. The name of this file is listed in the variable DEAD.
e

Invoke the editor to edit the message. The name of the editor is listed in the EDITOR variable.
The default editor is ex(l}.

-r [message-list]
Forward the listed messages, or the current message being read. Valid only when sending a message while reading mail; the messages are inserted without alteration (as opposed to the - m
escape).
-h

Prompt for the message header lines: Subject, To, Cc, and Bcc. If the header line contains text,
you can edit the text by backspacing over it and retyping.

-i variable
Insert the value of the named variable into the message.
- m [message-list]

Insert text from the specified messages, or the current message, into the letter. Valid only when
sending a message while reading mail; the inserted text is shifted to the right by one tab stop.
p

Print the message being entered.

q

Quit from input mode by simulating an interrupt If the body of the message is not empty, the partial message is saved in the dead. letter file.

-r filename
- ' in the header summary. For commands that take an optional list of messages, if you omit a message number as an argumen4 the command applies to the current message.

Sun Release 3.2

Last change: 17 July 1986

251

MAa(I)

USER COMMANDS

MAIL(I)

A message-list is a list of message specifications, separated by spaces, which may include:
The current message.
Message number n.
The first undeleted message.
S
The last message.
+
The next undeleted message.
The previous undeleted message.
*
All messages.
n-m
An inclusive range of message numbers.
user
All messages from user.
I string All messages with string in the subject line (case ignored).
:c
All messages of type c, where c is one of:
d
deleted messages
n
new messages
o
old messages
r
read messages
u
unread messages
Note that the context of the command determines whether this type of message
specification makes sense.
n

Additional arguments are treated as strings whose usage depends on the command involved. Filenames,
where expected, are expanded using the normal shell filename-substitution mechanism.
Special characters, recognized by certain commands, are documented with those commands.
Commands

While in command mode, if you type in an empty command line (a carriage-return or NEWLINE only), the
print command is assumed. The following is a complete list of mail commands:

! shell-command

Escape to the shell. The name of the shell to use is listed in the SHELL variable.

# comment

Null command (comment). This may be useful in .mailrc files.

=

Print the current message number.

?

Prints a summary of commands.

alias [alias recipient ... ]
group [alias recipient ... ]
Declare an alias for the given list of recipients. The list will be substituted when the
alias is used as a recipient while sending mail. When put in the .mailrc file, this
command provides you with a record of the alias. With no arguments, the command
displays the list of defined aliases.
alternates name. . .

cd[ directory]
chdir [directory]

Declares a list of alternate names for your login. When responding to a message,
these names are removed from the list of recipients for the response. With no arguments, alternates prints the current list of alternate names.
Change directory. If directory is not specified, $HOME is used.

copy [message-list] [filename]
Copy messages to the file without marking the messages as saved. Otherwise
equivalent to the save command.
Copy [message-list] Save the specified messages in a file whose name is derived from the author of the
message to be saved, without marking the messages as saved. Otherwise equivalent
to the Save command.

252

Last change: 17 July 1986

Sun Release 3.2

MAIL ( 1)

USER COMMANDS

MAIL(1)

delete [message-list] Delete messages from the system mailbox. If the variable autoprint is set, print the
message following the last message deleted.
discard [header-field ... ]
ignore [header-field ... ]
Suppress printing of the specified header fields when displaying messages on the
screen, such as "Status" and "Received". The fields are included when the message
is saved unless the variable alwaysignore is set The Print and Type commands
display all header fields, ignored or not
dp [message-list]
dt [message-list]

Delete the specified messages from the system mailbox, and print the message after
the last one deleted. Equivalent to a delete command followed by a print command.

echo [string ... ]

Echo the given strings (like echo (1V».

edit [message-list]

Edit the given messages. The messages are placed in a temporary file and the
EDITOR variable is used to get the name of the editor. The default editor is ex(1).

exit
xit
file [filename]
folder [filename]

Exit from mail without changing the system mailbox. No messages are saved in the
mbox (see also quit).
Quit from the current mailbox file and read in the named mailbox file. Several special characters are recognized when used as file names:
%
Your system mailbox.
% user
The system mailbox for user.
#
The previous mail file.
&
Your mbox file (of messages previously read).
+filename The named file in the/older directory (listed in the folder variable).
With no arguments, file prints the name of the current mail file, and the number of
messages and characters it contains.

folders

Print the name of each mail file in the/older directory (listed in the folder variable).

followup [message]

Respond to a message, recording the response in a file, name of which is derived
from the author of the message (overrides the record variable, if set). See also the
Followup, Save, and Copy commands and the outfolder variable.

Followup [message-list]
Respond to the first message in the message list, sending the message to the author of
each message in the list. The subject line is taken from the first message, and the
response is recorded in a file, the name of which is derived from the author of the
first message (overrides the record variable, if set). See also the followup, Save, and
Copy commands and the outfolder variable.
from [message-list]

Print the header summary for the indicated messages or the current message.

group alias name. .. Same as the alias command.
headers [message]

Prints the page of headers that includes the message specified, or the current message. The screen variable sets the number of headers per page. See also the z command.

help

Prints a summary of commands.

hold [message-list]
preserve [message-list]
Holds the specified messages in the system mailbox.

Sun Release 3.2

Last change: 17 July 1986

253

MAIL ( 1)

USER COMMANDS

MAIL(I)

ifslrlt
mail-command

else
mail-command
endif

Conditional execution, where s will execute following mail-command up to an else
or emlif, if the program is in send mode, r executes the mail-command only in
receive mode, and t executes the mail-command only if mail is being run from a terminal. Useful primarily in the .mailrc file.

ignore [header-fteld . .. ]
Same as the discard command.
list

Prints all commands available. No explanation is given.

mail recipient . ..

Mail a message to the specified recipients.

mbox [message-list] Arrange for the given messages to end up in the standard mbox file when mail terminates normally. See also the exit and quit commands.
new [message-list]
New [message-list]
unread [message-list]
Unread [message-list]
Takes a message list and marks each message as not having been read.
next message

Go to next message matching message. A message-list can be given instead of message, but only first valid message in the list is used. (This can be used, for instance,
to jump to the next message from a specific user.)

pipe [message-list] [shell-command]
[shell-command]
Pipe the message through shell-command. The message is treated marked as read
(and normally saved to the mbox file when mail exits). If no arguments are given,
the current message is piped through the command specified by the value of the cmd
variable. If the page variable is set, a form feed character is inserted after each message.

I [message-list]

preserve [message-list]
Same as the hold command.
print [message-list]
type [message-list]

Print the specified messages. If the crt variable is set, messages longer than the
number of lines it indicates paged through the command specified by the PAGER
variable. The default paging command is more (1).

Print [message-list]
Type [message-list] Print the specified messages on the screen, including all header fields. Overrides
suppression of fields by the ignore and retain commands.
quit

Exit from mail storing messages that were read in the mbox file and unread messages
in the system mailbox. Messages that have been explicitly saved in a file are deleted
unless the variable keepsave is set.

reply [message-list]
respond [message-list]
replysender [message-list]
Send a response to the author of each message in the message-list. The subject line
is taken from the first message. If record is set to a filename, a copy of the the reply
is added to that file. If the replyaU variable is set, the actions of Reply/Respond and

254

Lastchange: 17 July 1986

Sun Release 3.2

MAIL(1)

USER COMMANDS

MAIL(1)

reply/respond are reversed. The repJysender command is not affected by the
repJyalI variable, but sends each reply only to the sender of each message.
Reply [message]
Respond [message]
replyall [message]

retain

Reply to the specified message, including all other recipients of that message. If the
variable record is set to a filename, a copy of the reply added to that file. If the
replyalI variable is set, the actions of Reply/Respond and reply/respond are
reversed. The replyall command is not affected by the repJyaU variable, but always
sends the reply to all recipients of the message.
Add the list of header fields named to the retained list. Only the header fields in the
retain list are shown on your tenninal when you print a message. All other header
fields are suppressed. The set of retained fields specified by the retain command
overrides any list of ignored fields specified by the ignore command The Type and
Print commands can be used to print a message in its entirety. If retain is executed
with no arguments, it lists the current set of retained fields.

save [message-list] ffilename]
Save the specified messages in the named file. The file is created if it does not exist.
If no filename is specified, the file named in the MBOX variable is used, mbox in
your home directory by default. Each saved message is deleted from the system
mailbox when mail terminates unless the keepsave variable is set. See also the exit
and quit commands.
Save [message-list]

Save the specified messages in a file whose name is derived from the author of the
first message. The name of the file is taken from the author's name, with all network
addressing stripped off. See also the Copy, followup, and Followup commands and
the outfolder variables.

set [variable [=value ] ]
Define a variable. To assign a value to variable, separate the variable name from
the value by an equal-sign (=) (there must be no space before or after the =). A variable may be given a null, string, or numeric value. To embed spaces within a value
enclose it in quotes.
With no arguments, set displays all defined variables and any values they might
have. See Variables for a description of all predefined mail variables.
shell

Invoke the interactive shell listed in the SHELL variable.

size [message-list]

Print the size in characters of the specified messages.

source filename

Read commands from the given file and return to command mode.

top [message-list]

Print the top few lines of the specified messages. If the toplines variable is set, it is
taken as the number of lines to print. The default number is 5.

touch [message-list] Touch the specified messages. If any message in message-list is not specifically
saved in a file, it will be placed in the mbox upon normal termination. See also the
exit and quit commands.

type [message-list]

Same as the print command

Type [message-list]

Same as the Print command.

undelete [message-list]
Restore deleted messages. This command only restores messages deleted in the
current mail session. If the autoprint variable is set, the last message restored is
printed.

Sun Release 3.2

Last change: 17 July 1986

255

MAIL(I)

USER COMMANDS

MAIL(l)

unread [message-list]
Unread [message-list]
Same as the new command.
Erases the specified variables. If the variable was imported from the environment
(that is, an environment variable or exported shell variable), it cannot be unset from
within mail.
version
Prints the current version and release date of the mail utility.
visual [message-list] Edit the given messages with the screen editor listed in the VISUAL variable. The
default screen editor is vi(1). Each message is placed in a temporary file for editing.
write [message-list] [filename]
Write the given messages onto the specified file, but without the header and trailing
blank line. Otherwise, this is equivalent to the save command.
xit
Same as the exit command.
Scroll the header display forward (+) or backward (-) one screenfull. The number
z[+I-]
of headers displayed is set by the screen variable.
Forwarding Messages
To forward a specific message, include it in a message to the desired recipients with the -f or - m tilde
escapes. To forward mail automatically, add the addresses of additional recipients to the .forward file in
your home directory. Note that forwarding addresses must be valid, or the messages will "bounce." (You
cannot, for instance, reroute your mail to a new host by forwarding it to your new address if it is not yet
listed in the yP aliases domain.)
Variables
The behavior of mail is governed by a set of predefined variables that are set and cleared using the set and
unset commands. Values for the following variables are read in automatically from the environment; they
cannot be altered from within mail:
HOME=direetory
The user's home directory.
MAILRC=filename
The name of the personal start-up file. The default is $HOMEI.maiIrc.
Below are listed the remaining predefined variables recognized by mail. Each can be initialized within the
.mailre file, or set and altered at any time while in mail, using the set command. They can also be imported
from the environment (in which case their values cannot be changed within mail). The unset command
clears variables. The set command can also be used to clear a variable by prefixing the word no to the name
of the variable to clear.
Variables for which values are normally supplied are indicated with an equal-sign (=). The equal-sign is
required by the set command, and there can be no spaces between the variable-name, equal-sign, and value,
using set to assign a value.
alInet
All network names whose last component (login name) match are treated as identical.
This causes the message list specifications to behave similarly. Default is noallnet. See
also the alternates command and the metoo variable.
alwaysignore Ignores header fields with ignore everywhere, not just during print or type. Affects the
save, Save, copy, Copy, top, pipe, and write commands, and the -m and -f tilde escapes.
Upon termination, append messages to the end of the mbox file instead of prepending
append
them. Default is noappend but append is set in the global start-up file (which can be
suppressed with the -n command line option).
Prompt for the Cc list after message is entered. Default is noaskcc.
askcc
Prompt for subject if it is not specified on the command line with the -s option. Enabled
asksub
by default.
Enable automatic printing of messages after delete and undelete commands. Default is
autoprint
noautoprint.
Enable the special-casing of exclamation points (!) in shell escape command lines as in
bang
vi. Default is nobang.
cmd=shell-eommand
unset variable . ..

256

Last change: 17 July 1986

Sun Release 3.2

MAIL ( 1)

USER COMMANDS

MAIL(I)

Set the default command for the pipe command. No default value.
conv=conversion

crt=number

Convert uucp addresses to the specified address style. The only valid conversion now is
internet, which requires a mail delivery program conforming to the RFC822 standard for
electronic mail addressing. Conversion is disabled by default. See also sendmail and the
-U command line option.
Pipe messages having more than number lines through the command specified by the
value of the PAGER variable (more by default). Disabled by default.

DEAD=filename

The name of the file in which to save partial letters in case of untimely interrupt or
delivery errors. Default is the file dead.Ietter in your horne directory.
debug
Enable verbose diagnostics for debugging. Messages are not delivered. Default is nodebug.
dot
Take a period on a line by itself during input from a terminal as end-of-file. Default is
nodot but dot is set in the global start-up file (which can be suppressed with the -n command line option).
EDITOR=shell-command
The command to run when the edit or - e command is used. Default is ex(I).
escape=c
Substitute c for the - escape character.
folder=directory
The directory for saving standard mail files. User specified file names beginning with a
plus (+) are expanded by preceding the filename with this directory name to obtain the
real filename. If directory does not start with a slash (I), the value of HOME is prepended
to it. There is no default for the folder variable. See also outfolder below.
Enable printing of the header summary when entering mail. Enabled by default.
header
Preserve all messages that are read in the system mailbox instead of putting them in the
hold
standard mbox save file. Default is nohold.
Ignore interrupts while entering messages. Handy for noisy dial-up lines. Default is
ignore
noignore.
ignoreeof
Ignore end-of-file during message input Input must be terminated by a period (.) on a
line by itself or by the -. command. Default is noignoreeof. See also dot above.
keep
When the system mailbox is empty, truncate it to zero length instead of removing it. Disabled by default.
keepsave
Keep messages that have been saved in other files in the system mailbox instead of deleting them. Default is nokeepsave.
LISTER=shell-command
The command (and options) to use when listing the files in the folder directory. The
default is Is (1 V).
MBOX=filename
The name of the file to save messages which have been read. The xit command overrides
this variable, as does saving the message explicitly to another file. Default is the file
mbox in your horne directory.
If your login appears as a recipient, do not delete it from the list. Default is nometoo.
metoo
When used as a prefix to a variable name, has the effect of unsetting the variable.
no
When responding to a message that was originally sent to several recipients, the other
one hop
recipient addresses are normally forced to be relative to the originating author's machine
for the response. This flag disables alteration of the recipients' addresses, improving
efficiency in a network where all machines can send directly to all other machines (that is,
one hop away).
outfolder
Locates the files used to record outgoing messages in the directory specified by the folder
variable unless the pathname is absolute. Default is nooutfolder. See folder above and
the Save, Copy, followup, and Followup commands.
page
Used with the pipe command to insert a form feed after each message sent through the

Sun Release 3.2

Last change: 17 July 1986

257

MAIL(I)

USER COMMANDS

MAIL(I)

pipe. Default is nopage.
PAGER=shell-command
The command to use as a filter for paginating output, along with any options to be used
Default is more(I).
prompt=string Set the command mode prompt to string Default is &.
quiet
Refrain from printing the opening message and version when entering mail Default is
noquiet.
record=filename
Record all outgoing mail in filename. Disabled by default. See also the variable outfolder.
replyaU
Reverses the effect of the reply and Reply commands.
save
Enable saving of messages in the dead.letter file on interrupt or delivery error. See DEAD
for a description of this file. Enabled by default
screen=number Sets the number of lines in a screen-full of headers for the headers command.
sendmail=shell-command
Alternate command for delivering messages. Default is sendmail (8).
sendwait
Wait for background mailer to finish before returning. Default is nosendwait.
SHELL=shell-command
The name of a preferred command interpreter. Typically inherited from the environment,
the shell is normally the one you always use. Otherwise defaults to sh(I).
When displaying the header summary and the message is from you~ print the recipient's
showto
name instead of the author's name.
sign=autograph The autograph text inserted into the message when the -a (autograph) command is given.
No default (see also the -i tilde escape).
Sign=autograph The autograph text inserted into the message when the -A command is given. No default
(see also the -i tilde escape).
toplines=number
The number of lines of header to print with the top command. Default is 5.
verbose
Invoke sendmail with the -v flag.
VISUAL=shell-command
The name of a preferred screen editor. Default is vi.
FILES

$HOME/.mailrc
$HOMEI forward
$HOMElmbox
$HOMEIdead. letter
lusrlspoollmail
lusrllibIMail.help*
lusrlliblMail.rc
ItmplR[emqsxl*

personal start-up file
list of recipients for automatic forwarding of messages
secondary storage file
undeliverable messages file
directory for system mailboxes
help message files
global start-up file
temporary files

SEE ALSO

binmail(I), mailtool(l) sendmail(8), biff(I), fmt(I), addresses(5), newaliases(8), vacation(l)
mail is found in lusr/ucblMail, as a link to lusr/ucb/mail. If you wish to use the original (version 7)
UNIX mail program, you can find it in !bin/mail. Its man page is named binmail (1).
BUGS

Where shell-command is shown as valid, arguments are not always allowed. Experimentation is recommended.
Internal variables imported from the execution environment cannot be unset
Replies do not always generate correct return addresses. Try resending the errant reply with onebop set.
mail does not lock your record file. So, if you use a record file and send two or more messages simultaneously, lines from the messages may be interleaved in the record file.

258

Last change: 17 July 1986

Sun Release 3.2

MAILTOOL ( 1 )

USER COMMANDS

MAILTOOL ( 1 )

NAME

mailtool - window- and mouse-based interface for mail
SYNOPSIS
mailtool [ -x ] [ -i seconds ]
DESCRIPTION

mailtool is a standard tool provided with the SunView environment.
mailtool manages your mail in much the same manner as mail, but provides a more convenient and powerful user interface. Scroll able windows allow easy access to your mailbox and mail folders. Software "buttons" make the most frequently used commands readily available. Less used commands are accessable
from menus and keyboard accelerators are provided for the more experienced user. The full editing capabilities of textedit(l) and the SunView selection service are available for modifying and composing mail.
In addition, the behavior of mailtool may be customized by setting parameters with defaultsedit(l). Users
who are not familiar with the mail program should read Mail and Messages: Beginner's Guide. For more
information on mailtool, text editing, and use of the selection service see Windows and Window-Based
Tools: Beginner's Guide.
OPTIONS

-x

expert mode - don't ask for confirmation after potentially damaging mail commands; off by
default

-i seconds
interval- check for new mail every seconds seconds - default is 300 (5 minutes)
mailtool also accepts all of the generic tool arguments discussed in suntools(I).
SUBWINDOWS

mailtool consists of four scrollable subwindows. From top to bottom they are:
header

a read-only text subwindow which lists the header information (From: and Subject: and so
on) for mail messages in the current folder or system mailbox

command

a panel subwindow with software buttons corresponding to the most frequently used mail
commands, and two text items for directory and file names

message

a text subwindow that allows reading and the editing of messages that you have received

composition

a text subwindow in which to compose and reply to messages (this subwindow appears only
when composing or replying)

COMMAND BUTTONS
All buttons except next and undelete operate on the currently selected message. To select a message, make
a selection anywhere on the line in the header subwindow corresponding to the desired message. This is
accomplished by positioning the cursor anywhere on the line, and clicking the select mouse button (the
leftmost one).

The set of command buttons in the command panel is as follows.
abort

quit the tool without modifying your system mailbox

cd

change to the directory specified in the Directory: text field

cancel

abort the message being composed in the composition subwindow

commit

commit changes to your system mailbox or the current folder

compose

open the composition subwindow to compose (or forward - see below) a message

copy

copy the selected message to the file or folder specified in the File: text field

deliver

send the message being composed in the composition subwindow

delete

delete the selected message

done

commit changes, close the tool, and read new mail on next open

Sun Release 3.2

Last change: 1 May 1986

259

MAILTOOL ( 1 )

USER COMMANDS

MAILTOOL ( 1 )

folder

commit changes and switch to the file or folder specified in the File: text field

new mail

commit changes and reread the system mailbox to see new mail

next

show the next message in the message subwindow

preserve

hold the selected message in the system mailbox after the next commit

print

print the selected message on a hardcopy printer

quit

commit changes and quit the tool

reply

open the composition subwindow to reply to the selected message

save

save the selected message in the file or folder specified in the File: text field

show

show the selected message in the message subwindow

undelete

undelete the most recently deleted message(s) - this may be used repeatedly

.mailrc

source your -/.mailrc file and thereby aquire the current option settings

COMMAND MENUS

All buttons in the command panel have menus behind them. Depress the right mouse button over a command button to see its menu. Variations on a button command or related commands in mailtool have been
grouped on these menus. For example, the reply buttton has menu items that reply to all recipients of the
original message, reply including the original message, and reply to all recipients including the message.
The compose button has the function forward grouped with it. All menus have corresponding keyboard
acclerators - i.e. you may hold down a key while clicking the left mouse button to achieve the same effect
without popping-up the menu. Two keys are used: SHIff and CTRL. In general, if a command has an
"inverse" function like reversed direction, the SHIFf key is used, and CfRL is used to "strengthen" a command or invoke a related function. When a menu has actions corresponding to all four combinations of
SHIFf and CfRL, the order of the menu items is as follows:
simply clicking on the command button,
holding SHIFf while clicking on the button,
holding CfRL while clicking on the button,
holding both SHIff and CTRL when clicking on the button.
With this organization of commands, the keyboard accelerators for these command menu items may be
quickly learned. Simply browse the button menus to discover what additional commands are available.
There are two special file menus in the command panel. The menu behind the folder button will show you
all your folders. The menu behind the File: text field holds the most recently used file (and folder) names.
Selecting a name from these menus replaces the contents of the File: item just as if you typed the name.
This name is used for the save, copy, and folder commands. Folder names are of the form +folder and are
relative to the directory specified by the mail's folder variable. Filenames typed into the File: field are
relative to the directory specified in the Directory: field.
To switch to a folder, select it from one of the file menus or type directly into the File: text field, and press
the folder button. To return to your system mailbox, use the new mail button.
MAIL VARIABLES

mailtool interprets several variables in addition to those of mail. All can be set in your .mailrc file by using
defaultsedit(1).
allowreversescan allows you to work through your mailbox in the reverse, as well as forward, directions.
This will affect which message is next - if the sense of direction is reverse then the
message displayed by next is actually the previous one.

260

autoprint

display the next message when the current message is deleted or saved

bell

number of times to ring the bell when new mail arrives

cmdlines

number of lines in command panel

expert

sets expert mode - no confirmations required (same as the -x flag)

Last change: 1 May 1986

Sun Release 3.2

USER COMMANDS

MAILTOOL ( 1 )

MAILTOOL ( 1 )

filemenu

list of files to initialize the File: menu, (e.g. "+mbox +trash")

filemenusize

specifies the maximum size of the File: menu

Hash

number of times to flash the window or icon when new mail arrives

headerlines

number of lines in header sub window

interval

interval in seconds to check for new mail (same as the -i flag)

maillines

number of lines in mail message subwindow

msgpercent

percent of the message sub window to remain visible during a reply or compose

printmail

the command to use when printing mail- the default is lpr -po

trash

name of trash bin (if set to "+trash", this may be accessed like any other folder)

H the trash variable is set, all deleted messages will be moved to the trash bin. You can look at the trash
bin as with any other folder by typing its name to the File: item and hitting the folder button. The trash bin
is emptied when you hit done.
In addition, you can make your .mailrc conditionally set mail variables depending on whether it is running
in the tty environment or the window environment. The command if t tests if you are in the tty environment For example:

ift
else
set autoprint
cd
endif
will set the variable autoprint and change to your home directory when mail is started in the Sun View
environment.
FILES

lusr/spool/mail/·
-I.mailrc

post office
file giving initial mail commands

SEE ALSO

binmail(I), defaultsedit(I), mail(I), suntools(I), textedit(l)
aliases(5), mailaddr(7), newaliases(8), sendmail(8)
Mail and Messages: Beginner's Guide,
Windows and Window-Based Tools: Beginner's Guide
BUGS

H mail receives an error then mailtool may hang and you must kill it.
New mail status is only approximate, therefore the presence of new mail is not always accurately reflected
in the icon image and tool namestripe.

H you press done and immediately interact with another window, a few interactions may be lost while
mailtool is becoming iconic.

Sun Release 3.2

Last change: 1 May 1986

261

MAKE(l)

USER COMMANDS

MAKE(l)

NAME

make - maintain, update, and regenerate groups of programs
SYNOPSIS

make [ -f makefile ] . .. [-deikmnpqrsStb] [ target. .. ] [ macro-name =value . .. ]
DESCRIPTION

make executes a list of shell commands associated with each target, typically to create or update a file of
the same name. makefile contains entries for targets that describe how to bring them up to date with respect
to the files andlor other targets on which each depends, called dependencies.
A target is out of date when the file it describes is missing, or when one (or more) of its dependency files
has a more recent modification time than that of the target file. make recursively scans the list of dependencies for each target argument (or the first target entry in the makefile if no target argument is supplied)
to generate a list of targets to check. It then checks, from the bottom up, each target against any files it
depends on to see if it is out of date. If so, make rebuilds that target
To rebuild a target, make executes the set of shell commands, called a rule, associated with it This rule
may be listed explicitly in a makefile entry for that target, or it may be supplied implicitly by make.
If no makefile is specified on the command line, make uses the first file it finds with a name from the following list:

makefile, Makefile, s.makefile ~ sMakefile, SCCSls.makefile, SCCSlsMakefile
If no target is specified on the command line, make uses the first target defined in makefile. If a target has
no makefile entry, or if its entry has no rule, make attempts to update that target using an implicit rule.
OPTIONS

-fmakefile
Use the description file makefile. A - as the makefile argument denotes the standard input The
contents of makefile. when present, override the builtin rules. When more than one -f makefile
argument pairs appear, make takes input from each makefile in the order listed (just as if they were
run through cat(IV».

262

-d

Debug mode. Print out detailed information on files and times examined.

-e

Environment variables override assignments within makefiles.

-i

Ignore error codes returned by invoked commands.

-k

When a nonzero error status is returned by an invoked command, abandon work on the current
target but continue with other branches that do not depend on that target

-D

No execution mode. Print commands, but do not execute them. Even lines beginning with an @
are printed. However, if a command line contains the $(MAKE) macro, that line is always executed (see the discussion of MAKEFLAGS in Environment Variables and Macros).

-p

Print out the complete set of macro definitions and target descriptions.

-q

Question mode. make returns a zero or nonzero status code depending on whether or not the target file is up to date.

-r

Do not use the the implicit rules make supplies by default. Implicit rules defined in the make file
remain in effect

-s

Silent mode. Do not print command lines before executing them.

-S

Undo the effect of the -k option.

-t

Touch the target files (bringing them up to date) rather than performing commands listed in their
rules.

-b

This option has no effect, but is present for compatibility reasons.

Last change: 19 June 1986

Sun Release 3.2

MAKE ( 1)

USER COMMANDS

MAKE(l)

macro-name =value
Macro definition. This definition overrides any definition for the specified macro that occurs in
the makefile itself, or in the environment. See Macros and Environment Variables and Macros,
for details.
USAGE

Refer to Doing More With UNIX: Beginner's Guide, and Make in Programming Utilities for the Sun Workstation for tutorial information about make.
Targets and Rules

There need not be an actual file named by a target, but every dependency in the dependency list must be
either the name of a file, or the name of another target.
If the target has no dependency list and no rule, or if the target has no entry in the makefile, make attempts
to produce an entry by selecting a rule from its its set of implicit rules. If none of the implicit rules apply,
make uses the rule specified in the .DEFAULT target (if it appears in the makefile). Otherwise make stops
and produces an error message.
Makefile Target Entries

A target entry has the following format:
target . .. : [dependency] ... [; command] ...
[command]

The first line contains the name of a target (or a space-separated list of target names), terminated with a
colon (:). This may be followed by a dependency, or a dependency list that make checks in the order listed.
The dependency list may be terminated with a semicolon (;), which in turn can be followed by a Bourne
shell command. Subsequent lines in the target entry begin with a TAB, and contain Bourne shell commands. These commands comprise a rule for building the target, and are performed when the target is
updated by make.
Shell commands may be continued across input lines by escaping the NEWLINE with a backslash (\). The
continuing line must also start with a TAB.
To rebuild a target, make expands any macros, strips off initial TABs and passes each resulting command
line to a Bourne shell for execution.
The first nonblank line that does not begin with a TAB or # begins another target or macro definition.
Makefile Special Characters

••

Conditional dependency branch. When used in place of a colon (:) the double-colons allow a target to be checked and updated with respect to more than one dependency list The double-colons
allow the target to have more than one branch entry in the makefile, each with a different dependency list and a different rule. make checks each branch, in order of appearance, to see if the target is outdated with respect to its dependency list. If so, make updates the target according to
dependencies and rule for that branch.

#

Start a comment The comment ends at the next NEWLINE.

$

Macro expansion. See Macros, below, for details.
Following the TAB, if the first character of a command line is a -, make ignores any nonzero error
code it may return. make nonnally terminates when a command returns nonzero status, unless the
-i or -k options are in effect.

@

Following the TAB, if the first character is a @, make does not print the command line before executing it.
If - and @ appear as the first two characters after the TAB, both apply.

$$

Sun Release 3.2

The dollar-sign, escaped from macro expansion. Can be used to pass variable expressions beginning with $ to the shell.

Last change: 19 June 1986

263

MAKE(I)

USER COMMANDS

MAKE(1)

Command Execution
Command lines are executed one at a time, each by its own shell. Shell commands, notably cd, are ineffectual across an unescaped NEWLINE in the makefile. A line is printed (after macro expansion) as it is executed, unless it starts with a @, there is a .SILENT entry in the dependency hierarchy of the current target,
or make is run with the -s option. Although the -n option specifies printing without execution, lines containing the macro $(MAKE) are executed regardless, and lines containing the @ special character are
printed. The -t (touch) option updates the modification date of a file without executing any rules. This can
be dangerous when sources are maintained by more than one person.

To take advantage of the Bourne shell if control statement, use a command line of the form:
if expression ; \
then command ; \
command; \
elif command

\

else command
\
fi
Although composed of several input lines, the escaped NEWLINEs insure that make treats them all as one
command line. To take advantage of the Bourne shell for control statement, use a command line of the
form:
for var in list ; do \
command; \

done
To write shell variables, use double dollar-signs ($$). This escapes expansion of the dollar-sign by make.
Signals
INT and QUIT signals received from the keyboard cause make to halt, and to remove the target file being
processed (unless it is in the dependency list for .PRECIOUS).
Special-Function Targets
When incorporated in a makefile, the following target names perform special functions .
•DEFAULT

If this target is defined in the makefile, its rule is used when there is no entry in the make file
for a given target and none of the implicit rules applies. make ignores the dependency list
for this target.

•PRECIOUS

List of files not to delete. Files listed as dependencies for this target are not removed if
make is interrupted while rebuilding them.

.SILENT

Run silently. When this target appears in the make file, make does not echo commands
before executing them.

.IGNORE

Ignore errors. When this target appears in the make file, make ignores nonzero error codes
returned from commands .

•SUFFIXES

The suffixes list for selecting implicit rules (see Implicit Rules).

Include Files
make has an include file capability. If the word include appears as the first seven letters of a line, and is
followed by a SPACE or a TAB, the string that follows is taken as a filename. The text of the named file is
read in at the current location in the makefile. include files can be nested to a depth of no more than about

16.

264

Last change: 19 June 1986

Sun Release 3.2

MAKE ( 1)

USER COMMANDS

MAKE(I)

Macros

Entries of the form
macro-name =value

define macros. name is the name of the macro, and value, which consists of all characters up to a comment
character or unescaped NEWLINE, is the value. Words in a macro value are delimited by SPACE, TAB, and
escaped NEWLINE characters, and the terminating NEWLINE.
Subsequent references to the macro, of the forms: $(name) or ${name} are replaced by value. The
parentheses or brackets can be omitted in a reference to a macro with a single-character name.
Macros definitions can contain references to other macros, but the nested references aren't expanded
immediately. Instead, they are expanded along with references to the macro itself.
Substitutions within macros can be made as follows:
$(name :str1 =str2)

where str1 is either a suffix, or a word to be replaced in the macro definition, and str2 is the replacement
suffix or word.
Dynamically Maintained Macros

There are several dynamically maintained macros that are useful as abbreviations within rules.

$*

The basename of the current target. It is assigned only for implicit rules.

$<

The name of the file on which the target is assumed to depend. This macro is only assigned for
implicit rules, or within the .DEFAULT target's rule.

$@

The name of the current target. It is assigned only for rules in targets that are explicitly defined in
the make file.

$?

The list of dependencies with respect to which the target is out of date. This macro is assigned
only for explicit rules.

$%

The library member. The $% macro is only evaluated when the target is an archive library
member of the form: lib (file.o ). In this case, $@ evaluates to lib and $% evaluates to the library
member, file.o .

All of these macros but $? can be modified to apply either to the filename part, or the directory part of the
strings they stand for, by adding an upper case F or D, respectively (and enclosing the resulting name in
parentheses or braces). Thus, $(@D) refers to the directory part of the string $@. If there is no directory
part, • is generated.
Environment Variables and Macros

After reading in its implicit rules, make reads in variables from the environment, treating them as if they
were macro definitions. Only then does make read in a makefile. Thus, macro assignments within a
makefile override environment variables, provided that the -e option is not in effect. In turn, make exports
environment variables to each shell it invokes. Macros not read in from the environment are not exported.
The MAKEFLAGS macro is a special case. When present as an environment variable, make takes its
options (except for -f, -p, and -d) from MAKEFLAGS, in combination with any flags entered on the command line. make retains this combined value, exports it automatically to each shell it forks, and reads its
value to obtain options for any make commands it invokes. Note, however that flags passed with
MAKEFLAGS, even though they are in effect, are not shown in the output produced by make.
The MAKE macro is another special case. It has the value "make" by default, and temporarily overrides
the -0 option for any line that contains a reference to it This allows nested invocations of make written as:
$(MAKE) ...

to run recursively, so that the command make -n can be used to test an entire hierarchy of makefiles.

Sun Release 3.2

Last change: 19 June 1986

265

MAKE ( 1)

USER COMMANDS

MAKE(l)

For compatibility with the 4.2 BSD make, the MFLAGS macro is set from the MAKEFLAGS variable by
prepending a "_". MFLAGS is not exported automatically.
make supplies the following macros for compilers and their options:
CC
C compiler, ee(IV)
CFLAGS
C compiler options
FC
FORTRAN 77 compiler,j77(1)
FFLAGS
FORTRAN 77 compiler options
RFLAGS
FORTRAN 77 compiler options with Ratfor (.r) source
PC
Pascal compiler, pc (1)
PFLAGS
Pascal compiler options
M2C
Modula-2 compiler
M2FLAGS
Modula-2 compiler options
GET
sees (1) get command
GFLAGS
sees get options
AS
the assembler, as(l)
ASFLAGS
assembler options
LD
the linker, Id(l)
LDFLAGS
linker options
LEX
lex (1)
LFLAGS
lex options
YACC
yaee(l)
YFLAGS
yaee options
Unless these macros are read in as environment variables, their values are not exported by make. If you
run make with any these set in the environment, it is a good idea to add commentary to the makefile to indicate what value each takes. If -r is in effect, make ignores these macro definitions.

When set to a single-word value such as Ibin/csh, the SHELL macro indicates the name of an alternate
shell to use for invoking commands. Note, however, that to improve normal performance make executes
command lines that contain no shell metacharacters directly. Such builtin commands as dirs, or set in the
C-Shell are not recognized unless the command line includes a metacharacter (for instance, a semicolon).
Implicit Rules
make supplies implicit rules for certain types of targets that have no explicit rule defined in the makefile.
For these types of targets, make attempts to select an implicit rule by looking for an association between
the target and a file in the directory that shares its basename. That file, if found, is presumed to be a dependency file. The implicit rule is selected according to the target's suffix (which may be null), and that of the
dependency file. If there is no such dependency file, if the suffix of either dependency or target is not the
suffixes list, or if there is no implicit rule defined for that pair of suffixes, no rule is selected. make either
uses the default rule that you have supplied (if any), or stops.

The suffixes list is a target with each known suffix listed as a dependency, by default:

.SUFFIXES:.o .c .c- .mod .mod- .sym .def .def- .p.p- .f .f- .r .r- .y .y- .1 .1- .s .s.sh .sh- .h .hMultiple suffix-list targets accumulate; a .SUFFIXES target with no dependencies clears the list of suffixes.
Order is significant; make selects a rule that corresponds to the target's suffix and the first dependency-file
suffix found in the list
A tilde (-) refers to the s. prefix of an sces history file (see sees(I». If make cannot locate a history file
(with a name of the form s.basename.suffix) in the current working directory, it checks for one in the sees
subdirectory (if that directory exists) for one from which to get(l) the dependency file.
An implicit rule is a target of the form:

dt:
rule

where t is the suffix of the target, d is the suffix of the dependency, and rule is the implicit rule for building
such a target from such a dependency. Both d and t must appear in the suffixes list for make to recognize
the target as one that defines an implicit rule.
An implicit rule with only one suffix describes how to build a target having a null (or no) suffix, from a
dependency having the indicated suffix. For instance, the .c rule describes how to build the executable file
from a C source file,jile.e.

Implicit rules are supplied for the following suffixes and suffix pairs:

.c .c- .p .p- .mod .mod- .f .f .F .F- .r .r- .sh .sh- .c.o .c-.0 .c-.c .p.o .p-.0 .p-.p
.mod.o .mod-.o .mod-.mod .def.sym .def.sym .def-.def .f.o .f-.f .F.o .F-.o .F-.F .r.o

266

Last change: 19 June 1986

Sun Release 3.2

MAKE ( 1)

USER COMMANDS

MAKE(I)

.r .0 .r-.r .s.o .s-.0 .s- .s .sh-.sh .y.o .y-.0 .1.0 .1-.0 .y.c .y-.c .y .y .I.c .l-.c .1-.1 .c.a
.c-.a .s-.a .h-.h
These rules can be changed within a makefile, and additional implicit rules can be added. To print out
make's internal rules, use the following command (note that this command only works with the Bourne
Shell):
$ make -fp - 2>/dev/null /dev/tty) >&/dev/null
Library Maintenance
If a target name contains parentheses, as with:

lib .a(member)
it is assumed to be the name of an archive (ar(I» library. The string within the parentheses refers to a
member of the library. (If the string contains more than one word, the only first word is used.) A member
of an archive can be explicitly made to depend on a file with a matching filename. For instance, given a
directory that contains the files meml.c and mem2.c, along with a makefile with the entries:
lib.a: lib.a(mem1.o) lib.a(mem2.0)
lib.a(mem1.o): mem1.o
ar rv lib.a mem1.o
lib.a(mem2.o): mem2.o
ar rv lib.a mem2.o

make, when run, compiles the .c files into relocatable object (.0) files using the .c.o implicit rule. It then
loads the freshly compiled version of each file into the library according to the explicit rules in the 'lib.aO'
targets.
Implicit rules pertaining to archive libraries have the form .xx.a where the XX is the suffix from which the
archive member is to be made. An unfortunate byproduct of the current implementation requires that XX to
be different from the suffix of the archive member itself. For instance, the target Iib(file.o) cannot depend
upon the file.o explicitly, but instead, must be made to depend on a source file, such as file.c. For this reason it is recommended that you define an explicit target in the makefile for each library member to maintain, as shown above.
A target name of the form
library «entry-point»
refers to the member of a randomized object library (see ranlib(I» that defines the symbol entry-point.
EXAMPLES
This makefile says that pgm depends on two files a.o and b.o, and that they in tum depend on their
corresponding source files (a.c and b.c) along with a common file incl.h:

pgm: a.o b.o
cc a.o b.o -0 $@
a.o: incl.h a.c
cc -c a.c
b.o: incl.h b.c
cc-c b.c
The following makefile uses the builtin inference rules to express the same dependencies:
pgm: a.o b.o
cc a.o b.o -0 pgm
a.o b.o: incl.h

Sun Release 3.2

Last change: 19 June 1986

267

MAKE(l)

USER COMMANDS

MAKE(l)

FILES

[MmJ akefile
s.[MmJakefile
SCCSls.[mMJakefile
DIAGNOSTICS
Don't know how to make target. Stop.
There is no rnakefile entry for target, and none of make's implicit rules apply (there is no dependency file with a suffix in the suffixes list, or the target's suffix is not in the list).

*** target removed.
make was interrupted in the middle of trying to build target. Rather than leaving a partiallycompleted version that is newer than its dependencies, make removes the file associated with target.

*** Error code n.
The previous shell command returned a nonzero error code. In this case make stops, unless either
the -k or the -i option is set, the target .IGNORE appears, or the command is prefixed with a - in
the makefile.
SEE ALSO
cc(lV), ar(l), cd(l), get(I), lex(I), ranlib(I), sh(I), sccs(1)

Doing More with UNIX: Beginner's Guide
Make, in Programming Utilities for the Sun Workstation
BUGS

Some commands return nonzero status inappropriately; use -i to overcome the difficulty.
Filenames with the characters = : @ will not work.
You cannot build lib(file.o) from file.o.
The macro substitution $(a:.o=.c-) does not work.
Options supplied by MAKEFLAGS should appear in output from make.

268

Last change: 19 June 1986

Sun Release 3.2

MAN ( 1)

USER COMMANDS

MAN(l)

NAME

man - display reference manual pages; find reference pages by keyword
SYNOPSIS

man [ - ] [ -t] [ -M path] [ - T macro-pkg ] [[ section] title ... ] ...
man [ ":""M path] -k keyword . . .
man [ -M path] -f filename . . .
DESCRIPTION

man displays information from the reference manuals. It can display complete manual pages that you
select by title. It can display one-line summaries selected either by keyword (-k), or by the name of an
associatedfile (-f).
When neither -k nor -f is specified, man formats a specified set of manual pages by title. A section, when
given, applies to the titles that follow it on the command line (up to the next section, if any). man looks in
the indicated section of the manual for those titles. section is either a digit (perhaps followed by a single
letter indicating the type of manual page), or one of the words 'new,' 'local,' 'old,' or 'public.' If section is
omitted, man searches all reference sections (giving preference to commands over functions) and prints the
first manual page it finds. If no manual page is located, man prints an error message.
If the standard output is not a terminal, or if the - flag is given, man pipes its output through cat(l). Otherwise, man pipes its output through more(l) to handle paging and underlining on the screen.
OPTIONS
-t

man arranges for the specified manual pages to be troffed to a suitable raster output device (see
trolf(l) or vtrolf(l)). If both the - and -t flags are given, man updates the trolfed versions of each
named title (if necessary), but does not display them.

-Mpath
Change the search path for manual pages. path is a colon-separated list of directories that contain
manual page directory subtrees. For example, 'Iusrlmanlu_ man:lusrlman/a_man' makes man
search in the standard System V locations. When used with the -k or -f options, the -M option
must appear first.

- T macro-pkg
man uses macro-pkg rather than the standard -man macros defined in lusrllibltmac/tmac.an for
formatting manual pages.
-kkeyword . ..
man prints out one-line summaries from the whatis database (table of contents) that contain any of
the given keywords.
-f filename ...

man attempts to locate manual pages related to any of the given file s. It strips the leading pathname components from each filename, and then prints one-line summaries containing the resulting
basename or names.
MANUAL PAGES

Manual pages are troff(l)/nrolf(l) source files prepared with the -man macro package. Refer to man(7),
or Formatting Documents on the Sun Workstation for more information.
When formatting a manual page, man examines the first line to determine whether it requires special processing.
Referring to Other Manual Pages

If the first line of the manual page is a reference to another manual page entry fitting the pattern:
.so man?*lsourcefile
man processes the indicated file in place of the current one. The reference must be expressed as a pathname relative to to the root of the manual page directory subtree.

Sun Release 3.2

Last change: 11 July 1986

269

MAN(I)

USER COMMANDS

MAN ( 1)

When the second or any subsequent line starts with .so, man ignores it; troff(l) or nroff(l) processes the
request in the usual manner.
Preprocessing Manual Pages
If the first line is a string of the form:
'\" X

where X is separated from the the " by a single space and consists of any combination of characters in the
following list, man pipes its input to troff(1) or nroff(l) through the corresponding preprocessors.
c
cw(I), where available
eqn(l), or neqn(l) for nroff
e
p
pic(I), where available
r
re;(er(l)
t
tbl (1), and col (1) for nroff
v
vgrind(l)
If eqn or neqn is invoked, it will automatically read the file lusrlpubleqnchar (see eqnchar(7».
FILES

lusrlman
lusrlmanlman?1*
lusrlmanl cat? 1*
1usrlmanifmt? 1*
lusrlmanlwhatis
lusrllibltmacltmac .an
ENVIRONMENT
MAN PATH

PAGER
TCAT
TROFF

root of the standard manual page directory subtree
unformatted manual entries
nroffed manual entries
trofted manual entries
table of contents and keyword database
standard -man macro package

If set, its value overrides lusrlman as the default search path. (The -M flag, in turn, overrides this value.)
A program to use for interactively delivering man's output to the screen. If not set, more-s
is used.
The name of the program to use to display troffed manual pages. If not set, Ipr -t is used.
The name of the formatter to use when the -t flag is given. If not set, troiT is used.

SEE ALSO

cat(IV), col(IV), eqn(I), more(I), nroff(l), tbl(I), troff{l), whatis(1), man(7), catman(8)
BUGS

The manual is supposed to be reproducible either on a phototypesetter or on an ASCII terminal. However,
on a terminal some information (indicated by font changes, for instance) is necessarily lost.
Some dumb terminals cannot process the vertical motions produced by the e (eqn(l» preprocessing flag.
To prevent garbled output on these terminals, when you use e also use t, to invoke col(l) implicitly. This
workaround has the disadvantage of eliminating superscripts and subscripts--even on those terminals that
can display them. CTRL-Q will clear a terminal that gets confused by eqn(l) output.

270

Last change: 11 July 1986

Sun Release 3.2

MESO ( 1)

USER COMMANDS

MESO ( 1)

NAME

mesg - permit or deny messages
SYNOPSIS

mesg [n] [y]
DESCRIPTION

Mesg with argument n forbids messages via write(l) by revoking non-user write permission on the user's
terminal. Mesg with argument y reinstates permission. All by itself, mesg reports the current state without
changing it.
FILES

ldev/tty*
SEE ALSO

write(I), ta1k(I)
DIAGNOSTICS

Exit status is 0 if messages are receivable, 1 if not, 2 on error.

Sun Release 3.2

Last change: 16 February 1984

271

MKDIR( 1)

USER COMMANDS

MKDIR(I)

NAME

mkdir - make a directory
SYNOPSIS

mkdir dimame ••.
DESCRIPTION
Mkdir creates directories. Standard entries, '.', for the directory itself, and ' •• ' for its parent, are made

automatically.
The current umask(2) setting determines the mode in which directories are created. Modes may be
modified after creation by using chmod(IV).
Mkdir requires write permission in the parent directory.
SEE ALSO

chmod(IV), rnndir(I),rEn(l)

272

Last change: 15 March 1983

Sun Release 3.2

MKSTR(l)

USER COMMANDS

MKSTR(l)

NAME

mkstr - create an error message file by massaging C source
SYNOPSIS

mkstr [ - ] messagefile prefix file •••
DESCRIPTION
Mkstr creates files of error messages. You can use mkstr to make programs with large numbers of error

diagnostics much smaller, and to reduce system overhead in running the program do not have to be constantly swapped in and out.

as the error messages

Mkstr processes each of the specified files, placing a massaged version of the input file in a file whose name
consists of the specified prefix and the original name. A typical example of using mkstr would be:

mks tr pistrings xx *.c
This command would cause all the error messages from the C source files in the current directory to be
placed in the file pistrings and processed copies of the source for these files to be placed in files whose
names are prefixed with xx.
To process the error messages in the source to the message file, mkstr keys on the string 'error('" in the
input stream. Each time it occurs, the C string starting at the "" is placed in the message file followed by a
null character and a new-line character; the null character terminates the message so it can be easily used
when retrieved, the new-line character makes it possible to sensibly cat the error message file to see its
contents. The massaged copy of the input file then contains a {seek pointer into the file which can be used
to retrieve the message, that is:

char
int

efilnameO
efil = -1;

=

"/usr/lib/pi_strings";

error(al, a2, a3, a4)
{

char buf[256];
if (efil < 0) {
efil = open(efilname, 0);
if (efil < 0) {

oops:
perror( efilname);
exit(I);
}
}
if (lseek(efil, (long) aI, 0)

II read(efil, buf, 256) <= 0)

goto oops;
printf(buf, a2, a3, a4);
}
OPTIONS

Place error messages at the end of the specified message file for recompiling part of a large mkstr' d
program.
SEE ALSO

xstr(l)

Sun Release 3.2

Last change: 1 November 1983

273

MORE ( 1)

USER COMMANDS

MORE ( 1)

NAME

more, page - browse through a text file
SYNOPSIS

more [ -cdOsu] [ -lines] [+linenumber] [+Ipattern] [name .•• ]
page [ -cdflsu] [ -lines] [ +linenumber] [ +1pattern] [ name. •• ]
DESCRIPTION

More is a filter which displays the contents of a text file one screenful at a time on a video terminal. It normally pauses after each screenful, and prints '--More--' at the bottom of the screen. More displays another
line if you type a carriage-return; more displays another screenful if you type a space.
If you use the page command instead of the more command, the screen is cleared before each screenful is
displayed (but only if a full screenful is being displayed), and k - 1 rather than k - 2 lines are displayed in
each screenful, where k is the number of lines the terminal can display.

More looks in the file /etc!termeap 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.
More 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 esh command "setenv MORE -e" or the sh command
sequence "MORE=' -e' ; export MORE" would cause all invocations of more, including invocations by
programs such as man to use this mode. Normally, the user will place the command sequence which sets
up the MORE environment variable in the .login or .profile file.
If more is reading from a file, rather than a pipe, a percentage is displayed along with the --More-- prompt.

This gives the fraction of the file (in characters, not lines) that has been read so far.
Other sequences which may be typed when more pauses, and their effects, are as follows (i is an optional
integer argument, defaulting to 1) :
i
display i more lines, (or another screenful if no argument is given)
AD

display 11 more lines (a "scroll"). If i is given, the scroll size is set to i .

d

same as AD (control-D)

iz

same as typing a space except that i, if present, 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 rrwre.
Display the current line number.
v

Start up the editor vi at the current line.

h

Help command; give a description of all the more commands.

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), the position in the file remains unchanged.
Otherwise, a screenful is displayed, starting two lines before the place where the expression was
found, or the end of the pipe, whichever comes first. 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.

274

Last change: 13 March 1984

Sun Release 3.2

MORE ( 1)

USER COMMANDS

MORE(I)

!command
invoke a shell with command. The characters '%' and '!' 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 n\%" and n\!" are replaced by n%n and n!" 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, more goes back to the beginning of the file. If i doesn't make sense, more skips
back to the first file. If more 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 more (same as q or Q).
(dot) repeat the previous command.
The commands take effect immediately; it is not necessary to type a carriage return. Up to the time when
the command character itself is given, the user may type the line kill character to cancel the numerical
argument being formed. In addition, the user may type the erase character to redisplay the --More--(xx%)
message.
At any time when output is being sent to the terminal, the user can type the quit key (normally control-\).
More stops sending output, and displays 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.

More sets the terminal to noecho mode so that the output can be continuous. Thus what you type does not
show on your terminal, except for the / and! commands.
If the standard output is not a terminal, more acts just like cat, except that a header is printed before each
file in a series.
OPTIONS

-lines

Set the size of the window to lines lines long instead of the default.

-c

Display each page by redrawing the screen instead of scrolling. This makes it easier to read text
while more is writing. This option is ignored if the terminal does not have the ability to clear to
the end of a line.

-d

Display the message 'Hit space to continue, Rubout to abort' at the end of each screenful. This is
useful if more is being used as a filter in some setting, such as a class, where users are unsophisticated.

-f

Count logical rather than screen lines. That is, long lines are not folded. This option is recommended if nroff output is being piped through ul, since the latter may generate escape sequences.
These escape sequences contain characters which would ordinarily occupy screen postions, but
which do not print when they are sent to the terminal as part of an escape sequence. Thus more
may think that lines are longer than they actually are, and fold lines erroneously.

-I

Do not treat "L (form feed) specially. If -I is not used, more pauses 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
is cleared before the file is printed.

-s

Squeeze mUltiple blank lines from the output, and replace them with single blank lines. Especially
helpful when viewing nroff output, this option maximizes the useful information present on the
screen.

-u

Normally, more handles underlining such as produced by nroffin a manner appropriate to the particular terminal: if the terminal can perform underlining or has a stand-out mode, more outputs
appropriate escape sequences to enable underlining or stand-out mode for underlined information
in the source file. The -u option suppresses this processing.

+Iinenumber

Sun Release 3.2

Last change: 13 March 1984

275

MORE ( 1)

USER COMMANDS

MORE(I)

Start up at linenumber.
+/pattern
Start up two lines before the line containing the regular expression pattern. Note that unlike with
editors, the construct should not end with a /. If it does, then the trailing slash is taken as a character in the search pattern.
EXAMPLES
A sample usage of more in previewing nroff output would be

nroff -ms +2 doc.n I more -s
FILES

/etc/termcap
Terminal data base
/usrllib/more.helpHelp file
SEE ALSO
csh(l), man(I), script(I), sh(I), environ(5V), termcap(5)

276

Last change: 13 March 1984

Sun Release 3.2

MT(I)

USER COMMANDS

MT(I)

NAME

mt - magnetic tape manipulating program
SYNOPSIS

mt [ -f tapename ] command [ count]
DESCRIPTION

sends commands to a magnetic tape drive. If tapename is not specified, the environment variable TAPE
is used; if TAPE does not exist, mt uses the device Idevlrmt12. Note that tapename must reference a raw
(not block) tape device. By default mt performs the requested operation once. Operations may be performed multiple times by specifying count.

mt

The available commands are listed below. Only as many characters as are required to uniquely identify a
command need be specified.
eof, weof
Write count end-of-file marks at the current position on the tape.
fsf

Forward space count files.

fsr

Forward space count records.

bsf

Back space count files.

bsr

Back space count records.

For the following commands, count is ignored:
rewind Rewind the tape.
offline, rewoffl
Rewind the tape and place the tape unit off-line.
status

Print status information about the tape unit

retension
Wind the tape to the end of the reel and then rewind it, smoothing out the tape tension.
(count is ignored.)
erase

Erase the entire tape.

mt returns a 0 exit status when the operation(s) were successful, 1 if the command was unrecognized, and 2
if an operation failed.
FILES

ldev/rmt*
Raw magnetic tape interface
/dev/rar*
Raw Archive cartridge tape interface
/dev/rst* Raw SCSI tape interface
/dev/rxt*
Raw Xylogics tape interface
SEE ALSO

mtio(4), dd(l), environ(5V)
BUGS

Not all devices support all options. For example, ar(4S) and st(4S) currently do not support the fsr, bsf, or
bsr options; but they are the only only ones that currently support the retension and rewind options.
Nine-track tapes, in particular, do not support the retension option.

Sun Release 3.2

Last change: 23 September 1985

277

MV(I)

USER COMMANDS

MV(I)

NAME
~v

- move or rename files

SYNOPSIS
mv [ -i ] [ -f] [ - ] filename1 filename2

mv [ -i ] [ -f] [ - ] directory1 directory2
mv [ -i ] [ -f] [ - ] filename . .. directory . .. directory
DESCRIPTION
my moves files and directories around in the file system. A side effect of my is to rename a file or directory. The three major forms of my are shown in the synopsis above.

The first form of mv moves (changes the name ot) filename1 to filename2. If filename2 already exists, it is
removed before filename1 is moved. If filename2 has a mode which forbids writing, my prints the mode
(see chmod(2» and reads the standard input to obtain a line; if the line begins with y, the move takes place,
otherwise mY exits.
The second form of mv moves (changes the name ot) directory1 to directory2 , ONLY if directory2 does not
already exist - if it does, the third form applies.
The third form of my moves one or more files and directories, with their original names, into the last directory in the list.
my refuses to move a file or directory onto itself.

OPTIONS
-i

-f

interactive mode: mv displays the name of the file or directory followed by a question mark whenever a move would replace an existing file or directory. If you type a line starting with 'y', mv
moves the specified file or directory, otherwise my does nothing with that file or directory.
force: override any mode restrictions and the -i switch. The -f option also suppresses any warning messages about modes which would potentially restrict overwriting.
Interpret all the following arguments to my as file names. This allows file names starting with
minus.

SEE ALSO
cp(I),ln(l)
BUGS

If filename1 and filename2 are on different file systems, then my must copy the file and delete the original.
In this case the owner name becomes that of the copying process and any linking relationship with other
files is lost.
my will not move a directory from one file system to another.

278

Last change: 23 September 1985

Sun Release 3.2

NICE ( 1)

USER COMMANDS

NICE ( 1)

NAME

nice - run a command at low priority
SYNOPSIS
nice [ -number] command [ arguments]
DESCRIPTION
There are two distinct versions of nice: it is built in to the C-Shell, and is an executable program available
in !bin/nice for use with the Bourne shell.

nice executes command with a higher "nice" value. The higher the value, the lower the command's
scheduling priority. If the number argument is present, the nice value is incremented by that amount, up to
a limit of 20. The default number is 10.
The super-user may run commands with priority higher than normal by using a negative nice value, such as

'-10'.
SEE ALSO
csh(l), nice(3C), renice(8)
DIAGNOSTICS
nice returns the exit status of the subject command.
BUGS

The nice C-Shell built-in has a slightly different syntax than the nice command described here. When
using the built-in, the additional + option, as in:
nice +n
sets the nice value to n rather than incrementing by n.
Although you can increase the nice value for any process you own, only the super-user can decrement that
value.

Sun Release 3.2

Last change: 17 July 1986

279

NL(I)

USER COMMANDS

NL(I)

NAME

nl- line numbering filter
SYNOPSIS
01 [ -b type] [ -b type] [ -ftype] [ -v start] [ -iincr] [ -p] [ -Inum] [ -ssep] [ -wwidth]

[ -ofmt] [ -ddelim ] filename
DESCRIPTION
nl reads lines from filename (or the standard input), numbers them according to the options in effect, and
sends its output to the standard output.

nl views the text it reads in terms of logical pages. Line numbering is normally reset at the start of each
page. A logical page is composed of header, body and footer sections. The start of each page section is signaled by input lines containing section delimiters only:
Start offile

\:\:\:
header

\:\:
body

\:
footer
Empty sections are valid. Different line-numbering options are available within each section. The default
scheme is no numbering for headers and footers.
OPTIONS
-b type

280

Specifies which logical page body lines are to be numbered. type is one of:
a
number all lines
t
number lines with printable text only (the default)
o,
no line numbering
p rexp number only lines that contain the regular expression rexp

-b type

Same as -b type except for the header. The default type for the logical page header is
lines numbered).

-ftype

Same as -b type except for the footer. The default for logical page footer is 0 (no lines numbered).

-p

Do not restart numbering at logical page delimiters.

-v start

start is the initial value used to number logical page lines. The default is 1.

-i incr

incr is the increment by which to number logical page lines. The default is 1.

-ssep

sep is the character(s) used to separate the line number from the corresponding text line. The
default is a TAB.

-w width

width is the number of characters to be used for the line-number field. The default is 6.

-ofmt

fmt is the line numbering format Recognized values are:
ro
right justified, leading zeroes supressed (the default)
In
left justified, leading zeroes suppressed
rz
right justified, leading zeroes kept

-I num

num is the number of blank lines to be considered as one. For example, -12 results in only
the second adjacent blank being numbered (if the appropriate -ba, -ba, and/or -fa option is
set). The default is 1.

Last change:

0

(no

Sun Release 3.2

NL(I)

USER COMMANDS

-d n

NL(l)

The delimiter characters specifying the start of a logical page section may be changed from
the default characters (\:) to two user-specified characters. If only one character is entered,
the second character remains the default character (:). No space should appear between the
-d and the delimiter characters. To enter a backslash, use two backslashes.

EXAMPLE

The command:

nl-vlO -itO -d!+ filel
will number filel starting at line number 10 with an increment of ten. The logical page delimiters are !+.
SEE ALSO

pr(l)

Sun Release 3.2

Last change:

281

NM(I)

USER COMMANDS

NM(I)

NAME

nm - print name list
SYNOPSIS
om [ -gooprua] [ [filename] ...
DESCRIPTION

Nm prints the name list (symbol table) of each object filename in the argument list If an argument is an
archive, a listing for each object file in the archive will be produced. If no filename is given, the symbols in
a.out are listed.

Each symbol name is preceded by its value (blanks if undefined) and one of the letters:
A

absolute

B

bsssegmentsymbol

C

common symbol

D

data segment symbol

f

filename

T

text segment symbol

U

undefined
debug, giving symbol table entries (see -a below)

The type letter is upper case if the symbol is external, and lower case if it is local. The output is sorted
alphabetically.
OPTIONS

-g

Print only global (external) symbols.

-0

Sort numerically rather than alphabetically.

-0

Prepend file or archive element name to each output line rather than only once.

-p

Don't sort; print in symbol-table order.

-r

Sort in reverse order.

-u

Print only undefined symbols.

-a

Print all symbols.

EXAMPLE

nm
prints the symbol list of a.out, the default output file for the C, FORTRAN 77 and Pascal compilers.
SEE ALSO

ar(l), ar(5), a.out(5)

282

Last change: 9 June 1983

Sun Release 3.2

USER COMMANDS

NOHUP(IV)

NOHUP(IV)

NAME

nohup - run a command immune to hangups and quits
SYNOPSIS
nohup command [ arguments]
DESCRIPTION
There are three distinct versions of nohup: it is built in to the C-Shell, and is an executable program available in lusr/binlnohup and lusr/5binlnohup when using the Bourne shell.

nohup executes command such that it is immune to HUP (hang up) and QUIT (quit) signals. If the standard
output is a terminal, it is redirected to the file nohup.out. If nohup.out is not writable in the current directory, output is redirected to $HOME/nohup.out. If the standard error is a terminal, it is redirected to the
standard output.
The priority is incremented by 5. nohup should be invoked from the shell with '&' in order to prevent it
from responding to interrupts or input from the next user.
EXAMPLE
It is frequently desirable to apply nohup to pipelines or lists of commands. This can be done only by placing pipelines and command lists in a single file, called a shell script. The command

manual % nohup sh script
applies to everything in script. (If the script is to be executed often, then the need to type sh can be eliminated by giving script execute permission). Add an ampersand and the contents of script are run in the
background with interrupts also ignored (see sh(I»:
manual % nohup script &
FILES

nohup.out
$HOME/nohup.out
SEE ALSO
chmod(lV), nice(I), sh(l), signal(2)
BUGS

If you use csh(I), then commands executed with '&' are automatically immune to HUP signals while in the
background.
There is a C-Shell built-in command nohup which provides immunity from terminate, but it does not
redirect output to nohup.out.
WARNINGS
nohup command 1; command2----- nohup applies only to command1
nohup (commandl; command2)
is syntactically incorrect.

Be careful of where standard error is redirected. The following command may put error messages on tape,
making it unreadable:
nohup cpio -0 /dev/rmt/lm&
while
nohup cpio -0 /dev/rmt/lm 2>errors&
puts the error messages into file errors.

Sun Release 3.2

Last change: 18 July 1986

283

NROFF(1)

USER COMMANDS

NROFF( 1)

NAME

nroff - format documents for display or line-printer
SYNOPSIS
orotT [ -opagelist] [ -oN] [ -sN] [ -m name] [ -r aN] [ -i ] [ -q] [ - T name ]
[ -e ] [ -h ] [filename] ...
DESCRIPTION

nrolfformats text in the named files for typewriter-like devices. See also trolf(1). The full capabilities of
nrolf and trolf are described in Formatting Documents with Nroff and Troff.
If no file argument is present, nrolf reads the standard input An argument consisting of a single minus (-)
is taken to be a file name corresponding to the standard input.
OPTIONS
Options may appear in any order so long as they appear before the files.

-olist

Print only pages whose page numbers appear in the comma-separated list of numbers and ranges.
A range N -M means pages N through M; an initial-N means from the beginning to page N; and a
final N - means from N to the end.

-oN

Number first generated page N.

-sN

Stop every N pages. nroff will halt prior to every N pages (default N = 1) to allow paper loading or
changing, and will resume upon receipt of a newline.

-mname
Prepend the macro file lusrllibltmacltmac.name to the input files.

-raN

Set register a (one-character) to N.

-i

Read standard input after the input files are exhausted

-q

Invoke the simultaneous input-output mode of the rd request.

-Tname
Prepare output for a device of the specified name. Known name s are:
37
Teletype Corporation Model 37 terminal- this is the default.
ert I Jpr I tn300
GE TermiNet 300, or any line printer or terminal without half-line capability.
DASI-300.
300
300-12 DASI-300 - 12-pitch.
300S I 302 I dte
DASI-300S.
300S-12 I 302-12 I dte12
DASI-300S.
382
DASI-382 (fancy DTC 382).
382-12 DASI-82 (fancy DTC 382 - 12-pitch).
450 I ipsi
DASI450 (Diablo Hyterm).
450-12 I ipsi12
DASI450 (Diablo Hyterm) - 12-pitch.
450-12-8 DASI450 (Diablo Hyterm) - 12-pitch and 8 lines-per-inch.
450X
DASI450X (Diablo Hyterm).
832
AI 832.
833
AI 833.
832-12 AI 832 - 12-pitch.
833-12 AI 833 -12-pitch.
itoh
C:ITOH Prowriter.
itoh-12 C:ITOH Prowriter - 12-pitch.

284

Last change: 16 June 1986

Sun Release 3.2

NROFF( 1)

USER COMMANDS

nee
nec12
nec-t
qume
qume12
xerox
xerox12
x-ecs
x-ecs12

NROFF( 1)

NEe 55?0 or NEe 77?0 Spinwriter.
NEe 55?0 or NEe 77?0 Spinwriter - 12-pitch.
NEe 55?0177?0 Spinwriter - Tech-MathlTimes-Roman thimble.

Qume Sprint - 5 or 9.
Qume Sprint - 5 or 9, 12-pitch.
Xerox 17'10 or Diablo 16'10.
Xerox 17'10 or Diablo 16'10 - 12-pitch.
Xerox/Diablo 1730/630 - Extended Character Set.
Xerox/Diablo 1730/630 - Extended Character Set, 12-pitch.

-e

Produce equally-spaced words in adjusted lines, using full terminal resolution.

-b

Use output tabs during horizontal spacing to speed output and reduce output character count. Tab
settings are assumed to be every 8 nominal character widths.

EXAMPLE

gaia% nroff -s4 -me users.guide
Formats users .guide using the -me macro package, and stopping every 4 pages.
FILES

Itmp/ta*
temporary file
lusr/lib/tmac/tmac. * standard macro files
lusr/lib/terml*
terminal driving tables for nroff
lusrllib/termlREADMEindex to terminal description files
SEE ALSO

troff(l), eqn(l), tbl(I), ms(7), me(7), man(7), col(IV), checknr(l), term(5V)
Formatting Documents on the Sun Workstation
Using nroff and troff on the Sun Workstation

Sun Release 3.2

Last change: 16 June 1986

285

OD( 1V)

USER COMMANDS

OD(IV)

NAME

od - octal, decimal, hex, ascii dump
SYNOPSIS
od [ -format] [file] [[+ ]offset[.] [b] [label] ]
DESCRIPTION
od displays file, or its standard input, in one or more dump formats as selected by the first argument. If the
first argument is missing, -0 (octal) is the default Dumping continues until end-of-file.

The meanings of the format argument characters are:
3

Interpret bytes as characters and display them with their ASCII names. If the p character is given
also, bytes with even parity are underlined. If the P character is given, bytes with odd parity are
underlined. Otherwise the parity bit is ignored.

b

Interpret bytes as unsigned octal.

c

Interpret bytes as ASCII characters. Certain non-graphic characters appear as C escapes: null=\O,
backspace=\b, forrnfeed=\f, newline=\n, retum=\r, tab=\t; others appear as 3-digit octal numbers.
Bytes with the parity bit set are displayed in octal.

d

Interpret (short) words as unsigned decimal.

f

Interpret long words as floating point

h

Interpret (short) words as unsigned hexadecimal.
Interpret (short) words as signed decimal.
Interpret long words as signed decimal.

o

Interpret (short) words as unsigned octal.

s[n]

Look for strings of ASCII graphic characters, terminated with a null byte. n specifies the minimum
length string to be recognized. By default, the minimum length is 3 characters.

v

Show all data. By default, display lines that are identical to the last line shown are not output, but are
indicated with an "*" in column 1.

w[n] Specifies the number of input bytes to be interpreted and displayed on each output line. If w is not

specified, 16 bytes are read for each display line. If n is not specified, it defaults to 32.
x

Interpret (short) words as hexadecimal.

An upper case format character implies the long or double precision form of the object
The offset argument specifies the byte offset into the file where dumping is to commence. By default this
argument is interpreted in octal. A different radix can be specified; if . is appended to the argument, then
offset is interpreted in decimal. If offset begins with x or Ox, it is interpreted in hexadecimal. If b (8) is
appended, the offset is interpreted as a block count, where a block is 512 (1024) bytes. If thefile argument
is omitted, thhe offset argument must be preceded by +.
The radix of the displayed address will be the same as the radix of the offset, if specified; otherwise it will
be octal.

label will be interpreted as a pseudo-address for the first byte displayed. It will be shown in "0" following the file offset. It is intended to be used with core images to indicate the real memory address. The syntax for label is identical to that for offset.
SYSTEM V DESCRIPTION
The 3, f, h, I, v, and w formats are not supported. The s format interprets (short) words as signed decimal,
rather than searching for strings. The options for interpreting long or double-precision forms are not supported. The label argument is not supported. The B suffix to the offset argument is not supported.

286

Last change: 17 July 1986

Sun Release 3.2

OD( IV)

USER COMMANDS

OD( IV)

SEE ALSO

adb(I), dbxtool(I), dbx(l)

BUGS
A file name argument can't start with +. A hexadecimal offset can't be a block count. Only one file name
argument can be given.
It is an historical botch to require specification of object, radix, and sign representation in a single character
argument

Sun Release 3.2

Last change: 17 July 1986

287

ONe lC)

USER COMMANDS

ON( lC)

NAME

on - execute a command remotely
SYNOPSIS
00 [

-i ] [ -0] [ -d] host command [ argument] ...

DESCRIPTION

The on program is used to execute commands on another system, in an environment similar to that invoking the program. All environment variables are passed, and the current working directory is preserved. To
preserve the working directory, the working file system must be either already mounted on the host or be
exported to it. Relative path names will only work if they are within the current file system; absolute path
names may cause problems.
Standard input is connected to standard input of the remote command, and standard output and standard
error from the remote command are sent to the corresponding files for the on command.
OPTIONS

-i

Interactive mode: use remote echoing and special character processing. This option is
needed for programs that expect to be talking to a terminal. All terminal modes and window size changes are propagated.

-0

No Input this option causes the remote program to get end-of-file when it reads from
standard input, instead of passing standard input from the standard input of the on program. For example, -0 is necessary when running commands in the background with job
control.

-d

Debug mode: print out some messages as work is being done.

SEE ALSO
rexd(8), exports(5)
DIAGNOSTICS

unknown host
cannot connect to server
can't find.
can't locate mount point

Host name not found
Host down or not running the server
Problem finding the working directory
Problem finding current file system

Other error messages may be passed back from the server.
BUGS

The SunView window system can get confused by the environment variables.

288

Last change: 07 November 1985

Sun Release 3.2

OVERVIEW ( 1 )

USER COMMANDS

OVERVIEW(l)

NAME

overview - run a program from SunView that takes over the screen
SYNOPSIS

overview [generic_toolJags] program_name [ arguments] ...
DESCRIPTION

Bitmap graphics based programs that are not SunView based can be run from SunView using overview.
Overview shows an icon in SunView when overview is brought up iconic (-Wi flag) or when the program
being run by overview is suspended (for example using ctrl-Z). Opening the overview icon, or starting
overview non-iconic, starts the program named on the command line. Overview supresses SunView so that
SunView window applications won't interfere with the program's display output or input devices.
Overview is mainly designed to run programs that fit the following profile:
own display
The program needs to own the bits on the screen. It doesn't use the sunwindow or suntool
libraries to arbitrate the use of the display and input devices between processes.
keyboard input from stdin
The program takes keyboard input from stdin directly.
mouse input from Idevlmouse
The program takes locator input from the mouse directly.
SEE ALSO

Windows and Window-Based Tools: Beginner's Guide
BUGS

Users of overview on a Prism need to be aware of the existence of plane groups for pre-3.2 applications.
You can't successfully run pre-3.2 applications under overview if overview itself is running in the color
buffer. If you start overview so that it is not running in the overlay plane then the enable plane wouldn't be
properly set up for viewing of the application running under overview. This means that you can't run overview with the -Wf or -Wb flags. Also, you can't run overview on a desktop created by sun tools using the
-8bit_color_only option.
NAME

pack, peat, unpack - compress and expand files
SYNOPSIS

pack [ - ] [ -f] filename ...
pcat filename . ..
unpackfilename ...
DESCRIPTION

pack attempts to store the specified files in a packed form using Huffman (minimum redundancy) codes on
a byte-by-byte basis. Wherever possible (and useful), each input file filename is replaced by a packed file
filename.z with the same access modes, access and modified dates, and owner as those of filename. If pack
is successful, filename will be removed.
Packed files can be restored to their original form using unpack or pcat.
The amount of compression obtained depends on the size of the input file and the frequency distribution of
its characters.
Because a decoding tree forms the first part of each .z file, it is usually not worthwhile to pack files smaller
than three blocks unless the distribution of characters is very skewed. This may occur with printer plots or
pictures.

Sun Release 3.2

Last change: 9 April 1986

289

PACK ( 1)

USER COMMANDS

PACK ( 1)

Typically, large text-files are reduced to 60-75% of their original size. Load modules, which use a larger
character set and have a more uniform distribution of characters, show little compression. Their packed
versions come it?- at about 90% of the original size.
No packing will occur if:
the file appears to be already packed
the file name has more than 12 characters
the file has links
the file is a directory
the file cannot be opened
no disk storage blocks will be saved by packing
a file called name.z already exists
the .z file cannot be created
an I/O error occurred during processing
The last segment of the filename must contain no more than 12 characters to allow space for the appended
.z extension. Directories cannot be packed.
.

pcat does for packed files what cat (1 V) does for ordinary files, except that pcat cannot be used as a filter.
The specified files are unpacked and written to the standard output. To view a packed file named name.z
use:
peat filename .z
or just:

peat filename
To make an unpacked copy without destroying the packed version, use

peat filename> newname
Failure may occur if:
the filename (exclusive of the .z) has more than 12 characters;
the file cannot be opened;
the file does not appear to be the output of pack.

unpack expands files created by pack. For each file name specified in the command, a search is made for a
file called name.z (or just name, if name ends in .z). If this file appears to be a packed, it is replaced by its
expanded version. The new file has the .z suffix stripped from its name, and has the same access modes,
access and modification dates, and owner as those of the packed file. Failure may occur for the same reasons that it may in pcat, as well as for the following:
a file with the "unpacked" name already exists
the unpacked file cannot be created.
OPTIONS

Print compression statistics for the following filename or names on the standard output. Subsequent -'s between filenames toggle statistics off and on.

-f

Force packing of filename. This is useful for causing an entire directory to be packed, even if
some of the files will not benefit.

DIAGNOSTICS
pack returns the number of files that it failed to compress.

peat returns the number of files it was unable to unpack.
unpack returns the number of files it was unable to unpack.
SEE ALSO
cat( 1), compact( 1)

290

Last change: 9 Apri11986

Sun Release 3.2

PAGESIZE ( 1 )

USER COMMANDS

PAGESIZE ( 1 )

NAME

pagesize - print system page size
SYNOPSIS

pagesize
DESCRIPTION
Pagesize prints the size of a page of memory in bytes, as returned by getpagesize(2). This program is useful in constructing portable shell scripts.
SEE ALSO
getpagesize(2)

Sun Release 3.2

Last change: 3 April 1983

291

PASSWD(l)

USER COMMANDS

PASSWD( 1)

NAME

passwd - change login password
SYNOPSIS

passwd [ -f filename] [ username ]
DESCRIPTION

This command changes (or installs) a password associated with the username (your own by default).
passwd prompts for the old password and then for the new one. You must supply both, and the new password must be typed twice to forestall mistakes.

New passwords should be at least five characters long, if they combine upper and lower-case characters, or
at least six characters long if in monocase. Users that persist in entering shorter passwords are compromising their own security.
Only the owner of the name or the super-user may change a password; the owner must prove he knows the
old password.
Use yppasswd to change your password in the network yellow pages. This will not affect your local password, or your password on any remote machines on which you have accounts.
OPTIONS
-f

Treat file as the password file.

FILES

/etc/passwd
/etc/yp/passwd
SEE ALSO

login(l), passwd(5), yppasswd(l)
Robert Morris and Ken Thompson, UNIX Password Security

BUGS
passwd will change a local password, but not a password in the network Yellow Pages. Refer to
yppasswd(l) for information on how to change a Yellow Pages password.

292

Last change: 23 September 1985

Sun Release 3.2

PASTE ( 1)

USER COMMANDS

PASTE(I )

NAME

paste - merge same lines of several files or subsequent lines of one file
SYNOPSIS
paste file 1 file2 ...
paste -dlist filel file2 ...
paste -s [ -dIist ] filel file2 ...
DESCRIPTION
In the first two forms, paste concatenates corresponding lines of the given input files filel , file2, etc. It
treats each file as a column or columns of a table and pastes them together horizontally (parallel merging).
It is the counterpart of cat which concatenates vertically, i.e., one file after the other. In the last form
above, paste replaces the function of an older command with the same name by combining subsequent
lines of the input file (serial merging). In all cases, lines are glued together with the tab character, or with
characters from an optionally specified list. paste can be used as a filter, if - is used in place of a filename.
OPTIONS
-d

Without this option, the new-line characters of each but the last file (or last line in case of the-s
option) are replaced by a tab character. This option allows replacing the tab character by one or
more alternate characters in list. The list is used circularly, i.e., when exhausted, it is reused. In
parallel merging (i.e., no -s option), the lines from the last file are always terminated with a newline character, not from the list. list may contain the special escape sequences: \n (new-line), \t
(tab), \\ (backs lash), and \0 (empty string, not a null character). Quoting may be necessary, if
characters have special meaning to the shell.

-s

Merge subsequent lines rather than one from each input file. Use tab for concatenation, unless list
is specified with -d. Regardless of the list, the very last character of the file is forced to be a
new-line.

EXAMPLES
Is I paste -d" " -

Is

I paste -

- - -

paste -s -d"\ t\n" file

list directory in one column
list directory in four columns
combine pairs of lines into lines

SEE ALSO
cut(1), grep(l), pr( 1)
DIAGNOSTICS

line too long

Output lines are restricted to 511 characters.

too many files

Except for -s option, no more than 12 input files may be
specified.

Sun Release 3.2

Last change:

293

PC( 1)

USER COMMANDS

PC(1)

NAME

pc - Pascal compiler
SYNOPSIS

pc [ -align _block] [ -b ] [ -c] [ -C] [ -dryrun ] [ -Dname [=def] ] [float_option]
[ -g] [ -belp] [ -H ] [ -mame ... ] [ -Ipathname] [ -J ] [ -I] [ -Ilib ]
[ -lpfc] [ -L ] [ -0 ouifile ] [ -0] [ -p ] [ -pg] [ -pipe] [ -P ]
[ -Qoption prog opt] [ -Qpath pathname] [ -Qproduce sourcetype] [ -R ] [ -s ]
[-s ] [-tdir ] [ -temp=dir] [ -time] [ -Uname ] [ -v] [ -V] [ -w] [ -z ] [ -Z ] sourcefile ...
DESCRIPTION

pc is the Sun Pascal compiler. If given an argument file ending with .p, pc compiles the file and leaves the
result in an executable file, called a.out by default
A program may be separated into multiple.p files. pc compiles a number of .p files into object files (with
the extension .0 in place of .p). Object files may then be linked into an executable file. Exactly one object
file must supply a program statement to successfully create an executable file. The rest of the files must
consist only of declarations which logically nest within the program. References to objects shared between
separately compiled files are allowed if the objects are header files declared with include statements.
Names of header files must end with .h. Header files may only be included at the outermost level, and thus
declare only global objects. To allow external functions and procedures to be declared, an external
directive has been added, whose use is similar to the forward directive but restricted to appear only in .h
files. function and procedure bodies may not appear in .h files. A binding phase of the compiler checks
that declarations are used consistently, to enforce the type checking rules of Pascal.
Filenames ending in .il are taken to be in-line expansion code template files; these are used to expand calls
to selected routines in-line when the -0 option is in effect.
Object files created by other language processors may be linked together with object files created by pc.
The functions and procedures they define must have been declared in .h files included by all the .p files
which call those routines.
Pascal's calling conventions are compatible with those of C, with var parameters passed by address and
other parameters passed by value.

pc(1) supports ISO Level 1 Standard Pascal, including conformant array parameters. Deviations from the
ISO Standard are noted under BUGS below.
See the Pascal User's Manual for details.
OPTIONS

See ld(l) for link-time options.
-align _block

Cause the global symbol whose Pascal name is block to be page-aligned: its size is
increased to a whole number of pages, and its first byte is placed at the beginning of a
page.

-b

Buffer the file output in units of disk blocks, rather than lines.

-c

Suppress linking with Id(1) and produce a.o file for each source file.

-C

Compile code to perform subscript and subrange checks, and verify assert statements.
Note that pointers are not checked. This option differs significantly from the -C option of
the cc compiler.

-dryrun

Show but do not execute the commands constructed by the compilation driver.

-Dname[=def] Define a symbol name to the C preprocessor (cpp(1». Equivalent to a #define directive
in the source. If no def is given, name is defined as '1'.
float_option

Floating -point code generation option. Can be one of:

-f68881
in-line code for the Motorola 68881 floating-point coprocessor (supported only

294

Last change: 29 May 1986

Sun Release 3.2

PC( 1)

USER COMMANDS

PC( 1)

on Sun-3).
-ffpa

in-line code for the Sun Floating-Point Accelerator (supported only on Sun-3).

-fsky

in-line code for the Sky floating-point processor (supported only on Sun-2).

-fsoft

software floating-point calls (This is the default).

-fswitch
run-time-switched floating-point calls. The compiled object code is linked at
runtime to routines that support one of the above types of floating point code.
This was the default in previous releases. Only for use with programs that are
floating-point intensive, and which must be portable to machines with various
floating-point options.

-g

Produce additional symbol table information for dbx(l) and pass the -Ig flag to ld(l).

-help

Display helpful information about pc.

-H

Compile code to perform range checking on pointers into the heap.

-iname ...

Produce a listing for the specified procedures, functions and include files.

-Ipathname

Add pathname to the list of directories in which to search for #include files with relative
filenames (not beginning with slash I). The preprocessor first searches for #include files
in the directory containing sourcefile then in directories named with -I options (if any),
and finally, in lusrlinclude .
J

-J

Generate 32-bit offsets in switch statement labels.

-I

Make a program listing during translation.

-Ilib

Link with object library lib (for ld(1».

-Ipfc

Link with common startup code for programs containing mixed Pascal and FORTRAN 77
object files. Such programs should also be linked with the FORTRAN 77 libraries (see
FILES below).

-L

Map upper case letters in keywords and identifiers to lower case.

-ooutfile

Name the output file outfile. outfile must have the appropriate suffix for the type of file to
be produced by the compilation (see FILES, below). outfile cannot be the same as
sourcefile (the compiler will not overwrite the source file).

-0

Optimize the object code.

-p

Prepare the object code to collect data for profiling with prof(I). Invokes a run-time
recording mechanism that produces a mon.out file (at normal termination).

-pg

Prepare the object code to collect data for profiling with gprof(1). Invokes a run-time
recording mechanism that produces a gmon.out file (at normal termination).

-pipe

Use pipes, rather than intermediate files, between compilation stages. (Very cpuintensive.)

-P

Use partial evaluation semantics for the boolean operators and and or. For these operators only, left-to-right evaluation is guaranteed, and the second operand is evaluated only
if necessary to determine the result.

-Qoption prog opt
Pass the option opt to the program pro g. The option must be appropriate to that program
and may begin with a minus sign. prog can be one of: as, cpp, or Id.
-Qpath pathname
Insert directory pathname into the compilation search path (to use alternate versions of
programs invoked during compilation).

Sun Release 3.2

Last change: 29 May 1986

295

PC(I)

USER COMMANDS

PC( 1)

-Qproduce sourcetype
Produce source code of the type sourcetype. sourcetype can be one of:
.pi
Preprocessed Pascal source from cpp (1) .
•0
Object file from as (1) .
.s
Assembler source (from c2,j1 or inline).

-R
-s

Merge data segment with text segment for as(I).

-S

Compile the named program, and leave the assembly language output on the corresponding file suffixed.s. No.o is created.

-temp=dir

Set directory for temporary files to be dire

-time

Report execution times for the various compilation passes.

-Uname

Remove any initial definition of the cpp(l) symbol name. (Inverse of the -D option.)

-v

Verbose. Print the version number of the compiler and the name of each program it executes.

-v

Report hard errors for nonstandard Pascal constructs.

-w
-z

Suppress warning messages.

-z

Initialize local variables to zero.

Accept standard Pascal only; nonstandard constructs and extensions cause warning diagnostics.

Allow execution profiling with pxp(l) by generating statement counters, and arranging
for the creation of the profile data file pmon.out when the resulting object is executed.

Other arguments are taken to be linker option arguments or libraries of pc-compatible routines. Certain
flags can also be controlled by comments within the program, as described in the Pascal User's Manual in
the Sun Pascal Manual.
ENVIRONMENT
FLOAT_OPTION When no floating-point option is specified, the compiler uses the value of this environ-

ment variable (if set). Recognized values are: f68881, ffpa, fsky, fswitch and fsoft.
FILES

a.out
file .a
file .c
file.d
file .r
file.F
file .il
file .0
file.p
file .pi
file.r
file.s
file.S
file.tcov
lliblc2
Iliblcompile
Iliblcpp
lliblcrtO.o
Ilib!fl
lliblF crt1 .0
lliblgcrtO.o

296

executable output file
library of object files
C source file
tcov(1) test coverage input file
F77 source file
F77 source file for cpp (1)
inline expansion file
object file
Pascal source file
Pascal source after preprocessing with cpp (1)
Ratfor source file
assembler source file
assembler source for cpp(l)
output from tcov(l)
object code optimizer
compiler command-line processing driver
macro preprocessor
runtime startoff
code generator
startup code for -rsoft option
startoff for profiling with gprof( 1)

Last change: 29 May 1986

Sun Release 3.2

PC( 1)

USER COMMANDS

llibllibc.a
lliblmcrtO.o
lliblMcrtl.o
lliblScrtl.o
lliblWcrtl.o
lusrlinclude
lusrlliblhow yc
lusrllibllibc y.a
lusrllibllibF77.a
I usrlliblinline
lusrllibllibI77.a
lusrllibllibm.a
lusrllibllibpc.a
lusrllibllibpfc .a
lusrlliblpcO
lusrlliblpc2.il
I usrlliblpc3
lusrllibllibU77.a
Ioopl*

mon.out
gmon.out

PC(l )

standard library, see intro (3)
startoff for profiling with prof(l)
startup code for -f68881 option
startup code for -fsky option
startup code for -tTpa option
standard directory for #include files
basic usage explanation
profiling library, see intro (3)
FORTRAN 77 library
inline expander of library calls
FORTRAN 77 library
math library
intrinsic functions and Pascal 110 library
startup code for combined Pascal and FORTRAN 77 programs
compiler front end
inline expansion templates for Pascal library
separate compilation consistency checker
FORTRAN 77 library
compiler temporary files
file produced for analysis by prof( 1)
file produced for analysis by gprof(l) intro(3)

SEE ALSO
pi(l), pxp(l), pxref(l)

Pascal Programmer's Guide
Floating-Point Programmer's Guide for the Sun Workstation
DIAGNOSTICS
For a basic explanation do
tutorial% pc
In the diagnostic output of the translator, lines containing syntax errors are listed with a flag indicating the
point of error. Diagnostic messages indicate the action which the recovery mechanism took in order to be
able to continue parsing. Some diagnostics indicate only that the input is 'malformed.' This occurs if the
recovery can find no simple correction to make the input syntactically valid
Semantic error diagnostics indicate a line in the source text near the point of error. Some errors evoke
more than one diagnostic to help pinpoint the error; the follow-up messages begin with an ellipsis ' ... '.
The first character of each error message indicates its class:
E
Fatal error; no code will be generated.
e
Nonfatal error.
w
Warning - a potential problem.
s
Nonstandard Pascal construct warning.

If a severe error occurs which inhibits further processing, the translator will give a diagnostic and then
'QUIT'.
Names whose definitions conflict with library definitions draw a warning. The library definition will be
replaced by the one supplied in the Pascal program. Note that this can have unpleasant side effects.
BUGS

The keyword packed is recognized but has no effect. The ISO standard requires packed and unpacked
structures to be distinguished for portability reasons.
Binary set operators are required to have operands with identical types; the ISO standard allows different
types, as long as the underlying base types are compatible.
The -z flag doesn't work for separately compiled files.

Sun Release 3.2

Last change: 29 May 1986

297

PERFMETER ( 1 )

USER COMMANDS

PERFMETER ( 1 )

NAME

perfmeter - meter display of system performance values
SYNOPSIS
perfmeter [ -s sample-time] [ -b h-hand-int] [ -m m-hand-int ]
[ -M smax minmax maxmax] [ -v value] [ hostname ]
DESCRIPTION
perfmeter starts a tool whose iconic form is a meter displaying a system performance value, and whose
open form is a strip chart of that value. By default, the meter is updated with a sample-time of 2 seconds.
The hour hand represents the average over a 20-second interval; the minute hand, an average over 2
seconds. The default value displayed is the percent of cpu being utilized.

These defaults can be modified with command line options, or dynamically after the tool has been started
using a popup menu.

If there is no hostname argument, then the data displayed will be for the local host In either case, the
rstatd(8C) daemon must be running on the machine for which statistics are being reported.
The maximum scale value for the strip chart will automatically double or halve to accommodate increasing
or decreasing values for the host machine. This scale can be restricted to a certain range with the -M
option.
OPTIONS

-s sample-time
Set the sample time to sample-time seconds.
-b h-hand-int
Set the hour-hand interval to h-hand-int seconds.
-m m-hand-int

Set the minute hand interval to m-hand-int seconds.

-M smax minmax maxmax
Set a range of maximum values for the strip chart. Values for each of the arguments should be
powers of 2. smax sets the starting maximum-value. minmax sets the lowest allowed maximumvalue for the scale. maxmax sets the highest allowed maximum-value.
-v value

Set the performance value to be monitored to one of:
cpu

percent of cpu being utilized

pkts

ethernet packets per second

page

paging activity in pages per second

swap

jobs swapped per second

intr

number of device interrupts per second

disk

disk traffic in transfers per second

cntxt

number of context switches per second

load

average number of jobs running on the server over the last minute

colls

collisions per second detected on the ethemet

errs

errors per second on receiving packets

COMMANDS

The value being displayed can be changed by clicking the tool with the rightmost mouse button, and then
selecting the appropriate menu item. The other meter parameters can be modified by moving the mouse
cursor into the tool (either open or closed), and typing:
m

298

decreases minutehandintv by one

Last change: 29 May 1986

Sun Release 3.2

PERFMETER ( 1 )

USER COMMANDS

M

increases minutehandintv by one

h

decreases hourhandintv by one

H

increases hourhandintv by one

1-9

Sets sampletime to a range from 1 to 9 seconds.

PERFMETER ( 1 )

FILES

/ etc/ servers

starts statistics server

SEE ALSO
perfmon(l), netstat(8C), vmstat(8), suntoo1s(l), rstatd(8C)

Sun Release 3.2

Last change: 29 May 1986

299

PERFMON(l)

USER COMMANDS

PERFMON(I)

NAME

perfmon - graphical display of general system statistics
SYNOPSIS

perfmon [statistic ] ...
DESCRIPTION

Perfmon provides a graphical display of the system-wide performance statistics and updates them approximately once a second It should be executed from a graphics tool inside the SunView system. The time
interval between updates can be adjusted by typing one of the following characters while the mouse is in
the graphics subwindow:

s

increases the interval by 0.05 seconds (small s means get slower by a little).

S

increases the interval by one second (capital S means get Slower by a lot).

f

decreases the interval by 0.05 seconds (small/means getfaster by a little).

F

decreases the interval by one second (capital F means get Faster by a lot).

R

resets the interval to the standard 1.05 seconds.

In addition, typing:
H, h or?
lists the characters that perfman is listening for.

Q or q causes perfman to cease executing.
If no statistic argument is given, perfmon displays all statistics. A tick is placed on the lines separating the
graphs once every fifteen seconds (due to scheduling vagaries, these ticks may not be evenly spaced).
Statistics
user

is the percentage of total CPU time spent in normal and low priority user processes.

system is the percentage of total CPU time attributed to system calls and overhead.
idle

is the percentage of total CPU time spent idle.

free

is the amount of available real memory (in Kbytes).

disk

is the total number of disk transfers performed.

interrupts
is the total number of interrupts serviced.
input

is the total number of input packets received.

output is the total number of output packets transmitted.
collision
is the total number of collisions between packets observed on the network.
SEE ALSO

netstat(8), perfmeter( 1), suntools{ 1), vmstat(8)
BUGS

Perfmon should use rstatd(8C).

300

Last change: 1 February 1985

Sun Release 3.2

PG( 1)

USER COMMANDS

PG( 1)

NAME

pg - file perusal filter for soft-copy terminals
SYNOPSIS

lusr/5binlpg [ -number] [ -p string] [ -cefns ] [ +linenumber ] [ +Ipatternl ] [files ••• ]
DESCRIPTION
Note:

Optional Software (System V Option). Refer to Installing
mation on how to install this command.

UNIX

on the Sun Workstation for infor-

The pg command is a filter which allows the examination of files one screenful at a time on a soft-copy terminal. Afile of -, or nofiles specified, indicates that pg should read from the standard input. Each screenful is followed by a prompt. If the user types a carriage return, another page is displayed; other possibilities are enumerated below.
This command is different from previous paginators in that it allows you to back up and review something
that has already passed. The method for doing this is explained below.
In order to determine terminal attributes, pg scans the terminfo(5V) data base for the terminal type
specified by the environment variable TERM. If TERM is not defined, the terminal type dumb is assumed
The responses that may be typed when pg pauses can be divided into three categories: those causing further
perusal, those that search, and those that modify the perusal environment.
Commands which cause further perusal normally take a preceding address, an optionally signed number
indicating the point from which further text should be displayed. This address is interpreted in either pages
or lines depending on the command. A signed address specifies a point relative to the current page or line,
and an unsigned address specifies an address relative to the beginning of the file. Each command has a
default address that is used if none is provided.
The perusal commands and their defaults are as follows:

(+1) or 
This causes one page to be displayed. The address is specified in pages.
(+1) I

With a relative address this causes pg to simulate scrolling the screen, forward or backward, the
number of lines specified. With an absolute address this command prints a screenful beginning at
the specified line.

(+1) d or AD
Simulates scrolling half a screen forward or backward.

The following perusal commands take no address .
• or AL

Typing a single period causes the current page of text to be redisplayed.

$

Displays the last windowful in the file. Use with caution when the input is a pipe.

The following commands are available for searching for text patterns in the text. The regular expressions
described in ed (1) are available. They must always be terminated by a , even if the -n option is
specified.

i/patternl
Search forward for the i th (default i = 1) occurrence of pattern. Searching begins immediately
after the current page and continues to the end of the current file, without wrap-around.
A

i"pattern
i?pattern?
Search backwards for the ith (default i=1) occurrence of pattern. Searching begins immediately
before the current page and continues to the beginning of the current file, without wrap-around.
The notation is useful for Adds 100 terminals which will not properly handle the ?
A

Sun Release 3.2

Last change: 17 April 1986

301

PG( 1)

USER COMMANDS

PG(l)

After searching, pg will normally display the line found at the top of the screen. This can be modified by
appending m or b to the search command to leave the line found in the middle or at the bottom of the window from now on. The suffix t can be used to restore the original situation.
The user of pg can modify the environment of perusal with the following commands:
io

Begin perusing the ith next file in the command line. The i is an unsigned number, default value
is 1.

ip

Begin perusing the ith previous file in the command line. i is an unsigned number, default is 1.

iw

Display another window of text. If i is present, set the window size to i.

sfilename
Save the input in the named file. Only the current file being perused is saved. The white space
between the s and filename is optional. This command must always be terminated by a , even if the -0 option is specified.
h

Help by displaying an abbreviated summary of available commands.

q or Q

Quitpg.

!command
Command is passed to the shell, whose name is taken from the SHELL environment variable. If
this is not available, the default shell is used. This command must always be terminated by a
, even if the -0 option is specified.
At any time when output is being sent to the terminal, the user can hit the quit key (normally control-\) or
the interrupt (break) key. This causes pg to stop sending output, and display the 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.
If the standard output is not a terminal, then pg acts just like cat (1 V), except that a header is printed before
each file (if there is more than one).
OPTIONS

The command line options are:
-number
An integer specifying the size (in lines) of the window that pg is to use instead of the default. (On
a terminal containing 24 lines, the default window size is 23).
-p string
Causes pg to use string as the prompt. If the prompt string contains a "%d", the first occurrence
of "%d" in the prompt will be replaced by the current page number when the prompt is issued.
The default prompt string is ":".

-c

Home the cursor and clear the screen before displaying each page. This option is ignored if
clear_screen is not defined for this terminal type in the terminfo(5V) data base.

-e

Causes p g not to pause at the end of each file.

-f

Normally, pg splits lines longer than the screen width, but some sequences of characters in the text
being displayed (e.g., escape sequences for underlining) generate undesirable results. The-f
option inhibits pg from splitting lines.

-0

Normally, commands must be terminated by a  character. This option causes an
automatic end of command as soon as a command letter is entered.

-s

Causes pg to print all messages and prompts in standout mode (usually inverse video).

+linenumber
Start up at linen umber .
+Ipatternl

302

Last change: 17 Apri11986

Sun Release 3.2

PG( 1)

USER COMMANDS

PG(1 )

Start up at the first line containing the regular expression pattern.
EXAMPLE
A sample usage of pg in reading system news would be
news I pg -p ,. (page %d):"
NOTES
While waiting for terminal input, pg responds to BREAK, DEL, and " by terminating execution. Between
prompts, however, these signals interrupt pg's current task and place the user in prompt mode. These
should be used with caution when input is being read from a pipe, since an interrupt is likely to terminate
the other commands in the pipeline.
Users of more (1) will find that the z and f commands are available, and that the terminal I, ", or ? may be
omitted from the searching commands.
FILES
893.sp 38u
lusr/lib/terminfol*
Terminal information data base
Itmplpg*
Temporary file when input is from a pipe
SEE ALSO
crypt( 1), ed( 1), grep( 1V), terminfo(4)
BUGS
If terminal tabs are not set every eight positions, undesirable results may occur.
When using pg as a filter with another command that changes the terminal I/O options (e.g., crypt(I», terminal settings may not be restored correctly.

Sun Release 3.2

Last change: 17 April 1986

303

PI( 1)

PI( I)

USER COMMANDS

NAME

pi - Pascal interpreter code translator
SYNOPSIS

pi [ -b ] [ -I] [ -L] [ -n] [ -0 name] [ -p] [ -s] [ -t] [ -u] [ -w] [ -z]
[ -i name. •• ] name.p
DESCRIPTION
Pi translates the program in the file name.p leaving interpreter code in the file obj in the current directory.
The interpreter code can be executed using px. Pix performs the functions of pi and px for 'load and go'

Pascal.
Both pi and pc (1) support ISO Levell Standard Pascal, including conformant array parameters. Deviations
from the ISO Standard are noted under BU GS below.
OPTIONS

The following flags are interpreted by pi; the associated options can also be controlled in comments within
the program; see the Pascal User's Manual in the Sun Fortran and Pascal
Manual for details.
-b

Buffer the file output in units of disk blocks, rather than lines.

-i name
Enable the listing for any specified procedures, functions, and include files.
-I

Make a program listing during translation.

-L

Map all identifiers and keywords to lower case.

-n

Begin each listed include file on a new page with a banner line.

-0

name

N arne the final output file name instead of a.out.
-p

Suppress the post-mortem control flow backtrace if an error occurs; suppress statement limit counting.

-s

Accept standard Pascal only; non-standard constructs cause warning diagnostics.

-t

Suppress runtime tests of subrange variables and treat assert statements as comments.

-u

Card image mode; only the first 72 characters of input lines are used.

-w

Suppress warning diagnostics.

-z

Allow execution profiling with pxp by generating statement counters, and arranging for the creation
of the profile data file prrwn.out when the resulting object is executed.

FILES

file.p
file.i
lusr/lib/pi3.*strings
lusrllib/howyi*

obj

input file
include file(s)
text of the error messages
basic usage explanation
interpreter code output

SEE ALSO

pix(l), px(l), pxp(l), pxref(l)
Pascal Programmer's Guide
DIAGNOSTICS

For a basic explanation do
tutorial% pi

304

Last change: 7 November 1984

Sun Release 3.2

PI( 1)

USER COMMANDS

PI( 1)

In the diagnostic output of the translator, lines containing syntax errors are listed with a flag indicating the
point of error. Diagnostic messages indicate the action which the recovery mechanism took in order to be
able to continue parsing. Some diagnostics indicate only that the input is 'malformed.' This occurs if the
recovery can find no simple correction to make the input syntactically valid.
Semantic error diagnostics indicate a line in the source text near the point of error. Some errors evoke
more than one diagnostic to help pinpoint the error; the follow-up messages begin with an ellipsis ' ... '.
The first character of each error message indicates its class:
E
e
w
s

Fatal error; no code will be generated.
Non-fatal error.
Warning - a potential problem.
Non-standard Pascal construct warning.

If a severe error occurs which inhibits further processing, the translator will give a diagnostic and then
'QUIT'.
BUGS

The keyword packed is recognized but has no effect. The ISO standard requires packed and unpacked
structures to be distinguished for portability reasons.
Binary set operators are required to have operands with identical types; the ISO standard allows different
types, as long as the underlying base types are compatible.
For clarity, semantic errors should be flagged at an appropriate place in the source text, and multiple
instances of the 'same' semantic error should be summarized at the end of a procedure or function rather
than evoking many diagnostics.
When include files are present, diagnostics relating to the last procedure in one file may appear after the
beginning of the listing of the next

Sun Release 3.2

Last change: 7 November 1984

305

PIX ( 1)

USER COMMANDS

PIX ( 1)

NAME

pix - Pascal translator and interpreter
SYNOPSIS
pix [ options] [ -i name ... ] name.p [ argument ... ]
DESCRIPTION
Pix is a 'load and go' version of Pascal which combines the functions of the translator pi and the interpreter
px. Pix uses pi to translate the program in the file name.p and, if there were no fatal errors during translation, calls px to execute the resulting interpretive code with the specified arguments. A temporary file is
used for the object code; the file obj is neither created nor destroyed

Options are as described under pi(I).
FILES

lusr/ucb/pi
/usr/ucb/px
/tmp/pix*
lusr/lib/howyix

Pascal translator
Pascal interpreter
temporary
basic explanation

SEE ALSO
The Pascal User's Manual in the Pascal/or the Sun Workstation Manual.
pi(I), px(l)
DIAGNOSTICS
For a basic explanation do
tutorial% pix

306

Last change: 7 November 1984

Sun Release 3.2

PLOT ( IG)

USER COMMANDS

PLOT ( IG)

NAME

plot, aedplot, bgplot, crtplot, dumbplot, gigiplot, hpplot, t300, t300s, t4013, t450, tek - graphics filters for
various plotters
SYNOPSIS

plot [ - Tterminal ]
DESCRIPTION
plot reads plotting instructions (see plot(5» from the standard input and produces plotting instructions suitable for a particular terminal on the standard output.

If no terminal is specified, the environment variable TERM is used. The default terminal is tek.

Except for ver, the following terminal-types can be used with Ipr -g to produce plotted output:
2648 \ 2648a \ h8 \ hp2648 \ hp2648a
Hewlett Packard 2648 graphics terminal.
300

DASI 300 or GSI terminal (Diablo mechanism).

300s\300S

DASI 300s terminal (Diablo mechanism).

450

DASI Hyterm 450 terminal (Diablo mechanism).

4013

Tektronix 4013 storage scope.

4014\ tek

Tektronix 4014 and 4015 storage scope with Enhanced Graphics Module. (Use 4013 for
Tektronix 4014 or 4015 without the Enhanced Graphics Module).

aed

AED 512 color graphics terminal.

bgplot \ bitgraph
BBN bitgraph graphics terminal.
crt

Any crt terminal capable of running vi(I).

dumb \ un \ unknown
Dumb terminals without cursor addressing or line printers.
gigi \ vtl25

DEC vt125 terminal.

h7 \ hp7 \ hp7221
Hewlett Packard 7221 graphics terminal.
var

Benson Varian printer-plotter

ver

Versatec D1200A printer-plotter. The output is scan-converted and suitable input to Ipr -v.

FILES

lusrlbinlt300
lusrlbinlt300s
lusrlbinlt4013
lusrlbinlt450
lusrlbinlaedplot
lusrlbinlcrtplot
Iusrlbinlgigiplot
lusrlbinlplot
lusrlbinlbgplot

lusr/binldumbplot
lusr/binlhpplot
Iusrlbinlvplot
lusr/binltek
lusr/binlt450
lusr/binlt300
lusr/binlt300s
lusr/binlvplot
lusrltmplvplot nnnnnn

SEE ALSO

graph(lG), lpr(l), plot(3X), plot(5), rasterfile(5)

Sun Release 3.2

Last change: 30 May 1986

307

PMERGE(I)

USER COMMANDS

PMERGE(I)

NAME

pmerge - pascal file merger
SYNOPSIS

pmerge name.p •••
DESCRIPTION
Pmerge assembles the named Pascal files into a single standard Pascal program. The resulting program is

listed on the standard output It is intended to be used to merge a collection of separately compiled
modules so that they can be run through pi, or exported to other sites.
FILES

lusr/tmp/MG*

default temporary files

SEE ALSO

pc(I), pi(I),
Pascal Programmer's Guide

BUGS
Very minimal error checking is done, so incorrect programs will produce unpredictable results. Block
comments should be placed after the keyword to which they refer or they are likely to end up in bizarre
places.

308

Last change: 11 November 1983

Sun Release 3.2

PR( IV)

USER COMMANDS

PR( IV)

NAME

pr - prepare file(s) for printing, perhaps in multiple columns
SYNOPSIS
pr [ -n ] [ +n] [ -b string] [ -wn] [ -f] [ -In] [ -t] [ -sc ] [ -m ] [file] ...
SYSTEM V SYNOPSIS

lusrlSbinlpr [ -r] [ -p ] [ -n] [ +n ] [ -b string] [ -nck] [ -eck ] [ -ick] [ -d ] [ -wn ]
[ -on ] [ -f] [ -In ] [ -t ] [ -sc ] [ -m ] [ -a ] [file] ...
DESCRIPTION
pr prepares one or morefiles for printing. By default, the output is separated into pages headed by a date,
the name of the file, and the page number. pr prints its standard input if there are no file arguments.
Formfeed characters in the input files cause page breaks in the output, as expected.

By default, columns are of equal width, separated by at least one space; lines that do not fit are truncated.
If the -s option is used, lines are not truncated and columns are separated by the separation character.
Inter-terminal messages via write are forbidden during apr.
OPTIONS
Options apply to all following files but may be reset betweenfiles:

-n

Produce n-column output For example:

Print
the
lines

of
one
file

in
three
columns.

Columns are not balanced; if, for example, there are as many lines in the file as there are lines
on the page, -only one column will be printed. Even if the -t option (see below) is specified,
blank lines will be printed at the end of the output to pad it to a full page.

+n

Begin printing with page n.

-b string Use string, instead of the file name, in the page header.

-wn

For multicolumn output, take the width of the page to be n characters instead of the default 72.

-f

Use formfeeds instead of NEWLINES to separate pages. A formfeed is assumed to use up two
blank lines at the top of a page. Thus this option does not affect the effective page length.

-In

Take the length of the page to be n lines instead of the default 66.

-t

Do not print the 5-line header or the 5-line trailer normally supplied for each page. Pages are
not separated when this option is used, even if the -f option was used. The -t option is
intended for applications where the results should be directed to a file for further processing.

-sc

Separate columns by the single character c instead of by the appropriate amount of white space.
A missing c is taken to be a tab.

-m

Print allfiles simultaneously, each in one column, for example:

Print
the
lines
of
file
one.

Print
the
lines
of
file
two.

The
third
file's
lines
go
here.

SYSTEM V OPTIONS
When the -n option is specified for multicolumn output, columns are balanced; for example, if there are as
many lines in the file as there are lines to be printed, and two columns are to be printed, each column will
contain half the lines of the file. If the -t option is specified, no blank lines will be printed to pad the last
page.

Sun Release 3.2

Last change: 17 July 1986

309

PR( IV)

USER COMMANDS

PR( IV)

The options -e and -i are assumed for multicolumn output. The -m option overrides the -k and -a
options.
The -f option does not assume that the formfeed uses up two blank lines; blank lines will be printed after
the formfeed, ifnecessary.
-r

Print no diagnostic reports if afile can't be opened, or if it is empty.

-p

Pause before beginning each page if the output is directed to a terminal (pr will ring the bell at the
terminal and wait for a carriage return).

-nck

Provide k-digit line numbering (default for k is 5). The number occupies the first k+l character
positions of each column of normal output or each line of -m output. If c (any non-digit character) is given, it is appended to the line number to separate it from whatever follows (default for c is
a tab).

-eck

Expand input tabs to character positions k+l, 2*k+l, 3*k+l, etc. If k is 0 or is omitted, default
tab settings at every eighth position are assumed. Tab characters in the input are expanded into
the appropriate number of spaces. If c (any non-digit character) is given, it is treated as the input
tab character (default for c is the tab character).

-ick

In output, replace white space wherever possible by inserting tabs to character positions k+l,
2*k+l, 3*k+I, etc. If k is 0 or is omitted, default tab settings at every eighth position are
assumed. If c (any non-digit character) is given, it is treated as the output tab character (default
for c is the tab character).

-d

Double-space the output.

-ok

Offset each line by k character positions. The number of character positions per line is the sum of
the width and offset

-a

When combined with the -n option, print multicolumn output across the page. For example:
Print
the
lines
of
one
file
in
three
columns.

EXAMPLES

Print a file called dreadnought on the printer - this is the simplest use of pr:
tutorial% pr dreadnought I Jpr
tutorial%
Produce three laminations of a file called ridings side by side in the output, with no headers or trailers, the
results to appear in the file called Yorkshire:
tutorial% pr -m -t ridings ridings ridings > Yorkshire
tutorial%
FILES

ldev/tty*

to suspend messages.

SEE ALSO

cat(IV),lpr(l)
DIAGNOSTICS

can't print 0 cols, using I instead.
-0 was specified as a -n option.
pr: bad key key
An illegal option was given.
pr: No room for columns.
The number of columns requested won't fit on the page.
pr: Too many args
More than 10 files were specified with the -m option.

310

Last change: 17 July 1986

Sun Release 3.2

PR( IV)

USER COMMANDS

PR( IV)

file: error
Afile could not be opened. This diagnostic is not printed if pr is printing on a terminal.
SYSTEM V DIAGNOSTICS

pr: bad option
An illegal option was given.
pr: width too small
The number of columns requested won't fit on the page.
pr: too many files
More than 10 files were specified with the -m option.
pr: page-buffer overflow
The formatting required is more complicated than pr can handle.
pr:outofspace
pr could not allocate a buffer it required.
pr: file -- empty file
The file was empty. This diagnostic is printed after all the files are printed if pr is printing on a
terminal.
pr: can't open file
A file could not be opened This diagnostic is printed after all the files are printed if pr is printing
on a terminal.
BUGS

The options described above interact with each other in strange and as yet to be defined ways.

Sun Release 3.2

Last change: 17 July 1986

311

PRINTENV ( 1 )

USER COMMANDS

PRINTENV ( 1 )

NAME

printenv - print out the environment
SYNOPSIS

printenv [ variable]
DESCRIPTION
printenv prints out the values of the variables in the environment. If a variable is specified, only its value is

printed.
DIAGNOSTICS
If a variable is specified and it is not defined in the environment, printenv returns an exit status of " l' , .
SEE ALSO

sh(l), environ(5V), csh(l), stty(l), tset(l)

312

Last change: 21 April 1986

Sun Release 3.2

PRMAIL( 1)

USER COMMANDS

PRMAIL(l)

NAME

prmail - display waiting mail
SYNOPSIS

prmail [ user] ...
DESCRIPTION
Prmail displays waiting mail for you, or the specified users. The mail is not disturbed.
FILES

lusrlspoollrnaill* waiting mail files
SEE ALSO
biff(l), mail(1), from(1), binmail(1)

Sun Release 3.2

Last change: 7 March 1984

313

PROF(l)

PROF(l)

USER COMMANDS

NAME

prof - display profile data
SYNOPSIS
prof [ -a ] [ -I ] [ -0 ] [ -s] [ -v [ -low [ -high] ] ] [ -z] [object-file [profile-file ... ] ]
DESCRIPTION
Pro/interprets the file produced by the monitor(3) subroutine. In the default case, the symbol table in the
named object file (object-file by default) is read and correlated with the profile file (profile-file by default).
For each external symbol, the percentage of time spent executing between that symbol and the next is
printed (in decreasing order), together with the number of times that routine was called and the number of
milliseconds per call. If more than one profile file is specified, the output represents the sum of the profiles.

To tally the number of calls to a routine, the program must be compiled with the -p option of cc ,f/7 or pc.
This option also means that the profile file is produced automatically.
Beware of quantization errors.
OPTIONS
-a

Report all symbols rather than just external symbols.

-I

Sort the output by symbol value.

-0

sort the output by number of calls.

-s

Produce a summary profile file in mon .sum. This is really only useful when more than one profile
file is specified.

-v [ -low [ -high ]]

Suppress all printing and produce a graphic version of the profile on the standard output for
display by the plot(IG) filters. When plotting, the numbers low and high, (by default 0 and 100),
select a percentage of the profile to be plotted, with accordingly higher resolution.
-z

Print routines which have zero usage (as indicated by call counts and accumulated time).

FILES

mon.out
a.out
mon.sum

for profile
for namelist
for summary profile

SEE ALSO
monitor(3), cc(IV), plot(IG), gprof(l)
BUGS

Pro/is confused by f/7 which puts the entry points at the bottom of subroutines and functions.

314

Last change: 8 October 1984

Sun Release 3.2

PRS(I)

USER eOMMANDS

PRS( 1)

NAME

prs - print an sees file
SYNOPSIS

lusrlsccs/prs [ -d [dataspec] ] [ -r [SID] ] [ -e ] [ -I ] [ -a ] filename •••
DESCRIPTION
prs prints, on the standard output, parts or all of an sees file (see sccsfile(5» in a user supplied format If
a directory is named, prs behaves as though each file in the directory were specified as a named file, except

that non-sees files (last component of the path name does not begin with s.), and unreadable files are
silently ignored. If a name of - is given, the standard input is read, in which case each line is taken to be
the name of an sees file or directory to be processed; non-sees files and unreadable files are silently
ignored.
OPTIONS

Options apply independently to each named file.
-d [ dataspec ]
Specifies the output data specification. The dataspec is a string consisting of sees file data keywords (see DATA KEYWORDS) interspersed with optional user supplied text.
-r [SID]

Specifies the sees ID entification SID string of a delta for which information is desired. If no SID
is specified, the SID of the most recently created delta is assumed.

-e

Requests information for all deltas created earlier than and including the delta designated via the
-r option.

-I

Requests information for all deltas created later than and including the delta designated via the -r
option.

-a

Requests printing of information for both removed, that is, delta type = R, (see rmdel(I» and
existing, that is, delta type = D, deltas. If the -a option is not specified, information for existing
deltas only is provided.

In the absence of the -d options, prs displays a default set of information consisting of: delta-type, release
number and level number, date and time last changed, user-name of the person who changed the file, lines
inserted, changed, and unchanged, the MR numbers, and the comments.
DATA KEYWORDS

Data keywords specify which parts of an sees file are to be retrieved and output All parts of an sees file
(see sccsfile(5» have an associated data keyword. There is no limit on the number of times a data keyword
may appear in a dataspec.
The information printed by prs consists of: 1) the user supplied text; and 2) appropriate values (extracted
from the sees file) substituted for the recognized data keywords in the order of appearance in the
dataspec. The format of a data keyword value is either Simple (S), in which keyword substitution is direct,
or Multi-line (M), in which keyword substitution is followed by a carriage return.
User supplied text is any text other than recognized data keywords. A tab is specified by \t and carriage
return/new-line is specified by \no

Sun Release 3.2

Last change: 18 February 1986

315

PRS( 1)

USER COMMANDS

Keyword
:Dt:
:DL:
:Li:
:Ld:
:Lu:
:DT:
:1:
:R:
:L:
:B:
:S:
:D:
:Dy:
:Dm:
:Dd:
:T:
:Th:
:Tm:
:Ts:
:P:
:DS:
:DP:
:DI:

:Dn:
:Dx:
:Dg:
:MR:
:C:
:UN:
:FL:
:Y:

:MF:
:MP:

:KF:
:BF:

:J:
:LK:
:Q:
:M:
:FB:
:CB:
:Ds:
:ND:

:FD:
:BD:
:GB:

:W:
:A:

:Z:
:F:
:PN:

TABLE 1. sces Files Data Keywords
Data Item
File Section Value
Delta information
Delta Table See below*
Delta line statistics
:Li:/:Ld:/:Lu:
Lines inserted by Delta
nnnnn
Lines deleted by Delta
nnnnn
Lines unchanged by Delta
nnnnn
Delta type
DorR
sces ID string (SID)
:R:.:L:.:B:.:S:
Release number
nnnn
Level number
nnnn
Branch number
nnnn
Sequence number
nnnn
Date Delta created
:Dy:/:Dm:/:Dd:
Year Delta created
nn
Month Delta created
nn
Day Delta created
nn
Time Delta created
:Th:::Tm:::Ts:
Hour Delta created
nn
Minutes Delta created
nn
Seconds Delta created
nn
Programmer who created Delta
Delta sequence number
nnnn
"
Predecessor Delta seq-no.
nnnn
Seq-no. of deltas incl.,
:Dn:/ :Dx:/:Dg:
excl., ignored
Deltas included (seq #)
:DS: :DS: •••
Deltas excluded (seq #)
:DS: :DS: •••
Deltas ignored (seq #)
:DS: :DS: •••
MR numbers for delta
text
Comments for delta
text
User names
User Names text
Flag list
Flags
text
Module type flag
text
MR validation flag
yes or no
MR validation pgm name
text
Keyword error/warning flag "
yes or no
Branch flag
yes or no
yes or no
Joint edit flag
Locked releases
:R: •••
User defined keyword
text
Module name
text
Floor boundary
:R:
Ceiling boundary
:R:
:1:
Default SID
yes or no
Null delta flag
Comments text
File descriptive text
Body
text
Body
text
Gotten body
:Z::M:\t:l:
A form of what string
N/A
A form of what string
N/A
:Z::Y: :M: :I::Z:
@(#)
what string delimiter
N/A
text
N/A
SCCS file name
N/A
text
SCCS file path name
* :Dt:

316

=

PRS(I)

Format
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
lognameS
S
S
S
S
S
S
M
M
M
M
S
S
S
S
S
S
S
S
S
S
S
S
S
M
M
M
S
S
S
S
S

:DT: :1: :D: :T: :P: :DS: :DP:

Last change: 18 February 1986

Sun Release 3.2

PRS(I)

USER COMMANDS

PRS(I)

EXAMPLES

/usr/sccs/prs -d"Users and/or user IDs for :F: are:\n:UN:" s.file
may produce on the standard output:
Users and/or user IDs for s.file are:
xyz
131
abc

lusr/sccs/prs -d"Newest delta for pgm :M:: :1: Created :D: By :P:" -r s.file
may produce on the standard output:
Newest delta for pgm main.c: 3.7 Created 77/1211 By cas
As a special case:

/usrlsccs/prs s.fiIe
may produce on the standard output:

D 1.1 77/1211 00:00:00 cas 1 000000/00000100000
MRs:

b178-12345
b179-54321
COMMENTS:

this is the comment line for s.file initial delta
for each delta table entry of the "D" type. The only option argument allowed to be used with the special
case is the -a option.
FILES

Itmp/pr?????
SEE ALSO

sccs(I), admin(I), delta(I), get(I), help(1), sccsfile(5)
Programming Utilities/or the Sun Workstation.
DIAGNOSTICS

Use help for explanations.

Sun Release 3.2

Last change: 18 February 1986

317

PRT( 1)

USER COMMANDS

PRT(1 )

NAME

prt - print SCCS file
SYNOPSIS

lusrlsccs/prt [-d] [-s] [-a] [-i] [-u] [-f] [-t] [-b] [-e] [-y[SID]] [-c[cutoffJ] [-r[rev-cutoff]] file•••
DESCRIPTION

N.B.: The prt command is an older version of prs(l) that in most circumstances is more convenient to use,
but is less flexible than prs.
Prt prints part or all of an sees file in a useful format. If a directory is named, prt behaves as though each
file in the directory were specified as a named file, except that non-sees files (last component of the pathname does not begin with s.) and unreadable files are silently ignored. If a name of - is given, the standard input is read; each line of the standard input is taken to be the name of an sees file to be processed.
Again, non-sees files and unreadable files are silently ignored.

The keyletter arguments are as follows. Each is explained as though only one named file is to be processed, but the effects of any keyletter argument apply independently to each named file.
-d

This keyletter normally causes the printing of delta table entries of the D type.

-s

Causes only the first line of the delta table entries to be printed; that is, only up to the statistics.
This keyletter is effective only if the d keyletter is also specified (or assumed).

-a

Causes those types of deltas nonnally not printed by the d keyletter to be printed. These are types
R (removed). This keyletter is effective only if the d keyletter is also specified (or assumed).

-i

Causes the printing of the serial numbers of those deltas included, excluded, and ignored. This
keyletter is effective only if the d keyletter is also specified (or assumed).
The following fonnat is used' to print those portions of the sees file as specified by the above
keyletters. The printing of each delta table entry is preceded by a newline character.
•
•

•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•

•

318

Type of delta (D or R).
Space.
sees identification string (SID).

Tab.
Date and time of creation (in the form YY/MM/DD HH:MM:SS).
Space.
Creator.
Tab.
Serial number.
Space.
Predecessor delta's serial number.
Tab.
Statistics (in the form inserted/deleted/unchanged).
Newline.
"Included: tab" , followed by SID's of deltas included, followed by newline (only if there were
any such deltas and if i key letter was supplied).
"Excluded: tab' " followed by SID's of deltas excluded, followed by newline (see note above).
"Ignored:tab", followed by SID's of deltas ignored, followed by newline (see note above).
"MRs:tab", followed by MR numbers related to the delta, followed by newline (only if any
MR numbers were supplied).
Lines of comments (delta commentary), followed by newline (if any were supplied).

-u

Causes the printing of the login-names and/or numerical group IDs of those users allowed to make
deltas.

-f

Causes the printing of the flags of the named file.

-t

Causes the printing of the descriptive text contained in the file.

Last change:

Sun Release 3.2

PRT( 1)

USER COMMANDS

-b

Causes the printing of the body of the sees file.

-e

This keyletter implies the d, i,

U,

PRT( 1)

r, and t keyletters and is provided for convenience.

-y[SID] This keyletter will cause the printing of the delta table entries to stop when the delta just printed
has the specified SID. If no delta in the table has the specified SID, the entire table is printed. If no
SID is specified, the first delta in the delta table is printed. This keyletter will cause the entire delta

table entry for each delta to be printed as a single line (the newlines in the normal multi-line format of the d keyletter are replaced by blanks) preceded by the name of the sees file being processed, followed by a :, followed by a tab. This keyletter is effective only if the d keyletter is also
specified (or assumed).

-c[euto.ff]
This keyletter will cause the printing of the delta table entries to stop if the delta about to be
printed is older than the specified cutoff date-time (see get(l) for the format of date-time). If no
date-time is supplied, the epoch 0000 GMT Jan. 1, 1970 is used. As with the y keyletter, this
keyletter will cause the entire delta table entry to be printed as a single line and to be preceded by
the name of the sees file being processed, followed by a :, followed by a tab. This keyletter is
effective only if the d keyletter is also specified (or assumed).
-r[rev-euto.ff]
This keyletter will cause the printing of the delta table entries to begin when the delta about to be
printed is older than or equal to the specified cutoff date-time (see get(l) for the format of datetime). If no date-time is supplied, the epoch 0000 GMT Jan. 1, 1970 is used. (In this case, nothing will be printed). As with the y keyletter, this keyletter will cause the entire delta table entry to
be printed as a single line and to be preceded by the name of the sees file being processed, followed by a :, followed by a tab. This keyletter is effective only if the d key letter is also specified
(or assumed).
If any keyletter but y, c, or r is supplied, the name of the file being processed (preceded by one newline and
followed by two newlines) is printed before its contents.
If none of the u, r, t, or b keyletters is supplied, the d keyletter is assumed.
Note that the s and i keyletters, and the c and r keyletters are mutually exclusive; therefore, they may not
be specified together on the same prt command.
The form of the delta table as produced by the y, c, and r keyletters makes it easy to sort multiple delta
tables by time order. For example, the following will print the delta tables of all sees files in directory
sees in reverse chronological order:
prt -c sees

I grep • I sort ..-rttOO' +2 -3

When both the y and c or the y and r keyletters are supplied, prt will stop printing when the first of the two
conditions is met
SEE ALSO
sccs(I), admin(1), get(I), delta(I), prs(1), what(I), help(I), sccsfile(5)

Programming Utilities/or the Sun Workstation.
DIAGNOSTICS
Use he/p(1) for explanations.

Sun Release 3.2

Last change:

319

PS( 1)

USER COMMANDS

PS( 1)

NAME

ps - process status
SYNOPSIS
ps [ acCegklsStuvwx] [num] [kernel_name] [ c_dumpJt.le] [ swapyle ]
DESCRIPTION
ps displays information about processes. Normally, only those processes that are started by you and are
attached to a con~I1ing terminal (see termio(4V» are shown. Additional categories of processes can be
added to the display using various options. In particular, the a option allows you to include processes that
are not owned by you (that do not have your user ID), and the x option allows you to include processes
without control tenninals. When you specify both a and x, you get processes owned by anyone, with or
without a control terminal. ps displays the process id, under PID; the control terminal (if any), under TT;
the cpu time used by the process so far, including both user and system time), under CPU; the state of the
process, under STAT; and finally, an indication of the COMMAND that is running.

The state is given by a sequence of four letters, for example, 'RWNA'.

First letter

indicates the runnability of the process:
R Runnable processes,
T Stopped processes,
P Processes in page wait,
D Processes in disk (or other short term) waits,
S Processes sleeping for less than about 20 seconds,
I Processes which are idle (sleeping longer than about 20 seconds).
Z A child processes that has terminated and is waiting for its parent process to do a
wait.

Second letter

indicates whether a process is swapped out;
blank
(that is, a space) in this position indicates that the process is loaded (in memory).
W Process is swapped out
> Process has specified a soft limit on memory requirements and has exceeded that
limit; such a process is (necessarily) not swapped.

Third letter

indicates whether a process is running with altered CPU scheduling priority (nice):
blank
(that is, a space) in this position indicates that the process is running without special
treatment
N The process priority is reduced,
< The process priority has been raised artificially.

Fourth letter

indicates any special treatment of the process for virtual memory replacement. The
letters correspond to options to the vadvise (2) system call. Currently the possibilities
are:
blank
(that is, a space) in this position stands for VA_NORM.
A Stands for VA_ ANOM. An A typically represents a program which is doing garbage collection.
S Stands for VA_SEQL. An S is typical of large image processing programs which
are using virtual memory to sequentially address voluminous data.

Kernel_name specifies the location of the system namelist. If the k option is given, c_dumpyle tells ps
where to look for core. Otherwise, the core dump is located in the file Ivmcore and this argument is
ignored. Swap yle gives the location of a swap file other than the default, Idevldrum.
OPTIONS
a

c

320

Include information about processes owned by others.
Display the command name, as stored internally in the system for purposes of accounting, rather than

Last change: 8 rune 1986

Sun Release 3.2

PS(l)

USER COMMANDS

PS(l)

the command arguments, which are kept in the process' address space. This is more reliable, if less
informative, since the process is free to destroy the latter information.
C

Display raw CPU time in the %CPU field instead of the decaying average.

e

Display the environment as well as the arguments to the command.

g

Display all processes. Without this option, ps only prints 'interesting' processes. Processes are
deemed to be uninteresting if they are process group leaders. This normally eliminates top-level
command interpreters and processes waiting for users to login on free terminals.

k

Normally, kernel_name, defaults to /vmunix, c_dumpJtle is ignored, and swapJtle defaults to
Idev/drum. With the k option in effect, these arguments default to /vmunix, /vmcore, and Idev/drum,
re spec ti vel y.
Display a long listing, with fields PPID, CP, PRI, NI, ADDR, SIZE, RSS and WCHAN as described
below.

s

Adds the size SSIZ of the kernel stack of each process (for use by system maintainers) to the basic
output format.

S

Display accumulated CPU time used by this process and all of its reaped children.

tx

Restrict output to processes whose controlling terminal is x (which should be specified as printed by
ps, for example, t3 for tty3, tco for console, tdO for ttydO, t? for processes with no terminal, etc).
This option must be the last one given.

u

Display user-oriented output. This includes fields USER, %CPU, NICE, SIZE, and RSS as described
below.

v

Display a version of the output containing virtual memory. This includes fields RE, SL, PAGEIN,
SIZE, RSS, LIM, TSIZ, TRS, %CPU and %MEM, described below.

w

Use a wide output format (132 columns rather than 80); if repeated, that is, ww, use arbitrarily wide
output. This information is used to decide how much of long commands to print.

x

Include processes with no controlling terminal.

num A process number may be given, in which case the output is restricted to that process. This option
must also be last.
DISPLAY FORMATS

Fields which are not common to all output formats:
USER
name of the owner of the process
%CPU
cpu utilization of the process; this is a decaying average over up to a minute of previous (real)
time. Since the time base over which this is computed varies (since processes may be very
young) it is possible for the sum of all %CPU fields to exceed 100%.
(or NI) process scheduling increment (see setpriority(2) and nice(3C).
NICE
virtual size of the process (in kilobyte units)
SIZE
real memory (resident set) size of the process (in kilobyte units)
RSS
soft limit on memory used, specified via a call to getrlimit(2); if no limit has been specified
LIM
then shown as xx
size of text (shared program) image
TSIZ
size of resident (real memory) set of text
TRS
percentage of real memory used by this process.
%MEM
residency time of the process (seconds in core)
RE
sleep time of the process (seconds blocked)
SL
PAGEIN number of disk i/o's resulting from references by the process to pages not loaded in core.
numerical user-id of process owner
UID
numerical id of parent of process
PPID
short-term cpu utilization factor (used in scheduling)
CP
process priority (non-positive when in non-interruptible wait)
PRI

Sun Release 3.2

Last change: 8 JUne 1986

321

PS( 1)

USER COMMANDS

ADDR
WCHAN

F

PS(l)

page fram number or swap area position
event on which process is waiting (an address in the system), with the initial part of the address
trimmed off, for example, 80004000 prints as 4000.

flags associated with process as in :
SLOAD
0000001 in core
SSYS
0000002 swapper or pager process
SLOCK
0000004 process being swapped out
SSWAP
0000008 save area flag
STRC
0000010 process is being traced
SWTED
0000020 another tracing flag
SULOCK
0000040 user settable lock in core
SPAGE
0000080 process in page wait state
SKEEP
0000100 another flag to prevent swap out
SOMASK
0000200 restore old mask after taking signal
SWEXIT
0000400 working on exiting
SPHYSIO
0000800 doing physical i/o (bio.c)
SVFORK
0001000 process resulted from vforkO
SVFDONE 0002000 another vfork flag
SNOVM
0004000 no vm, parent in a vforkO
SPAGI
0008000 init data space on demand, from inode
SSEQL
0010000 user warned of sequential vm behavior
SUANOM
0020000 user warned of anomalous vm behavior
STIMO
0040000 timing out during sleep
SOUSIG
0100000 using old signal mechanism
SOWEUPC 0200000 owe process an addupcO call at next ast
SSEL
0400000 selecting; wakeup/waiting danger
SLOGIN
0800000 a login process (legit child of init)
SPTECHG
1000000 pte's for process have changed

A process that has exited and has a parent, but has not yet been waited for by the parent is marked
; a process which is blocked trying to exit is marked ; ps makes an educated guess as to
the file name and arguments given when the process was created by examining memory or the swap area.
The method is inherently somewhat unreliable and in any event a process is entitled to destroy this information, so the names cannot be counted on too much.
FILES

system namelist
Ivmunix
/devlkmem kernel memory
Idev/drum swap device
core file
Ivrncore
searched to find swap device and terminal names
Idev
SEE ALSO

kill(I), w(I), pstat(8), termio(4V)

BUGS
Things can change while ps is running; the picture it gives is only a close approximation to the current
state.

322

Last change: 8 JUne 1986

Sun Release 3.2

PTI(l)

USER COMMANDS

PTI(l)

NAME

pti - phototypesetter interpreter
SYNOPSIS
pti [ file ••• ]
DESCRIPTION
Pti shows the commands in a stream from the standard output of troff(l) using troff s -t option, interpreting them as they would act on the typesetter. Horizontal motions shows as counts in internal units and are
marked with '<' and '>' indicating left and right motion. Vertical space is called leading and is also indicated.

The output is really cryptic unless you are an experienced C/AfT hardware person. It is better to use

troff -a.
SEE ALSO
troff(l)

Sun Release 3.2

Last change: 21 August 1985

323

PTX( 1)

USER COMMANDS

PTX(l)

NAME

ptx - permuted index
SYNOPSIS
ptx [ -f] [ -t ] [ -w n ] [ -g n ] [ -0 only] [ -i ignore] [ -b break] [ -r] [input [ output] ]
DESCRIPTION

Ptx generates a permuted index of the contents of file input onto file output (defaults are standard input and
output). Ptx has three phases: the first does the permutation, generating one line for each keyword in an
input line. The keyword is rotated to the front. The permuted file is then sorted. Finally, the sorted lines
are rotated so the keyword comes at the middle of the page. Ptx produces output in the form:
.xx "tail" "before keyword" "keyword and after" "head"
where .xx may be an nroff(1) or troff(l) macro for user-defined formatting. The before keyword and keyword and after fields incorporate as much of the line as will fit around the keyword when it is printed at the
middle of the page. Tail and head, at least one of which is an empty string "", are wrapped-around pieces
small enough to fit in the unused space at the opposite end of the line. When original text must be discarded, 'I' marks the spot.
OPTIONS
-f

Fold upper and lower case letters for sorting.

-t

Prepare the output for the phototypesetter; the default line length is 100 characters.

-wn

Use the next argument, n, as the width of the output line. The default line length is 72 characters.

-gn

Use the next argument, n, as the number of characters to allow for each gap among the four parts
of the line as finally printed. The default gap is 3 characters.

-oonly Use as keywords only the words given in the only file.
-iignore
Do not use as keywords any words given in the ignore file. If the -i and -0 options are missing,
use /usrllib/eign as the ignore file.

-bbreak
Use the characters in the break file to separate words. In any case, tab, newline, and space characters are always used as break characters.
-r

Take any leading nonblank characters of each input line to be a reference identifier (as to a page
or chapter) separate from the text of the line. Attach that identifier as a 5th field on each output
line.

FILES

Ibin/sort
lusr/libl eign
BUGS

Line length counts do not account for overstriking or proportional spacing.

324

Last change: 1 November 1983

Sun Release 3.2

PWD(I)

USER COMMANDS

PWD(I)

NAME

pwd - print working directory name
SYNOPSIS

pwd
DESCRIPTION
Pwd prints the pathname of the working (current) directory.

If you are using csh(I), you can use the dirs builtin command to do the same job more quickly; BUT dirs
can give a different answer in the rare case that the current directory or a containing directory was moved
after the shell descended into it. This is because pwd searches back up the directory tree to report the true
pathname, whereas dirs remembers the pathname from the last cd command. The example below illustrates the differences.

% cd /usr/wendy/january/reports
%pwd
lusr/wendy/j anuary/reports

%dirs
-/januaryIreports

% mv -/january -/february
%pwd
lusr/wendy/february/reports
% dirs
-/januaryIreports
%
pwd and mrs also give different answers when you change directory through a symbolic link. For example:

% cd lusr/wendy/january/reports
%pwd
lusr/wendy/j anuary/reports

%dirs
-/januaryIreports
% Is -l/usr/wendy/january
Irwxrwxrwx 1 wendy
17 Jan 30 1983/usr/wendy/january -> /usr/wendy/1984/jan/

% cd lusr/wendy/january
%pwd
lusr/wendy/1984/j an

% dirs
lusr/wendy/january
SEE ALSO
cd(I), csh(l)

Sun Release 3.2

Last change: 1 February 1985

325

PX(l)

USER COMMANDS

PX(l)

NAME

px - Pascal interpreter
SYNOPSIS

px [ obj [ argument . .. ] ]
DESCRIPTION

px interprets the abstract machine code generated by pi. The first argument is the file to be interpreted, and
defaults to obj; remaining arguments are available to the Pascal program using the built-ins argv and argc.
px is also invoked by pix when running 'load and go' .
If the program terminates abnormally an error message and a control flow backtrace are printed. The
number of statements executed and total execution time are printed after normal termination. The p option
of pi suppresses all of this except the message indicating the cause of abnormal termination.
FILES

obj
pmon.out

default object file
profile data file

SEE ALSO

pie 1), pix(1)
Pascal Programmer's Guide
DIAGNOSTICS

Most run-time error messages are self-explanatory. Some of the more unusual ones are:
Reference to an inactive file
A file other than input or output was used before a call to reset or rewrite.
Statement count limit exceeded
The limit of 500,000 executed statements (which prevents excessive looping or recursion) has been
exceeded.
Bad data found on integer read
Bad data found on real read
Usually, non-numeric input was found for a number. For reals, Pascal requires digits before and
after the decimal point so that numbers like '.1' or '21.' evoke the second diagnostic.
panic: Some message
Indicates a internal inconsistency detected in px probably due to a Pascal system bug.
BUGS

Post-mortem traceback is not limited; infinite recursion leads to almost infinite traceback.

326

Last change: 29 April 1986

Sun Release 3.2

PXP( 1)

USER COMMANDS

PXP( 1)

NAME

pxp - Pascal execution profiler
SYNOPSIS

pxp [ -acdefjLnstuw_] [ -23456789 ] [ -z [ name ... ] ] name.p
DESCRIPTION

pxp can be used to obtain execution profiles of Pascal programs or as a pretty-printer. To produce an execution profile all that is necessary is to translate the program specifying the z option to pc, pi, or pix, execute the program, and then type the command
tutorial% pxp -z name.p
pxp generates a reformatted listing if none of the c, t, or z options are specified; thus
tutorial% pxp old.p > new.p
places a pretty-printed version of the program in old.p in the file new.p.
OPTIONS

The use of the following options of pxp is discussed in the Pascal User's Manual in the Sun Pascal
Manual.
-a

Print the bodies of all procedures and functions in the profile; even those which were never executed.

-c

Extract profile data from the file core.

-d

Include declaration parts in a profile.

-e

Eliminate include directives when reformatting a file; the include is replaced by the reformatted contents of the specified file.

-f

Fully parenthesize expressions.

-j

Left justify all procedures and functions.

-L

Map all identifiers and keywords to lower case.

-n

Eject a new page as each file is included; in profiles, print a blank line at the top of the page.

-s

Strip comments from the input text.

-t

Print a table summarizing procedure and function call counts.

-u

Card image mode; only the first 72 characters of input lines are used.

-w

Suppress warning diagnostics.

-z [ name ... ] name .p
Generate an execution profile. If no names are given the profile is of the entire program. If a list of
names is given, then only the specified procedures or functions and the contents of the specified
include files will appear in the profile.
Underline keywords.

-d

Use d spaces (where d is a digit, 2 ~ d ~ 9) as the basic indenting unit. The default is 4.

FILES

name.p
input file
name.i
include file(s)
name.h
include file(s)
pmon.out
profile data
core
profile data source for -c option
/usr/lib/howyxp information on basic usage

Sun Release 3.2

Last change: 7 November 1984

327

USER COMMANDS

PXP( 1)

PXP( 1)

SEE ALSO
pc(I), pi(I), px(l)

Pascal Programmer's Guide
DIAGNOSTICS
For a basic explanation do
tutorial% pxp

Error diagnostics include ~No profile data in file' with the c option if the z option was not enabled to pi;
~Not a Pascal system core file' if the core is not from a px execution; 'Program and count data do not
correspond' if the program was changed after compilation, before profiling; or if the wrong program is
specified.
BUGS

Does not place multiple statements per line.
Procedures and functions as parameters are printed without nested parameter lists, as in the obsolete Jensen'
and Wirth syntax.

328

Last change: 7 November 1984

Sun Release 3.2

PXREF( 1)

USER COMMANDS

PXREF( 1)

NAME

pxref - Pascal cross-reference program
SYNOPSIS

pxref [ - ] name
DESCRIPTION

Pxref makes a line numbered listing and a cross reference of identifier usage for the program in name. The
optional '-' argument suppresses the listing. The keywords goto and label are treated as identifiers for the
purpose of the cross reference. Include directives are not processed, but cause the placement of an entry
indexed by '-include' in the cross reference.
SEE ALSO

Pascal Programmer's Guide
BUGS

Identifiers are trimmed to 10 characters.

Sun Release 3.2

Last change: 11 November 1983

329

QUOTA(1)

USER COMMANDS

QUOTA(1)

NAME

quota - display disk usage and limits
SYNOPSIS
quota [ -y ] [ user]
DESCRIPTION

quota displays users' disk usage and limits. Only the super-user may use the optional user argument to
view the limits of users other than himself.
quota without options displays only warnings about mounted file systems where usage is over quota.
Remotely mounted file systems which are mounted with the "noquota" option (seefstab(5)) are ignored.
OPTIONS
-y

display user's quotas on all mounted file systems where quotas exist.

FILES

quotas

quota file at the file system root

letclmtab

list of currently mounted filesystems

SEE ALSO

quotactl(2), quotaon(8), edquota(8), rquotad(8C), fstab(5)

330

Last change: 21 August 1985

Sun Release 3.2

RANLIB( 1)

USER COMMANDS

RANLIB( 1)

NAME

ranlib - convert archives to random libraries
SYNOPSIS

ranlib [ -t] archive ...
DESCRIPTION

ranlib converts each archive to a form that can be linked more rapidly. ran lib does this by adding a table
of contents called __.SYMDEF to the beginning of the archive. ranlib uses ar(l) to reconstruct the
archive. Sufficient temporary file space must be available in the file system that contains the current directory.
OPTIONS
-t

option, ran lib only "touches" the archives and does not modify them. This is useful after copying
an archive or using the -t option of make(l) in order to avoid having ld(l) complain about an
"out of date" symbol table.

SEE ALSO

ld( 1), ar(l), lorder( 1), make( 1)
BUGS

Because generation of a library by ar and randomization of the library by ranlib are separate processes,
phase errors are possible. The linker, ld, warns when the modification date of a library is more recent than
the creation date of its dictionary; but this means that you get the warning even if you only copy the
library.

Sun Release 3.2

Last change: 8 April 1986

331

RASFILTER8TO I ( IG)

USER COMMANDS

RASFILTER8TOI ( I G)

NAME

rasfilter8toI- convert an 8-bit deep rasterfile to a I-bit deep raster:file
SYNOPSIS

rasfiIter8toi [ -r threshold] [ -g threshold] [ -b threshold] [ -a threshold]
DESCRIPTION
Rasfilter8tol reads an 8-bit deep rasterfile from standard input and converts it to a I-bit deep rasterfile on
standard output. The format is Sun standard raster:file format (see lusrlincludelrasterfile.h). This is useful

for displaying 8-bit raster images on devices that can only handle monochrome raster:file images.
OPTIONS

Options can be specified to control thresholding of color values. There can be more than one threshold
option set, in which case all threshold options specified must be met.
All options take a threshold value which can range from 0 to 255. Pixels, whose threshold conditions
exceed the threshold value are given a value of 0 in the I-bit rasterfile. Those that don't are given a value
of 1. The default option is -a 128.
-r threshold

The threshold condition is the red component of the pixel value.
-g threshold

The threshold condition is the green component of the pixel value.
-b threshold
The threshold condition is the blue component of the pixel value.

-a threshold
The average of the red, green, and blue components is tested against the threshold value.
EXAMPLE

The command:
tutorial% screendump -f Idev/cgtwoO \ rasfilter8toI\lpr -Pversatec -v
prints a monochromatic representation of the IdevlcgtwoO frame buffer on the printer named "versatec"
using the flv" output filter. (see letclprintcap).
FILES

ldevlcgtwoO

Default name of the Sun-2 color display frame buffer.

SEE ALSO

lpr(l), rastrepl(I), screendump(l), screenload(I)
pr_dump in Programmer's Reference Manual for Sun Windows

332

Last change: 28 April 1986

Sun Release 3.2

RASTREPL ( 1 )

USER COMMANDS

RASTREPL ( 1 )

NAME

rastrepl- magnify a raster image by 2 times
SYNOPSIS

rastrepl [ input-file [ output-file ]]
DESCRIPTION
Rastrepl reads input-file (or the standard input if input-file is not specified) which should be in rasterfile format (see /usr/include/rasterfile.h), replicates each pixel in both the x and y directions, and writes the resulting rasterfile to output-file (or the standard output if output-file is not specified).
EXAMPLES

tutoria1% screendump

I rastrepl I Ipr -Pversatec -v

sends a rasterfile containing the current frame buffer to the Versatec plotter, doubling the size of the image
so that it fills a single page.
SEE ALSO
screendump( 1), screenload( 1), lpr( 1)

Sun Release 3.2

Last change: 5 November 1984

333

RATFOR( 1)

USER COMMANDS

RATFOR(1)

NAME

ratfor - rational FORTRAN dialect
SYNOPSIS

ratfor [ -6c ] [ -c ] [-b ] [ filename .•• ]

DESCRIPTION

ratfor converts the rational FORTRAN dialect into ordinary FORTRAN 77. It provides control flow constructs essentially identical to those in C. See the FORTRAN 77 Programmer's Guide for a description of the
Ratfor language.
OPTIONS

-6c

Use the character c as the continuation character in column 6 when translating to FORTRAN. The
default is to use the & character as a continuation character.

-C

Pass Ratfor comments through to the translated code.

-b

Translate Ratfor string constants to Hollerith constants of the form nnn b string. Otherwise just
pass the strings through to the translated code.

SEE ALSO

t77(l)
Ratfor in the FORTRAN Pro grammer's Guide

334

Last change: 21 December 1983

Sun Release 3.2

RCP( IC)

USER COMMANDS

RCP( IC)

NAME

rcp - remote file copy
SYNOPSIS

rep filel file2
rep [ -r ] file ... directory
DESCRIPTION

rep copies files between machines. Eachfile or directory argument is either a remote file name of the fonn
"rhostpath", or a local file name (containing no ':' characters, or a 'I' before any ':'s.)
If the -r is specified and any of the source files are directories, rep copies each subtree rooted at that name;
in this case the destination must be a directory.

If path is not a full path name, it is interpreted relative to your login directory on rhost. A path on a remote
host may be quoted (using \, ", or') so that the metacharacters are interpreted remotely.
rep does not prompt for passwords; your current local user name must exist on rhost and allow remote
command execution via rsh(IC).
rep handles third party copies, where neither source nor target files are on the current machine. Hostnames
may also take the form' 'rhost.marne" to use rname rather than the current user name on the remote host.

Please note: rep is meant to copy from one host to another; if by some chance you try to copy a file on top
of itself, you will end up with a severely corrupted file (for example, if you executed the following command from host george: 'george% rep testfile george:/usr/meltestfile'). Remember where you are at all
times (putting your hostname in your prompt helps with this)!
SEE ALSO

ftp(IC), rsh(IC), rlogin(IC)
BUGS

Doesn't detect all cases where the target of a copy might be a file in cases where only a directory should be
legal.
Is confused by any output generated by commands in a .login, .profile, or .cshrc file on the remote host.
rep doesn't copy ownership, mode, and timestamps to the new files.
rep requires that the source host have permission to execute commands on the remote host when doing
third-party copies.

If you forget to quote metacharacters intended for the remote host you get an incomprehesible error message.

Sun Release 3.2

Last change: 23 September 1985

335

RDIST( 1)

RDIST( 1)

USER COMMANDS

NAME

rdist - remote file distribution program
SYNOPSIS

rdist [-nqbRhivwy] [ -f distfile] [ -d var=value] [ -m host] [name ... ]
rdist [ -nqbRhivwy ] -c name ... [login@]host[:dest]
DESCRIPTION
Rdist is a program to maintain identical copies of files over multiple hosts. It preserves the owner, group,
mode, and mtime of files if possible and can update programs that are executing. Rdist reads commands
from distfile to direct the updating of files and/or directories. If distfile is '-', the standard input is used. If
no -f option is present, the program looks first for 'distfile', then 'Distfile' to use as the input. If no names
are specified on the command line, rdist will update all of the files and directories listed in distfile. Otherwise, the argument is taken to be the name of a file to be updated or the label of a command to execute. If
label and file names conflict, it is assumed to be a label. These may be used together to update specific files
using specific commands.

The -c option forces rdist to interpret the remaining arguments as a small distfile. The equivalent distfile is
as follows.

( name ... ) -> [login@]host
install [dest];
Other options:

336

-d

Define var to have value. The -d option is used to define or override variable definitions in the
distfile. Value can be the empty string, one name, or a list of names surrounded by parentheses
and separated by tabs and/or spaces.

-m

Limit which machines are to be updated. Multiple -m arguments can be given to limit updates to
a subset of the hosts listed in the distfile.

-0

Print the commands without executing them. This option is useful for debugging distfile.

-q

Quiet mode. Files that are being modified are normally printed on standard output. The -q option
suppresses this.

-R

Remove extraneous files. If a directory is being updated, any files that exist on the remote host
that do not exist in the master directory are removed. This is useful for maintaining truely identical copies of directories.

-b

Follow symbolic links. Copy the file that the link points to rather than the link itself.

-i

Ignore unresolved links. Rdist will normally try to maintain the link structure of files being
transfered and warn the user if all the links cannot be found.

-v

Verify that the files are up to date on all the hosts. Any files that are out of date will be displayed
but no files will be changed nor any mail sent.

-w

Whole mode. The whole file name is appended to the destination directory name. Normally, only
the last component of a name is used when renaming files. This will preserve the directory structure of the files being copied instead of flattening the directory structure. For example, renaming a
list of files such as ( dirllfl dir2!f2 ) to dir3 would create files dir3/dirl/fl and dir3/dir2lf2 instead
of dir3/fl and dir3/f2.

-y

Younger mode. Files are normally updated if their mtime and size (see stat(2) disagree. The-y
option causes rdist not to update files that are younger than the master copy. This can be used to
prevent newer copies on other hosts from being replaced. A warning message is printed for files
which are newer than the master copy.

-b

Binary comparison. Perform a binary comparison and update files if they differ rather than

Last change: 17 July 1986

Sun Release 3.2

RDIST( 1)

USER COMMANDS

RDIST( 1)

comparing dates and sizes.

Distfile contains a sequence of entries that specify the files to be copied, the destination hosts, and what
operations to perform to do the updating. Each entry has one of the following formats.
 '=' 
[label: ]  '->'  
[label: ]  '::'  
The first format is used for defining variables. The second format is used for distributing files to other
hosts. The third format is used for making lists of files that have been changed since some given date. The
source list specifies a list of files and/or directories on the local host which are to be used as the master
copy for distribution. The destination list is the list of hosts to which these files are to be copied. Each file
in the source list is added to a list of changes if the file is out of date on the host being updated (second format) or the file is newer than the time stamp file (third format).
Labels are optional. They are used to identify a command for partial updates.
Newlines, tabs, and blanks are only used as separators and are otherwise ignored. Comments begin with
'-' and end with a newline.
Variables to be expanded begin with '%' followed by one character or a name enclosed in curly braces (see
the examples at the end).
The source and destination lists have the following format:

or
'('  ')1
The shell meta-characters '[" ']" '{', '}t, '.', and'1' are recognized and expanded (on the local host only)
in the same way as csh(l). They can be escaped with a backslash. The ,-, character is also expanded in
the same way as csh but is expanded separately on the local and destination hosts. When the -w option is
used with a file name that begins with '-', everything except the home directory is appended to the destination name. File names which do not begin with 'I' or ,-, use the destination user's home directory as the
root directory for the rest of the file name.
The command list consis ts of zero or more commands of the following format.
'install'  opt_dest_name ';'
'notify' ';'
'except' ';'
'exceptyat'
';'
string ';'
'special'
The install command is used to copy out of date files and/or directories. Each source file is copied to each
host in the destination list. Directories are recursively copied in the same way. Opt_dest_name is an
optional parameter to rename files. If no install command appears in the command list or the destination
name is not specified, the source file name is used. Directories in the path name will be created if they do
not exist on the remote host. To help prevent disasters, a non-empty directory on a target host will never be
replaced with a regular file or a symbolic link. However, under the '-R' option a non-empty directory will
be removed if the corresponding filename is completely absent on the master host. The options are '-R',
'-h', '-i', '-v', '-w', '-y', and '-b' and have the same semantics as options on the command line except
they only apply to the files in the source list. The login name used on the destination host is the same as the
local host unless the destination name is of the format "login@host".

Sun Release 3.2

Last change: 17 July 1986

337

RDIST( 1)

USER COMMANDS

RDIST( 1)

The notify command is used to mail the list of files updated (and any errors that may have occured) to the
listed names. If no '@' appears in the name, the destination host is appended to the name (e.g.,
namel@host, name2@host, ... ).
The except command is used to update all of the files in the source list except for the files listed in name
list. This is usually used to copy everything in a directory except certain files.
The exceptyat command is like the except command except that pattern list is a list of regular expressions
(see ed(l) for details). If one of the patterns matches some string within a file name, that file will be
ignored. Note that since '\' is a quote character, it must be doubled to become part of the regular expression. Variables are expanded in pattern list but not shell file pattern matching characters. To include a
'%', it must be escaped with '\'.
The special command is used to specify sh(l) commands that are to be executed on the remote host after
the file in name list is updated or installed. If the name list is omitted then the shell commands will be executed for every file updated or installed. The shell variable 'FILE' is set to the current filename before executing the commands in string. String starts and ends with "" and can cross multiple lines in distjile. Multiple commands to the shell should be separated by';'. Commands are executed in the user's home directory on the host being updated. The special command can be used to rebuild private databases, etc. after a
program has been updated.
The following is a small example.
HOSTS = ( matisse root@arpa )
FILES

= (

Ibin !lib lusrlbin lusrl games
lusr/include! { *.h, {stand,sys,vax *,pascal, machine}I*.h}
lusr/lib lusr/man/man? lusr/ucb lusr/locallrdist)

EXLIB

=

(Mai1.rc aliases aliases.dir aliases.pag crontab dshrc
sendmail.cf sendmail.fc sendmai1.hf sendmail.st uucp vfont )

%{FILES} -> %{HOSTS}
install-R;
except lusrllib/%{EXLIB} ;
except lusr/games/lib ;
special lusr/lib/sendmail "/usr/lib/sendmail-bz" ;
srcs:
lusrlsrc/bin -> arpa

exceptyat (\\.0\% ISCCS\%) ;
IMAGEN = (ips dviimp catdvi)
imagen:
lusr/local/%{IMAGEN} -> arpa
install lusrllocal/lib ;
notify ralph ;
%{FILES} :: stamp.cory
notify root@cory ;
FILES

distfile
Itmplrdist*

338

input command file
temporary file for update lists

Last change: 17 July 1986

Sun Release 3.2

RDIST( 1)

USER COMMANDS

RDIST( 1)

SEE ALSO

sh(1), csh(1), stat(2)
DIAGNOSTICS

A complaint about mismatch of rdist version numbers may really stem from some problem with starting
your shell, e.g., you are in too many groups.
BUGS

Source files must reside on the local host where rdist is executed.
There is no easy way to have a special command executed after all files in a directory have been updated.
Variable expansion only works for name lists; there should be a general macro facility.

Rdist aborts on files which have a negative mtime (before Jan 1, 1970).
There should be a 'force' option to allow replacement of non-empty directories by regular files or symlinks. A means of updating file modes and owners of otherwise identical files is also needed.

Sun Release 3.2

Last change: 17 July 1986

339

REFER ( 1)

USER COMMANDS

REFER(I)

NAME

refer - find and insert literature references in documents
SYNOPSIS
refer [ -ar] [ -b] [ -cstring ] [ -e ] [ -kx] [ -lm,n ] [ -p file] [ -n] [ -skeys] file

000

DESCRIPTION
Refer is a preprocessor for nroff(I), or trojf(I), that finds and formats references. The input files (standard
input by default) are copied to the standard output, except for lines between and command lines, Such
lines are assumed to contain keywords as for lookbib(I), and are replaced by information from a bibliographic data base. The user can avoid the search, override fields from it, or add new fields. The reference
data, from whatever source, is assigned to a set of troJ! strings. Macro packages such as ms(7) print the
finished reference text from these strings. A flag is placed in the text at the point of reference. By default,
the references are indicated by numbers.
0 [

0]

When refer is used with eqn(I), neqn(l), or tbl(I), refer should be used first in the sequence, to minimize
the volume of data passed through pipes.
OPTIONS
-ar

-b

Reverse the first r author names (Jones, J. A. instead of J. A. Jones). If r is omitted, all author
names are reversed.
Bare mode - do not put any flags in text (neither numbers or labels).

-cstring
Capitalize (with SMALL CAPs) the fields whose key-letters are in string.

-e

Accumulate references instead of leaving the references where encountered, until a sequence of
the form:
.[
%LIST%
.]
is encountered, and then write out all references collected so far. Collapse references to the same
source.

-kx

Instead of numbering references, use labels as specified in a reference data line beginning with the
characters %x; By default, x is L.

-Jm,n

Instead of numbering references, use labels from the senior author's last name and th~ year of
publication. Only the first m letters of the last name and the last n digits of the date are used. If
either of m or n is omitted, the entire name or date, respectively, is used.

-p

Take the next argument as a file of references to be searched. The default file is searched last.

-0

Do not search the default file.

-skeys Sort references by fields whose key-letters are in the key~ string, and permute reference numbers
in the text accordingly. Using this option implies the -e option. The key-letters in keys may be
followed by a number indicating how many such fields are used, with a + sign taken as a very
large number. The default is AD, which sorts on the senior author and date. To sort on all authors
and then the date, for instance, use the options -sA+ T.
FILES

lusr/dict/papers
lusrllib/refer

directory of default publication lists and indexes
directory of programs

SEE ALSO
addbib(l), indxbib(l), lookbib(l), roffbib(l), sortbib(l)

340

Last change: 29 April 1983

Sun Release 3.2

REV ( 1)

USER COMMANDS

REV(1)

NAME

rev - reverse lines of a file
SYNOPSIS

rev [file] ...
DESCRIPTION
Rev copies the named files to the standard output, reversing the order of characters in every line. If no file
is specified, the standard input is copied.

Sun Release 3.2

Last change: 16 March 1983

341

RLOGIN(IC)

USER COMMANDS

RLOGIN( IC)

NAME

rlogin - remote login
SYNOPSIS

rlogin rhost [ -ec] [ -I username] [ -7] [ -8]
rhost [ -ec] [ -I username] [ -7] [ -8]
DESCRIPTION

rlogin connects your terminal on the current local host system lhost to the remote host system rhost.
Host names are given in the file letclhosts. Each host has one standard name (the first name given in the
file), which is unambiguous, and optionally one or more nicknames. The host names for machines to
which your machine is networked are also found in the directory lusr/hosts, as symbolic links to rsh. If you
put this directory in your search path then the rlogin can be omitted.
Additionally, each host has a file letclhosts.equiv which contains a list of rhost's with which it shares
account names. When you rlogin on a host specified in your letclhosts.equiv (and if the remote host, in
turn, specifies your host in its /etclhosts.equiv) you don't need to give a password.
Each user may also have a private equivalence list in a file .rhosts in his login directory. Each line in this
file should contain an rhost and a username separated by a space, giving additional cases where logins
without passwords are to be permitted. If the originating user and host is not found in these files, the
remote machine will prompt for a password
To avoid some security problems, the Jhosts file must be owned by either the remote user or root and may
not be a symbolic link.
Your remote terminal type is the same as your local terminal type (as given in your environment TERM
variable). All echoing takes place at the remote site, so that (except for delays) the rlogin is transparent.
Flow control via AS and AQ and flushing of input and output on interrupts are handled properly.
ESCAPES

Lines that you type which start with the tilde character are 'escape sequences' (the escape character can be
changed via the -e options):
Disconnect from the remote host - this is not the same as a logout, because the local host breaks
the connection with no warning to the remote end.
Suspend the login session (only if you are using the C-Shell). susp is your 'suspend' characterusually AZ - see tty(1).
dsusp

Suspend the input half of the login, but output will still be seen (only if you are using the C-Shell).
dsusp is your 'deferred suspend' character - usually Ay - see tty(l).

OPTIONS

-I

Specifies a different user name (username, in the synopsis) for the remote login. If you do not use
this option, the remote usemame used is the same as your local usemame.

-e

Specifies a different escape character (c, in the synopsis) for the line used to disconnect from the
remote host.

-8

Pass eight-bit data across the net instead of seven-bit data.

SEE ALSO

rsh(IC), stty(IV)
FILES

lusr/hosts/*
I etc/hos ts.eq ui v
-/.rhosts

for rhost version of the command
list of rhost s with shared account names
private list of rhost s with shared account names

BUGS

342

Last change: 23 September 1985

Sun Release 3.2

RLOGIN(lC)

USER COMMANDS

RLOGIN(lC)

This implementation can only use the TCP network service.
More terminal characteristics should be propagated.

Sun Release 3.2

Last change: 23 September 1985

343

RM(I)

USER COMMANDS

RM(l)

NAME

no, nndir - remove (unlink) files or directories
SYNOPSIS
rm [ -r ] [ -f] [ -i] [ - ] filename ...

rmdir directory . ..
DESCRIPTION
Rm
rm removes (directory entries for) one or more files. If an entry was the last link to the file, the contents of
that file are lost. (See In(l) for more information about multiple links to files.)

To remove a file, you must have write permission in its directory; but you don't need read or write permission on the file itself. If you don't have write permission on the file and the standard input is a terminal, rm
displays the file's pennissions and waits for you to type in a response. If your response begins with 'y' the
file is deleted; otherwise the file is left alone.
Rmdir
rmdir removes each named directory, which must be empty.
OPTIONS

-r

Force files to be removed without displaying permissions, asking questions or reporting errors.

-r

Recursively delete the contents of a directory, its subdirectories, and the directory itself.

-i

Ask whether to delete each file, and, under -r, whether to examine each directory. Sometimes
called the interactive option.
Treat the following arguments as filenames minus.

so that you can specify filenames starting with a

WARNING
It is forbidden to remove the file' .. ' to avoid the antisocial consequences of inadvertently doing something
like 'rm -r .*'.
SEE ALSO
In(l)

344

Last change: 1 Aug 1986

Sun Release 3.2

USER eOMMANDS

RMDEL(I)

RMDEL(I)

NAME

rmdel- remove a delta from an sees file
SYNOPSIS

lusrlsccs/rmdel-rSID file •••
DESCRIPTION

Rmdel removes the delta specified by the SID from each named sees file. The delta to be removed must be
the newest (most recent) delta in its branch in the delta chain of each named sees file. In addition, the SID
specified must not be that of a version being edited for the purpose of making a delta (that is, if ap-file (see
get (1» exists for the named sees file, the SID specified must not appear in any entry of the p-file).
If a directory is named, mulel behaves as though each file in the directory were specified as a named file,
except that non-SCeS files (last component of the path name does not begin with s.) and unreadable files
are silently ignored. If a name of - is given, the standard input is read; each line of the standard input is
taken to be the name of an sees file to be processed; non-sees files and unreadable files are silently
ignored

The exact permissions necessary to remove a delta are documented in the Source Code Control System
User's Guide. Simply stated, they are either 1) if you make a delta you can remove it; or 2) if you own the
file and directory you can remove a delta.
FILES

x-file
z-file

(see delta(l»
(see delta(l»

SEE ALSO

sccs(I), delta(I), get(I), help(I), prs(I), sccsfile(5).
Programming Utilities for the Sun Workstation.
DIAGNOSTICS

Use help(l) for explanations.

Sun Release 3.2

Last change: 17 February 1986

345

ROFFBIB( 1)

USER COMMANDS

ROFFBm(l)

NAME

roftbib - run off bibliographic database
SYNOPSIS
roftbib [ -e ] [ -b] [ -m name ] [ -np ] [ -oUst] [ -Q
[ -x] [filename] ...

] [ -raN] [ -sN]

[ - Tterm] [ -V]

DESCRIPTION

Roffbib prints out all records in a bibliographic database, in bibliography format rather than as footnotes or
endnotes. Generally it is used in conjunction with sortbib:
sortbib database I roftbib
OPTIONS

Roffbib accepts all options understood by nroff(l) except -i and -q.

-e

Produce equally-spaced words in adjusted lines using full terminal resolution.

-b

Use output tabs during horizontal spacing to speed output and reduce output character count. Tab
settings are assumed to be every 8 nominal character widths.

-m

Prepend the macro file lusrllibltrlUlcltrlUlc .name to the input files. There should be a space
between the -m and the macro filename. This set of macros will replace the ones defined in
lusrnib/tmac/tmac.bib.

-np

Number first generated page p .

-olist

Print only page numbers that appear in the comma-separated list of numbers and ranges. A range
N-M means pages N through M; an initial -N means from the beginning to page N; a final Nmeans from page N to end

-Q

Queue output for the phototypesetter. Page offset is set to 1 inch.

-raN

Set register a (one-character) to N. The command-line argument -rNl will number the references starting at 1.
Four command-line registers control formatting style of the bibliography, much like the number
registers of ms(7). The flag -rV2 will double space the bibliography, while -rVl will double
space references but single space annotation paragraphs. The line length can be changed from the
default 6.5 inches to 6 inches with the -rL6i argument, and the page offset can be set from the
default of 0 to one inch by specifying -rOli (capital 0, not zero).

-sN

Halt prior to every N pages for paper loading or changing (default N =1). To resume, enter a newline or carriage return.

-T

Specify term as the terminal type.

-V

Send output to the Versatec. Page offset is set to 1 inch.

-x

If abstracts or comments are entered following the %X field key, roffbib will format them into
paragraphs for an annotated bibliography. Several %X fields may be given if several annotation
paragraphs are desired.

FILES

lusrnib/tmac/tmac.bib

file of macros used by nroffltroff

SEE ALSO

refer(l), addbib(I), sortbib(I), indxbib(I), lookbib(I), nroff(l)

"Refer" in ForrlUltting Documents on the Sun Workstation
BUGS

Users have to rewrite macros to create customized formats.

346

Last change: 21 August 1985

Sun Release 3.2

RPCGEN(l)

USER COMMANDS

RPCGEN(l)

NAME

rpcgen - an RPC protocol compiler
SYNOPSIS
rpcgen -h [-0 outfile] [inputfile]
rpcgen -c [-0 outfile] [infile]
rpcgen infile
rpcgen [-s transport]* [-0 outfileJ [infile]
DESCRIPTION
rpcgen is a tool that generates C code to implement an RPC protocol. The input to rpcgen is a language
with striking similarity to C known as RPCL (Remote Procedure Call Language). rpcgen operates in four
modes. The first mode is used to convert RPCL definitions into C definitions for use as a header file. The
second mode compiles the XDR routines required to serialize the protocol described by RPCL. The third
mode compiles both, leaving the header file in a file named infile with a .h extension and the XDR routines
in infile with a .c extension. The fourth mode is used to compile an RPC server skeleton, so that all you
have to do is write local procedures that know nothing about RPC in order to implement an RPC server.

The input may contain C-style comments and preprocessor directives. Comments are ignored, while the
directives are simply stuffed uninterpreted in the output header file.
You can customize some of your XDR routines by leaving those data types undefined. For every data type
that is undefined, rpcgen will assume that there exists a routine with the name 'xdr_' prepended to the
name of the undefined type.
OPTIONS
-c

Compile XDR routines.

-h

Compile C data-definitions (a header file)

-ooutfile
Specify the name of the output file. If none is specified, standard output is used (-c, -h and -s
modes only).

-s transport
Compile a server, using the the given transport. The supported transports are udp and tcp. This
option may be invoked more than once so as to compile a server that serves multiple transports.
USAGE
RPCL Syntax Summary
This summary of RPCL syntax, which is used for rpcgen input, is intended more for aiding comprehension
than as an exact statement of the language.

Primitive Data Types
[ unsigned] char
[unsigned] short
[ unsigned] int
[ unsigned] long
unsigned
float
double
void
bool
Except for the added boolean data-type bool, RPCL is identical to C. rpcgen converts bool declarations to
int declarations in the output header file (literally it is converted to a boott, which has been -define'd to
be an int). Also, void declarations may appear only inside of union and program definitions. For those
averse to typing the prefix unsigned, the abbreviations u_char, u_short, u_int and u_long are available.

Sun Release 3.2

Last change: 11 March 1986

347

RPCGEN(I)

USER COMMANDS

RPCGEN(1)

Declarations
RPCL allows only three kinds of declarations:

declaration:
simple-declaration
pointer-declaration
vector-declaration
simple-declaration:
type-name object-ident
pointer-declaration:
type-name *object-ident
vector-declaration:
type-name object-ident[size]
(size can be either an integer or a symbolic constant)
RPCL declarations contain both limitations and extensions with respect to C. The limitations are that you
cannot declare multidimensional arrays or pointers-to-pointers in-line (You can still declare them though,
using typedef). There are two extensions:
Opaque data is declared as a vector as follows:

opaque object-ident [ size]
In the protocol, this results in an object of size bytes. Note that this is not the same as a declaration
of size characters, since XDR characters are 32-bits. Opaque declarations are compiled in the output header file into character array declarations of size bytes.
Strings are special and are declared as a vector declaration:

string object-ident [ rruzx-size ]
If max-size is unspecified, then there is essentially no limit to the maximum length of the string.
String declarations get compiled into the following:
char *object-ident
Type Definitions
The only way to generate an XDR routine is to define a type. For every type zetype you define, there is a
corresponding XDR routine named xdr_zetype.

There are six ways to define a type:

type-definition:
typedef
enumeration-de!
structure-deJ
variable-length-array-def
discriminated-union-de!
program-de!
The first three are very similar to their C namesakes. C does not have a formal type mechanism to define
variable-length arrays and XDR unions are quite different from their C counterparts. Program definitions
are not really type definitions, but they are useful nonetheless.
You may not nest XDR definitions. For example, the following will cause rpcgen to choke:
struct dontdoit {
struct ididit {
intoops;
} sorry;
enum ididitagain { OOPS, WHOOPS} iapologize;

348

Last change: 11 March 1986

Sun Release 3.2

RPCGEN(l)

USER COMMANDS

RPCGEN(l)

};
Typedefs
An XDR typeder looks as follows:

typedef'

typeder declaration;
The object-ident part of declaration is the name of the new type, whereas the type-name part is the name of
the type from which it is derived.
Enumeration Types
The syntax is:
enumeration-def'
enum enum-ident {
enum-list
};

enum-list:
enum-symbol-ident [ = assignment]
enum-symbol-ident [ = assignment] , enum-list
(assignment may be either an integer or a symbolic constant)
If there is no explicit assignment, then the implicit assignment is the value of the previous enumeration plus
1. If not explicitly assigned, the first enumeration receives the value O.
Structures

structure-def'

struct struct-ident {
declaration-list

};
declaration-list:
declaration ;
declaration ; declaration-list
Variable-Length Arrays

variable-length-array-def'
array array-ident {
unsigned length-identifer ;
vector-declaration ;
};

A variable length array definition looks much like a structure definition. Here's an example:
array mp_ int {
unsigned len;
short val[MAX_MP_LENGTII];
};
This is compiled into:
struct mp_ int {
unsigned len;
short *val;
};
typedef struct mp_int mp_int;
Disriminated Unions

discriminated-union-def:
union union-ident switch ( discriminant-declaration) {
case-list
[ default: declaration; ]

Sun Release 3.2

Last change: 11 March 1986

349

RPCGEN(I)

USER COMMANDS

RPCGEN(1)

};

case-list:

case case-ident : declaration;
case case-ident : declaration ; case-list
discriminant-declaration:
declaration
The union definition looks like a cross between a C-union and a C-switch. An example:
union net_object switch (net_kind kind) {
case MACHINE:
struct sockaddrIn sin;
case USER:
int uid;
default:
string whatisit;
};
Compiles into:
struct net_object {
net_kind kind;
union {
struct sockaddr_in sin;
int uid;
char *whatisit;
} net_object;
};
typedef struct net_object net_object;
Note that the name of the union component of the output struct is the same as the name of the type itself.
Program Definitions

pro gram-def.·

program program-ident {
version-list
}=program-number;
version-list:
version
version version-list
version:
version version-ident {
procedure-list
}=version-number ;
procedure-list:
procedure-declaration
procedure-declaration procedure-list
procedure-declaration:
type-name procedure-ident ( type-name)

=procedure-number ;

Program definitions look like nothing you've ever seen before, so we turn to an example to explain them.
Suppose you wanted to create server that could get or set the date. It's declaration might look like this:
program DATE_PROG {
version DATE_VERS {
date DATE_GET(timezone) = 1;
1* Greenwich mean time *1
voidDATE_SET(date) = 2;

} = 1;
} =

350

100;

Last change: 11 March 1986

Sun Release 3.2

RPCGEN(l)

USER COMMANDS

RPCGEN(l)

In the header file, this compiles into the following:
-defineDATE PROG 100
-define DATE VERS 1
-defineDATE GET 1
-define DATE SET 2
These define's are intended for use by the client program to reference the remote procedures.

If you are using rpcgen to compile your server, then there are some important things for you to know. The
server interlaces to your local procedures by expecting a C function with the same name as that in the program definition, but in all lower-case letters and followed by the version number. Here is the local procedure that implements DATE_GET:
date * /* always returns a pointer to the results */
date_get_l(tz)
timezone *tz;
/* always takes a a pointer to the arguments */
{

static date d;

/* must be static! */

/*

* figure out the date
* and store it in d

*/
return(&d);
}
The name of the routine is the same as the -define'd name, but in all lower case letters and followed by the
version number. XDR will recursively free the argument after getting the results from your local procedure,
so you should copy from the argument any data that you will need between calls. However, XDR neither
allocates nor frees your results. You must take care of their storage yourself.

Make Inference Rules For Compiling XDR Headers
It is possible to set up suffix transformation rules in make (1) for compiling XDR routines and header files.
The convention is that RPCL protocol files have the extension oX. The make rules to do this are:
.SUFFIXES: .x
.x.c:
rpcgen -c %< -0 %@

.x.h:
rpcgen -h %< -0 %@
SEE ALSO

Remote Procedure Call: Programming Guide and External Data Representation: Protocol Specification in
Networking on the Sun Workstation
BUGS

Name clashes can occur when using program definitions, since the apparent scoping does not really apply.
Most of these can be avoided by giving unique names for programs, versions, procedures and types.

Sun Release 3.2

Last change: 11 March 1986

351

RSH(lC)

USER COMMANDS

RSH( IC)

NAME

rsh - remote shell
SYNOPSIS

rsh host [ -I username ] [ -0] command
host [ -I username ] [ -0 ] command
DESCRIPTION
rsh connects to the specified host, and executes the specified command. rsh copies its standard input to the

remote command, the standard output of the remote command to its standard output, and the standard error
of the remote command to its standard error. Interrupt, quit and terminate signals are propagated to the
remote command; rsh normally terminates when the remote command does.
If you omit command, instead of executing a single command, rsh logs you in on the remote host using 710gin.

Shell metacharacters which are not quoted are interpreted on the local machine, while quoted metacharacters are interpreted on the remote machine. Thus the command:
tutorial% rsh lizard cat lizard.file » tutorial. file
appends the remote file lizard.file from the machine called lizard to the file called tutorial file on the
machine called tutorial, while the command:
tutorial% rsh lizard cat lizard.file "»" another.lizard.file
appends the file lizardfile on the machine called lizard to the file another.lizard.fi1e. which also resides on
the machine called lizard.
Host names are given in the file letclhosts. Each host has one standard name (the first name given in the
file), which is rather long and unambiguous, and optionally one or more nicknames. The host names for
machines to which your machine is networked are also found in the directory lusrlhosts, as symbolic links
to rsh. If you put this directory in your search path then the rsh can be omitted.
OPTIONS
-I username

use username as the remote username instead of your local usemame. In the absence of this
option, the remote usemame is the same as your local usemame, This remote name must be
equivalent to the originating account. No provision is made for specifying a password with a command, and none is necessary - if your usemame is known at the remote end you will be admitted,
otherwise you will be prompted for a password.
-n

redirect the input of rsh to !devlnull. You sometimes need this option to avoid unfortunate
interactions between rsh and the shell which invokes it For example, if you are running csh and
invoke a rsh in the background without redirecting its input away from the terminal, it will block
even if no reads are posted by the remote command. The -n option will prevent this.

The type of remote shell (sh or csh) is determined by the user's entry in the file letclpasswd on the remote
system.
FILES

letclhosts
lusrlhostsl*
SEE ALSO

rlogin (Ie)
BUGS

You cannot run an interactive command (like vi; use rio gin if you wish to do so.)
Stop signals stop the local rsh process only; this is arguably wrong, but currently hard to fix for reasons too
complicated to explain here.

352

Last change: 23 September 1985

Sun Release 3.2

RSH(IC)

USER COMMANDS

RSH( IC)

The current local environment is not passed to the remote shell.
Sometimes the -n option is needed for reasons that are less than obvious. For example, the command:
rsh somehost dd if=/dev/nrmtO bs=20b I tar xvpBf •
will put your shell into a strange state. Evidently, what happens is that the tar tenninates before the rsh.
The rsh then tries to write into the "broken pipe" and, instead of terminating neatly, proceeds to compete
with your shell for its standard input. Invoking rsh with the -n option avoids such incidents.
Note, however, that this bug occurs only when rsh is at the beginning of a pipeline and is not reading standard input. Don't use the -n if the rsh actually needs to read standard input. For example,
tar cf - • I rsh sundial dd of=ldev/rmtO obs=20b
doesn't produce the bug. If you were to use the -n in a case like this, the rsh would incorrectly read from
ldevlnull instead of from the pipe.

Sun Release 3.2

Last change: 23 September 1985

353

RUP( lC)

USER COMMANDS

RUP( lC)

NAME

rup - show host status of local machines (RPC version)
SYNOPSIS
rup [ -b ] [ -I] [ -t] [ host. •• ]
DESCRIPTION
Rup gives a status similar to uptime for remote machines; It broadcasts on the local network, and displays
the responses it receives.

Normally, the listing is in the order that responses are received, but this order can be changed by specifying
one of the options listed below.
When host arguments are given, rather than broadcasting rup will only query the list of specified hosts.
A remote host will only respond if it is running the rstatd daemon, which is normally started up from
inetd(8C).
OPTIONS
-b sort the display alphabetically by host name.

-I sort the display by load average
-t sort the display by up time.

FILES

/ etc! servers
SEE ALSO
ruptime(IC), inetd(8C), rstatd(8C)
BUGS

Broadcasting does not work through gateways.

354

Last change: 5 July 1985

Sun Release 3.2

RUPTIME( lC)

USER COMMANDS

RUPTIME( lC)

NAME

ruptime - show host status of local machines
SYNOPSIS
ruptime [ -a ] [ -I ] [ -t] [ -u ]
DESCRIPTION

Ruptime gives a status line like uptime for each machine on the local network; these are formed from packets broadcast by each host on the network once a minute.
Machines for which no status report has been received for 5 minutes are shown as being down.
Normally, the listing is sorted by host name, but this order can be changed by specifying one of the options
listed below.
OPTIONS

-a count even those users who have been idle for an hour or more.
-I sort the display by load average.
-t sort the display by up time.
-u sort the display by number of users.

FILES
lusrlspoollrwho/whod. *

data files

SEE ALSO
rwho(IC)

Sun Release 3.2

Last change: 7 March 1984

355

RUSERS(IC)

USER COMMANDS

RUSERS( lC)

NAME

rusers - who's logged in on local machines (RPC version)
SYNOPSIS

rusers [ -a ] [ -b ] [ -i ] [ -I] [ -u ] [ host ••• ]
DESCRIPTION
The rusers command produces output similar to users(1) and who(1). but for remote machines. It broadcasts on the local network, and prints the responses it receives. Normally, the listing is in the order that
responses are received, but this order can be changed by specifying one of the options listed below. When
host arguments are given, rather than broadcasting rusers will only query the list of specified hosts.

The default is to print out a listing in the style of users(1) with one line per machine. When the -I flag is
given, a rwho(1) style listing is used. In addition, if a user hasn't typed to the system for a minute or more,
the idle time is reported.
A remote host will only respond if it is running the rusersd daemon, which is normally started up from
inetd.
OPTIONS

-a

gives a report for a machine even if no users are logged on.

-b

sort alphabetically by host name.

-i

sort by idle time.

-I

Give a longer listing in the style of who(1).

-u

sort by number of users.

FILES

tete/servers
SEE ALSO
rwho(IC), inetd(8C), rusersd(8C)
BUGS

Broadcasting does not work through gateways.

356

Last change: 5 July 1985

Sun Release 3.2

RWALL(lC)

USER COMMANDS

RWALL(lC)

NAME

rwall- write to all users over a network
SYNOPSIS

rwall hostname ...
rwall-n netgroup ...
rwall-h host .,..n netgroup
DESCRIPTION

Rwall reads a message from standard input until end-of-file. It then sends this message, preceded by the
line uBroadcast Message ... ", to all users logged in on the specified host machines. With the -n option, it
sends to the specified network groups, which are defined in netgroup(5).
A machine can only receive such a message if it is running rwalld(8), which is normally started up from
tetclservers by the daemon inetd(8).
FILES

fetc/servers
SEE ALSO
wall(l), netgroup(5), rwalld(8C), shutdown(8)
BUGS

The timeout is fairly short in order to be able to send to a large group of machines (some of which may be
down) in a reasonable amount of time. Thus the message may not get thru to a heavily loaded machine.

Sun Release 3.2

Last change: 4 August 1986

357

RWHO(IC)

USER COMMANDS

RWHO(lC)

NAME

rwho - who's logged in on local machines
SYNOPSIS

rwho [-a]
DESCRIPTION
The rwho command produces output similar to who(l), but for all machines on your network. If no report
has been received from a machine for 5 minutes, rwho assumes the machine is down, and does not report

users last known to be logged into that machine.
If a user hasn't typed to the system for a minute or more, rwho reports this idle time. If a user hasn't typed
to the system for an hour or more, the user is omitted from the output of rwho unless the -a flag is given.
OPTIONS

-a

report all users whether or not they have typed to the system in the past hour.

FILES

lusrlspoo1/rwho/whod. *

information about other machines

SEE ALSO

ruptime( IC), rwhod(8C)
BUGS

Does not work through gateways.
This is unwieldy when the number of machines on the local net is large.

358

Last change: 8 March 1984

Sun Release 3.2

SACT( 1)

USER COMMANDS

SACT( 1)

NAME

sact - print current SCCS file editing activity
SYNOPSIS

lusrlsccs/sact file .••
DESCRIPTION
Sact informs the user of any sees files which have had one or more get -e commands applied to them, that
is, there are files out for editing, and deltas are pending. If a directory is named on the command line, sact
behaves as though each file in the directory were specified as a named file, except that non-sees files and
unreadable files are silently ignored. If a name of - is given, the standard input is read with each line being
taken as the name of an sees file to be processed. The output for each named file consists of five fields
separated by spaces.

Field 1

specifies the SID of a delta that currently exists in the sees file to which changes will
be made to make the new delta.

Field 2

specifies the SID for the new delta to be created.

Field 3

contains the logname of the user who will make the delta (that is, executed a get for
editing).

Field 4

contains the date that get -e was executed.

Field 5

contains the time that get -e was executed.

SEE ALSO
sccs(l), delta(l), get(l), unget(l).

Programming Utilities/or the Sun Workstation.
DIAGNOSTICS
Use help (1) for explanations.

Sun Release 3.2

Last change: 6 March 1984

359

SCCS( 1)

USER COMMANDS

SCCS(l)

NAME
sccs - front end for the SCCS subsystem

SYNOPSIS
sees [ -r ] [ -dprefixpath] [ -pfinalpath ] command [ SCCS-flags ... ] [file ... ]
DESCRIPTION
The secs command is a front end to the utility programs of the Source Code Control System (sees).
secs normally prefixes each file, or the last component of each file, with the string sees/s., because YOll
normally keep your sees database files in a directory called sees, and each database file starts with an s.
prefix. If the environment variable PROJECTDIR is set, and is an absolute pathname (Le., begins with a
slash) sees will search for sees files in the directory given by that variable. If it is a relative pathnarne
(Le., does not begin with a slash), it is treated as the name of a user, and secs will search in that user's
home directory for a directory named sre or source. If that directory is found, sccs will search for sees
files in the directory given by that variable.
secs program options must appear before the command argument. Flags to be passed to the actual sees
command (utility program) must appear after the command argument. These flags are specific to the command being used, and are discussed in Programming Utilities/or the Sun Workstation.
secs also includes the capability to run 'set user id' to another user to provide additional protection. Certain commands (such as admin) cannot be run 'set user id' by all users, since this would allow anyone to
change the authorizations. Such commands are always run as the real user.

OPTIONS
-r

Runs secs as the real user rather than as whatever effective user sccs is 'set user id' to.

-dprefixpath
Defines the prefix portion of the pathname for the sees database files. The default prefix portion
of the pathname is the current directory. prefixpath is prefixed to the entire pathname. For example:
tutorial% sees -dlusr/include get syslinode.h
converts to:
get lusr/include/syslSeeS/s.inode.h
The intent here is to create aliases such as:
alias syssces sees -dlusrlsre
which will be used as:
tutorial% syssces get emdlwho.e
This flag overrides any directory specified by the PROJECTDIR environment variable.
-pfinalpath
Defines the name of a lower directory in which the sees files will be found; sees is the default
ftnalpath is appended before the final component of the pathname. For example:
tutorial% sees -pprivate get usr/include/stdio.h
converts to:
get usr/include/private/s.stdio.h
ADDnnONALSCCSCO~ANDS

Several 'pseudo-commands' are available in addition to the usual sees commands. These are:

360

create

create is used when creating new s. files. For example, given a C source language file called
obscure.c, create would perform the following actions: (1) create the s. file called s.obscure.e in
the sees directory; (2) rename the original source file to ,obscure.c; (3) do an sees get on
obscure .c. Compared to the sees admin command, create does more of the startup work for you
and should be used in preference to admin.

enter

enter is just like create, except that it does not do the final sees get. It is usually used if an sees
edit is to be performed immediately after the enter.

edit

Get a file for editing.

Last change: 17 July 1986

Sun Release 3.2

SCCS( 1)

delget

USER COMMANDS

SCCS( 1)

Perform a delta on the named files and then get new versions. The new versions have id keywords expanded, and so cannot be edited.

deledit Same as delget, but produces new versions suitable for editing. deledit is useful for making a
'checkpoint' of your current editing phase.

fix

Removes the named delta, but leaves you with a copy of the delta with the changes that were in it.
must be followed by a -r flag. fix is useful for fixing small compiler bugs, etc. Since fix
doesn't leave audit trails, use it carefully.

fix
clean

Removes everything from the current directory that can be recreated from SCCS files. clean
checks for and does not remove any files being edited. If clean -b is used, branches are not
checked to see if they are currently being edited. Note that -b is dangerous if you are keeping the
branches in the same directory.

unedit

'Undoes' the last edit or get -e and returns a file to its previous condition. If you unedit a file
being edited, all changes made since the beginning of the editing session are lost

info

Displays a list of all files being edited. If the -b flag is given, branches (that is, SID's with two or
fewer components) are ignored. If the -u flag is given (with an optional argument), only files
being edited by you (or the named user) are listed.
.

check

Checks for files currently being edited, like info, but returns an exit code rather than a listing:
nothing is printed if nothing is being edited, and a non-zero exit status is returned if anything is
being edited. check may thus be included in an 'install' entry in a makefile, to ensure that everything is included in an sees file before a version is installed.

tell

Displays a list of files being edited on the standard output Filenames are separated by newlines.
Takes the -b and -u flags like info and check.

diffs

Compares (in diff-like format) the current version of the program you have out for editing and the
versions in sees format. diffs accepts the same arguments as diff, except that the -c flag must be
specified as -C instead, because the -c flag is taken as a flag to get indicating which version is to
be compared with the current version.

print

Print verbose information about the named files. print does an sees prs -e followed by an sees
get -p -m on each file.

EXAMPLES
To put a file called myprogram.c into
directory already existing:

sees format for the first time, assuming

also that there is no sees

sees

tutorial% mkdir
tutorial% sees create myprogram.e
myprogram.c:
1.1
14 lines
after you have verified that everything is all right
you remove the version of the file that starts with a comma:
tutorial% rm ,myprogram.e
tutorial%
To get a copy of myprogram.c for editing, edit that file, then place it back in the sees database:
tutorial% sees edit myprogram.e
1.1
new delta 1.2
14 lines
tutorial% vi myprogram.e
your editing session

Sun Release 3.2

Last change: 17 July 1986

361

SCCS( 1)

USER COMMANDS

SCCS( 1)

tutorial% sees delget myprogram.e
comments? Added abusive responses for compatibility with rest of system
1.2
7 inserted
7 deleted
7 unchanged
1.2
14 lines
tutorial%
To get a file from another directory:
tutorial% sees -p/usrlsrclsecsl get ee.e
or:
tutorial% sees get lusrlsrclseeslee.e
To make a delta of a large number of files in the current directory:
tutorial% sees delta *.e
To get a list of files being edited that are not on branches:
tutorial% sees info -b
To delta everything that you are editing:
tutorial% sees delta 'sees tell-u'
In a makefile, to get source files from an sees file if it does not already exist
SRCS = 
%(SRCS):
sccs get %(REL) %@
REGULARSeeSeO~ANDS

The 'regular' sees commands are described very briefly below. It is unlikely that you ever need to use
these commands because the user interface is so complicated, and the sees front end command does 99.9%
of the interesting tasks for you.

admin

Creates new sees files and changes parameters of existing sees files. You can use sees create to
create new sees files, or use sees admin to do other things.

cdc

Changes the commentary material in an sees delta

comb

Combines sees deltas and reconstructs the sees files.

delta

Permanently introduces changes that were made to a file previously retrieved via sees get. You
can use sees delget as the more useful version of this command since sees delget does all of the
useful work and more to boot.

get

Extracts a file from the sees database, either for compilation, or for editing when the -e option is
used Use sees get if you really need it, but sees delget will normally have done this job for you.
Use sees edit instead of get with the -e option.

help

Supposed to help you interpret sees error messages, but usually just parrots the messaage and is
generally not considered very helpful.

prs

Displays information about what is happening in an sees file.

rmdel

Removes a delta from an sees file.

sccsdiff Compares two versions of an sees file and generates the differences between the two versions.

unget

362

Undoes the work of a previous get -e command or a sees edit command. Use the sees unedit
command as a useful alternative.

Last change: 17 July 1986

Sun Release 3.2

SCCS( 1)

USER COMMANDS

SCCS( 1)

val

Determines if a given sees file meets specified criteria. If you use the sees command, you
shouldn't need to use val, because its user interface is unbelievable.

what

Displays sees identification information.

FILES

lusrlsces/*
SEE ALSO

admin(1), cdc(1), eomb(l), delta(1), get(1), help(1), prs(1), rmdel(1), sact(1), sccsdiff(1), unget(l), val(I),
vvhat(1), sccsfile(5)
Programming Utilities/or the Sun Workstation

Sun Release 3.2

Last change: 17 July 1986

363

SCCSDIFF ( 1 )

USER COMMANDS

seeSDIFF ( 1 )

NAME

sccsdiff - compare two versions of an sees file
SYNOPSIS

lusrlsccs/sccsdifT -r SID 1 -r SID2 [ -p ] [ -ditTopts ] filenames
DESCRIPTION

sccsdiff compares two versions of an sees file and generates the differences between the two versions.
Any number of sees files may be specified, but options apply to all files.
OPTIONS
-rSID?

SID1 and SID2 specify the deltas of an
passed to diff in the order given.

sees

file that are to be compared. Versions are

-p

pipe output for each file through pr.

-diffopts

the -1:, -e, -f, -b, -b and -D options of diff can be specified here.

FILES

Itmp/get????? Temporary files
SEE ALSO

sccs(I), diff(I), get(I), help(l)
Programming Utilities/or the Sun Workstation.
DIAGNOSTICS

"file: No differences"
Use help for explanations.

364

If the two versions are the same.

Last change: 23 September 1985

Sun Release 3.2

SCREENBLANK ( 1 )

USER COMMANDS

SCREENBLANK ( 1 )

NAME

screenblank - tum off video when the mouse and keyboard are idle
SYNOPSIS

screenblank [ -m ] [ -k ] [ -d interval] [ -e interval ] [ -f frame_buffer]
DESCRIPTION

screenblank turns off the display when the mouse and keyboard are idle for an extended period (the default
is 10 minutes).
OPTIONS

-m

Do not check whether the mouse has been idle.

-k

Do not check whether the keyboard has been idle.

-d interval
Disable after interval seconds. interval is a number of the form xxx..n:x where each x is a decimal
digit The default is 600 seconds (10 minutes).

-e interval
Enable within interval seconds. interval is the time between successive polls for keyboard or
mouse activity. If a poll detects keyboard or mouse activity, the display is resumed interval is a
number of seconds, of the form xxx..n:x where each x is a decimal digit The default is 0.25
seconds.
-f frame _buffer
frame_buffer is the path name of the frame buffer on which video disabling/enabling applies. The
defaults is /dev/fb.
SEE ALSO

lockscreen( 1)
BUGS

When not running suntools(l), only the RETURN key resumes video display.

Sun Release 3.2

Last change: 21 June 1986

365

SCREENDUMP ( 1 )

USER COMMANDS

SCREENDUMP ( 1 )

NAME

screendump - dump frame buffer image
SYNOPSIS
screendump [ -f display] [ -e] [ -t type] [ output-file ]
DESCRIPTION
Screendump reads out the contents of a frame buffer on any model of Sun Workstation and outputs the
display image in Sun standard rasterfile format (see lusrlindudelrasterfile.h) on output-file (or on the standard output if output-file is not specified).

By default, screendump attempts to output the contents of the console frame buffer (Idevlfb). The-f
option explicitly sets the name of the desired frame buffer device.
The utility program screen load displays Sun standard rasterfiles on an appropriate Sun Workstation monitor. Output filters exist for printing standard monochrome rasterfiles on Versatec V-80 electrostatic
plotters.
OPTIONS
-f display
Use display as the device name of the display.

-e

Shorthand for -t 2.

-t type Specify the type of the rasterfile to write:

o

1
2
65535

Old format files compatible with Release 1.1 software.
Standard format.
Run-length encoding of bytes.
To experiment with private encodings.

EXAMPLES

tutorial% screendump >save.this.image
writes the current contents of the console frame buffer into the file save .this. image .
tutorial% screendump -f Idev/cgoneO >save.color.image
writes the current contents of the frame buffer ldevlcgoneO into the file save.color.image.
tutorial% screen dump

I Ipr -Pversatec -v

sends a rasterfile containing the current frame buffer to the lineprinter, selecting the printer named' 'versatec" and the "v" output filter (see letc!printcap).
FILES

ldev/tb
Idev/cgoneO
Idev/cgtwoO
lusrllib/rasfilters/*

Default name of console display frame buffer.
Default name of the Sun-l color display frame buffer.
Default name of the Sun-2 color display frame buffer.
Filters for the raster file

SEE ALSO
lpr( 1), rastrepl( 1), screenload( 1)

pr_dump in SunView Programmer's Guide and Sun View System Programmer's Guide

366

Last change: 1 February 1985

Sun Release 3.2

SCREENLOAD ( 1 )

USER COMMANDS

SCREENLOAD ( 1 )

NAME

screenload - restore frame buffer image
SYNOPSIS
screenload [ -d] [ -f display] [ -iindex] [ -b ] [ -g] [ -p ] [ -w] [ -b hex-constants [ input-file ]
DESCRIPTION
Screenload accepts input in Sun standard rasterfile format (see lusrlincludelrasterfile.h) and attempts to
display the input on the appropriate monitor (monochrome or color). Screen load normally displays
rasterfiles on the console display, but displays them on some heuristically determined color display if it
finds no console display. Screenload displays color rasterfiles only on a color monitor. Screenload is able
to display monochrome rasters on a color display.

If the dimensions of the image contained in the input data are smaller than the actual resolution of the
display (for example, loading a 1024-by-800 Sun-l image on a 1152-by-900 Sun-2 display), screenload
centers the image on the actual workstation screen and fills the border area with solid black (by default).
Various options may be used to change the fill pattern.
If the dimensions of the image contained in the input data are larger than the actual resolution of the
display, screenload clips the right and bottom edges of the input image.
If there is an optional filename argument, screen load reads its input data from that file. If no filename
argument is given, screenload reads its input data from the standard input.
The utility program screendump creates Sun standard rasterfiles from the display on a Sun Workstation
monitor.
OPTIONS
-d

Verify that display dimensions and input data image dimensions match, and print warning messages if they do not.

-f display
Use display as the name of the frame buffer device.

-iindex If the image is smaller than the display, use index (0 <= index < 256) as the index value into the
color map for the foreground color of the border fill pattern. The default index value is 255.
-b

If the input data dimensions are smaller than the display dimensions, fill the border with a pattern
of solid ones (default). On a monochrome display this results in a black border; on a color display
the color map value selected by the -i option determines the border color.

-g

If the input data dimensions are smaller than the display dimensions, fill the border with a pattern
of "desl(top grey". On a monochrome display this results in a border matching the background
pattern used by SunView; on a color display the color map value selected by the -i option determines the foreground border color, though the pattern is the same as on a monochrome display.

-p

Wait for a newline to be typed on the standard input before exiting.

-w

If the input data dimensions are smaller than the display dimensions, fill the border with a pattern
of solid zeros. On a monochrome display this results in a white border; on a color display the
color map value at index 0 determines the border color.

-b hex-constants
If the input data dimensions are smaller than the display dimensions, fill the border with the bit
pattern described by the following # 16-bit hexadecimal constants. Note that a "I" bit is black
and a "0" bit is white on the monochrome display; on a color diplay the color map value selected
by the -i option determines the border foreground color. The number of hex constants in the pattern is limited to 16.
EXAMPLES

tutorial% screenload saved.display.image
reloads the raster image contained in the file saved.display.image on the display type indicated by the

Sun Release 3.2

Last change: 6 February 1985

367

SCREENLOAD ( 1 )

USER COMMANDS

SCREENLOAD ( 1 )

rasterfile header in that file.
tutorial% screenload -f/dev/cgoneO monochrome.image
reloads the raster image in the file monochrome. image on the frame buffer device /dev/cgoneO.
tutorial% screenload -hI fflT sun_I.saved.image
is equivalent to the -b option (fill border with black), while
tutorial% screenload -h4 8888 8888 2222 2222 sun_I.saved.image
is equivalent to the -g option (fill border with desktop grey).
FILES

/dev/tb
/dev/cgoneO
/dev/cgtwoO
/usrllib/rasfilters/*

Default name of console display frame buffer
Default name of Sun-l color display frame buffer
Default name of the Sun-2 color display frame buffer.
Filters for the raster file

SEE ALSO
screendump( 1)
pr_load in SunView Programmer's Guide and SunView System Programmer's Guide

368

Last change: 6 February 1985

Sun Release 3.2

SCRIPT ( 1)

USER COMMANDS

SCRIPT ( 1)

NAME

script - make typescript of terminal session
SYNOPSIS
script [ -a] [file]
DESCRIPTION

Script makes a typescript of everything printed on your terminal. The typescript is written to file, or
appended to file if the -a option is given. It can be sent to the line printer later with lpr. If no file name is
given, the typescript is saved in the file typescript.
The script ends when the forked shell exits.
OPTIONS
Append the script to the specified file instead of writing over it.

BUGS
Script places everything in the log file. This is not what the naive user expects.

Sun Release 3.2

Last change: 24 March 1983

369

SDIFF( 1)

USER COMMANDS

SDIFF( 1)

NAME

sdiff - side-by-side difference program
SYNOPSIS

sdifT [ -I] [ -0 outfile ] [ -5 ] [ -w n ] filel file2
DESCRIPTION
sdiff uses the output of diff to produce a side-by-side listing of two files indicating those lines that are different Each line of the two files is printed with a blank gutter between them if the lines are identical, a < in

the gutter if the line only exists infilel , a> in the gutter if the line only exists infile2, and a I for lines that
are different
For example:
x
a
b
c
d

y
a
<
<
>

OPTIONS
-w n

d
c

Use n as the width of the output line. The default line length is 130 characters.

-I

Only print the left side of any identical lines.

-s

Silent Do not print identical lines.

-0

outfile
Use the next argument, output, as the name of an output file created as an interactively controlled
merging of filel and file2. Identical lines of filel and file2 are copied to output. Sets of differences, as produced by diff, are printed; where a set of differences share a common gutter character. After printing each set of differences, sdiff prompts with a % and waits for you to type one of
the following commands:

append the left column to the output file
r

append the right column to the output file

s

turn on silent mode; do not print identical lines

v

turn off silent mode

eI

call the ed(1) with the left column

er

call ed (1) with the right column

eb

call ed (1) with the concatenation of left and right columns

e

call ed (1) with a zero length file
On exit from ed(l), the resulting file is concatenated to the named output file.

q

exit from the program

SEE ALSO

diff(l), ed(l)

370

Last change:

Sun Release 3.2

SED ( IV)

USER COMMANDS

SED ( IV)

NAME

sed - stream editor
SYNOPSIS

sed [ -0] [ -e script] [ -f sfile] [file] •••
DESCRIPTION
Sed copies the named files (standard input default) to the standard output, edited according to a script of
commands.
OPTIONS
-e

script is an edit command for sed. If there is just one -e option and no -f's, the -e flag -e may be
omitted

-f

Take the script from sfile.

-0

Suppress the default output.

USAGE
SED SCRIPTS
sed scripts consist of editing commands, one per line, of the following form:

[ address [, address] ] function [ arguments]
In normal operation sed cyclically copies a line of input into a pattern space (unless there is something left
after a D command), sequentially applies all commands with addresses matching that pattern space until
reaching the end of the script, copies the pattern space to the standard output (except under -0), and finally,
deletes the pattern space.
Some commands use a hold space to save all or part of the pattern space for subsequent retrieval.
An address is either a decimal number linecount, which is cumulative across input files, a % that addresses
the last input line, or a context address, or Iregular expressionl in the style of ed(l) with the following
exceptions:

\n

Matches a newline embedded in the pattern space.
Matches any character except the newline ending the pattern space.

null

A command line with no address selects every pattern space.

addr

Selects each pattern space that matches.

addr1,addr2
Selects the inclusive range from the first pattern space matching addr1 to the first pattern
space matching addr2. Selects only one line if addrl is greater than or equal to addr2.
Comments
If the first nonwhite character in a line is a pound sign (-), sed treats that line as a comment, and ignores it.
If, however, the first such line is of the form
-0

sed runs as if the -0 flag were specified.
Functions
The maximum number of permissible addresses for each function is indicated in parentheses in the list
below.

An argument denoted text consists of one or more lines, all but the last of which end with \ to hide the newline. Backslashes in text are treated like backslashes in the replacement string of an s command, and may
be used to protect initial blanks and tabs against the stripping that is done on every script line.
An argument denoted rfile or wfile must terminate the command line and must be preceded by exactly one
blank. Each wfile is created before processing begins. There can be at most 10 distinct wfile arguments.

(l)a\

Sun Release 3.2

Last change: 11 April 1986

371

SED ( IV)

USER COMMANDS

SED ( IV)

text
Append: Place text on the output before reading the next input line.
(2) b label
Branch to the : command bearing the label. Branch to the end of the script if label is empty.

(2)c\

text
Change: Delete the pattern space. With 0 or 1 address or at the end of a 2-address range, place
text on the output. Start the next cycle.
(2) d

Delete the pattern space. Start the next cycle.

(2) D

Delete the initial segment of the pattern space through the first newline. Start the next cycle.

(2) g

Replace the contents of the pattern space by the contents of the hold space.

(2) G

Append the contents of the hold space to the pattern space.

(2) h

Replace the contents of the hold space by the contents of the pattern space.

(2) H

Append the contents of the pattern space to the hold space.

(1) i\

text
Insert: Place text on the standard output
(2) I

List the pattern space on the standard output in an unambiguous form. Non-printing characters are
spelled in two-digit ASCII and long lines are folded

(2) n

Copy the pattern space to the standard output Replace the pattern space with the next line of
input.

(2) N

Append the next line of input to the pattern space with an embedded newline. (The current line
number changes.)

(2) p

Print Copy the pattern space to the standard output.

(2) P

Copy the initial segment of the pattern space through the first newline to the standard output.

(1) q

Quit Branch to the end of the script Do not start a new cycle.

(2) r rfile
Read the contents of rfile. Place them on the output before reading the next input line.

(2) slregular expressionlreplacementljlags
Substitute the replacement string for instances of the regular expression in the pattern space. Any
character may be used instead of /. For a fuller description see ed(l). Flags is zero or more of

g

Global: Substitute for all nonoverlapping instances of the regular expression rather than
just the first one.

p

Print the pattern space if a replacement was made.

w wfile Write: Append the pattern space to wfile if a replacement was made.

(2) t label
Test: Branch to the : command bearing the label if any substitutions have been made since the
most recent reading of an input line or execution of a t. If label is empty, branch to the end of the
script.

(2)wwfile
Write: Append the pattern space to wfile.
(2) x

Exchange the contents of the pattern and hold spaces.

(2) y/stringllstring21
Transform: Replace all occurrences of characters in string1 with the corresponding character in

372

Last change: 11 April 1986

Sun Release 3.2

SED ( IV)

USER COMMANDS

SED ( IV)

string2. The lengths of string1 and string2 must be equal.
(2)! function

Don't Apply the/unction (or group, if/unction is {) only to lines not selected by the address(es).
(0): label
This command does nothing; it bears a label for b and t commands to branch to. Note that the
maximum length of label is seven characters.

(1) =

Place the current line number on the standard output as a line.

(2) {

Execute the following commands through a matching} only when the pattern space is selected.

(0)

An empty command is ignored

SYSTEM V SED SCRIPTS

The following additional rule applies to addresses:
In a context address, the construction \?regular expression?, where? is any character, is identical
to Iregular expression I. Note that in the context address \xabc\xdefx, the second x stands for
itself, so that the regular expression is abcxdef.

The following additionaljlag applies to the s command:
n

n= 1 - 512. Substitute for just the nth occurrence of the regular expression.

SEE ALSO

ed(I), grep(I), awk(I), lex(I)
Using UNIX Text Utilities on the Sun Workstation
Editing Text Files on the Sun Workstation

Sun Release 3.2

Last change: 11 April 1986

373

SETKEYS( I}

USER COMMANDS

SETKEYS(l}

NAME

setkeys - modify the interpretation of keyboard keys
SYNOPSIS
setkeys [ reset I nosunview I [ [lefty] [noarrows ] ] ] [sunIl sun21 sun3 ]
DESCRIPTION

Setkeys changes the kernel's keyboard translation tables, converting a keyboard to one of a number of commonly desired configurations. It takes an indication of the modifications to be performed, and optionally,
the kind of keyboard attached to the user's machine. It affects all keyboard input for the machine it is run
on (in or out of the window system) until that effect is superseded by rebooting, or by running "setkeys
reset".
Setkeys has been superseded by the Input category in defaultsedit(l}, and by the program
input_from_defaults(l}. It is retained for backwards compatibility.
OPTIONS

modifications

Empty, or one of "reset", "nosunview", or some combination of "lefty" and "noarrows". By default, the keyboard is set to produce the SunView function-key codes
(Stop, Props, Front, Oose, Find, Again, Undo, Put, Get and Erase; ). On Sun2 and Sun3 keyboards, this is a no-op; on the
Sun1, those functions are assigned to two columns of the right numeric I function
pad.

Lefty

indicates the SunView functions are to be produced from keys on the right side of
the keyboard, convenient for using the mouse in the left hand

On the Sun2 and Sun3, the SunView functions are reflected to the outside columns
of the right function pad; those right-side functions are distributed in a more complicated fashion dictated by keeping the arrow keys together; see below. Also, the
Line Feed key, immediately below Return, is converted to a second Control.
On the Sunl, "lefty" is the same as the default, since there is no left function pad
Noarrows

Reassigns the keys with cursor arrows on their caps to produce simple function
codes (so they may be used with filters in the textsw, or mapped input in the
ttysw).

Nosunview

Valid only on a Sun2 or Sun3 keyboard, and incompatible with "lefty", "noarrows", or ''''reset'' This option assigns new codes to keys F1 and L2 - LIO, codes
that are not normally produced anywhere on the keyboard. These codes may be
selected by a mapi or mapo operation defined in a user's .ttyswrc file.
This option supports a measure of backwards compatibility to programs that apply
some other interpretation to the affected function keys. It allows them to access
the new codes when the standard codes would be preempted by SunView functions (e.g. in a tty subwindow).

Reset

is incompatible with "lefty", "noarrows", or "nosunview"; it causes the keyboard
to be reset to its original interpretation.

keyboard-type

One of "Sun1", "Sun2", or "Sun3". Normally, this option is omitted; the type of
keyboard attached to the system is obtained from the kernel. If included, the
option is believed in preference to the kernel's information. Setkeys treats Sun2
and Sun3 keyboards identically except when the modification is "reset."
Note: the keyboard type is not necessarily the same as the machine type. A Sunl
keyboard is the VT100-style keyboard shipped with Model 100Us, while Sun2
and Sun3 keyboards may be attached interchangeably to Sun-2 and Sun-3
machines. A Sun3 keyboard is distinguished by its aerodynamic housing, and the
presence of Caps and Alternate keys.

374

Last change: 29 April 1986

Sun Release 3.2

SETKEYS( 1)

USER COMMANDS

SETKEYS( 1)

Options may appear in any order, and case is not significant. The accompanying charts show the exact distribution of codes for each combination of keyboard and arguments to setkeys.
EXAMPLES

setkeys lefty noarrows
puts the SunView functions on the right pad of the keyboard, replacing arrow keys by the corresponding
right-function codes, and displacing right-function codes to the left pad
setkeys sunl reset
restores a Sunl keyboard to its original arrangement
SEE ALSO
defaultsedit(1 )
inputJrom_ defaults(1)
kb(4S)
Editing and the Text Facility, in Windows and Window-Based Tools, Beginner's Guide
BUGS
DIAGRAMS
Sunl,

reset:
A

V <
standard ]
typing
array

>

TFl
]
]
]

TF2
7
4
1

TF3
8
5
2

TF4
9
6
3

RFI
Undo
Put
Get
Delete

Stop
RF3
RF5
RF7
Find

RF2
Props
Front
Close

RF4
RF6
RF8

RFl
Undo
Put
Get
Delete

Stop
RF3
RF5

RF2
Props
Front
Close

RF4
RF6
RF8

0

Enter

default / lefty:
A

[
[
[
[

V <
standard]
typing
array

>

Again
]
]
]

default / lefty, noarrow:

[
[
[
[

Sun Release 3.2

TFITF2TF3TF4
Again
standard ]
]
typing
]
array
]

RF7

Find

Last change: 29 April 1986

375

SETKEYS(l)

USER COMMANDS

SETKEYS(l)

Sun2&Sun3,
reset I default

Stop
Props
Front
Close
Find

Again
Undo
Put
Get
Delete

TFl TF2 ...
[ standard
[
typing
[
array
[
[

RFl
RF4
RF7

RF2
RF5

<

RFll

RF13

V

RF3
RF6
RF9
>
RF15

RFl
RF4
RF7
RFIO
RF13

RF2
RF5
RF8
RFll
RF14

RF3
RF6
RF9
RF12
RF15

Retn
Ctrl

Again <
Undo
>
Put
RFll
Get
Delete V

Stop
Props
Front
Close
Find

Ret
Ctrl

Again
Undo
Put
Get
Delete

RF2
RF5
RF8
RFll
RF14

Stop
Props
Front
Close
Find

RFl
RF4
RF7

RF2
RF5

RF3
RF6
RF9
>
RF15

Retn
LF

noarrows (only):

Stop
Props
Front
Close
Find

Again
Undo
Put
Get
Delete

TFl TF2 ...
[ standard
[
typing
[
array
[
[

Retn

LF

lefty:

Stop
RF6
RF9
RF12
RF15

RFI
RF4
RF7
RFI0
RF13

TFl TF2 ...
[ standard
[
typing
[
array
[
[

]
]
]
]

lefty, noarrows

Stop
RF6
RF9

RF12
RF15

RFl
RF4
RF7
RFIO
RF13

TFl TF2 ...
[ standard
[
typing
[
array
[
[

nosunview:

Stop
LF12
LF13
LF14
LF15

376

TFll
TF12
TF13
TF14
TF15

LFll TF2 ...
[ standard
[
typing
[
array
[
[

Ret
LF

<

RFll

RF13

Last change: 29 April 1986

V

Sun Release 3.2

SH( 1)

USER COMMANDS

SH(I)

NAME

sh - shell, the standard UNIX command interpreter and command-level language
SYNOPSIS

sh [ -acetbiknstuvx ] [ arguments]
DESCRIPTION

sh, the Bourne shell, is the standard UNIX command interperter. It executes commands read from a terminal or a file.
Definitions

A blank is a TAB or a SPACE character. A name is a sequence of letters, digits, or underscores beginning
with a letter or underscore. A parameter is a name, a digit, or any of the characters *, @, -, ?, -, %, and

!.
Invocation
If the shell is invoked through exec(2) and the first character of argument zero is -, commands are initially
read from %HOMEI.profile, if such a file exists and is owned by you. Thereafter, commands are read as
described below, which is also the case when the shell is invoked as Ibinlsh.
OPTIONS

The flags below are interpreted by the shell on invocation only; unless the -c or -s flag is specified, the first
argument is assumed to be the name of a file containing commands, and the remaining arguments are
passed as positional parameters for use with the commands that file contains.

-c string

-s
-i

If the -c flag is present commands are read from string.
If the -s flag is present or if no arguments remain commands are read from the standard input.
Any remaining arguments specify the positional parameters. Shell output (except for Special
Commands) is written to file descriptor 2.
If the -i flag is present or if the shell input and output are attached to a terminal, this shell is
interactive. In this case TERMINATE is ignored (so that kill 0 does not kill an interactive
shell) and INTERRUPT is caught and ignored (so that wait is interruptible). In all cases, QUIT
is ignored by the shell.

The remaining flags and arguments are described under the set command, under Special Commands,
below.
USAGE

Refer to Doing More With UNIX Beginner's Guide for more information about using the shell as a programming language.
Commands
A simple command is a sequence of nonblank words separated by blanks. The first word specifies the
name of the command to be executed Except as specified below, the remaining words are passed as arguments to the invoked command The command name is passed as argument 0 (see exec (2». The value of
a command is its exit status if it terminates normally, or (octal) 200+status if it terminates abnormally (see
sigvec(2) for a list of status values).
A pipeline is a sequence of one or more commands separated by I (or, for historical compatibility, by'').
The standard output of each command but the last is connected by a pipe (2) to the standard input of the
next command. Each command is run as a separate process; the shell normally waits for the last command
to terminate before prompting for or accepting the next input line. The exit status of a pipeline is the exit
status of its last command.
A list is a sequence of one or more simple commands or pipelines, separated by;, &, &&, or II, and
optionally terminated by ; or &. Of these four symbols, ; and & have equal precedence, which is lower
than that of && and II. The symbols && and II also have equal precedence. A semicolon (;) causes
sequential execution of the preceding pipeline; an ampersand (&) causes asynchronous execution of the
preceding pipeline (the shell does not wait for that pipeline to finish). The symbols && and II are used to
indicate condition execution of the list that follows. With && , list is executed only if the preceding

Sun Release 3.2

Last change: 7 July 1986

377

SH( 1)

USER COMMANDS

SH( 1)

pipeline (or command) returns a zero exit status. With I I, list is executed only if the preceding pipeline (or
command) returns a nonzero exit status. An arbitrary number of NEWLINEs may appear in a list, instead of
semicolons, to delimit commands.
A command is either a simple command or one of the following constructions. Unless otherwise stated, the
value returned by a command is that of the last simple command executed in the construction.

for name [ in word. .. ] do list done
Each time a for command is executed, name is set to the next word taken from the in word list. If
in word. .. is omitted, then the for command executes the do list once for each positional parameter that is set (see Parameter Substitution below). Execution ends when there are no more words
in the list
case word in [pattern[ I pattern] ... ) list ;; ] ... esac
A case command executes the list associated with the first pattern that matches word. The form
of the patterns is the same as that used for filename generation (see Filename Generation) except
that a slash, a leading dot, or a dot immediately following a slash need not be matched explicitly.
if list then list [ ellf list then list ] ... [ else list ] fi
The list following if is executed and, if it returns a zero exit status, the list following the first then
is executed. Otherwise, the list following ellf is executed and, if its value is zero, the list following the next then is executed. Failing that, the else list is executed. If no else list or then list is
executed, then the if command returns a zero exit status.
while list do list done
A while command repeatedly executes the while list and, if the exit status of the last command in
the list is zero, executes the do list; otherwise the loop terminates. If no commands in the do list
are executed, then the while command returns a zero exit status; until may be used in place of
while to negate the loop termination test.
(list)
Execute list in a subshell.
{list;} list is simply executed.
name 0 {list;}

Define a function which is referenced by name. The body of the function is the list of commands
between { and }. Execution of functions is described below (see Execution ).
The following words are only recognized as the first word of a command and when not quoted:

if then else elif fi case esac for while until do done { }
Comments

A word beginning with - causes that word and all the following characters up to a NEWLINE to be ignored.
Command Substitution'

The standard output from a command enclosed in a pair of grave accents (, , ) may be used as part or all of
a word; trailing NEWLINE s are removed.
Parameter Substitution
The character % is used to introduce substitutable parameters. There are two types of parameters, positional and keyword. If parameter is a digit, it is a positional parameter. Positional parameters may be

assigned values by set. Keyword parameters (also known as variables) may be assigned values by writing:
name=value [ name=value ] ...

Pattern-matching is not performed on value. There cannot be a function and a variable with the same
name.
% {parameter}

The value, if any, of the parameter is substituted. The braces are required only when parameter is
followed by a letter, digit, or underscore that is not to be interpreted as part of its name. If parameter is * or @, all the positional parameters, starting with % 1, are substituted (separated by
spaces). Parameter %0 is set from argument zero when the shell is invoked.

378

Last change: 7 July 1986

Sun Release 3.2

SH( 1)

USER COMMANDS

SH( 1)

If the colon (:) is omitted from the following expressions, the shell only checks whether parameter is set or

not
% {parameter:-word}

If parameter is set and is nonnull, substitute its value; otherwise substitute word.
% {parameter:=word}
If parameter is not set or is null set it to word; the value of the parameter is substituted. Positional
parameters may not be assigned to in this way.
% {parameter:?word}
If parameter is set and is nonnull, substitute its value; otherwise, print word and exit from the
shell. If word is omitted, the message "parameter null or not set" is printed.
% {parameter:+word}
If parameter is set and is nonnull, substitute word; otherwise substitute nothing.
In the above, word is not evaluated unless it is to be used as the substituted string, so that, in the following
example, pwd is executed only if d is not set or is null:
echo %{ d:-' pwd' }
The following parameters are automatically set by the shell:
The number of positional parameters in decimal.
Flags supplied to the shell on invocation or by the set command.
?
The decimal value returned by the last synchronously executed command
%
The process number of this shell.
The process number of the last background command invoked.
The following parameters are used by the shell:
HOME The default argument (home directory) for the cd command.
PATH The search path for commands (see Execution below).
CDPATH
The search path for the cd command.
MAIL If this parameter is set to the name of a mail file and the MAILPATH parameter is not set,
the shell informs the user of the arrival of mail in the specified file.
MAILCHECK
This parameter specifies how often (in seconds) the shell will check for the arrival of
mail in the files specified by the MAILPATH or MAIL parameters. The default value is
600 seconds (10 minutes). If set to 0, the shell will check before each prompt.
MAILPATH
A colon (:) separated list of filenames. If this parameter is set, the shell informs the user
of the arrival of mail in any of the specified files. Each filename can be followed by %
and a message that will be printed when the modification time changes. The default message is you have mail.
PSt
Primary prompt string, by default" % ".
PS2
Secondary prompt string, by default' '> ".
IFS
Internal field separators, normally SPACE, TAB. and NEWLINE.
SHELL When the shell is invoked, it scans the environment (see Environment below) for this
name. If it is found and there is an 'r' in the filename part of its value, the shell becomes
a restricted shell.
The shell gives default values to PATH, PSI, PS2, MAILCHECK and IFS. HOME and MAIL are set by
login (1).
Blank Interpretation
After parameter and command substitution, the results of substitution are scanned for internal field separator characters (those found in IFS) and split into distinct arguments where such characters are found
Explicit null arguments (tt" or ,,) are retained. Implicit null arguments (those resulting from parameters
that have no values) are removed.

Sun Release 3.2

Last change: 7 July 1986

379

SH( 1)

USER COMMANDS

SH( 1)

Filename Generation
Following substitution, each command word is scanned for the characters *, ?, and [. If one of these characters appears the word is regarded as a pattern. The word is replaced with alphabetically sorted filenames
that match the pattern. If no filename is found that matches the pattern, the word is left unchanged. The
character. at the start of a filename or immediately following a /, as well as the character / itself, must be
matched explicitly.

*
?
[ ... ]

Matches any string, including the null string.
Matches any single character.
Matches anyone of the enclosed characters. A pair of characters separated by - matches
any character lexically between the pair, inclusive. If the first character following the
opening "[" is a "!" any character not enclosed is matched.

Quoting
The following characters have a special meaning to the shell and cause termination of a word unless
quoted:

I

; & ( )

A

< > NEWLINE SPACE TAB

A character may be quoted (i.e., made to stand for itself) by preceding it with a \. The pair \NEWLINE is
ignored All characters enclosed between a pair of single quote marks (, '), except a single quote, are
quoted. Inside double quote marks (" "), parameter and command substitution occurs and \ quotes the characters \ "', ", and %. "%*" is equivalent to "%1 %2 ...", whereas "%@" is equivalent to "%1"

"%2" ....
Prompting
When used interactively, the shell prompts with the value of PSI before reading a command. IT at any time
a NEWLINE is typed and further input is needed to complete a command, the secondary prompt (i.e., the
value of PS2) is issued.
Input/Output
Before a command is executed, its input and output may be redirected using a special notation interpreted
by the shell. The following may appear anywhere in a simple command or may precede or follow a command and are not passed on to the invoked command; substitution occurs before word or digit is used:

word
> >word
< <[ - ] word

<&digit

<&-

Use file word as standard input (file descriptor 0).
Use file word as standard output (file descriptor 1). If the file does not exist it is created;
otherwise, it is truncated to zero length.
Use file word as standard output. If the file exists output is appended to it (by first seeki(lg to the end-of-file); otherwise, the file is created.
The shell input is read up to a line that is the same as word, or to an end-of-file. The
resulting document becomes the standard input If any character of word is quoted, no
interpretation is placed upon the characters of the document; otherwise, parameter and
command substitution occurs, (unescaped) \NEWLINE is ignored, and \ must be used to
quote the characters \ %, "', and the first character of word. If - is appended to < <, all
leading TABs are stripped from word, and from the document.
Use the file associated with file descriptor digit as standard input. Similarly for the standard output using >&digit.
The standard input is closed. Similarly for the standard output using >&-.

If any of the above is preceded by a digit, the file descriptor which will be associated with the file is that
specified by the digit (instead of the default 0 or 1). For example:
... 2>&1

associates file descriptor 2 with the file currently associated with file descriptor 1.
The order in which redirections are specified is significant The shell evaluates redirections left-to-right
For example:

380

Last change: 7 July 1986

Sun Release 3.2

SH( 1)

USER COMMANDS

SH(I)

... l>xu2>&1

first associates file descriptor 1 with file xu. It associates file descriptor 2 with the file associated with file
descriptor 1 (i.e. xu). If the order of redirections were reversed, file descriptor 2 would be associated with
the terminal (assuming file descriptor 1 had been) and file descriptor 1 would be associated with file xu.
If a command is followed by & the default standard input for the command is the empty file /dev/null.
Otherwise, the environment for the execution of a command contains the file descriptors of the invoking
shell as modified by input/output specifications.
Redirection of output is not allowed in the restricted shell.
Environment
The environment (see environ(5V» is a list of name-value pairs that is passed to an executed program in
the same way as a normal argument list. The shell interacts with the environment in several ways. On
invocation, the shell scans the environment and creates a parameter for each name found, giving it the
corresponding value. If the user modifies the value of any of these parameters or creates new parameters,
none of these affects the environment unless the export command is used to bind the shell's parameter to
the environment (see also set -a). A parameter may be removed from the environment with the unset command. The environment seen by any executed command is thus composed of any unmodified name-value
pairs originally inherited by the shell, minus any pairs removed by unset, plus any modifications or additions, all of which must be noted in export commands.

The environment for any simple command may be augmented by prefixing it with one or more assignments
to parameters. Thus:
TERM=450 cmd
and
(export TERM; TERM=450; cmd)
are equivalent (as far as the execution of cmd is concerned).
If the -k flag is set, all keyword arguments are placed in the environment, even if they occur after the command name. The following first prints a=b c and c:
echo a=b c
set -k
echo a=b c
Signals
The INTERRUPT and QUIT signals for an invoked command are ignored if the command is followed by &;
otherwise signals have the values inherited by the shell from its parent, with the exception of signal 11 (but
see also the trap command below).
Execution
Each time a command is executed, the above substitutions are carried out. If the command name matches
one of the Special Commands listed below, it is executed in the shell process. If the command name does
not match a Special Command, but matches the name of a defined function, the function is executed in the
shell process (note how this differs from the execution of shell procedures). The positional parameters
% 1, % 2, .. .. are set to the arguments of the function. If the command name matches neither a Special
Command nor the name of a defined function, a new process is created and an attempt is made to execute
the command via exec (2).

The shell parameter PATH defines the search path for the directory containing the command. Alternative
directory names are separated by a colon (:). The default path is :/bin:/usr/bin (specifying Ibin, and
lusrlbin, in addition to the current directory). Directories are searched in order. The the current directory
is specified by a null path name, which can appear immediately after the equal sign (PATH=: ... ) or
between the colon delimiters ( ... :: ... ) anywhere else in the path list If the command name contains a I
the search path is not used; such commands will not be executed by a restricted shell. Otherwise, each
directory in the path is searched for an executable file. If the file has execute permission but is not an

Sun Release 3.2

Last change: 7 July 1986

381

SHe 1)

USER COMMANDS

SH(1 )

binary executable (see a.out(S) for details) it is assumed to be a file containing shell commands. A subshell is spawned to read it. A parenthesized command is also executed in a subshell.
The location in the search path where. a command was found is remembered by the shell (to help avoid
unnecessary execs later). If the command was found in a relative directory, its location must be redetermined whenever the current directory changes. The shell forgets all remembered locations whenever
the PATH variable is changed or the hash -r command is executed (see below).
Special Commands

Input/output redirection is now permitted for these commands. File descriptor 1 is the default output location.
No effect; the command does nothing. A zero exit code is returned.
Read and execute commands from file and return. The search path specified by PATH is used to
find the directory containing file .
break [ n ]
Exit from the enclosing for or while loop, if any. If n is specified break n levels.
continue [ n ]
Resume the next iteration of the enclosing for or while loop. If n is specified resume at the n-th
enclosing loop.
cd [ arg]
Change the current directory to arg. The shell parameter HOME is the default arg. The shell
parameter CDPATH defines the search path for the directory containing arg. Alternative directory
names are separated by a colon (:). The default path is  (specifying the current directory).
Note that the current directory is specified by a null path name, which can appear immediately
after the equal sign or between the colon delimiters anywhere else in the path list. If arg begins
with a I the search path is not used. Otherwise, each directory in the path is searched for arg.
echo [ arg ... ]
Echo arguments. See echo(IV) for usage and description.
eval [ arg ... ]
The arguments are read as input to the shell and the resulting command(s) executed.
exec [ arg ... ]
The command specified by the arguments is executed in place of this shell without creating a new
process. Input/output arguments may appear and, if no other arguments are given, cause the shell
input/output to be modified
exit [ n ]
Causes a shell to exit with the exit status specified by n. If n is omitted the exit status is that of the
last command executed (an end-of-file will also cause the shell to exit.)
export [ name... ]
The given names are marked for automatic export to the environment of subsequently-executed
commands. If no arguments are given, a list of all names that are exported in this shell is printed
Function names may not be exported.
hash [ -r ] [ name... ]
For each name, the location in the search path of the command specified by name is determined
and remembered by the shell. The -r option causes the shell to forget all remembered locations.
If no arguments are given, information about remembered commands is presented. Hits is the
number of times a command has been invoked by the shell process. Cost is a measure of the work
required to locate a command in the search path. There are certain situations which require that
the stored location of a command be recalculated. Commands for which this will be done are
indicated by an asterisk (*) adjacent to the hits information. Cost will be incremented when the
recalculation is done.
login [ arg . .. ]
Equivalent to exec login arg .... See login(l) for usage and description.
pwd
Print the current working directory. See pwd(l) for usage and description.
read [ name... ]
• file

382

Last change: 7 July 1986

Sun Release 3.2

SH( 1)

USER COMMANDS

SH( 1)

One line is read from the standard input and the first word is assigned to the first name, the second
word to the second name, etc., with leftover words assigned to the last name. The return code is 0
unless an end-of-file is encountered.
readonly [ name . .. ]
The given names are marked readonly and the values of the these names may not be changed by
subsequent assignment If no arguments are given, a list of all readonly names is printed.
return [ n ]
Causes a function to exit with the return value specified by n. If n is omitted, the return status is
that of the last command executed.
set [ -aefbkntuvx- [ arg . .. ] ]
-a
Mark variables which are modified or created for export
-e
Exit immediately if a command exits with a nonzero exit status.
-r
Disable filename generation
-h
Locate and remember function commands as functions are defined (function commands
are normally located when the function is executed).
-k
All keyword arguments are placed in the environment for a command, not just those that
precede the command name.
-n
Read commands but do not execute them.
-t
Exit after reading and executing one command.
-u
Treat unset variables as an error when substituting.
-v
Print shell input lines as they are read.
-x
Print commands and their arguments as they are executed.
Do not change any of the Bags; useful in setting % 1 to -.
Using + rather than - causes these Bags to be turned off. These Bags can also be used upon invocation of the shell. The current set of Bags may be found in %-. The remaining arguments are
positional parameters and are assigned, in order, to % 1, % 2, and so on. If no arguments are
given, the values of all names are printed.
shift [ n ]
The positional parameters are shifted to the left, from position n+ 1 to position 1, and so on. Previous values between % 1 and %n are discarded. If n is not given, it is assumed to be 1.
test
Evaluate conditional expressions. See test(1V) for usage and description.
times Print the accumulated user and system times for processes run from the shell.
trap [ arg ] [ n ] ...
The command arg is to be read and executed when the shell receives signal(s) n. (Note that arg is
scanned once when the trap is set and once when the trap is taken.) Trap commands are executed
in order of signal number. Any attempt to set a trap on a signal that was ignored on entry to the
current shell is ineffective. An attempt to trap on signal 11 (memory fault) produces an error. If
arg is absent all trap(s) n are reset to their original values. If arg is the null string this signal is
ignored by the shell and by the commands it invokes. If n is 0 the command arg is executed on
exit from the shell. The trap command with no arguments prints a list of commands associated
with each signal number.
type [ name ... ]
For each name, indicate how it would be interpreted if used as a command name.
umask [ 000 ]
The user file-creation mode mask is set to 000. The three octal digits refer to read/write/execute
permissions for owner, group, and others, respectively. The value of each specified digit is subtracted from the corresponding 'digit' specified by the system for the creation of a file. For example, umask 022 removes group and others write permission (files normally created with mode 777
become mode 755; files created with mode 666 become mode 644). The current value of the
mask is printed if 000 is omitted.
unset [ name ... ]
For each name, remove the corresponding variable or function. The variables PATH, PSt, PS2,
MAILCHECK and IFS cannot be unset

Sun Release 3.2

Last change: 7 July 1986

383

USER COMMANDS

SH(l)

SH(l)

wait [ n ]
Wait for the specified process and report its termination status. If n is not given all currently
active child processes are waited for and the return code is zero.
EXIT STATUS

Errors detected by the shell, such as syntax errors, cause the shell to return a nonzero exit status. If the
shell is being used noninteractively execution of the shell file is abandoned. Otherwise, the shell returns
the exit status of the last command executed (see also the exit command above).
FILES
%HOMEI.profiie
Itmplsh*

ldev/null
SEE ALSO

csh(1), cd(l), echo(lV), login(I), pwd(l), test(IV), dup(2), exec(2), fork(2), pipe(2), signal(2), umask(2),
wait(2), aout(5), profile(5), environ(5).
CAVEATS
If a command is executed, and a command with the same name is installed in a.directory in the search path
before the directory where the original command was found, the shell will continue to exec the original

command Use the hash command to correct this situation.
If you move the current directory or one above it, pwd may not give the correct response. Use the cd command with a full path name to correct this situation.

384

Last change: 7 July 1986

Sun Release 3.2

SHELLTOOL ( 1 )

USER COMMANDS

SHELLTOOL (1 )

NAME

shelltool- Run a shell (or other program) in the SunView environment
SYNOPSIS
shelltool [ -C] [ -B boldstyle] [ -I command] [program [args ]]
DESCRIPTION

shelltool is a standard tool provided with the SunView environment.
When invoked, shelltool runs a program, (usually a shell) in an interactive terminal emulator based on a tty
subwindow. Keystrokes typed to the shelltool are passed to the program running in the shelltool. If this
program is a shell, it accepts commands and runs programs in the usual way. For its scrolling and editting
capabilities, you may prefer to use cmdtool instead of shelltool. See cmdtool(l), suntools(I), Terminal
Emulators, and Windows and Window-Based Tools: Beginner's Guide for more information.
To run graphics programs, use gfxtool- see gfxtool(l).
DEFAULTS OPTIONS
/TtylBold_style
For programs that use emphasized text, shell tool supports bolding as well as inverse video. To set
the emphasis style, choose the category Tty in defaultsedit and choose one of the following for the
Bold_style entry:
None
disables emphasis
Offset X
thicken character horizontally
Offset Y
thicken character vertically
Offset X and Y
thicken character both horizontally and vertically
- - Offset XY
thicken character diagonally
Offset X and XY
thicken character both horizontally and diagonally
- - Offset Y and XY
thicken character both vertically and diagonally
- - Offset- X - and Y and- XY
thicken character horizontally, vertically and diagonally
display emphasis as inverse video, the standard default
Invert

/Tty/Retained
No is the standard default; it specifies that tty subwindows are not retained. If Yes is chosen, tty
sub windows are retained; this enhances display speed at the expense of memory consumption.
Repaint speed when the window is uncovered is greatly enhanced.
COMMANDLINE OPTIONS
-C
Redirect system console output to this instance of the shelltool.

-B boldstyle
Sets the boldstyle for this instance of shelltool. Boldstyle may be any of the choices for the
defaults database entry for ITty/Bold_style, or it may be a number from 0 to 8. The numbers
mean:
o
None
1
Offset X
Offset Y
2
3
Offset_X_and_ Y
(means Offset_XI Offset_Y)
4
Offset XY
5
Offset_X_and_XY
(means Offset_X I Offset_XY)
6
Offset_Y_and_ XY
(means Offset_Y I Offset_XY)
Offset_X_and_ Y_and_ XY (means Offset_XI Offset_Y I Offset_XY)
7
8
Invert
-I command
Input a command to the shell. Spaces in the command must be escaped.

shelltool also takes generic tool arguments; see suntools(l) for a list of these arguments.

Sun Release 3.2

Last change: 30 September 1985

385

SHELLTOOL ( 1 )

USER COMMANDS

SHELLTOOL ( 1 )

If a program argument is present, shelltool runs it. If there are no arguments, shelltool runs the program
corresponding to your SHELL environment variable. If this environment variable is not available, then
shelltool runs Ibin/sh.
THE TERMINAL EMULATOR
The tty subwindow of shelltool is a terminal emulator. Whenever a tty subwindow is created, the startup
file -I.ttyswrc is parsed for tty subwindow-specific parameters. A sample .ttyswrc file may be found in
lusrllib/ttyswrc. The command format of this file is:

Comment
Turn on the specified variable.
When key is typed pretend text was input
When key is typed pretend text was output.

#

set variable
mapi key text
mapo key text

The only currently defined "variable" is "pagemode". "Key" is one of LI-L15, FI-F15, TI-T15, RI-R15,
LEFT, or RIGHT (see note below). "Text" may contain escapes such as \E, \n, AX, etc. (escape, newline,
control-X, respectively). See termcap(5) for the format of the string escapes that are recognized. Note that
"mapi" and "mapo" may be replaced by another keymapping mechanism in the future.
NOTE: When using the default kernel keyboard tables, the keys Ll, LEFT, RIGHT, BREAK, R8, RIO,
R12, and R14 cannot be mapped in this way because they send special values to the tty subwindow. Also,
when using the default kernel keyboard tables, LI-LIO are now used by SunView. See setkeys(l) and
kbd(5) for more information on how to change the behavior of the keyboard.
It is possible to have terminal-based programs drive the tool in which its tty subwindow resides by sending
it special escape sequences. These escape sequences may also be sent by typing a key appropriately
mapped using the "mapo" function described above. The following functions pertain to the tool in which
the tty subwindow resides, not the tty subwindow itself.
\E[lt
\E[2t
\E[3t
\E[3;TOP;LEFTt
\E[4t
\E[4;WIDTH;HTt
\E[St
\E[6t
\E[7t
\E[8;ROWS;COLSt
\E[llt
\E[13t
\E[14t
\E[18t
\E[20t
\E [21t
\E]l\E\
\E]I\E\
\E]L\E\
\E[>OPT; .•. h
\E[>OPT; .•. k
\E[>OPT; .•. l

-open
- close (become iconic)
- move, with interactive feedback
- move, to TOP LEFT (pixel coordinates)
- stretch, with interactive feedback
- stretch, to WIDTH HT size (in pixels)
-expose
-hide
-refresh
- stretch, to ROWS COLS size (in characters)
- report if open or iconic by sending \ E [ 1 t or \E [2 t
- report position by sending \E [3; TOP; LEFTt
- report size in pixels by sending \E [ 4; WIDTH; HTt
- report size in characters by sending \E [8; ROWS; COLSt
-report icon label by sending \E] Llabel \E\
- report tool header by sending \E] llabel \E \
- set tool header to 
- set icon to the icon contained in ;
 must be in iconedit output format
- set icon label to 
- tum OPT on (OPT = 1 => pagemode), e.g., \ E [> 1 ; 3 ; 4h
-report OPT; sends \E [>OPTl or \E [>OPTh for each OPT
-tum OPT off (OPT = 1 =>pagemode), e.g., \E[>1;3;41

As an example of using this facility, the following aliases can be put into your -I.cshrc file:
# dynamically set the name stripe of the tool:
alias header ' echo -n "\E] 1 \! *\E\ ' I f
# dynamically set the label on the icon:

386

Last change: 30 September 1985

Sun Release 3.2

SHELLTOOL ( 1 )

USER COMMANDS

SHELLTOOL ( 1 )

alias iheader 'echo -n n\E]L\!*\E\'"
# dynamically set the image on the icon:

alias icon 'echo -n n\E]I\!*\E]\'"

Selections
Terminal subwindows support a facility called selection, which provides for limited inter-tool communication and mouse-oriented text manipulation. A selection is a span of characters which you can manipulate.
To make a selection:
Press the select (left) mouse button while the tip of the cursor is over the desired character. Your selection becomes highlighted (video inverted). This feedback helps you see what you're doing. Any previous selections in any window are de-selected; the highlighting around the old selection disappears.
Move the mouse with the select button down, and the selection changes. Release the select button to
complete the selection.
Press the adjust (middle) mouse button down and move the mouse to change the span of characters that
you select. Release the button. All characters, from the ones you originally selected through the one
indicated when you released adjust, are selected. The highlighting indicating the selection adjusts to
reflect its new contents.
You can also adjust your selection by multi-clicking. If clicks are less than .5 seconds apart, they combine
into a multiple click. For example, if you click twice on a character, the highlighting adjusts to select a
word (non-white-space delimited by white-space). Click three (3) times, and the highlighting adjusts to
select a line. You can select characters obscured by another window if they lie between the characters you
chose as the endpoints to the selection. The selection is deselected if you type any key or any new output is
written to the window which holds the selection.
Menu
To manipulate your selection, press the menu button over the terminal subwindow. A ttysw menu appears
with the menu items discussed below:
Put, then Get
When there is a selection in any window, this item reads Put, then Get. Selecting it copies the
selection both to the shelf and to the insertion point (cursor). It copies selections in tty, text, command, and panel subwindows. It is intended to bridge the gap between Stuff and the new selection functionality (see Windows and Window-Based Tools: Beginner's Guide and cmdtool(l».
Put, then Get
When there is no selection but there is text on the shelf, Put, then is grayed out, though Get
remains active. Selecting this item causes the contents of the shelf to be copied to the insertion
point (cursor). When there is no selection and nothing on the shelf, this item is inactive.
Enable Page Mode
Select Enable Page Mode to prevent voluminous tty sub window output from scrolling off the
screen. Page Mode can save you from redoing a command with a pipe to more in such cases.
When Page Mode is on, the cursor becomes a tiny stop sign when a command generates a screenful of output To restart output, type any key, or select the Continue menu item, which temporarily replaces Enable Page Mode. When there is no output waiting to be shown, the cursor
remains in the shape of an arrow, and Disable Page Mode replaces Enable Page Mode in the
menu.
Stuff

is provided for backward compatibility. Select Stuff, and the characters in the selection are
copied to the insertion point (cursor) as though they had been typed at the keyboard. The window
in which you invoke Sturr does not have to be the same as the one in which you made the selection, but the selection does have to be in a tty subwindow.

Flush Input

Sun Release 3.2

Last change: 30 September 1985

387

SHELLTOOL( 1)

USER COMMANDS

SHELLTOOL ( 1 )

This item does not always appear in the menu. Occasonally the input buffer fills up and the terminal emulator appears to freeze. If this happens to you, Flush Input will appear in the menu.
Selecting it will clear the buffer and allow you to continue using the terminal emulator.
SEE ALSO

suntools (1), gfxtool (1), cmdtool(I), defaultsedit(I), Windows and Window-Based Tools: Beginner's
Guide
FILES

-I.ttyswrc
lusrllib/ttyswrc
lusrlbinlshelltool
lusrlbinlsuntools
lusr/demol*
lusrlsrc/sun/suntool/shelltoo1.c
BUGS

This release has the following notable bugs:

388

(1)

Remote login to another machine should be done with a terminal emulator sub window matching
the standard terminal size for the remote machine (for example, 34 by 80 characters for a Sun
workstation). The remote machine does not understand terminals with non-standard size.

(2)

If more than 256 characters are input to a terminal emulator subwindow without an intervening
newline, the terminal emulator may hang. If this occurs, display the tty subwindow menu; it contains the item, "Flush input", that you can invoke to correct the problem. -

Last change: 30 September 1985

Sun Release 3.2

SIZE ( 1)

USER COMMANDS

S1ZE( 1)

NAME

size - size of an object file
SYNOPSIS

size [ object-ftle ... ]
DESCRIPTION
Size prints the (decimal) number of bytes required by the text, data, and bss portions, and their sum in hex
and decimal, of each object-ftle argument. If no file is specified, a.out is used.
SEE ALSO
a.out(5)

Sun Release 3.2

Last change: 2 June 1983

389

SLEEP ( 1)

USER COMMANDS

SLEEP(I)

NAME

sleep - suspend execution for an interval
SYNOPSIS

sleep time
DESCRIPTION
Sleep suspends execution for time seconds. It is used to execute a command after a certain amount of time
as in:

(sleep 105; comrnand)&
or to execute a command every so often, as in:
while true
do
command
sleep 37
done
SEE ALSO
sleep(3)
BUGS

Time must be less than 2,147,483,647 seconds.

390

Last change: 10 June 1983

Sun Release 3.2

SOELIM( 1)

USER COMMANDS

SOELIM(l)

NAME

soelim - resolve and eliminate .so requests from nroff input
SYNOPSIS

soelim [ file • •• ]
DESCRIPTION

Soelim reads the specified files or the standard input and performs the textual inclusion implied by the nroff
directives of the form
.so somefile
when they appear at the beginning of input lines. This is useful since programs such as tbi do not normally
do this; it allows the placement of individual tables in separate files to be run as a part of a large document.
An argument consisting of a single minus (-) is taken to be a file name corresponding to the standard input.

Note that inclusion can be suppressed by using' " instead of ' . " that is,
, so lusr/lib/tmac.s
EXAMPLE

A sample usage of soelim would be
soelim exum?n I tbll nroff -ms I coilipr
SEE ALSO

colcrt( 1), more( 1)

Sun Release 3.2

Last change: 2 June 1983

391

SORT( 1)

USER COMMANDS

SORT(l)

NAME

sort - sort and/or merge files
SYNOPSIS

sort [-c] [-m] [-u] [-0 output] [-y kmem] [-z recsz] [-T dir] [-d] [-f] [-i] [-M] [-n]
[ -r ] [ -b ] [ -tx] [ +posl [ -pos2 ] ... ] filename ...
SYSTEM V SYNOPSIS

lusrlSbin/sort [ -c] [ -m] [ -u] [ -0 output] [ -y kmem] [ -z recsz] [ -T dir] [ -d] [ -f] [ -i] [ -M]
[ -n] [ -r] [ -b] [ -tx] [+posl [ -pos2] ... ] filename ...
DESCRIPTION

sort sorts lines of all the named files together and writes the result on the standard output. The standard
input is read if - is used as a file name or no input file s are named.
Comparisons are based on one or more sort keys extracted from each line of input. By default, there is one
sort key, the entire input line, and ordering is lexicographic by bytes in machine collating sequence.
The notation +posl -pos2 restricts a sort key to one beginning at posl and ending at pos2. The characters
at positions pos1 and pos2 are included in the sort key (provided that pos2 does not precede pos1). A missing -pos2 means the end of the line.
Specifying posl and pos2 involves the notion of a field, a minimal sequence of characters followed by a
field separator or a new-line. By default, the first blank (space or tab) of a sequence of blanks acts as the
field separator. All blanks in a sequence of blanks are considered to be part of the next field; for example,
all blanks at the beginning of a line are considered to be part of the first field. The -t option (see below)
can be used to specify a character which is to be used as the field separator.
Posl and pos2 each have the form m.n optionally followed by one or more of the flags bdfiMnr, which
cause the option selected by that flag (see below) to be applied to that field. A starting position specified by
+m.n is interpreted to mean the n+lst character in the m+lst field. A missing .n means .0, indicating the
first character of the m+lst field. If the b flag is in effect n is counted from the first non-blank in the m+lst
field; +m.Ob refers to the first non-blank character in the m+1st field.
A last position specified by -m.n is interpreted to mean the nth character (including separators) after the
last character of the m th field. A missing.n means .0, indicating the last character of the mth field. If the

b flag is in effect n is counted from the last leading blank in the m+lst field; -m.l b refers to the first nonblank in the m+1st field.
When there are multiple sort keys, later keys are compared only after all earlier keys compare equal. Lines
that otherwise cOII~pare equal are ordered with all bytes significant.
SYSTEM V DESC_RIPTION

In the System V version of sort, if no restricted sort keys have been specified, leading blanks are considered part of the sort key, even if the -n option has been specified. Thus, a line containing " 02" will
sort before a line containing " I", even if the -n option has been specified, because the "initial numeric
string" is empty and the lines would "otherwise compare equal"; thus, they are ordered with all bytes
significant.
OPTIONS

The following options alter the default behavior:
-c

Check that the input file is sorted according to the ordering rules; give no output unless the file is out
of sort.

-m

Merge only, the input files are already sorted.

-0

Unique: suppress all but one in each set of lines having equal keys.

-ooutput
The argument given is the name of an output file to use instead of the standard output. This file may
be the same as one of the inputs. There may be optional blanks between -0 and output.

392

Last change: 9 April 1986

Sun Release 3.2

SORT ( 1)

USER COMMANDS

SORT ( 1)

-ykmem
The amount of main memory used by the sort has a large impact on its peIformance. Sorting a small
file in a large amount of memory is a waste. If this option is omitted, sort begins using a system
default memory size, and continues to use more space as needed. If this option is presented with a
value, kmem, sort will start using that number of kilobytes of memory, unless the administrative
minimum or maximum is violated, in which case the corresponding extremum will be used. Thus,
-yO is guaranteed to start with minimum memory. By convention, -y (with no argument) starts with
maximum memory.
-zrecsz
The size of the longest line read is recorded in the sort phase so buffers can be allocated during the
merge phase. If the sort phase is omitted via the -c or -m options, a size of 1024 bytes will be used
Lines longer than the buffer size will cause sort to terminate abnonnally. Supplying the actual
number of bytes in the longest line to be merged (or some larger value) will prevent abnonnal termination.
-Tdir
The dir argument is the name of a directory in which temporary files should be made.
The following options override the default ordering rules.
-d

"Dictionary" order: only letters, digits and blanks (spaces and tabs) are significant in comparisons.

-r

Fold lower case letters into upper case.

-i

Ignore characters outside the ASCII range 040-0176 in non-numeric comparisons.

-M

Compare as months. The first three non-blank characters of the field are folded to upper case and
compared so that "JAN" < "FEB" < ... < "DEC". Invalid fields compare low to "JAN". The-M
option implies the -b option (see below).

-0

An initial numeric string, consisting of optional blanks, optional minus sign, and zero or more digits
with optional decimal point, is sorted by arithmetic value. The -0 option implies the -b option (see
below). Note that the -b option is only effective when restricted sort key specifications are in effect

-r

Reverse the sense of comparisons.

When ordering options appear before restricted sort key specifications, the requested ordering rules are
applied globally to all sort keys. When attached to a specific sort key (described above), the specified ordering options override all global ordering options for that key.
The treatment of field separators can be altered using the options:

-tx Use x as the field separator character; x is not considered to be part of a field (although it may be
included in a sort key). Each occurrence of x is significant (e.g., xx delimits an empty field).
-b

Ignore leading blanks when determining the starting and ending positions of a restricted sort key. If
the -b option is specified before the first +posl argument, it will be applied to all +posl arguments.
Otherwise, the b flag may be attached independently to each +posl or -pos2 argument (see above).

EXAMPLES
Sort the contents of infile with the second field as the sort key:

sort + 1 -2 infile
Sort, in reverse order, the contents of infilel and infile2, placing the output in outfile and using the first
character of the second field as the sort key:
sort -r -0 outfile + 1.0 -1.2 infilel infile2
Sort, in reverse order, the contents of infilel and infile2 using the first non-blank character of the second
field as the sort key:
sort -r + 1.0b -1.1b infilel infile2

Sun Release 3.2

Last change: 9 April 1986

393

SORT ( 1)

USER COMMANDS

SORT(l)

Print the password file (passwd(5» sorted by the numeric user ID (the third colon-separated field):
sort -t +2n -3/etclpasswd
Print the lines of the already sorted file infile, suppressing all but the first occurrence of lines having the
same third field (the options -urn with just one input file make the choice of a unique representative from a
set of equal lines predictable):
sort -urn +2 -3 infile
FILES
lusr/tmp/stm 1?1

SEE ALSO
comm(l), join(l), rev(l), uniq(l).
DIAGNOSTICS
Comments and exits with non-zero status for various trouble conditions (e.g., when input lines are too
long), and for disorder discovered under the -c option. When the last line of an input file is missing a newline character, sort appends one, prints a warning message, and continues.

394

Last change: 9 April 1986

Sun Release 3.2

SORTBIB( 1)

USER COMMANDS

SORTBffi(l)

NAME

sortbib - sort bibliographic database
SYNOPSIS

sortbib [-sKEYS] database ...
DESCRIPTION
Sortbib sorts files of records containing refer key-letters by user-specified keys. Records may be separated

by blank lines, or by .[ and .] delimiters, but the two styles may not be mixed together. This program reads
through each database and pulls out key fields, which are sorted separately. The sorted key fields contain
the file pointer, byte offset, and length of corresponding records. These records are delivered using disk
seeks and reads, so sortbib may not be used in a pipeline to read standard input.
By default, sortbib alphabetizes by the first %A and the %D fields, which contain the senior author and
date. The -s option is used to specify new KEYS. For instance, -sAID will sort by author, title, and date,
while -sA+D will sort by all authors, and date. Sort keys past the fourth are not meaningful. No more than
16 databases may be sorted together at one time. Records longer than 4096 characters will be truncated.
Sortbib sorts on the last word on the %A line, which is assumed to be the author's last name. A word in the
final position, such as "jr." or "ed." , will be ignored if the name beforehand ends with a comma. Authors
with two-word last names or unusual constructions can be sorted correctly by using the nroff convention
"\0" in place of a blank. A %Q field is considered to be the same as %A, except sorting begins with the
first, not the last, word. Sortbib sorts on the last word of the %D line, usually the year. It also ignores leading articles (like "A" or "The") when sorting by titles in the %T or %J fields; it will ignore articles of any
modem European language. If a sort-significant field is absent from a record, sortbib places that record
before other records containing that field
SEE ALSO

refer(l), addbib(l), roffbib(l), indxbib(l), lookbib(l)
"Refer" in Formatting Documents on the Sun Workstation

BUGS
Records with missing author fields should probably be sorted by title.

Sun Release 3.2

Last change: 8 March 1983

395

SPELL ( 1)

USER COMMANDS

SPELL ( 1)

NAME

spell, spellin, spellout - find spelling errors
SYNOPSIS

spell [ -v] [ -b ] [ -d hlist] [ -s hstop ] [ -b spellhist] [ file] ...
spellin [ list]
spellout [ -d ] list
DESCRIPTION

Spell collects words from the named documents, and looks them up in a spelling list Words that neither
occur among nor are derivable (by applying certain inflections, prefixes or suffixes) from words in the spelling list are printed on the standard output. If no files are named, words are collected from the standard
input.
Spell ignores most troff(l), tbl (1), and eqn(l) constructions.
The spelling list is based on many sources, and while more haphazard than an ordinary dictionary, is also
more effective in respect to proper names and popular technical words. Coverage of the specialized vocabularies of biology, medicine and chemistry is light.
Pertinent auxiliary files may be specified by name arguments, indicated below with their default settings.
Copies of all output are accumulated in the history file. The stop list filters out misspellings (for example,
thier=thy-y+ier) that would otherwise pass.
Two routines help maintain the hash lists used by spell. Both expect a list of words, one per line, from the
standard input- Spellin -adds the words on the standard input to the preexisting list and places a new list on
the standard output. If no list is specified, the new list is created from scratch. Spellout looks up each word
in the standard input and prints on the standard output those that are missing from (or present on, with
option -d) the hash list
OPTIONS

-v

Print all words not literally in the spelling list, as well as plausible derivations from spelling list
words.

-b

Check British spelling. Besides preferring centre, colour, speciality, travelled, and so on, the-b
option insists upon -ise in words like standardise, Fowler and the OED to the contrary notwithstanding.

-x

print every plausible stem with '=' for each word.

FILES

lusr/dictlhlist[ab] hashed spelling lists, American & British
lusr/dictlhstop
hashed stop list
lusr/dictlspellhist history file
lusr/dictlwords
list of words
lusrflibl spell
SEE ALSO

deroff(l), sort(lV), tee(l), sed(lV)

BUGS
The spelling list's coverage is uneven; new installations will probably wish to monitor the output for
several months to gather local additions.
British spelling was done by an American.

396

Last change: 1 November 1983

Sun Release 3.2

SPLINE ( 10)

USER COMMANDS

SPLINE ( IG)

NAME

spline - interpolate smooth curve
SYNOPSIS
spline [ -a] [ -k] [ -n] [ -p ] [ -x ]
DESCRIPTION

Spline takes pairs of numbers from the standard input as abcissas and ordinates of a function. It produces a
similar set, which is approximately equally spaced and includes the input set, on the standard output. The
cubic spline output (R. W. Hamming, Numerical Methods for Scientists and Engineers. 2nd ed., 349ft) has
two continuous derivatives, and sufficiently many points to look smooth when plotted, for example by
graph(10).
OPTIONS

-a

Supply abscissas automatically (they are missing from the input); spacing is given by the next argument, or is assumed to be 1 if next argument is not a number.

-k

The constant k used in the boundary value computation

is set by the next argument By default k

=

O.

-0

Space output points so that approximately n intervals occur between the lower and upper x limits.
(Default n = 100.)

-p

Make output periodic, that is, match derivatives at ends. First and last input values should normally
agree.

-x

Next 1 (or 2) arguments are lower (and upper) x limits. Normally these limits are calculated from the
data. Automatic abcissas start at lower limit (default 0).

SEE ALSO
graph(10)
DIAGNOSTICS
When data is not strictly monotonic in x. spline reproduces the input without interpolating extra points.
BUGS

A limit of 1000 input points is enforced silently.

Sun Release 3.2

Last change: 1 June 1983

397

SPLIT ( 1)

USER COMMANDS

SPLIT(l )

NAME

split - split a file into pieces
SYNOPSIS

split [ -number] [infile [outfile ] ]
DESCRIPTION
split reads file and writes it in n-line pieces (default 1000) onto a set of output files (as many files as necessary). The name of the first output file is outfile with aa appended, the second file is outfileab, and so on
lexicographically.

If no outfile is given, x is used as default (output files will be called xaa,xab, etc.).
If no infile is given, or if - is given in its stead, then the standard input file is used.
OPTIONS

-number Number of lines in each piece.

398

Last change: 23 September 1985

Sun Release 3.2

STRINGS ( 1)

USER COMMANDS

STRINGS(I)

NAME

strings - find printable strings in an object file or binary
SYNOPSIS

strings [ - ] [ -0 ] [ -number] file •••
DESCRIPTION

Strings looks for ASCII strings in a binary file. A string is any sequence of 4 or more printing characters
ending with a newline or a null.
Strings is useful for identifying random object files and many other things.
OPTIONS

Look everywhere in the file for strings. If this flag is omitted, strings only looks in the initialized
data space of object files.
-0

Precede each string by its offset in the file (in octal).

-number
Use number as the minimum string length rather than 4.
SEE ALSO

od(IV)
BUGS

The algorithm for identifying strings is extremely primitive.

Sun Release 3.2

Last change: 13 March 1984

399

STRIP ( 1)

STRIP(l)

USER COMMANDS

NAME

strip - remove symbols and relocation bits
SYNOPSIS

strip name ...
DESCRIPTION

strip removes the symbol table and relocation bits ordinarily attached to the output of the assembler and
linker. This is useful to save space after a program has been debugged.

The effect of strip is the same as use of the -s option of ld.
SEE ALSO

ld(l), sun3cvt(1), a.out(5)
BUGS

Unstripped 2.0 binary files will not run if stripped by the 3.0 version. A message of the form:
pid xxx: killed due to swap problems in getxfile: I/O error mapping page.
when attempting to run a program indicates that this is the problem.

400

Last change: 8 July 1986

Sun Release 3.2

STIY( 1)

USER COMMANDS

SITY( 1)

NAME

stty - set tenninal options
SYNOPSIS

stty [ option ... ]
DESCRIPTION
stty sets certain I/O options on the current output terminal, and directs its output to the diagnostic output.
With no argument, it reports the speed of the terminal and the settings of options which are different from
their defaults. With the argument Hall", all normally-used option settings are reported. With the argument
"everything", everything stty knows about is printed.
OPTIONS
Options to stty are selected from the following set:

even
-even
odd
-odd
raw
-raw
cooked
cbreak
-cbreak
-nl
nl
echo

-echo
lease

-lease
tandem
-tandem
-tabs
tabs
ek

allow even parity input
disallow even parity input
allow odd parity input
disallow odd parity input
raw mode input (no input processing (erase, kill, interrupt, ... ); parity bit passed back)
negate raw mode
same as '-raw'
make each character available to read(2) as received; no erase and kill processing, but all
other processing (interrupt, suspend, ... ) is performed
make characters available to read only when newline is received
allow carriage return for new-line, and output CR-LF for carriage return or new-line
accept only new-line to end lines
echo back every character typed
do not echo characters
map upper case to lower case
do not map case
enable flow control, so that the system sends out the stop character when its internal queue is
in danger of overfiowing on input, and sends the start character when it is ready to accept
further input
disable flow control
replace tabs by spaces when printing
preserve tabs
set er~e and kill characters to AH (control-H) and AU

For the following commands which take a character argument c, you may also specify c as "u" or
"undef", to set the value to be undefined. A value of "AX", a 2 character sequence, is also interpreted as a
control character, with' ,A1" representing delete.

erase c
kill c
iotr c
quit c
start c
stop c
eor c
brk c

set erase character to c (default 'A?').
set kill character to c (default ~AU').
set interrupt character to c (default ,AC').
set quit character to c (default ,A\,).
set start character to c (default 'AQ').
set stop character to c (default 'AS').
set end of file character to c (default 'AD').
set break character to c (default undefined.) This character is an extra wakeup causing character.

crO cr 1 cr2 cr3
select style of delay for carriage return (see ioctl (2»

nlO nil 012 nl3
select style of delay for linefeed

tabO tabl tab2 tab3

Sun Release 3.2

Last change: 19 March 1984

401

STTY( 1)

ITO ff1
bsO bsl
tty33
tty37
vt05
dec

USER COMMANDS

STIY( 1)

select style of delay for tab
select style of delay for fonn feed
select style of delay for backspace
set all modes suitable for the Teletype Corporation Model 33 terminal.
set all modes suitable for the Teletype Corporation Model 37 terminal.
set all modes suitable for Digital Equipment Corp. VT05 terminal
set all modes suitable for Digital Equipment Corp. operating systems users; (erase, kill, and
interrupt characters to "?, "U, and "C, decctlq and "newcrt".)

tn300
ti700
tek

set all modes suitable for a General Electric TermiNet 300
set all modes suitable for Texas Instruments 700 series terminal
set all modes suitable for Tektronix 4014 terminal
o
hang up phone line immediately
50751101341502003006001200180024004800960019200 exta extb
Set terminal baud rate to the number given, if possible. (These are the speeds supported by the
DH-ll interface).

The driver which supports the job control processing of csh(l) is fully described in tty(4). The options in
the list below can only be selected by using the new option to stty(l).
new
crt
crtbs
prterase
crterase
-crterase
crtkill
-crtkill
ctlecho
-ctlecho
decctJq

Use new driver (switching flushes typeahead).
Set options for a CRT (crtbs, ctlecho and, if >= 1200 baud, crterase and crtkill.)
Echo backspaces on erase characters.
For printing terminal echo erased characters backwards within "\" and "/".
Wipe out erased characters with "backspace-space-backspace."
Leave erased characters visible; just backspace.
Wipe out input on like kill ala crterase.
Just echo line kill character and a newline on line kill.
Echo control characters as ""x" (and delete as ""?".) Print two backspaces following the
EOT character (default 'AD').
Control characters echo as themselves; in cooked mode EOT (default 'AD') is not echoed.
Mter output is suspended (normally by AS), only a start character (normally "Q) will restart it.
This is compatible with DEC's vendor supplied systems.

-decctlq

Mter output is suspended, any character typed will restart it; the start character will restart output without providing any input (This is the default.)
Background jobs stop if they attempt terminal output.
tostop
-tostop
Output from background jobs to the terminal is allowed.
Convert "-,, to " . . " on output (for Hazeltine terminals).
tilde
Leave poor "-" alone.
-tilde
Output is being discarded usually because user hit '''0' (internal state bit).
8usho
-8usho
Output is not being discarded.
Input is pending after a switch from cbreak to cooked and will be re-input when a read
pendin
becomes pending or more input arrives (internal state bit).
-pendin Input is not pending.
Send a signal (SIGTINT) to the terminal control process group whenever an input record (line
intrup
in cooked mode, character in cbreak or raw mode) is available for reading.
-intrup
Don't send input available interrupts.
mdmbuf Start/stop output on carrier transitions (not implemented).
-mdmbuf Return error if write attempted after carrier drops.
Send output characters without any processing.
Iitout
Do normal output processing, inserting delays, etc.
-Iitout
Don't send hangup signal if carrier drops.
nohang
-nohang Send hangup signal to control process group when carrier drops.
Diablo style etxlack handshaking (not implemented).
etxack

402

Last change: 19 March 1984

S un Release 3.2

STIY( 1)

USER COMMANDS

STIY( 1)

The following special characters are applicable only to the new teletype driver and are not normally
changed.

susp c
dsusp c
rprnt c
flush c
werase c
lnext c

set suspend process character to c (default 'AZ').
set delayed suspend process character to c (default '''Y').
set reprint line character to c (default '''R').
set flush output character to c (default '''0').
set word erase character to c (default '''W').
set literal next character to c (default '''Y').

SEE ALSO
tset(1), tty(4)

Sun Release 3.2

Last change: 19 March 1984

403

STTY( 1V)

USER COMMANDS

STTY( 1V)

NAME

stty - set the options for a terminal, System V
SYNOPSIS
/usr/Sbin/stty [ -3 ] [ -g ] [option ] ...
SYSTEM V DESCRIPTION
Note:
Optional Software (System V Option). Refer to Installing UNIX on the Sun Workstation for information on how to install this command.

There are two distinct versions of stty: /bin/stty and /usr/Sbin/stty. This manual page describes the latter
version.

/usr/5bin/stty sets certain terminallJO options for the device that is the current standard input Without
arguments, it reports the settings of certain terminal options.
Detailed information about the modes listed in the first five groups below may be found in termio(4V). In
the current implementation, the values of certain values cannot be altered, and certain combinations of
values are not supported. These restrictions are given in termio(4V). Note that many combinations of
options make no sense, but no sanity checking is performed.
OPTIONS
-a

-g

Report all of the option settings.
Report current settings in a form that can be used as an argument to another stty command.

Control Modes
[-]parenb Enable parity generation and detection. With a -, disable parity checking.

[-]parodd Select odd parity. With a -, select even parity.
es7 esS

Select character size.

o

Hang up phone line immediately.

SO 7511013415020030060012001800240048009600 exta extb
Set terminal baud rate to the number given, if possible. (All speeds are not supported by all
hardware interfaces.)

[-]hupcl

Hang up connection on last close. With a -, do not hang up connection.

[-]hup

Same as hupel.

[-]estopb

Use two stop bits per character. With a -, use one stop bit per character.

[-]eread

Enable the receiver. With a -, disable the receiver.

[-]clocal

Assume a line without modem control. With a -, assume a line with modem control.

Input Modes
[-]ignbrk Ignore break on input. With a -, do not ignore a break on input.
[-]brkint

Signal INTR on break. With a -, do not signal.

[-]ignpar Ignore parity errors. With a -, do not ignore parity errors.
[-]parmrk Mark parity errors With a -, do not mark parity errors (always clear).

404

[-]inpek

Enable input parity checking. With a -, disable input parity checking.

[-]istrip

Strip input characters to seven bits. With a -, do not strip input characters.

[-]inler

Map NL to CR on input (always clear). With a -, do not map on input (always clear).

[-]igner

Ignore CR on input. With a -, do not ignore CR on input (always clear).

[-]iernl

Map CR to NL on input. With a -, do not map.

[-]iuelc

Map upper-case alphabetics to lower case on input. With a -, do not map.

Last change: 18 July 1986

Sun Release 3.2

STIY(lV)

USER COMMANDS

S1TY( IV)

[-]ixon

Enable START/STOP output control. With a -, disable output control. When enabled, output is
stopped by sending an ASCII DC3 and started by sending an ASCII DCl.

[-]ixany

Allow any character to restart output. With a -, only restart with DCl.

[-]ixoff

Request that the system send (not send) START/STOP characters when the input queue is
nearly empty/full. With a -, request that the system not send START/STOP characters.

Output Modes
[-]opost

Post-process output With a -, do not post-process output; ignore all other output modes.

[-]olcuc

Map lower-case alphabetics to upper case on output. With a -, do not map.

[-]onlcr

Map NL to CR-NL on output. With a -, do not map.

[-]ocrnl

Map CR to NL on output With a -, do not map.

[-]onocr

Do not place CRs at column zero. With a -, do place CRs at column zero (always clear).

[-]onlret

On the terminal NL performs the CR function. With a -, NL does not perform the CR function.

[-]0611

Use fill characters for delays. With a -, use timing for delays (always clear).

[-]ordel

Fill characters are DELs. With a -, fill characters are NULs (always clear).

crO crl cr2 cr3
Select style of delay for carriage returns.
nlO nil

Select style of delay for line-feeds.

tabO tabl tab2 tab3
Select style of delay for horizontal tabs.
bsO bsl

Select style of delay for backspaces.

nuffl

Select style of delay for form-feeds.

vtO vtl

Select style of delay for vertical tabs.

Local Modes
[-]isig

Enable the checking of characters against the special control characters INTR and QUIT. With
a -, disable this checking.

[-]icanon Enable canonical input (ERASE and KILL processing). With a -, disable canonical input
[-]xcase

Canonical upper/lower-case presentation. With a -, do not process cases.

[-]echo

Echo.back every character typed. With a -, do not echo back.

[-]echoe

Echo ERASE character as a sequence of backspace-space-backspace. With a -, do not echo
ERASE character.

[-]echok

Echo NL after KILL character. With a -, do not echo NL after KILL (always set).

Ifkc

the same as echok; obsolete.

[-]echonl Echo NL. With a -, do not echo (always clear).
[-]noftsh

Disable flush after INTR or QUIT. With a -, enable flush.

Control Assignments
control-c haracter c
Set control-character to c, where control-character is one of erase, kill, intr, quit, eor, eol,
min ,or time (min and time are used with -icanon) If c is preceded by an (escaped from the
shell) caret C'), then the value used is the corresponding CTRL character (e.g., ""d" is a CTRLd); ""1" is interpreted as DEL and ""-" is interpreted as undefined

line i

Sun Release 3.2

Set line discipline to i (0 < i < 127 ).

Last change: 18 July 1986

405

STIY( IV)

USER COMMANDS

STIY( IV)

Combination Modes
cooked Process ERASE, KILL, INTR, QUIT, SWTCH, EDT, and perform output post-processing.

evenp or parity
Enable parenb and cs7.
oddp

Enable parenb, cs7, and parodd.

-parity, -evenp, or -oddp
Disable parenb, and set cs8.
[-]raw

Enable raw input and output. With a -, disable raw I/O. In raw mode, there is no ERASE,
KILL, INTR, QUIT, SWTCH, EOT, or output post-processing.

[-]nl

Unset icrnl, onlcr. With a -, set them. In addition -nl unsets inler, igncr, ocrnl, and onlret.

[-]Icase

Setxcase, iudc, andoleuc. With a-, unset them.

[-]LCASE Same as lease (-lease).

[-]tabs
tabs3
ek
sane

term

Preserve TABs when printing. With a -, or with tabs3, expand TABs to spaces.
Reset ERASE and KILL characters back to normal: - and @.
•
Reset all modes to some reasonable values.
set all modes suitable for the terminal type term, where term is one of tty33, tty37, vtOS,
t0300, ti700, or tek.

SEE ALSO
ioct1(2), termio(4V)

406

Last change: 18 July 1986

Sun Release 3.2

USER COMMANDS

NAME

stty_from_defaults - set "editing characters" from defaults database
SYNOPSIS

stty_from _defaults
DESCRIPTION

sttyyom_defaults is a utility provided with the SunView environment
sttyyom_defaults sets the three editing characters (to erase a character, erase a word., and kill a line)
according to the choices in your defaults database. It does not set any other tty options. If you run stty(lV)
in your .login or rc.local files, you may want to run sttyJrom_defaults immediately after it This will override any settings of stty erase, stty werase, or stty kill, so that you will have the same character-editing
behavior with SunView applications and other Unix programs.
To specify the editing characters sttyJrom_defaults will set, run defaultsedit(l) and select the "Text"
category. The editing characters are called Edit_back_char, Edit_back_word., and Edit_back_line. Type
the value you want to the right of each item. To specify CfRL-X, type "\"X" - that is, the three characters
'\', '''', and 'X'. To specify DEL, type "\"1".
If you do not specify your own values, the default values are DEL, CfRL-W, and CfRL-U, respectively.
SEE ALSO

defaults edit (1), stty (IV), suntools (1)

Windows and Window-Based Tools: Beginner's Guide

Sun Release 3.2

Last change: 26 December 1985

407

SU( 1)

USER COMMANDS

SU( 1)

NAME

su - super-user, temporarily switch effective user ID
SYNOPSIS

su [ - ] [username ] [ -c command] [ -f]
DESCRIPTION

su changes your login to that of the specified username. su asks for the password, just as if you were logging in as username, and, if the password is given, changes to that username and invokes the shell
speCified in the password file for that username, without changing the current directory. The user environment is thus unchanged except for HOME and SHELL, which are taken from the password file for the user
being substituted (see environ(5V». The new user ill stays in force until the shell exits.
If no username is specified, 'root' is assumed. To remind the super-user of his responsibilities, the Shell
substitutes '-' for its usual prompt
OPTIONS

The - flag performs a complete login. That is, it moves to the home directory, reads the .login
file, and reads the .cshrc file for the new user-ill to configure the new shell.

-ccommand
execute command after logging in as the new user.
-f

Perform a fast login. That is, do not change directories, do not read the .cshrc file, and do not read
the .login file for the new user ID to configure the new shell.

If the - and .fflags are omitted, only the .cshrc file for the new user-ID is used to configure the new shell.
SEE ALSO

sh(I), csh(l)

408

Last change: 17 February 1986

Sun Release 3.2

SUM ( 1)

USER COMMANDS

SUM ( 1)

NAME

sum - sum and count blocks in a file
SYNOPSIS
sum filename
SYSTEM V SYNOPSIS

lusrlSbinlsum [ -r ] filename
DESCRIPTION
sum calculates and displays a 16-bit checksum for the named file, and also displays the size of the file in
kilobytes. It is typically used to look for bad spots, or to validate a file communicated over some transmission line. The checksum is calculated by an algorithm which may yield different results on machines with
16-bit ints and machines with 32-bit ints, so it cannot always be used to validate that a file has been
transferred between machines with different-sized ints.
SYSTEM V DESCRIPTION
sum calculates and prints a 16-bit checksum for the named file, and also prints the number of 512-byte
blocks in the file. It is typically used to look for bad spots, or to validate a file communicated over some
transmission line. This algorithm is independent of the size of ints on the machine.
SYSTEM V OPTIONS
The option -r causes the (machine-dependent) algorithm used by the non-System V sum to be used in
computing the checksum.
SEE ALSO
wc(1)
DIAGNOSTICS
'Read error' is indistinguishable from end of file on most devices; check the block count.

Sun Release 3.2

Last change: 9 April 1986

409

SUN3CVT(I)

USER COMMANDS

SUN3CVT(I)

NAME

sun3cvt - convert large Sun-2 executables to Sun-3 executables
SYNOPSIS

sun3cvt [ oldfile [ newfile ] ]
DESCRIPTION

sun3cvt converts an old Sun-2 program file (predating Sun release 3.0) into a Sun-3 executable file.
The default oldfile is a.out. The default newfile is sun3.out.

sun3cvt will attempt to create a file of the same type (magic number). However, for sharable-text files with
less than 128kb of text, the new file will not be sharable (since Sun-3 data segments must begin on 128kb
boundaries). Also, most programs will have some text in the data segment as a consequence of the new
larger Sun-3 page.and segment sizes.
execve(2) will execute an old Sun-2 program file, but it will never make the program's text sharable. Old
pure-text programs with text segments larger than 128kb can be made sharable on machines running
release 3.0 or subsequent releases by using sun] cvt.

410

Last change: 26 March 1986

Sun Release 3.2

SUNTOOLS ( 1 )

USER COMMANDS

SUNTOOLS ( 1 )

NAME

suntools, othertools, selection_ svc - the SunView window environment
SYNOPSIS
sun tools [ -n I -s startup-file] [ -S ] [ -d display-device] [ -m mouse-device] [ -k keyboard-device]
[ -p] [-b red green blue] [-f red green blue] [ -i] [-B I-F I-P]
[ -pattern on I off I gray I iconedit-file-name ] [ -background raster-file-name ]
-Sbit_color_only] [ -toggle_enable] [ -overlay_only]
GETTING STARTED
suntools starts up the SunView environment and (unless you have specified otherwise) a default arrangement of a few useful "tools," or window-based utilities.

See Start-up Processing below to learn how to specify your own initial arrangement of tools. Some of the
behavior of suntools is controlled by settings in your defaults database; see SunView Defaults below.
OPTIONS
-n

Bypass startup processing by ignoring both the lusrlliblsuntools and -I.suntools files. See Startup
Processing for details.

-s startup-file
Read startup commands from startup file (instead of lusrlliblsuntools or -I.suntools).
-S

Set "click-to-type" mode, allowing you to select a window by clicking in it. Having done so, input
is directed to that window regardless of the position of the mouse-cursor, until you click to select
some other window.

-d display-device
Use display device as the output device on which to run, rather than the default frame buffer device, Idevlfb.
-m mouse-device
Use mouse device as the system pointing device (locator), rather than the default mouse device,

ldevlmouse.
-k keyboard-device
Accept keyboard input from keyboard device, rather than the default keyboard device, Idevlkbd.
-p

Prints to standard out the name of the window device used for the suntools Root Window.

-b red green blue
Specifies the values of the red, green and blue components of the background color. If this option
is not specified, each component of the background color is 255 (white). Prism users that use this
option should use the -Sbit_color_only option too.

-f red green blue
Specifies the values of the red, green and blue components of the foreground color. If this option
is not specified, each component of the foreground color is 0 (black). Prism users that use this
option should use the -Sbit_color_only option too.
-i

Invert the background and foreground colors used on the screen. On a monochrome monitor, this
option provides a video reversed image. On a color monitor, colors that are not used as the background and foreground are not affected.

-B

Use the background color for the Root Window color.

-F

Use the foreground color for the Root Window color.

-P

Use a stipple pattern for the Root Window color. This option is assumed unless -F or -B is
specified.

-pattern [on I otT I gray I iconedit-file-name]
Use the indicated "pattern" to cover the Root Window. on means to use the default desktop gray
pattern. otT means to not use the default desktop gray pattern. gray means to use a 50% gray

Sun Release 3.2

Last change: 29 June 1986

411

SUNTOOLS ( 1 )

USER COMMANDS

SUNTOOLS ( 1 )

color on color monitors. iconedit-file-name is the name of a file produced with iconedit(l) which
contains an image that is replicated allover the Root Window.
-background raster-file-name
Use the indicated raster file as the image in your Root Window. The raster file can be created with
screendump(I). Screen dumps produced on color monitors currently do not work as input to this
option. Small images are centered on the screen.
-Sbit_color_only
For multiple plane group frame buffers, only let windows be created in the 8 bit color plane group.
This frees up the black and white overlay plane to have a separate desktop running on it. This
option is usually used with the -toggle_enable option. See the section below entitled Multiple
Desktops on the Same Screen.
-toggle_enable
For multiple plane group frame buffers, when sliding the cursor between different desktops running within different plane groups on the same screen, change the enable plane to allow viewing
of the destination desktop. See the section below entitled Multiple Desktops on the Same Screen.
-overlay_only
For multiple plane group frame buffers, only let windows be created in the black and white overlay plane group. This frees up the 8 bit color plane group to have a separate desktop running in it.
This option is usually used with the -toggle_enable option. See the section below entitled Multiple Desktops on the Same Screen.
DESCRIPTION
Windows
The SunView environment always has one window open, called the Root Window, which covers the whole
screen. A solid color is its only content Each tool is given its own window which lies on top of some of
the Root Window (and possibly on top of other tools). A window obscures any part of another window
which lies below it
Input to Windows
Mouse input is always directed to the window the mouse cursor is in. You can have keyboard input follow
mouse input, or you can use the "Click-to-Type" approach. With Click-to-Type, keyboard input continues to be directed to a window, no matter where the mouse is pointing, until you click the left or middle
mouse button in another window. Click-to-Type is an option in your defaults database; see SunView
Defaults below. If you are not using Click-to-Type, and your mouse cursor is in the Root Window, keyboard input is discarded.

Your input actions (mouse motions, button pushes, and keystrokes) are synchronized This means that you
can "type-ahead" and "mouse-ahead," even across windows.
The Mouse Buttons
Left button

(the select button) Click once to select or choose objects.

Middle button

(the adjust button) Click once to shorten or lengthen your selection.

Right button

(the menu button) Depress and hold down to invoke menus.

Menus
suntools provides pop-up menus. In the current release, there are two styles of pop-up menus: the original
menu style, called stacking menus, and a new style, called walking menus (also known as "pull-right
menus"). A menu is invoked by pressing and holding the menu button. The menu remains on the screen
as long as you hold the menu button down. To select a menu item, point at it (it will be highlighted), then
release the menu button.

With stacking menus, more than one menu can appear simultaneously. The menus are shown in a stack,
with the label of each menu visible, and with the current menu on top so that its items are visible. To bring
a menu to the top (and make its items available), select its label as you would a menu item. Then push the
menu button again. The menu stack is repainted with the selected menu on top.

412

Last change: 29 June 1986

Sun Release 3.2

SUNTOOLS ( 1 )

USER COMMANDS

SUNTOOLS ( 1 )

With walking menus, any menu item can have an arrow ( => ) on the right. Pointing to this arrow invokes
a sub-menu, with additional menu items th2.t can be selected. Selecting an item that has an arrow (a
"pull-right item' ') invokes the first item on the sub-menu.
Walking menus are an option in your defaults database; see Sun View Defaults below.
The Root Window Menu
You can use the default Root Window Menu to start ten common tools and perform three functions. To
invoke it, hold down the menu button when the mouse cursor is anywhere in the Root Window.

The items in the default Root Window Menu are:
ShellTool

Creates a new shelltool(1), running a new copy of the shell.

CommandTool

Creates a new cmdtool(1), a scrollable cousin of the shelltool.

MailTool

Creates a new mailtool(I).

TextEditor

Creates a new textedit(l).

DefaultsEditor

Creates a new defaultsedit(1), for browsing or changing your defaults database.

IconEditor

Creates a new iconedit(1).

DbxTool

Creates a new dbxtool(1), a window-based debugger.

PerIMeter

Creates a new perfmeter(I), to monitor system performance.

GraphicsTool

Creates a new gfxtool(1), for running graphics programs.

Console

Creates a new Console window, a cmdtool with a -C flag, which acts as the system console. In particular, most error messages will be directed to the console. You should
always have a console window on your screen.

Lock Screen

Completely covers the screen with a graphics display, and "locks" the workstation until
you type your password. When you "unlock" the workstation, the screen is restored as
it was when you locked it See lockscreen(1) for details.

Redisplay All

Redraws all the contents of the screen. Use this to repair damage done by processes that
wrote to the screen without consulting the SunView system.

Exit Suntools

Exits the suntools program. Closes all tool windows and kills their associated processes
(depending on the processes, this can be fairly slow). You return to the shell which
invoked sun tools .
This command requires confirmation: When it prompts you, press the left mouse button
to complete the Exit Suntools command; press the right button to cancel.

You can specify your own Root Window Menu; see SunView Defaults below.
The Frame Menu
A small set of universal functions are available through the Frame Menu. There are also accelerators for
some of these functions; see below.

You can invoke the Frame Menu when the cursor is over any part of the tool which does not provide an
application-specific menu, such as the tool names tripe (black stripe holding the tool's name), the border
stripes of the window, and the whole of the tool's icon.
The items in the Frame Menu are:
Close (Open)

Only one of Close or Open appears in the menu, depending on the current state of the
window. Close shrinks the tool to a small image (an icon). Open reopens an icon and
places the tool in the spot it occupied when it was open. Icons are placed on the screen
according to the icon policy in your defaults database; see SunView Defaults below.
You can move a closed window just like an open window. When the window is closed,
the tool's process(es) continue to run.

Move

Moves the tool window to another spot on the screen. When invoked, Move instructs

Sun Release 3.2

Last change: 29 June 1986

413

SUNTOOLS ( 1 )

USER COMMANDS

SUNTOOLS ( 1 )

you with an instruction box that appears in the middle of the screen.
If you are using walking menus, Move has a sub-menu with two items: Constrained
and Unconstrained. Constrained moves are either vertical or horizontal, but not both.
Selecting Move invokes a Constrained move.
Resize

Shrinks or stretches the size of a window on the screen. Resize, like Move, instructs
you with an instruction box that appears in the middle of the screen.
If you are usrrig walking menus, Resize has a sub-menu with four items: Constrained,
Unconstrained, Zoom (or UnZoom, depending on the current state of the window) and
FullScreen. Constrained resizes are either vertical or horizontal, but not both. Zoom
makes a window the full height of the screen; UnZoom undoes this. FullScreen makes
a window the full height and width of the screen; UnZoom undoes this. Selecting
Resize invokes a Constrained resize.

Expose

Brings the window to 'the top of the pile'. The whole window becomes visible, and
occludes any window it happens to overlap on the screen.

Hide

Puts the window on the 'bottom of the pile'. The window is occluded by any window
which overlaps it

Redisplay

Redraws the contents of the window.

Quit

Notifies the tool to tenninate gracefully. This command requires the same type of
confirmation as the Exit Sun tools command in the Root Window Menu.

Frame Menu Accelerators
Accelerators are provided for some of the Frame Menu functions. You can invoke these functions quickly
with a simple button push in the tool window's name stripe or outer boundary, without displaying a menu.
See Windows and Window-Based Tools: Beginner's Guide for more details.

The accelerators for the various functions are:
Open

Click the select mouse button when the cursor is over the icon.

Move

Depress the adjust mouse button while the cursor is in the tool's name stripe or outer
boundary. A bounding box is displayed which tracks the mouse as long as you hold
the adjust button down.
If the cursor is near a comer when you press the mouse button, the move is Unconstrained. If it is in the middle third of a side, the move is Constrained.

Resize

While holding down the CfRL key, depress the adjust mouse button while the cursor
is in the tool's name stripe or outer boundary. A bounding box is displayed, one side
or comer of which tracks the mouse as long as you hold the adjust button down.
If the cursor is near a comer when you press the mouse button, the resize is Unconstrained. If it is in the middle third of a side, the resize is Constrained.

Zoom (UnZoom)

While holding down the CTRL key, click the select mouse button while the cursor is
in the tool's name stripe or outer boundary.

Expose

Click the select mouse button while the cursor is on the tool's name stripe or outer
boundary.

Hide

While holding down the SHIFf key, click the select mouse button while the cursor is
on the tool's name stripe or outer boundary.

In addition, you can use two function keys as even faster accelerators. To expose a window that is partially
hidden, hit the Expose key (normally 1..5) while the cursor is anywhere in the tool window, not just on the
tool's name stripe or outer boundary. Or, if the window is completely exposed, use the Expose key to hide
it Similarly, to close an open window, hit the Open key (normally L7) while the cursor is anywhere in the
tool window, not just on the tool's name stripe or outer boundary. Or, if the window is iconic, use the
Open key to open it You can change which keys mean Expose and Open by using setkeys(I).

414

Last change: 29 June 1986

Sun Release 3.2

SUNTOOLS ( 1 )

USER COMMANDS

SUNTOOLS ( 1 )

In many multi-subwindow tools, you can adjust the boundary between two sub windows up or down
without changing the overall size of the tool. While holding down the CfRL key, depress the adjust mouse
button over the boundary. A bounding box is displayed for the subwindow selected. Adjust the size of that
subwindow, exactly as with the Resize operation.
Startup Processing: The .suntools File
Unless you override it, suntools will start up with a predefined arrangement of windows. The default
arrangement is specified by the file lusrlliblsuntools. If there is a file called .suntools in your home directory, that will be used instead. The -s flag on the command line indicates that the initial window arrangement should be read from a file with a different name. The -0 switch suppresses this start-up processing
altogether.
To create your own .suntools, arrange the screen the way you like, then save the arrangement by running
toolplaces and redirecting its standard output to .suntools. See toolplaces(1) for a description of the format
of this file, or take a look at lusrlliblsuntools.
SunView Defaults
SunView allows you to customize the behavior of tools and packages by setting options in a defaults database (one for each user). Use defaultsedit(l) to browse and edit your defaults database. Select the "SunView" category to see the following items:

Walking_menus

If enabled, the Root Window Menu, the Frame Manager Menu, and many tools will use
walking menus. Tools that have not been converted will still use stacking menus. If disabled, all tools will use stacking menus. Default value is "Disabled" .

Click_to_Type

If enabled, keyboard input will stay in a window until you click the left or middle mouse
button in another window. If disabled, keyboard input will follow the mouse. Default
value is "Disabled" .

Font

You can change the SunView default font by giving the full pathname of the font you
want to use. Some alternate fonts are in the directory lusrlliblfonts!fixedwidthfonts. The
previous (2.0 release) default font is lusrlliblfontslfixedwidthfontslscreen.r.13. Default
value is null, which gives you the same effect as if you had specified
lusrlliblfontslfixedwidthfontslscreen.r.l1.

Rootmenu filename
You can change the Root Window Menu by giving the full pathname of a file that
specifies your own menu. See Customizing the Root Window Menu below for details.
Default value is null, which gives you the menu found in lusrlliblrootmenu.
Icon_gravity

. Determines which edge of the screen ("North", "South", "East", or "West") icons
will place themselves against Default value is "North".

Icon close level Determines whether icons will close ahead of or behind other windows and icons.
Default value is "Ahead of all".
Jump cursor on resize
- - If enabled, during a resize the cursor will jump to the edge of the window. If disabled,
the window edge will move to the current location of the cursor. Default value is "Disabled".
Audible bell

If enabled, the "bell" command will result in a beep. Default value is "Enabled".

Visible bell

If enabled, the "bell" command will cause the screen to flash. Default value is
"Enabled" .

Embolden Labels

If enabled, all tool labels are boldface. Default value is "Disabled".
Root Pattern

Sun Release 3.2

Used to specify the "pattern" that covers the Root Window. "on" means to use the
default desktop gray pattern. "off' means to not use the default desktop gray pattern.
"gray" means to use a 50% gray color on color monitors. Anything else is the name of

La~t

change: 29 June 1986

415

SUNTOOLS ( 1 )

USER COMMANDS

SUNTOOLS ( 1 )

a file produced with iconedit(l) which contains an image that is replicated all over the
Root Window. Default value is "on".
Mter you have set the options you want, click on the Save button in defaultsedit; then exit suntools and restart it
Customizing the Root Window Menu

The file called lusrlliblrootmenu contains the specification of the default Root Window Menu. You can
change the Root Window Menu by creating your own file and giving its name in the Rootmenu_filename
item in the SunView Defaults (see above).
Lines in the file have the following format: The left side is a menu item to be displayed; the right side is a
command to be executed when that menu item is invoked. You can also include comment lines (beginning
with a '-') and blank lines.
If you are using stacking menus ("Walking_menus Disabled" in SunView defaults), the menu item must
be a string (strings with embedded blanks must be delimited by double quotes). If you are using walking
menus ("Walking_menus Enabled"), the menu item can be a string or the full pathname of an icon file,
delimited by angle brackets. With care, strings and icons can be mixed in one menu.
There are four reserved-word commands that can appear on the right side.
EXIT

Exit the suntools program, after user confirmation.

REFRESH

Redraw the entire screen.

MENU

If you are using stacking menus, a menu is added to the pile with the Root Window
Menu. The menu contents are taken from the filename that follows the MENU command. You must give the full pathname of the file.
If you are using walking menus, this menu item is a pull-right item with a submenu. If a
filename follows the MENU command, the submenu contents are taken from the
filename. Otherwise, all the lines between this MENU command and a matching END
command are added to the submenu.

END

Marks the end of a nested submenu. The left side of this line should match the left side
of a line with a MENU command. Not valid if you are using stacking menus.

If the command is not one of these four reserved-word commands, it is treated as a command line and executed. No shell interpretation is done, although you can run a shell as a command.
Here is a menu file that demonstrates some of these features:
Quit

EXIT

Clock

clock-r-f

"Mail reader"

mailtool

"More tools"

MENU lusr/foo/me/moretools.menu

"Click to type"

swin --c

"Follow mouse"

swin-m

"Print selection"

sh --c get_selection Ilpr

- Only if you are using walking menus:
"Nested menu"

416

MENU

Cmdtool

cmdtool

Shelltool

shelltool

"Nested menu"

END

"Icon menu"

MENU

Last change: 29 June 1986

Sun Release 3.2

SUNTOOLS ( 1 )

USER COMMANDS

SUNTOOLS ( 1 )

<.Jusr/includelimages/textedit.icon>

textedit

<.Jusr/includelimages/iconedit.icon>

iconedit

"Icon menu"

END

Multiple I Color Displays
The suntools program runs on either a monochrome or color screen. Each screen on a machine may have
its own invocation of suntools running on it The keyboard and mouse input devices are shared among
multiple screens. The mouse cursor slides from one screen to another when you move the cursor off the
edge of a screen.

A common multiple display configuration is one monochrome and one color screen. You could set up an
instance of sun tools on each screen in the following way:

1.

Invoke suntools on the monochrome display by running "suntools". This starts suntools on the
default frame buffer named Idevljb.

2.

In a shelltool, run "suntools -d /dev/cgoneO -n &". This starts sun too Is on a color screen named
/dev/cgoneO.

3.

In a shelltool on the monochrome screen, run "adjacentscreens Idev/fb -r /dev/cgoneO". This sets
up cursor tracking so that the cursor slides from the monochrome screen to the color screen when
you move the cursor off the right hand side of the monochrome screen, and back when you move
the cursor off the left hand side of the color screen.

Multiple Desktops on the Same Screen
Given appropriate hardware, the suntools program can be made to run separate desktops on the same
screen. This facility is an extension of the features described in the previous section entitled
Multiple I Color Displays. The Prism is an example of a machine with multiple plane groups that can take
advantage of this facility. Each plane group on a machine may have its own invocation of suntools running
on it Such an invocation is called a desktop. The keyboard and mouse input devices are shared among
multiple desktops. The mouse cursor slides from one desktop to another when you move the cursor off the
edge of the screen.

A common multiple desktop configuration for the Prism is one monochrome and one color desktop. You
could set up an instance of suntools on each plane group in the following way:

1.

Invoke suntools in the color plane group by running "suntools -8bit_color_only -toggle_enable".
This starts suntools on the default frame buffer named Idevlfb but limits access to the color plane
group.

2.

In a shelltool, run "suntools -d Idev/bwtwoO -toggle_enable -n &". This starts suntools in the
overlay plane that is accessed by Idev/bwtwoO.

3.

In a shelltool run "adjacentscreens -c Idev/fb -l/dev/bwtwoO". This sets up cursor tracking so
that the cursor slides from the monochrome desktop to the color desktop when you move the cursor off the right hand side of the monochrome desktop, and back when you move the cursor off
the left hand side of the color desktop.

Old pre-3.2 applications run on the 8bit_color_only desktop will not appear because they will be writing to
the overlay plane. I.e., don't run old pre-3.2 applications on an 8bit_color_only desktop.
There is an application called the switcher that is used as an alternative to adjacentscreens for getting
between desktops on the Prism. Clicking the switcher icon gets you to another desktop using some amusing video wipe type animation. The switcher can also be used to simply set the enable plane to 0 or 1 if the
enable plane get out of wack. See the man page switcherl(l) for details.
Generic Tool Arguments
Most window-based applications now take the following arguments in their command lines:

FLAG
-Ww

Sun Release 3.2

(LONG FLAG)
(-width)

ARGS
columns

Last change: 29 June 1986

NOTES

417

SUNTOOLS ( 1 )

-Wb

-Ws
-Wp
-WP
-WI
-Wi
-Wt
-Wn
-Wf
-Wb
-Wg
-WI
-WL
-WT
-WH

USER COMMANDS

(-height)
(-size)
(-position)
(-iconyosition)
(-label)
(-iconic)
(-font)
(-no_name_stripe)
(-foreground_color)
(-background_color)
(-set_default_color)
(-iconJmage)
(-iconJabel)
(-icon_font)
(-help)

lines
xy
xy
xy
"string"

SUNTOOLS ( 1 )

x and y are in pixels
x and y are in pixels
x and y are in pixels
makes the tool start iconic (closed)

filename
red green blue
red green blue
filename
"string"
filename

0-255 (no color-full color)
0-255 (no color-full color)
(apply color to subwindows too)
(for tools with non-default icons)
(for tools with non-default icons)
(for tools with non-default icons)
print this table

Each flag option may be specified in either its short form or its long fonn; the two are completely
synonymous.
Getting Out

To exit any tool, invoke the Quit command in the Frame Menu as described above. To exit the entire window system, invoke Exit Suntools in the Root Window Menu as described above. Make sure that all windows are in a safe condition (for example, editors have written out all changes) first
You can exit suntools via the keyboard by typing AD followed by AQ. There is no confirmation. This facility provides an escape if you inadvertently start suntools without a mouse attached to the system.
SEE ALSO

Windows and Window-Based Tools: Beginner's Guide
Some of the applications that run in the SunView environment

clock(l), cmdtool(l), dbxtool(l), defaultsedit(l),fontedit(l), gfxtool(l), iconedit(l), lockscreen(l), mailtool(l), overview (1), perfmeter(l), perfmon(l), shelltool(1), tektool(l), textedit(1), traffic(1)
Some of the utility programs that run in or with the SunView environment:

adjacentscreens(l), clearJunctions(l), get_selection (1), rastps(l), setkeys(l),
sttyJrom_defaults(1), swin(1), switcher(l), toolplaces(l)
FILES

-I.suntools
lusr/binl suntools
lusr/binl othertools
lusr/binl get_selection

lusr/binlselection svc
lusrllib/suntools
lusr/lib/rootmenu
lusrllib/fonts/fixedwidthfonts/*
ldev/winx
ldev/ptypx
ldev/ttypx
ldev/fb
ldevlkbd
ldev/mouse
letc/utmp

418

Last change: 29 June 1986

Sun Release 3.2

SUNTOOLS ( 1 )

USER COMMANDS

SUNTOOLS ( 1 )

BUGS

Messages from the kernel ignore window boundaries unless console messages have been redirected, thus
trashing the display. Recover from this by invoking the Redisplay All item on the Root Window Menu.
Then invoke the Console item to start a console.
To improve interactive performance, the kernel should be reconfigured in order to make more memory
available for applications. See the System Manager's Guide.
With an optical mouse, sometimes the arrow-shaped cursor will not move at start-up; moving the mouse in
large circles on its special pad for a few seconds will bring the cursor to life.

suntools needs the file letclutmp to have read and write permission for all users. It should have been
installed with these permissions, but if not, you need to use chrrwd to change the permissions.
On a color display, all of the colors may "go strange" when the cursor is in certain windows. This is
caused by SunView accommodating a particular window's request for a large number of colors.
When running multiple desktops, be careful to not have more than one shelltool or cmdtool acting as the
console at once. Kill one console before starting another.

Sun Release 3.2

Last change: 29 June 1986

419

SWIN (1)

USER COMMANDS

SWIN(l)

NAME

swin - set/get SunView user input options
SYNOPSIS

swin [ -c] [ -g] [ -b] [ -m] [-r event value shift_state] [ -s event value shift_state] [ -t seconds]
DESCRIPTION
The swin (set window; analogous to stty(l) command lets you change some of the input behavior of your

SunView environment. By default, your keyboard input follows your mouse cursor. This means that in
order to type to a window you position the mouse cursor over the window. This is called keyboardfollows-mouse mode.
You can specify that the keyboard input continues to go to the same window, regardless of the mouse cursor position, until you take some specific action, like clicking the mouse. When this is done, you can roam
around the screen with the mouse cursor and not change the window to which keyboard input is directed.
Running SunView like this is said to be operating in click-to-type mode.
When running in click-to-type mode, one user action sets the type-in point in the window that you want to
receive keyboard input. The default user action to do this is the pressing of the left mouse button while
positioning the mouse cursor over the new type-in point This user action can be changed.
Another user action restores the previous type-in point in the window that you want to receive keyboard
input. The default user action to do this is the pressing of the middle mouse button while positioning the
mouse cursor over the window. This user action can be changed.
OPTIONS

-c

Turn on click-to-type mode using the default user actions: the left mouse button sets the type-in
point and the middle button restores the type-in point. You can use the defaultsedit(l) program to
set click-to-type on permanently; see the SunView/Click_to_Type option.

-m

Run in keyboard-follows-mouse mode.

-s event value shift_state
Set the user action that sets the type-in point and sets the keyboard input window. The event
identifies the particular user action and is one of:
LOC_WINENTER

the mouse cursor entering a window
the left mouse button
MS MIDDLE

the middle mouse button
MS RIGHT

the right mouse button
decimal number
place the decimal number of a firm event here; see list of events in
/usr/includelsundevlvuid_event.h (avoid function keys, normally unused control-ascii
characters are OK, normally unused shift keys are OK).
value identifies the transition of the event and is one of:
ENTER

the mouse cursor entering a window (use with LOC_WINENTER)

DOWN

the button associated with event went down

UP

the button associated with event went up (avoid this)

The shift_state identifies the state of the shift keys at the time of the event/value pair in order for
that pair to be used to control the keyboard input window. The shift_state is one of:
SHIFf DONT CARE

420

Last change: 24 December 1985

Sun Release 3.2

SWIN(I)

USER COMMANDS

SWIN(I)

ignore the state of the shift keys
SIllFf_ALL_UP

all the shift keys must be up
SIllFf LEFf

the left shift key must be down (not the key labelled LEFf)
SIllFf_RIGHT

the right shift key must be down (not the key labelled RIGHT)
SIllFf_LEFTCTRL

the left control key must be down
SHIFf RIGHTCfRL

the right control key must be down
-r event value shift_state

Set the user action that restores the type-in point and sets the keyboard input window. This user
action is swallowed so that the application that owns the window doesn't see it. However, if the
window already has keyboard input or if the window refuses keyboard input then this user action
is passed on through to the application. The parameters to this command are like for -so The following example shows modifying the default click-to-type user actions so that a left-shift is
required for the restore user event:
tutorial% swin -c -r MS_MIDDLEDOWN SHIFf_LEFf
-t seconds

SunView synchronizes input so that it doesn't hand out the next user action until the application
fielding the current user action finishes its processing. This allows type-ahead and mouse-ahead.
If an application doesn't finish processing within a given length of time (process virtual time; not
wall clock time), the next user action is handed out anyway. This avoids anyone application from
hanging the workstation. The -t command sets this time limit. A seconds value of 0 tells SunView to run unsynchronized; beware of race conditions in this mode. The default seconds value is
2 and the -t: command makes it 10 seconds.

-g

Get the state of the user input options controlled by swine If no arguments are supplied to swin
then -g is implied.

-b

Print out a help message that briefly describes the options to swine

FILES

lusrlincludelsundevlvuid event.h - list of event codes
SEE ALSO
suntools(1), defaultsedit(1)
Windows and Window-Based Tools: Beginner's Guide
DIAGNOSTICS
"swin not passed parent window in environment" - must be running suntools already; swin doesn't work
unless SunView is started already.
BUGS

swin gets you no help in preventing you from specifying -r or -s parameters that are not sensible.

Sun Release 3.2

Last change: 24 December 1985

421

SWITCHER ( 1 )

USER COMMANDS

SWITCHER ( 1 )

NAME

switcher - switch attention between multiple desktops on the same physical screen
SYNOPSIS

switcher [ -dframe-buffer] [ -s 0 III r Ii 101 f] [ -m x y ] [ -0] [ -e 0 11 ]
DESCRIPTION
Switcher is used as an alternative to adjacentscreens for getting between desktops on the Prism. Clicking
the switcher icon gets you to another desktop using some amusing video-wipe animation. When using
walking menus, a menu is available to invoke the switch as well. switcher can also be used to simply set

the enable plane to 0 or 1 should it get out of wack.
OPTIONS
-dframe-buffer
Theframe buffer is a frame buffer device name, such as ldev/fb, IdevlcgfourO or IdevlbwtwoO, on
which the desktop that you want to get to resides. This name is the same one supplied to suntools.
The -d flag is optional because if not specified, the default device is ldevlfb.

-s nllirliiolf
The -s flag specifies the type of animation used when switching: n(ow), l(eft wipe), r(ight wipe),
i(tunnel In), o(tunnel Out), or .f{ade). The -s flag is optional because if not specified, The -s flag
is optional because if not specified, the default animation is to switch immeditately, i.e., now
mode.

-m x y The -m indicates what the mouse position should be on the destination desktop after the switch.
An (x y) value-pair of (-1 -1) says to use the position of the mouse on the desktop at the time of
the switch as the mouse position on the destination desktop. The -m ft.ag is optional because if
not specified, the default is (-1 -1).
-0

The -0 ft.ag means no·switcher icon is wanted so do the switch right now and exit switcher after
the switch. This is handy if you want to switch from a root menu command.

-e 0 11 The -e flag causes the overlay enable plane of the device specified with the -d flag to be set to
either 0 (show color) or 1 (show black and white). switcher run with this option has nothing to do

with SunView, only the enable plane is set
EXAMPLE

A common multiple desktop configuration for the Prism is one monochrome and one color desktop. You
could set up an instance of suntools on each plane group in the following way:
1.

Invoke suntools in the color plane group by running:
% suntools -8bit_color_only -toggle_enable

This starts suntools on the default frame buffer named Idev/fb but limits access to the color plane
group.
2.

In a shelltool, run:
% suntools -d Idev/bwtwoO -toggle_enable &

This starts suntools in the overlay plane that is accessed by Idev/bwtwoO.
3.

In a shelltool on the original desktop run:
% switcher -d Idev/bwtwoO -s i &

Clicking on the switcher icon when it is visible moves you to the Idevlbwtwo desktop.
4.

In a shelltool on the Idevlbwtwo desktop run:
% switcher -s 0 &

Clicking on the switcher icon when it is visible moves you back to the Idevlfb desktop.

422

Last change: 18 July 1986

Sun Release 3.2

SWITCHER ( 1 )

USER COMM:ANDS

SWITCHER ( 1 )

FILES

lusrlbinl switcher
SEE ALSO
suntools( 1), shelltool( 1), adjacentscreens( 1)

Sun Release 3.2

Last change: 18 July 1986

423

SYMORDER ( 1 )

USER COMMANDS

SYMORDER ( 1 )

NAME

symorder - rearrange name list
SYNOPSIS
orderlist symbolfile
DESCRIPTION
orderlist is a file containing symbols to be found in symbolfile, 1 symbol per line.

symbolfile is updated in place to put the requested symbols first in the symbol table, in the order specified.
This is done by swapping the old symbols in the required spots with the new ones. If all of the order symbols are not found, an error is generated.
This program was specifically designed to cut down on the overhead of getting symbols from Ivmunix.
SEE ALSO
nlist(3)

424

Last change: 17 February 1986

Sun Release 3.2

SYNC ( 1)

USER COMMANDS

SYNC(l)

NAME

sync - update the super block
SYNOPSIS

sync
DESCRIPTION
sync forces any information on its way to the disk to be written out immediately. sync can be called to
ensure that all disk writes are completed before the processor is halted abnormally.
SEE ALSO
halt(8), reboot(8), cron(8), fsck(8)

Sun Release 3.2

Last change: 1 November 1983

425

SYSLOG( 1)

USER COMMANDS

SYSLOG(I)

NAME

syslog - make system log entry
SYNOPSIS

syslog [ -p ] [ -i name ] [ -level] [ - ] [message ••• ]
DESCRIPTION
Syslog sends the specified message (or stdin if - is specified) as a system log entry to the syslog daemon.
The log entry is sent to the daemon on the machine specified by the log host entry in the fetc/hosts file.
OPTIONS

-p

Syslog will log its process id in addition to the other information.

-i name The specified name will be used as the "ident" for the log entry.
-level

The message will be logged at the specified level. The level can be specified numerically, in the
range 1 through 9, or symbolically using the names specified in the include file
lusr/include/syslog.h (with the leading LOG_ stripped off). "syslog -HELP" will list the valid
symbolic level names. Only the superuser can make log entries at levels less than or equal to
SALERT.
Each line of the standard input is sent as a log entry.

FILES

lusr/etc/in.syslog
syslog daemon
lusr/include/syslog.h for names of logging levels
SEE ALSO

syslog(3), syslog(8)

426

Last change: 25 April 1983

Sun Release 3.2

USER COMMANDS

TAIL ( 1)

TAIL ( 1)

NAME

tail - display the last part of a file
SYNOPSIS

tail + I-number [ Ibc ] [ fr] [filename ]
DESCRIPTION
tail copies filename to the standard output beginning at a designated place. If no file is named, the standard
input is used.
OPTIONS
Options are all jammed together, not specified separately with their own - signs.

+number
Begin copying at distance number from the beginning of the file. number is counted in units of
lines, blocks or characters, according to the appended option l, b, or c. When no units are
specified, counting is by lines. If number is not specified, the value lOis used.
-number
Begin copying at distance number from the end of the file. Number is counted in units of lines,
blocks or characters, according to the appended option I, b, or c. When no units are specified,
counting is by lines. If number is not specified, the value 10 is used.
r

Copy lines from the end of the file in reverse order. The default for r is to print the entire file this
way.

f

If the input file is not a pipe, do not terminate after the line of the input file has been copied, but
enter an endless loop, sleeping for a second and then attempting to read and copy further records
from the input file. This option may be used to monitor the growth of a file that is being written
by some other process. For example, the command:
tail -f fred
will print the last ten lines of the file fred, followed by any lines that are appended to fred
between the time tail is initiated and killed. As another example, the command:
tail -15cf fred
will print the last 15 characters of the file fred, followed by any lines that are appended to fred
between the time tail is initiated and killed.

SEE ALSO
dd(l)

BUGS
Data for a tail relative to the end of the file is stored in a buffer, and thus is limited in size.
Various kinds of anomalous behavior may happen with character special files.

Sun Release 3.2

Last change: 17 February 1986

427

TALK ( 1)

USER COMMANDS

TALK ( 1)

NAME
talk - talk to another user
SYNOPSIS

talk person [ ttyname ]
DESCRIPTION
talk is a visual communication program which copies lines from your terminal to that of another user.

If you wish to talk to someone on your own machine, then person is just the person's login name. If you
wish to talk to a user on another host, then person is of the form :
host!user or
host .user or
host:user or
user@host
though user@host is perhaps preferred.
If you want to talk to a user who is logged in more than once, the ttyname argument may be used to indicate the appropriate terminal name.

When first called, talk sends the message:
Message from TalkDaemon@his_machine...
talk: connection requested by your_name@your_machine.
talk: respond with: talk your_ name@your_machine
to the user you wish to talk to. At this point, the recipient of the message should reply by typing:
tutorial% talk your_ name@your_machine
It doesn't matter from which machine the recipient replies, as long as their login-name is the same. Once
communication is established, the two parties may type simultaneously, with their output appearing in
separate windows. Typing control-L redraws the screen, while your erase, kill, and word kill characters
will work in talk as normal. To exit, just type your interrupt character; talk then moves the cursor to the
bottom of the screen and restores the terminal.
Permission to talk may be denied or granted by use of the mesg command At the outset talking is allowed.
Certain commands, in particular nroff and pr disallow messages in order to prevent messy output.
FILES

fete/hosts
fete/utmp

to find the recipient's machine
to find the recipient's tty

SEE ALSO
mesg(l), who(l), mail(I), write(I), talkd(8)

428

Last change: 23 September 1985

Sun Release 3.2

TAR ( 1)

USER COMMANDS

TAR(I)

NAME

tar - tape archiver
SYNOPSIS

tar [-] ctxru[ovwfbXlmhFpB014S78i] [tarfile] [blocksize] [exclude file]
filename1 filename2 ... -C dir filenameN ...
DESCRIPTION

tar saves and restores multiple files on a single tarfile (usually a magnetic tape, but it can be any file). tar's
actions are controlled by its first argument, the key, a string of characters containing exactly one function
letter from the set ntoc and one or more optional/unction modifiers. Other arguments to tar are file or
directory names specifying which files to dump or restore. In all cases, appearance of a directory name
refers to the files and (recursively) subdirectories of that directory.
FUNCTION LETTERS

c

Create a new tarfile and write the named files onto it

r

Write the named files on the end of the tarfile. Note that this option does not work with quarter-inch
archive tapes.

x

Extract the named files from the tarfile. If a named file matches a directOry whose contents had been
written onto the tape, this directory is (recursively) extracted. The owner, modification time, and mode
are restored (if possible). If no file arguments are given, the entire content of the tape is extracted.
Note that if multiple entries specifying the same file are on the tape, the last one overwrites all earlier
versions.

t

List all of the names on the tarfile.

u

Add the named files to the tarfile if they are not there or have been modified since last put on the tarfile.
Note that this option does not work with quarter-inch archive tapes.

FUNCTION MODIFIERS

014578
Select an alternate drive on which the tape is mounted. The numbers 2, 3, 6, and 9 do not specify valid
drives. The default is Idev/rmt8.
f

Use the next argument as the name of the tarfile instead of Idev/rmt8. If the name is '-', tar writes to
standard output or reads from standard input, whichever is appropriate. Thus, tar can be used as the
head or tail of a filter chain. tar can also be used to copy hierarchies with the command:
tutorial% cd fromdir; tar cf -.\ (cd todir; tar xffip-)

o

Suppress information specifying owner and modes of directories which tar normally places in the
archive. Such information makes former versions of tar generate an error message like:
'/: cannot create'
when they encounter it.

v

Normally tar does its work silently; the v (verbose) option displays the name of each file tar treats, preceded by the function letter. When used with the t function, v displays the tarfile entries in a form similar to Is -I.

w Wait for user confirmation before taking the specified action. If you use w, tar displays the action to be

taken followed by the file name, and then waits for a 'y' response to proceed. No action is taken on the
named file if you type anything other than a line beginning with 'y'.
b

Use the next argument as the blocking factor for tape records. The default blocking factor is 20 blocks.
The block size is determined automatically when reading tapes (key letters x and t). This determination
of the blocking factor may be fooled when reading from a pipe or a socket (see the B key letter below).
The maximum blocking factor is determined only by the amount of memory available to tar when it is
run. Larger blocking factors result in better throughput, longer blocks on nine-track tapes, and better
media utilization.

X Use the next argument as a file containing a list of named files (or directories) to be excluded from the

Sun Release 3.2

Last change: 17 July 1986

429

TAR ( 1)

USER COMMANDS

TAR ( 1)

tarfile when using the key letters c, x, or t. Multiple X arguments may be used, with one exclude file
per argument.
I

Display error messages if all links to dumped files cannot be resolved. If I is not used, no error messages are printed.

sees

F With one F argument specified, exclude all directories named
from tarfile. With two arguments
FF, exclude all directories named
all files with .0 as as their suffix, and all files named errs,
core, and a.out.

sees,

m Do not restore modification times of extracted files. The modification time will be the time of extraction.
h

Follow symbolic links as if they were normal files or directories. Normally, tar does not follow symbolic links.

p Restore the named files to their original modes, ignoring the present umask(2). Setuid and sticky information are also restored if you are the super-user. This option is only useful with the x key letter.
B Force tar to perform multiple reads (if necessary) so as to read exactly enough bytes to fill a block.
This option exists so that tar can work across the Ethernet, since pipes and sockets return partial blocks
even when more data is coming.
Ignore directory checksum errors.
If a file name is preceded by -C in a c· (create) or r (replace) operation, tar will perform a chdir(2) to that
file name. This allows multiple directories not related by a close common parent to be archived using short
relative path names. For example, to archive files from lusr/include and from letc, one might use:
tutorial% tar c -C lusr include -C letc •
If you get a table of contents from the resulting tarfile, you will see something like:
includel
include/a.outh
and all the other files in lusrlinclude
1

lchown
and all the other files in Ietc

Note that the -C option only applies to one following directory name and one following file name.
EXAMPLES

Here is a simple example using tar to create an archive of your home directory onto Idev/rmtO:
tutorial%' cd
position yourself in your home directory
tutorial% tar cvf Idev/rmtO •
create the archive
lots of messages from tar
tutorial%
The c option means create the archive; the v option makes tar tell you what it's doing as it works; the f
option means that you are specifically naming the file onto which the archive should be placed (/dev/rmtO
in this example).
Now you can read the table of contents from the archive like this:
display table of contents of the archive
tutorial% tar tvf Idev/rmtO
(access user-id!group-id
size
mod. date
rw-r--r-- 1677/40
2123
Nov 7 18:15:1985
tutorial%
You can extract files from the archive like this:
tutorial% tar xvf Idev/rmtO
lots of messages from tar
tutorial%

430

filename)

.IarchiveltJ

extract files from the archive

Last change: 17 July 1986

Sun Release 3.2

TAR(l)

USER COMMANDS

TAR ( 1)

If there are multiple archive files on a tape, each is separated from the following one by an end-of-file
marker. tar does not read the end-of-file mark on the tape after it finishes reading an archive file because
tar looks for a special header to decide when it has reached the end of the archive. Now if you try to use
tar to read the next archive file from the tape, tar doesn't know enough to skip over the end-of-file mark
and tries to read the end-of-file mark as an archive instead. The result of this is an error message from tar
to the effect:
tar: blocksize=O
This means that to read another archive from the tape, you must skip over the end-of-file marker before
starting another tar command. You can achieve this via the mt command, as shown in the example below.
Assume that you are reading from /dev/nrmtO.
tutorial% tar xvfp /dev/nrmtO
read first archive from tape
lots of messages from tar
tutorial% mt fsf 1 skip over the end-of-file marker
tutorial% tar xvfp /dev/nrmtO read second archive from tape
lots of messages from tar
tutorial%
Finally, here is an example using tar to transfer files across the Ethernet. First, here is how to dump files
from the local machine (tutorial) to a tape on a remote system (krypton):
tutorial% tar cvfb - 20 files I rsh krypton dd or=ldev/rmtO obs=20b
lots of messages from tar
tutorial%
In the example above, we are creating a tarfile with the c key letter, asking for verbose output from tar with
the v option, specifying the name of the output tarfile via the f option (the standard output is where the
tarfile appears, as indicated by the - sign), and specifying the blocksize (20) with the b option. If you want
to change the blocksize, you must change the blocksize arguments both on the tar command and on the dd
command.
Now, here is how to use tar to get files from a tape on the remote system (krypton) back to the local system
(tutorial):
tutorial% rsh krypton dd if=/dev/rmtO bs=20b I tar xvBfb - 20 files
lots of messages from tar
tutorial%
In the example above, we are extracting from the tarfile with the x key letter, asking for verbose output
from tar with the v option, telling tar it is reading from a pipe with the B option, specifying the name of the
input tarfile via die f option (the standard input is where the tarfile appears, as indicated by the - sign), and
specifying the blocksize (20) with the b option.
FILES

/dev/rmt? half-inch magnetic tape interface
/dev/rar? quarter-inch magnetic tape interface
/dev/rst? SCSI tape interface
/tmpltar*
SEE ALSO
tar(5), cpio(l), dump(8), restore(8)
BUGS

Neither the r option nor the u option can be used with quarter-inch archive tapes, since these tape drives
cannot backspace.
There is no way to ask for the n 'th occurrence of a file.
Tape errors are handled ungracefully.

Sun Release 3.2

Last change: 17 July 1986

431

TAR ( 1)

USER COMMANDS

TAR(l)

The u option can be slow.
There is no way selectively to follow symbolic links.
When extracting tapes created with the r or u options, directory modification times may not be
correctly.

set

Files with names longer that 100 characters cannot be processed
Filename substitution wildcards don't work for extracting files from the archive. To get around this, use a
command of the form:
tar xvf... /dev/rstO 'tar tf... /dev/rstO I grep 'pattern"

432

Last change: 17 July 1986

Sun Release 3.2

TBL( 1)

USER COMMANDS

TBL( 1)

NAME

tbl- format tables for nroff or troff
SYNOPSIS
tbl [ -IDS]

[ -IDID ]

[files] •••

DESCRIPTION
Tbl is a preprocessor for formatting tables for nroff or troff(l). The inputfiles are copied to the standard
output, except that lines between .TS and.TE command lines are assumed to describe tables and are reformatted Details are given in the tb/(1) reference manual.

If no arguments are given, tbl reads the standard input, so tbl may be used as a filter. When tbl is used with
eqn or neqn the tbl command should be first, to minimize the volume of data passed through pipes.
OPTIONS
-ms
-mm

Copy the -IDS macro package to the front of the output file.
Copy the -mID macro package to the front of the output file.

EXAMPLE

As an example, letting \trepresent a tab (which should be typed as a genuine tab) the input
.TS
css
ccs
ccc
Inn.
Household Population
Town\tHouseholds
\tN umber\tSize
Bedminster\t789\t3.26
Bernards Twp.\t3087\t3.74
Bernardsville\t2018\t3 .30
Bound Brook\t3425\t3.04
Branchburg\t1644\t3 .49
Bridgewater\t7897\t3.81
Far Hills\t240\t3.19
.TE
yields
Household Population
Town
Households
Number
Size
789
3.26
Bedminster
3.74
3087
Bernards Twp.
2018
3.30
Bernardsville
3425
3.04
Bound Brook
1644
Branchburg
3.49
3.81
7897
Bridgewater
240
3.19
Far Hills
SEE ALSO
troff( 1), eqn( 1)

Formatting Documents on the Sun Workstation

Sun Release 3.2

Last change: 14 December 1983

433

TCOV( 1)

USER COMMANDS

TCOV(l)

NAME

tcov - construct test coverage analysis and statement-by-statement profile
SYNOPSIS

tcov [ -a ] [ -n ] srcfile ...
DESCRIPTION

tcov produces a test coverage analysis and statement-by-statement profile of a C or FORTRAN program.
When a program in a file named file.c or file .r is compiled with the -a option, a corresponding file.d file is
created. Each time the program is executed, test coverage information is accumulated in file .d.
tcov takes source files as arguments. It reads the corresponding file.d file and produces an annotated listing
of the program with coverage data infile.tcov. Each straight-line segment of code (or each line if the-a
option to tcov is specified) is prefixed with the number of times it has been executed; lines which have not
been executed are prefixed with #####.
Note that the profile produced includes only the number of times each statement was executed, not execution times; to obtain times for routines use gprof(l) or prof(l).
OPTIONS

-a

display an execution count for each statement; if -a is not specified, an execution count is
displayed only for the first statement of each straight-line segment of code.

-n

display table of the line numbers of the n most frequently executed statements and their execution
counts.

EXAMPLES

sun% cc -a -0 prog prog.c
sun%prog
sun% tcov prog.c

Compile with the -a option - produces prog.d
Execute the program - accumulates data in prog.d
Produces an annotated listing in file prog.tcov

SEE ALSO

cc( 1V), prof( 1), gprof(1)
FILES

file.c
file.f
file.d
file.tcov
lusr/binl count
lusr/lib/bb link.o

input C program file
input FORTRAN program file
input test coverage data file
output test coverage analysis listing file
preprocessor for test coverage analysis for C program
entry and exit routines for test coverage analysis

BUGS

The analyzed program must call exit(2) or return normally for the coverage information to be saved in the
.d file.
,A premature end of file' message is issued for routines containing no statements.

434

Last change: 24 March 1985

Sun Release 3.2

TEE ( 1)

USER COMMANDS

TEE(I)

NAME

tee - copy standard output to many files
SYNOPSIS
tee [ -i] [ -a ] [ file] •••
DESCRIPTION
Tee transcribes the standard input to the standard output and makes copies in the files.
OPTIONS
-i

-a

Sun Release 3.2

Ignore interrupts.
Append the output to the files rather than overwriting them.

Last change: 2 June 1983

435

TEKTOOL(1)

USER COMMANDS

TEKTOOL(1 )

NAME

tektool- Tektronix 4014 terminal emulator tool
SYNOPSIS

tektool [-fJontdir] [-s[ledeg[ee]m[12]] [-[er] command-line]
DESCRIPTION
tektool emulates a Tektronix 4014 terminal with the enhanced graphics module. It does this in much the
same way as shelltool (see suntools(1» emulates a regular glass tty. When tektool is invoked, a command
(usually a shell) is started up, its output and input are connected to the emulator, and a new window is
formed The default window is the entire screen. When the emulator is running, buttons TF(I) through
TF(3), (usually function keys FI-F3 (see kbd(5» have special meaning.

TF(I)

Unshifted, this is the 4014 PAGE button. Shifted, this is the 4014 RESET button.

TF(2)

Copy screen. The raster image (Iusrlincludelrasterfile .h) of the 4014 screen is piped to a command found in the TEKCOPY environment variable. If TEKCOPY is not found in the environment, "Ipr -v" is used. The copy button is unaffected by window manipulations, and will
transmit the contents of the 4014 screen only.

TF(3)

Release page full condition.

These functions are also available through the tool menu. When in graphics input (GIN) mode and the
4014 crosshairs are visible, the left hand mouse button may be used as the space bar to terminate GIN
mode.
OPTIONS
-fJontdir
Look for fonts in the directory specified by Jontdir. The fonts must be called tekfontO through tekfont3.
Fonts must be in vJont(5) format If this option is not given, the font directory is obtained from the
TEKFONTS environment variable (if it exists). If no font directory is specified, lusrlliblfontsltekfonts is
used.

-s Specifies the Tektronix 4014 strap options with the following modifiers:
1 Received line feeds also generate carriage returns.
c Received carriage returns also generate linefeeds.
d Received DEL characters are used as low order Y axis (LOY) addresses.
e Echo keyboard input
g Graphic input mode (GIN) terminator specification. If this strap is followed by a e, GIN mode data
is terminated by a carriage return. If it is followed by a e, GIN mode data is terminated by a carriage return followed by an EOT character. If this strap is not present, no characters are sent after
GIN mode data.
m Page full control specification. If this strap is followed by a 1, tektool will stop accepting tty input
when a line feed is done past the last line in margin 1. This is the 4014 page full condition. The
page full condition it released by a PAGE or a RELEASE or any ascii keyboard input. If this strap is
followed by a 2, the page full condition happens at the end of margin 2. H this strap is not present,
the page full condition never occurs.

If the -s option is not given, the environment is searched for the TEKSTRAPS variable which provides
the modifiers. The straps may also be set by the property sheet available by selecting the PROPS menu
item. If no straps are specified the d strap is assumed.

-e command-line
Take terminal emulator input from a shell which in turn runs the command-line following the -e
option.
-r command-line
Run command-line to provide input to the terminal emulator. This must be the last option, since the
remainder of the arguments are used by the command.

436

Last change: 5 June 1986

Sun Release 3.2

TEKTOOL(l)

USER COMMANDS

TEKTOOL(l)

CAVEATS
Like all 4014 emulators, this doesn't duplicate every nuance of the 4014. For instance, certain programs
redraw stuff already on the screen in order to highlight things with the storage flash. This won't work here.
Also, even though the emulator supports the full 4096 point addressing of the 4014, it cannot display this
on the screen. All points will be rounded to the nearest available pixel. This may cause some funny
effects.

The tektool window may be treated just like other windows; it can be overlaid, moved, reshaped etc. However, when the window is reshaped, the contents will not scale.
FILES

lusrllib/fontsltekfontsltekfont[0-3]
SEE ALSO
suntools( 1)
DIAGNOSTICS
copy command failed

The copy command in the TEKCOPY environment variable or in the property sheet could not be
executed.
BUGS

Special point plot mode is not supported.

Z axis stuff, except for defocusing, is not supported.
Defocused alpha characters are not supported.

Sun Release 3.2

Last change: 5 June 1986

437

TELNET(IC)

USER COMMANDS

TELNET( lC)

NAME

telnet - user interface to the TELNET protocol
SYNOPSIS

telnet [ host [ port] ]
DESCRIPTION

telnet communicates with another host using the TELNET protocol. If telnet is invoked without arguments,
it enters command mode, indicated by its prompt ("teInet>"). In this mode, it accepts and executes the
commands listed below. If it is invoked with arguments, it performs an open command (see below) with
those arguments.
Once a connection has been opened, lelnet enters input mode. In this mode, text typed is sent to the remote
host. To issue telnet commands when in input mode, precede them with the telnet "escape character" (initially "A]", control-right-bracket). When in command mode, the normal terminal editing conventions are
available.
TELNET COMMANDS

The following commands are available. Only enough of each command to uniquely identify it need be
typed.
open host [port]
Open a connection to the named host. If the no port number is specified, telnet will attempt to
contact a TELNET server at the default port. The host specification may be either a host name (see
hosts(5» or an Internet address specified in the "dot notation".
close

Close a TELNET session and return to command mode.

quit

Close any open TELNEr session and exit telnet.

z

Suspend telnet. This command only works when the user is using the csh.

escape [ escape-char]
Set the telnet "escape character". Control characters may be specified as "A" followed by a single letter; e.g. "control-X" is ""X".
status

Show the current status of telnet. This includes the peer one is connected to, as well as the state
of debugging.

options Toggle viewing of TELNET options processing. When options viewing is enabled, all TELNET
option negotiations will be displayed Options sent by telnet are displayed as "SENT", while
options received from the TELNET server are displayed as "RCVD".
crmod Toggle carriage return mode. When this mode is enabled any carriage return characters received
from the remote host will be mapped into a carriage return and a line feed. This mode does not
affect those characters typed by the user, only those received. This mode is not very useful, but is
required for some hosts that like to ask the user to do local echoing.

? [command]
Get help. With no arguments, lelnet prints a help summary. If a command is specified, telnet will
print the help information available about the command only.
SEE ALSO

rlogin(IC)
BUGS

There is no provision in the standard TELNET protocol to support "srQ type commands. This implementation is very simple because rlogin(IC) is the standard mechanism used to communicate locally with hosts.

438

Last change: 23 September 1985

Sun Release 3.2

TEST ( IV)

USER COMMANDS

TEST ( IV)

NAME

test, - test a condition
SYNOPSIS

test expr
[expr]
DESCRIPTION
test evaluates the expression expr and, if its value is true, returns a zero (true) exit status; otherwise, a nonzero (false) exit status is returned. test returns a non-zero exit if there are no arguments.

The following primitives are used to construct expr.

-b file

true if file exists and is a block special device.

-cfile

true iffile exists and is a character special device.

-dfile

true if file exists exists and is a directory.

-ffile

true if file exists and is not a directory.

-gfile

true iffile exists and its set-group-ID bit is set

-hfile

true if file exists and is a symbolic link.

-kfile

true if file exists and its sticky bit is set

-I string

the length of the string.

-os1

true if the length of the string s1 is non-zero.

-pfile

true iffile exists and is a named pipe (fifo).

-r file

true iffile exists and is readable.

-sfile

true iffile exists and has a size greater than zero.

-t [fildes]

true if the open file whose file descriptor number iSfildes (1 by default) is associated with a terminal device.

-ufile

true if file exists and its set-user-ID bit is set

-w file

true if file exists and is writable.

-x file

true if file exists and is executable.

-z s1

true if the length of string s1 is zero.

s1

=s2

true if the strings s1 and s2 are equal.

s1 != s2

true if the strings s1 and s2 are not equal.

s1

true if s1 is not the null string.

n1 -eq n2 true if the integers n1 and n2 are algebraically equal. Any of the comparisons -De, -gt, -ge,
-It, or -Ie may be used in place of -eq.
These primaries may be combined with the following operators:
unary negation operator

-a

binary and operator

-0

binary or operator

( expr) parentheses for grouping.

-a has higher precedence than -0. Notice that all the operators and flags are separate arguments to test.
Notice also that parentheses are meaningful to the Shell and must be escaped.

Sun Release 3.2

Last change: 1 May 1986

439

TEST ( tV)

USER COMMANDS

TEST ( tV)

SYSTEM V DESCRIPTION

The actions of the System V version of test are the same, except for the following primitives:
-f file

true if file exists and is a regular file.

-I string

not supported.

NOTE

The test command is built into the shell. The shell chooses the 4.2BSD or the System V version of test
depending on whether lusr/5bin appears before Ibin in the shell's PATH variable, just as the 4.2BSD or
System V versions of regular commands are selected depending on whether lusr/5bin appears before the
directory in which the 4.2BSD version of that command appears.
The fact that test is built into the shell also means that a program named test cannot be run without specifying a pathname; if the program is in the current directory, Jtest will suffice.
SEE ALSO

sh( 1), find( 1)
WARNING

In the second form of the command (Le., the one that uses [], rather than the word test), the square brackets must be delimited by blanks.
Some UNIX systems do not recognize the second form of the command

440

Last change: 1 May t986

Sun Release 3.2

TEXTEDIT ( 1 )

USER COMMANDS

TEXTEDIT ( 1 )

NAME

textedit - mouse and window oriented text editor
SYNOPSIS
textedit [ -generic_option genericJXlraTnS ... ] [ -EH ] [ -Ea on Ioff] [ -Ei on lofT] [ -EL N ]
[ -Em N] [ -ES N] [ -ET N] [ -En N] [ -Eo on Ioff] [ -Er on Ioff] [ -Es N]
[-EuN] [-EUN] [-EcN]filename
DESCRIPTION
textedit is a mouse-oriented text editor that runs within the SunView environment.

When invoked, textedit creates a window containing two text subwindows. The much smaller, top subwindow (known as the scratch window) is used for keeping small pieces of text in, such as directory and file
names. The bottom subwindow is used to display and edit the file specified on the command line (or simply serves as a large scratch area if no file was specified). The name of the file currently being edited is
displayed in the left-hand portion of the name stripe. The name of the current working directory is
displayed in the right-hand portion of the name stripe.
For a description of how to use the facilities of the text subwindows, see Windows and Window-Based
Tools: Beginner's Guide.

H textedit hangs, for whatever reason, it can be forced to try to write out the edited version of the text by
sending its process a SIGHUP, usually via a command line of the form:
kill -HUP pid
The edits will be written to the file textedit .pid in the current working directory. H the write fails,
textedit tries IUSTIImp, then Itmp. In addition, whenever textedit catches a fatal signal, such as SIGILL, it
tries to write out the edits before aborting for a post-mortem.
DEFAULTS OPTIONS
There are several dozen user specified defaults that affect the behaviour of the text subwindow facilities.
See defaultsedit(1) for a description of how to browse and edit these defaults. Important default entries in
the Text category to be aware of are:

Edit_back_char

The character that, when typed, erases the character just before the insertion
point. The default value is DEL. This, and the following editing characters,
can only be specified via use of defaultsedit; in particular, stty(1) cannot be
used to set the erase character.
The character that, when typed, erases the word just before the insertion
point. The default value is CfRL-W.

Edit back line

The character that, when typed, erases the portion of the line before the
insertion point. The default value is CfRL-U.

Checkpoint_frequency

ois the standard default; it means that no checkpointing will take place.

-

-

For
a value n greater than zero, checkpointing will take place after every nth
edit Each character typed, each Get, and each Delete counts as an edit. H
the file being edited is namedfoo, at each checkpoint, an updated copy of
the file will be saved infoo%%.

COMMAND LINE OPTIONS
-generic_option textedit accepts the SunView generic tool arguments; see suntools(1) for a complete list
of generic_options.

-EH

textedit outputs a page of helpful information to stderr and then exits. (-text_help is a
synonym for this option.)

-Ea onloff

If the parameter value is on, adjusting a selection span has the side-effect of making the
selection pending-delete. This option (or the synonym -adjust_isyending_delete)
corresponds to, and overrides, the Text package's defaults database entry
Adjust_isyending_delete, which has default value False, meaning off.

Sun Release 3.2

Last change: 19 February 1986

441

TEXTEDIT ( 1 )

USER COMMANDS

TEXTEDIT ( 1 )

-Eionloff

If on, typing a newline indents the created line to match the indentation of the previous
line. (Synonym is -auto_indent; overrides default Auto_indent which has value False.)

-ELN

N is the minimum number of lines kept between the insertion point (indicated by the
caret) and the bottom of the text subwindow. (Synonym is -lower_context; overrides
default Lower_context which has value 2.)

-EmN

N is the number of pixels by which the left edge of the text is offset from the scrollbar.
(Synonym is -margin; overrides default Left_margin which has value 4.)

-ESN

N is the number of pixels within which two clicks of a mouse button must occur in order
to be considered a multi-click. (Synonym is -multi_c1ick~pace; overrides default
Multi_click_space which has value 3.)

-ETN

N is the number of rnilli-seconds within which two clicks of a mouse button must occur
in order to be considered a multi-click. (Synonym is -multtclick_timeout; overrides
default Multi_click_timeout which has value 390.)

-EnN

N is the number of lines in the bottom subwindow. (Synonym is -number_of_lines;
standard value is 45.)

-Eoonloff

(Synonym is -i)kay_to_overwrite; overrides default Store_self_is_save which has value
False.)
on

A Store menu operation to the current file name is treated as a Save.

off

Store to the current file results in an error message and is aborted.

-Er onloff

H on, the text cannot be modified, only browsed. (Synonym is -read_only, standard
value is off.)

-EsN

N is the number of lines in the scratch window. A zero value means that there is no
scratch window. (Synonym is -scratch_window; overrides default Scratch_window
which has value 1.)

-EtN

N is the number of spaces that define a column when a TAB is displayed. This option has
no effect on the characters actually stored in the file being edited; it only affects their
display. (Synonym is -tab_width; overrides default Tab_width which has value 8.)

-EuN

N is the number of editing sequences that can be undone or replayed. (Synonym is
-history_limit; overrides default History_limit which has value 50.)

-EUN

N is the minimum number of lines kept between the insertion point and the top of the
text sub window . (Synonym is -upper_context; overrides default Upper_context which
has value 2.)

-EcN

N specifies the checkpoint frequency. 0 means that no checkpointing will take place.
For a value N greater than zero, checkpointing will take place after every nth edit Each
character typed, each Get, and each Delete counts as an edit. If the file being edited is
named /00, at each checkpoint, an updated copy of the file will be saved in /00%%.
(Synonym is -checkpoint; overrides default CheckpointJrequency which has value 0.)

COMMANDS
Making a selection
In textedit the mouse is used to specify a selection, which is a character span to operate on. The mouse is

also used to position the insertion point and to invoke a menu of additional commands. The assignment of
commands to the mouse buttons is:
Command
Select

442

Mouse button
Left

Description
Starts a new selection and moves the insertion
point to the end of the selection nearest the
mouse cursor.

Last change: 19 February 1986

Sun Release 3.2

TEXTEDIT ( 1 )

USER COMMANDS

TEXTEDIT ( 1 )

Adjust

Middle

Extends a selection, and moves the insertion
point.

Menu

Right

Displays a menu of operations, explained below.

There are two types of selections: a primary selection is indicated by video-inversion of the span of characters, and tends to persist. A secondary selection is indicated by underlining the span of characters and only
exists while one of the four function keys corresponding to the commands Delete, Find, Get, or Put, is
depressed
In addition, either type of selection can have the property of being pending-delete, indicated by overlaying
the span of characters with a light gray pattern. A selection is made pending-delete by holding the CONTROL key down while doing either a Select or an Adjust. If a primary selection is pending-delete, it is only
deleted when characters are inserted, either by type-in or by Get or Put. If a secondary selection is
pending-delete, it is deleted when the function key is released, except in the case of the Find command,
which deselects the secondary selection. Either the defaults entry Adjust_isyending_delete or the -Ea
command line option can be used to make either type of selection pending-delete whenever it is adjusted;
in this case, holding the CONTROL key while doing an Adjust makes the selection not be pending-delete.
Commands that operate upon the primary selection do so even if the primary selection is not in the window
that issued the command
Inserting text and command characters
For the most part, typing any of the standard keys either causes the corresponding character to be inserted
at the insertion point, or causes characters to be erased However, certain key combinations are treated as
commands:

Command

Character

Description

Delete-Primary

CTRL-D

Find-Primary

CTRL-F

Get-Shelf

CTRL-G

Put-then-Get
Go-to-EOF

CTRL-P

Erases, and moves to the Shelf, the
primary selection.
Searches the text for the
pattern specified by the primary
selection or by the Shelf, if there is no
primary selection.
Copies the Shelf to the insertion
point.
Accelerator for Put then Get.
Moves the insertion
point to the end of the text, positioning
the text so that the insertion point is visible.

CTRL-RETURN

Function Keys
The commands indicated by use of the function keys are:

Command

Sun-213 Key

Description

Stop
Again

Ll
L2

Undo
Expose

IA
L5

Put

L6

Close

L7

Aborts the current command.
Repeats the previous editing sequence since a
primary selection was made.
Undoes a prior editing sequence.
Makes the window completely visible (or
hides it, if it is already exposed).
Copies the primary selection, either to the
Shelf or at the closest end of the secondary
selection.
Makes the window iconic (or normal, if it is already
iconic).

Sun Release 3.2

Last change: 19 February 1986

443

TEXTEDIT ( 1 )

USER COMMANDS

Get

L8

Find

L9

Delete

LtO

CAPSLOCK

Fl

TEXTEDIT ( 1 )

Copies either the secondary selection or the Shelf at
the insertion point.
Searches for the pattern specified by, in order, the
secondary selection, the primary selection, or the Shelf.
Erases, and moves to the Shelf, either the primary or
the secondary selection.
Forces all subsequently typed alphabetic characters
to be upper-case.
This key is a toggle; striking it a second time undoes the
effect of the first strike.

Find usually searches the text forwards, towards the end. Holding down the SHIFf key while invoking Find
causes the search to go backward through the text, towards the beginning. If the pattern is not found before
the search encounters either extreme, it "wraps around" and continues from the other extreme. Find starts
the search at the appropriate end of the primary selection, if the primary selection is in the subwindow that
the search is made in; otherwise it starts at the insertion point, unless the subwindow cannot be edited, in
which case it starts at the beginning of the text.

If the default assignment of function keys to commands is inconvenient (or does not make sense, in the
case of a Sun-l keyboard), it can be modified by the setkeys(1) program.
Menu Items
Commands that are available by use of the generic text sub window menu are:
Menu Item

Description

Save
Save file

A pull-right item, it is equivalent to Save file.
Saves the edits (requires that a file is being
edited).
If the Save succeeds, textedit terminates.
If the Save succeeds, textedit Resets.
Makes the window iconic and then does the Save.
Stores the edits to the file specified
by the primary selection, and then continues editing that
file.
If the Store succeeds, textedit
terminates.
Makes the window iconic and then does the Store
as described above.
textedit begins editing the file specified
by the primary selection.
Displays the line specified by the primary
selection,
interpreted as an integer (where 1, not 0, is the first line).
Requires a following mouse button click to indicate
where to divide the text subwindow, then it creates another view
on the same text
Destroys the view over which the menu was invoked.
Discards all edits made to the text;
requesting confirmation first. If there were no edits,
unloads the file if editing a file.
Displays a message indicating the line
number containing the start of the primary selection.
Copies to the insertion point the contents of the
file specified by the primary selection.
Positions the text in the view over which the

Save & Quit
Save & Reset
Close & Save
Store to named file

Store & Quit
Close & Store
Load file
Select line #

Split view

Destroy view
Reset

Whatline#?
Get from file
Caret to top

444

Last change: 19 February 1986

Sun Release 3.2

TEXTEDIT ( 1 )

Line break
Clip lines

Wrap at character
Set directory
Find
Find, forward
Find, backward
Find Shelf, forward
Find Shelf, backward
Put then Get

USER COMMANDS

TEXTEDIT ( 1 )

menu was invoked so that the insertion point is just below
the top of the view.
A pull-right item, it is equivalent to Clip lines.
Any line that does not terminate in a newline before
encountering the right edge of the window is clipped at the right
edge.
Long lines are displayed on multiple window lines.
Changes the working directory to the directory name
specified by the primary selection.
A pull-right item, it is equivalent to Find, forward.
Searches for, in order, the primary selection or the
Shelf.
Searches for, in order, the primary selection or the
Shelf, but moving backward through the text
Searches for the Shelf.
Searches for the Shelf, but moving backward
through the text
Equivalent to a Put followed by a Get.

Only those commands that are active appear normally in the menu; inactive commands, which are inappropriate at the time that the menu is invoked (such as Destroy view when there is only one view), are indicated by being" grayed out" .
User Defined Commands

The file 7 .textswrc specifies filter programs that are executed when unassigned function keys are
depressed These filters are invoked with the contents of the primary selection available on their stdin, and
output on their stdout is entered in the text being edited at the insertion point
An example file that contains filters useful for programming and documenting is available as
lusrllibl.textswrc. This file can be copied and edited to re-bind filters to function keys according to individual preferences. See Windows and Window-Based Tools: Beginner's Guide for a specification of the format of the .textswrc and a list of filters and their descriptions.
FILES

7.textswrc
lusrlbin
filename%
textedit.pid
ItmplEtHost*

specifies bindings of filters to function keys
contains useful filters, including shift_lines and capitalize.
prior version of filename is available here after a Save menu operation
edited version offilename; generated in response to fatal internal errors
editing session logs

SEE ALSO

defaultsedit(l), kill(l), setkeys(l), suntools(l)
Windows and Window-Based Tools: Beginner's Guide
DIAGNOSTICS

Messages displayed by textedit during initialization (and their cause) are:
Cannot open file 'file', aborting!
file does not exist or cannot be read.
The exit status codes produced are:
o
normal termination
1
standard SunView help message was printed
2
help message was requested and printed
3
abnormal termination in response to a signal, usually due to an internal error
4
abnormal termination during initialization, usually due to a missing file or running out of swap
space.

Sun Release 3.2

Lastchange: 19 February 1986

445

TEXTEDIT ( 1 )

USER COMMANDS

TEXTEDIT ( 1 )

BUGS

Multi-click to change the current unit does not work for Adjust Selection.
Handling of long lines is incorrect in certain scrolling situations.
There is no way to replay any editing sequence except the most recent.

446

Last change: 19 February 1986

Sun Release 3.2

TFfP( lC)

USER COMMANDS

TFfP( lC)

NAME

tftp - trivial file transfer program
SYNOPSIS

trtp [host]
DESCRIPTION

tftp is the user interface to the Internet TFrP (Trivial File Transfer Protocol), which allows users to transfer
files to and from a remote machine. The remote host may be specified on the command line, in which case
tftp uses host as the default host for future transfers (see the connect command below).
An account or password on the remote machine is not required. Due to lack of authentication information,
tftp is only able to access publicly readable files. Search permissions of directories leading to accessed files

are not checked.
COMMANDS
Once tftp is running, it issues the prompt trtp> and recognizes the following commands:

connect host-name [port]
Set the host (and optionally port) for transfers. Note that the TFfP protocol, unlike the FfP protocol, does not maintain connections betweeen transfers; thus, the connect command does not
actually create a connection, but merely remembers what host is to be used for transfers. You do
not have to use the connect command; the remote host can be specified as part of the get or put
commands.
mode transfer-mode
Set the mode for transfers; transfer-mode may be one of ascii, binary, or mail. The default is
ascii.
put file ... destination
Put a file or set of files to the specified destination. destination can be in one of two forms: a
filename on the remote host, if the host has already been specified, or a string of the form
host :filename to specify both a host and filename at the same time. If the latter form is used, the
hostname specified becomes the default for future transfers.
get source ... file
Get a file or set of files from the specified sources. source can be in one of two forms: a filename
on the remote host, if the host has already been specified, or a string of the form host: filename to
specify both a host and filename at the same time. If the latter form is used, the last hostname
specified becomes the default for future transfers.
quit

Exit tftp.

verbose Toggle verbose mode. Has no effect.
trace

Toggle packet tracing.

status

Show current status.

rexmt retransmission-timeout
Set the per-packet retransmission timeout, in seconds.
timeout total-transmission-timeout
Set the total transmission timeout, in seconds.
? [command-name ... ]
Print help information.
BUGS

Because there is no user-login or validation within the TFTP protocol, the remote site will probably have
some sort of file-access restrictions in place. The exact methods are specific to each site and therefore
difficult to document here.

Sun Release 3.2

Last change: 17 July 1986

447

TFTP(IC)

USER COMMANDS

TFfP( IC)

The verbose command has no effect

448

Last change: 17 July 1986

Sun Release 3.2

TIC ( 1V)

USER COMMANDS

TIC ( 1V)

NAME

tic - tenninfo compiler
SYNOPSIS

tic [ -v[n] ] file . ..
DESCRIPTION
Note:

Optional Software (System V Option). Refer to Installing UNIX on the Sun Workstation for information on how to install this command.

tic translates terminfo files from the source format into the compiled format. The results are placed in the
directory lusrl5liblterminfo.
tic compiles all terrninfo descriptions in the given files. When a use= field is discovered, tic searches first
the current file, then the master file, which is lterminfo.src.
OPTIONS
-v

Verbose. Produce trace information showing tic's progress. With the optional integer n, the
degree of verbosity can be increased

ENVIRONMENT
If the environment variable TERMINFO is set, the results are placed there instead of lusrl5liblterminfo.
LIMIT ATIONS
Some limitations: total compiled entries cannot exceed 4096 bytes. The name field cannot exceed 128
bytes.
FILES
lusr/5Iib/terminfol*l*

compiled terminal capability data base

SEE ALSO
curses(3V), terminfo(5V)
BUGS

Instead of searching Jterminfo.src, it should check for an existing compiled entry.

Sun Release 3.2

Last change: 1 May 1986

449

TIME ( IV)

USER COMMANDS

TIME ( IV)

NAME

time - time a command
SYNOPSIS

time [ command]
DESCRIPTION

There are three distinct versions of time: it is built in to the C-Shell, and is an executable program available
in /bin/time and lusr/5binltime when using the Bourne shell. In each case, times are displayed on the
diagnostic output stream.
In the case of the C-Shell, a time command with no command argument simply displays a summary of time
used by this shell and its children. When arguments are given the specified simple command is timed and
the C-Shell displays a time summary as described in csh(1).
The time commands in Ibin/time and lusr/5bin/time time the given command, which must be specified,
that is, command is not optional as it is in the C-Shell's timing facility. When the command is complete,
time displays the elapsed time during the command, the time spent in the system, and the time spent in execution of the command. Times are reported in seconds. The only difference between the versions in
Ibin/time and lusr/5binltime is between their output formats; /bin/time prints all three times on the same
line, while lusrlSbinltime prints them on separate lines.
EXAMPLES

The three examples here show the differences between the csh version of time and the versions in /bin/time
and lusrlbin/time. The example assumes that csh is the shell in use.
angel% time we lusr/man/manllesh.l
1876 11223 65895/usr/manlmanllcsh.l
2.7u 0.9s 0:03 91% 3+5k 19+2io 1pf+Ow
angel% Ibin/time we lusr/man/manllcsh.l
1876 11223 65895/usr/manlmanllcsh.1
4.3 real
2.7 user
1.0 sys
angel% lusr/5bin/time we lusr/man/manl/csh.l
1876 11223 65895/usr/manlmanllcsh.1
real
4.3
user
2.7
1.0
sys
angel%
SEE ALSO

csh(1)

BUGS
Elapsed time is accurate to the second, while the CPU times are measured to the 50th second. Thus the
sum of the CPU times can be up to a second larger than the elapsed time.

450

Last change: 23 September 1985

Sun Release 3.2

TlP( lC)

USER COMMANDS

TIP ( lC)

NAME

tip, cu - connect to a remote system
SYNOPSIS

tip [ -v ] [ -speed] system-name
tip [ -v [ -speed_entry] [phone-number]
co phone-number [ -t ] [ -s speed] [ -a acu] [ -I line ] [ -# ]
DESCRIPTION

tip and cu establish a full-duplex connection to another machine, giving the appearance of being logged in
directly on the remote computer. It goes without saying that you must have a account on the machine (or
equivalent) to which you wish to connect. The preferred interface is tip. The cu interface is included for
those people attached to the 'call UNIX' command of the version 7 UNIX system. This manual page
describes only tip.
When tip starts up it reads commands from the file .tiprc in your home directory. If you use the -v option
on the tip command line, tip displays these commands as it executes them. See the discussion on variables
later on.
Typed characters are normally transmitted directly to the remote machine (which does the echoing as well).
A tilde ('-') appearing as the first character of a line is an escape signal which directs tip to perform some
special action. tip recognizes the following escape sequences:
-AD -.
Drop the connection and exit (you may still be logged in on the remote machine).

-c [name]
Change directory to name (no argument implies change to your home directory).
-!

Escape to a shell (exiting the shell returns you to tip ).

->

Copy file from local to remote.

-<

Copy file from remote to local.

-pfrom [to]
Send a file to a remote UNIX host. When you use the put command, the remote UNIX system runs
the command string
cat> to
while tip sends it the from file. If the to file isn't specified, the from file name is used. This command is actually a UNIX specific version of the ,->' command.
-tfrom [to]
Take a file from a remote UNIX host. As in the put command the to file defaults to the from file name
if it isn't specified. The remote host executes the command string
cat> from; echo A
to send the file to tip.
A

-I

Pipe the output from a remote command to a local UNIX process. The command string sent to the
local UNIX system is processed by the shell.

-C

Connect a program to the remote machine. The command string sent to the program is processed by
the shell. The program inherits file descriptors 0 as remote line input, 1 as remote line output, and 2
as tty standard error.

-#

Send a BREAK to the remote system. For systems which don't support the necessary ioctl call the
break is simulated by a sequence of line speed changes and DEL characters.

-s

Set a variable (see the discussion below).

-AZ

Stop tip (only available when run under the C-Shell).

-?

Get a summary of the tilde escapes

Sun Release 3.2

Last change: 25 November 1985

451

TIP ( lC)

USER COMMANDS

TIP ( lC)

Copying files requires some cooperation on the part of the remote host. When a -> or - < escape is used to
send a file, tip prompts for a file name (to be transmitted or received) and a command to be sent to the
remote system, in case the file is being transferred from the remote system. The default end of transmission string for transferring a file from the local system to the remote is specified as the 'oe' parameter in the
remote (5) file, but may be changed by the set command. While tip is transferring a file the number of lines
transferred will be continuously displayed on the screen. A file transfer may be aborted with an interrupt
An example of the dialogue used to transfer files is given below (input typed by the user is shown in bold
face).
arpa% tip monet
[connected]
.. .{assume we are talking to another UNIX system) ...
ucbmonetlogin:sam
Password:
monet% cat > sylvester.c
-> Filename: sylvester.c
32 lines transferred in 1 minute 3 seconds
monet%
monet% - < Filename: reply.c
List command for remote host: cat reply.c
65 lines transferred in 2 minutes
monet%
.. .{or. equivalently) ...
monet% -p sylvester.c
.. .(actually echoes as 7putj sylvester. c) . ..
32 lines transferred in 1 minute 3 seconds
monet%
monet% -t reply.c
.. .{actually echoes as 7takej reply.c) ...
65 lines transferred in 2 minutes
monet%
.. .{to print afile locally) ...
monet% -ILocal command: pr -b sylvester.c Ilpr
List command for remote host: cat sylvester.c
monet% -AD
[EOT]
.. .{back on the local system) ...
The remote (5) file contains the definitions for remote systems known by tip; refer to the remote manual
page for a full description. Each system has a default baud rate with which to establish a connection. If
this value is not suitable, the baud rate to be used may be specified on the command line, for example:
tip -300 mds
When a phone number is specified, instead of a system name, tip looks for an entry in fetclremote of the
form tipspeed_entry. When it finds such an entry, it sets the connection-speed accordingly. If it doesn't
find a corresponding entry, tip interprets speed_entry as if it were a system name, resulting in an error message. If you omit -speed_entry, tip uses the tipO entry to set a speed for the connection.
When tip establishes a connection it sends out a connection message to the remote system. The default
value for this string may be found in the remote file.
At any time that tip prompts for an argument (for example, during setup of a file transfer) the line typed
may be edited with the standard erase and kill characters. A null line in response to a prompt, or an interrupt, aborts the dialogue and returns you to the remote machine.

452

Last change: 25 November 1985

Sun Release 3.2

TIP ( IC)

USER COMMANDS

TIP ( IC}

When tip attempts to connect to a remote system, it opens the associated device with an exclusive-open
ioctl (2) call. Thus only one user at a time may access a device. This is to prevent multiple processes from
sampling the tenninalline. In addition, tip honors the locking protocol used by uucp(IC).
AUTO-CALL UNITS
tip may be used to dial up remote systems using a number of auto-call unit's (ACU's). When the remote
system description contains the 'du' attribute, tip uses the call-unit ('cu'), ACU type ('at'), and phone
numbers ('pn') supplied. Normally tip displays verbose messages as it dials. See remote (5) for details of
the remote host specification.

Depending on the type of auto-dialer being used to establish a connection the remote host may have garbage characters sent to it upon connection. The user should never assume that the first characters typed to
the foreign host are the first ones presented to it. The recommended practice is to immediately type a 'kill'
character upon establishing a connection (most UNIX systems support '@' as the initial kill character).

tip currently supports the Ventel MD-2I2+ modem and DC Hayes-compatible modems.
REMOTE HOST DESCRIPTIONS
Descriptions of remote hosts are normally located in the system-wide file tetc/remote. However, a user
may maintain personal description files (and phone numbers) by defining and exporting the REMOTE shell
variable. The remote file must be readable by tip, but a secondary file describing phone numbers may be
maintained readable only by the user. This secondary phone number file is tetc/phones, unless the shell
variable PHONES is defined and exported. As described in remote (5), the phones file is read when the host
description's phone number(s) capability is an '@'. The phone number file contains lines of the form:

system-name

phone-number

Each phone number found for a system is tried until either a connection is established, or an end of file is
reached. Phone numbers are constructed from '0123456789-=*', where the '=' and '*' are used to indicate
a second dial tone should be waited for (ACU dependent).
TIP INTERNAL VARIABLES
tip maintains a set of variables which are used in normal operation. Some of these variables are read-only
to normal users (root is allowed to change anything of interest). Variables may be displayed and set
through the '-s' escape. The syntax for variables is patterned after vi and mail. Supplying 'all' as an argument to the set command displays all variables that the user can read. Alternatively, the user may request
display of a particular variable by attaching a '?' to the end. For example 'escape?' displays the current
escape character.

Variables are numeric, string, character, or Boolean values. Boolean variables are set merely by specifying
their name. They may be reset by prepending a '!' to the name. Other variable types are set by appending
an '=' and the value. The entire assignment must not have any blanks in it A single set command may be
used to interrogate as well as set a number of variables.
Variables may be initialized at run time by placing set commands (without the '-s' prefix) in a .tiprc file in
one's home directory. The -v option makes tip display the sets as they are made. Comments preceded by
a 'I' sign can appear in the .tiprc file.
Finally, the variable names must either be completely specified -or an abbreviation may be given. The following list details those variables known to tip, their abbreviations (surrounded by brackets), and their
default values. Those variables initialized from the remote file are marked with a '*'. A mode is given for
each variable - capitalization indicates the read or write capability is given only to the super-user.
Variable

Type Mode Default

[be]autify
[ba]udrate
[c]har[delay]
[dial] timeout

bool
num
num
num

Sun Release 3.2

rw
rW

true

*

rw

0

rW

60

Description
discard unprintables when scripting
connection baud rate
character delay for file transfers to remote (cl)
timeout (seconds) when establishing connection

Last change: 25 November 1985

453

USER COMMANDS

TIP ( Ie)

[di]sconnect
[ec]hocheck
[eofr]ead
[eofw]rite
[eol]
[es]cape
[et]imeout
[ex]ceptions
[fo]rce
[fr] arnesize
[h]alf[d]uple[x]
[holst
[l]ine[delay]
[l]ocal[e]cho
[par]ity
[phones]
[pr]ompt
[ra]ise
[r]aise[c]har
[raw]ftp

str
bool
str
str
str
char
num
str
char
num
bool
str
num
bool
str
str
char
bool
char
bool

rw
rw
rw
rw
rw
rw
rw
rw
rw
rw
rw
r
rw
rw
rw
r
rW
rw
rw
rw

[rec]ord
[remote]
[sc]ript
[tab] expand
[ta]ndem
[verb]ose
[SHELL]
[HOME]

str
str
bool
bool
bool
bool
str
str

rw
r
rw
rw
rw
rw
rw
rw

TIP ( Ie)

string to send to disconnect (di)
false

*
*
*,-,
10
"\t\n\t\b"
'''1'

*

false

*

0
false
"none"
It/etc/phones "
'\n'
false
'''1'
false

"tip.record"
"/etc/remote"
false
false
true
true
"/bin/shlt

char's signifying EOT from the remote host
string sent for EOT
end of line indicators
command prefix character
echo check timeout (et)
char's not discarded due to beautification
force character (default ASCII 255)
size of buffering between writes on reception
host is half duplex - do local echo (hd)
name of host connected to
line delay for transfers to remote (dl)
synonym for halfduplex
parity to be generated (pa)
file for hidden phone numbers
end of line indicator set by host
upper case mapping switch
interactive toggle for raise (default ASCII 255)
send all characters during file transfer (rw)
do not filter non-printable characters
do not do translations like \n to \T.
name of script output file
system description file
session scripting switch
expand tabs during file transfers
use XON/XOFF flow control (ta and nt)
make noise during file transfers
name of shell for -! escape
home directory for -c escape

ENVIRONMENT VARIABLES
The following variables are read from the environment:
REMOTE

The location of the remote file.

PHONES

The location of the file containing private phone numbers.

HOST

A default host to connect to.

HOME

One's log-in directory (for chdirs).

SHELL

The shell to fork on a '-I' escape.

FILES

-/.tiprc initialization file.
/usr/spool/uucp/LCK.. * lock file to avoid conflicts with
/usr/admlaculog uucp
DIAGNOSTICS
Diagnostics are, hopefully, self explanatory.
SEE ALSO
remote(5), phones(5)
BUGS

Note that chardelay and linedelay are currently not implemented.

454

Last change: 25 November 1985

Sun Release 3.2

TOOLPLACES ( 1 )

USER COMMANDS

TOOLPLACES ( 1 )

NAME

toolplaces - show current window tool locations, sizes, and other attributes
SYNOPSIS

toolplaces [ -ulolO ] [ -belp ]
DESCRIPTION

toolplaces generates position, size, label, and program attributes for the windows running on a window system screen at the time of execution. (toolplaces doesn't work when the window system isn't running.)
Many people redirect standard output from toolplaces to the .suntools file, so as to reuse the current window system attributes each time they execute suntools, the window system program.
For each window on the screen at execution time, toolplaces shows:
the tool name
the "open" window position
the size of the window in pixels
the "closed," or icon, window position
an indicator of whether the window is open or closed
the label at the top of the window
the name of the program running in the window, if a
program is running there
any flags or options to a program running in the window

toolplaces describes each window on one output line, as long as necessary, using the current suntools format.
Current suntools format consists of window tool descriptions, one per line, as in this example (the \ indicates that the current line continues on the next line):
clocktool -Wp 120 120 -Ws 122 55 -WP 1086826 -Wi \
-WI open clock" -S -r -d wdm
shelltool -Wp 0510 -Ws 490 343 -WP 256836 \
-WI "Task Window: Ibinlcsh" lusr/local/emacs task.file
shelltool -Wp 491 795 -Ws 580 87 -WP 0836 -C
shelltool -Wp 491166 -Ws 650 567 -WP 702 836 \
-WI due rlogin due
shelltool -Wp 0 0 -Ws 650 525 -WP 64 836 \
-WI "Small Window: /binlcsh"
shelltool -Wp 501 0 -Ws 650812 -WP 128 836 \
-WI "Big Window: /binlcsh"
tt

OPTIONS

-u

Shows the updated window tool information in the order that you originally specified it.

-0

Shows window tool information in the old suntools format for window attributes, but
specifies the appropriate tool names for each tool.

-0

Shows window tool information in the old suntools format for window attributes, specifying toolname as the name for each tool.

-help

Shows help information preceding tool attributes.

FILES

-I.suntools

Format file for suntools window system program.

SEE ALSO

suntools(l)
Windows and Window-Based Tools: Beginner's Guide

Sun Release 3.2

Last change: 28 August 1985

455

TOUCH(lV)

USER COMMANDS

TOUCH(lV)

NAME

touch - update times of last access and modification of a file
SYNOPSIS

touch [ -c ] [ -f] filename ...
SYSTEM V SYNOPSIS

touch [ -c ] [ -a ] [ -m ] [ mmddhhmm [yy] ] filename . ..
DESCRIPTION
touch causes the access and modification times of each argument to be set to the current time. A file is
created if it does not already exist

touch is valuable when used in conjunction with make(l), where, for instance, you might want to force a
complete rebuild of a program composed of many pieces. In such a case, you might type:
% touch *.c
% make
make would then see that all the .c files were more recent than the corresponding
the compilation from scratch.

.0

files, and would start

OPTIONS

-c

Do not create filename if it does not exist.

-f

Attempt to force the touch in spite of read and write permissions on filename .

SYSTEM V OPTIONS
-a
Update only the access time.
-m

Update only the modification time.

mmddhhmm [yy]
Update the times to the specified time rather than to the current time. The first mm is the month,
dd is the day of the month, hh is the hour, and the second mm is the minute; if yy is specified, it is
the last two digits of the year, otherwise the current year is used.
SEE ALSO
utimes(2), make(l)
BUGS

It is difficult to touch a file whose name consists entirely of digits in the System V touch, as it will interpret
the first such non-flag argument as a time. You must ensure that there is a character in the name which is
not a digit, by specifying it as Jname rather than name .

456

Last change: 24 April 1986

Sun Release 3.2

TPUT( IV)

TPUT( IV)

USER COMMANDS

NAME

tput - query terminfo database
SYNOPSIS
lusrlSbinltput [ -Ttype ] capname
DESCRIPTION
Note:

Optional Software (System V Option). Refer to Installing
mation on how to install this command.

UNIX

on the Sun Workstation for infor-

tput uses the terminfo (5) database to make terminal-dependent capabilities and information available to the
shell. tput outputs a string if the attribute (capability name) is of type string, or an integer if the attribute is
of type integer. If the attribute is of type boolean, tput simply sets the exit code (0 for TRUE, 1 for
FALSE), and does no output
OPTIONS
-Ttype

indicates the type of terminal. Normally this flag is unnecessary, as the default is taken from
the environment variable $TERM.
indicates the attribute from the terminfo database. See terminfo(5).

capname
EXAMPLES
tput clear
tput cols
tput -T 450 cols
bold='tput smso'

tput he

Echo clear-screen sequence for the current terminal.
Print the number of columns for the current terminal.
Print the number of columns for the 450 terminal.
Set shell variable "bold" to stand-out mode sequence for current terminal. This
might be followed by a prompt:
echo "${bold}Please type in your name: \c"
Set exit code to indicate if current terminal is a hardcopy terminal.

FILES

Terminal descriptor files
lusrI5lib/terrninfol?l*
lusrISinclude/term.h
Definition files
lusrlSinclude/curses.h
DIAGNOSTICS
Tput prints error messages and returns the following error codes on error:
-1
Usage error.
-2
Bad terminal type.
-3
Bad capnarne.
In addition, if a capnarne is requested for a terminal that has no value for that capnarne (e.g., tput -T450
lines), -1 is printed.
SEE ALSO
stty(l), terrninfo(5)

Sun Release 3.2

Last change: 17 April 1986

457

TR( 1V)

USER COMMANDS

TR( 1V)

NAME
tr - translate characters

SYNOPSIS

tr [ -cds] [stringl [ string2 ] ]
DESCRIPTION
tr copies the standard input to the standard output with substitution or deletion of selected characters. The
arguments string1 and string2 are considered sets of characters. Any input character found in stringl is
mapped into the character in the corresponding position within string2. When string2 is short, it is padded
to the length of string1 by duplicating its last character.

In either string the notation
a-b
denotes a range of characters from a to b in increasing ASCII order. The character \, followed by 1,2 or 3
octal digits stands for the character whose ASCII code is given by those digits. As with the shell, the escape
character \, followed by any other character, escapes any special meaning for that character.
SYSTEM V DESCRIPTION
When string2 is short, characters in stringl with no corresponding character in string2 are not translated.

In either string the following abbreviation conventions introduce ranges of characters or repeated characters into the strings. Note that in the System V version, square brackets are required to specify a range.
[a-z]

Stands for the string of characters whose ASCII codes run from character a to character z,
inclusive.

[a*n]

Stands for n repetitions of a. If the first digit of n is 0, n is considered octal; otherwise, n is taken
to be decimal. A zero or missing n is taken to be huge; this facility is useful for padding string2.

OPTIONS
Any combination of the options -cds may be used:
-c

Complement the set of characters in string1 with respect to the universe of characters whose
ASCII codes are 01 through 0377 octal;

-d

Delete all input characters in string1 .

-s

Squeeze all strings of repeated output characters that are in string2 to single characters.

EXAMPLE
The following example creates a list of all the words in 'file 1' one per line in 'file2', where a word is taken
to be a maximal string of alphabetics. The second string is quoted to protect '\' from the Shell. 012 is the
ASCII code for newline.

tr-cs A-Za-z ,012' file2
In the System V version, this would be specified as:
tr-cs '[A-Z][a-z]' '[\012*]' file2
SEE ALSO
ed(1), ascii(7), expand(l)
BUGS

Won't handle ASCII NUL in stringl or string2. tr always deletes NUL from input

458

Last change: 24 April 1986

Sun Release 3.2

TRAFFIC ( lC)

USER COMMANDS

TRAFFIC ( lC)

NAME

traffic - graphical display of Ethernet traffic
SYNOPSIS

traffic [ -b host] [ -s subwindows ]
DESCRIPTION

Traffic graphically displays ethernet traffic. It gets statistics from etherd(8C), running on machine host.
The tool is divided into sub windows, each giving a different view of network traffic.
OPTIONS
-b host Specify a host from which to get statistics. The default value of host is the machine that traffic is

running on.

-s subwindows
Specify the number of subwindows to display initially. The default value of subwindows is 1.
SUBWINDOWS

To the right of each sub window is a panel that selects what the sub window is viewing. When Size is
checked, than the size distribution of packets is displayed. Proto is for protocol, Src is for source of
packet, and Dst is for destination of packet. Since it is not possible to show all possible sources, when Src
is selected, only the 8 highest sources are displayed (and similarly for Dst).
For each of these choices, the distribution is displayed by a histogram. The panel above each subwindow
controls characteristics of the histograms. At the left of the panel is a shaded square, corresponding to one
of the two shades of bars in the histogram. You can switch the shade by either clicking on the square with
the left button, or bringing up a menu over the square with the right mouse button. When the light colored
square is visible, then the slider in the center of the panel controls how often the light colored bars are
updated. When the dark square is visible, then the slider refers to the dark bars of the histogram. To the
right of the slider is a choice of Abs versus Rei. This selects whether the height of the histogram is Absolute in packets per second, or Relative in percent of total packets on the ethemet. Next in the panel are
three small horizontal bars. When selected (that is, when a check mark appears to the left of the three
bars), a horizontal grid appears on the histogram. Finally the button marked Delete Me will delete the
subwindow.
The right hand panel also has a choice for Load. Load is represented as a strip chart, rather than a histogram. The maximum value of the graph represents a load of 100%, that is 10 megabits per second on the
ethemet When Load is selected, there is only one slider, and no Rei versus Abs choice.
At the very top of the tool is a panel that contains filters, as well as a Split button that splits the tool and
creates a new subwindow, and a Quit button that exits the tool. The filters apply to all the subwindows.
When a filter is selected, a check mark appears to the left of the word Filter. There can be more than one
filter active at the same time. The meaning of each filter is as follows. Src is a host or net, which can be
specified either by name or address (similarlry for Dst). Proto is an ip protocol, and can either be a name
(such as udp, icmp) or a number. Lnth is either a packet length, or a range oflengths separated by a dash.
SEE ALSO

etherd(8C)
BUGS

If multiple copies of traffic are using the same copy of etherd, and one of them invokes a filter, then all the
copies of traffic will be filtered

Sun Release 3.2

Last change: 28 Aug 1985

459

TROFF( 1)

USER COMMANDS

TROFF(I)

NAME

troff - typeset or format documents
SYNOPSIS
troff[ -opagelist] [-oN] [-sN] [ -mname] [-raN] [-i] [-q] [-t] [-f]
[ -w] [ -b ] [ -a ] [ -pN] [ -z] [filenames] ...
DESCRIPTION
troff formats text in the named files. The output is by default destined for printing on a Graphic Systems
CIAff phototypesetter, but suitable postprocessing software can convert the CIAff output to a form which
can be directed to other high-resolution devices. See also the nroff(l) manual page, which describes a formatter which formats text for typewriter-like devices. The capabilities of both trolf and nrolf are described
in Formatting Documents with Nroff and Troff.
If no filenames argument is present, the standard input is read. An argument consisting of a single minus
(-) is taken to be a file name corresponding to the standard input

OPTIONS
Options may appear in any order so long as they appear before the filenames.

-olist

Print only pages whose page numbers appear in the comma-separated list of numbers and ranges.
A range N -M means pages N through M; an initial-N means from the beginning to page N; and a
final N - means from N to the end.

-oN

Number first generated page N.

-mname
Prepend the macro file lusr/lib/tmacltmac.name to the input files.
-raN

Set register a (one-character) to N.

-i

Read standard input after the input files are exhausted

-q

Disable echoing during a .rd request

-t

Direct output to the standard output instead of the phototypesetter. In general, you will have to
use this option if you don't have a typesetter attached to the system.

-a

Send a printable ASCII approximation of the results to the standard output.

Some options of troff only apply if you have a CI NT typesetter attached to your system. These options are
here for historical reasons:

-sN

Stop every N pages. troff stops the phototypesetter every N pages, produces a trailer to allow
changing cassettes, and resumes when the typesetter's start button is pressed.

-f

Refrain from feeding out paper and stopping phototypesetter at the end of the run.

-w

Wait until phototypesetter is available, if currently busy.

-b

Report whether the phototypesetter is busy or available. No text processing is done.

-pN

Print all characters in point size N while retaining all prescribed spacings and motions, to reduce
phototypesetter elasped time.

-z

Supress all formatted output. Display only terminal messages produced by .tm requests and diagnostics.

If the file lusrladm/tracet is writable, troffkeeps phototypesetter accounting records there. The integrity of
that file may be secured by making troffa 'set user-id' program.
FILES

Itrnplta*
lusrllib/trnac/trnac. *
lusrllib/terml*
lusrllib/fontl*

460

temporary file
standard macro files
terminal driving tables for nrof!
font width tables for trof!

Last change: 17 February 1986

Sun Release 3.2

TROFF( 1)

/dev/cat
/usr/admltracct

USER COMMANDS

TROFF( 1)

phototypesetter
accounting statistics for ldev/cat

SEE ALSO

nroff(I), eqn(I), tbl(I), rns(7), me(7), man(7), col(IV), checknr(l)
Formatting Documents on the Sun Workstation
Using nroff and troff on the Sun Workstation

Sun Release 3.2

Last change: 17 February 1986

461

TRUE ( 1)

USER COMMANDS

TRUE(I)

NAME

true, false - provide truth values
SYNOPSIS

true
false
DESCRIPTION

True and false are usually used in a Bourne shell script They test for the appropriate status "true" or
"false" before running (or failing to run) a list of commands.
EXAMPLE

while true
do
command list
done
SEE ALSO

csh(l), sh(I), false(l)
DIAGNOSTICS

True has exit status zero.

462

Last change: 11 January 1982

Sun Release 3.2

TSET( 1)

USER COMMANDS

TSET(1 )

NAME

tset, reset - establish terminal characteristics for the environment
SYNOPSIS
tset [ - ] [ -ec] [ -I ] [ -kc ] [ -n ] [ -Q ] [ -r ] [ -s] [
[ -m [port-ID [baudrate][ :type] ... ] [type]

-s ]

reset ...
DESCRIPTION
tset sets up your terminal, typically when you first log in. It does terminal dependent processing such as
setting erase and kill characters, setting or resetting delays, sending any sequences needed to properly initialized the terminal, and the like. tset first determines the type of terminal involved, and then does necessary initializations and mode settings. The type of terminal attached to each UNIX port is specified in the
letc!ttytype database. Type names for terminals may be found in the termcap(5) database. If a port is not
wired permanently to a specific terminal (not hardwired) it is given an appropriate generic identifier such as

dialup.
reset clears the terminal settings by turning off cbreak and raw modes, output delays and parity checking,
turns on newline translation, echo and tab expansion, and restores undefined special characters to their
default state. It then sets the modes as usual, based on the terminal type (which will probably override
some of the above). (See stty(lV) for more information.) reset also uses the rs= and rf= "reset string and
file" instead of the initialization string and file from letcltermcap. This is useful after a program dies and
leaves the terminal in a funny state. Often in this situation, characters will not echo as you type them. You
may have to type "reset" since  may not work.
When no arguments are specified, tset reads the terminal type from the TERM environment variable and
re-initializes the terminal, and performs initialization of mode, environment and other options at login time
to determine the terminal type and set up terminal modes.
When used in a startup script (.profile for sh users or .login for csh users) it is desirable to give information
about the type of terminal you will usually use on ports that are not hardwired. These ports are identified in
letclttytype as dialup or plugboard, etc. Any of the alternate generic names given in termcap may be used
for the identifier. Refer to the -m option under OPTIONS for more information. If no mapping applies and a
final type option, not preceded by a -m, is given on the command line then that type is used; otherwise the
identifier found in the letc!ttytype database is used as the terminal type. This should always be the case for
hardwired ports.
It is usually desirable to return the terminal type, as finally determined by tset, and information about the
terminal's capabilities, to a shell's environment. This can be done using the -, -s, or -S options. (Refer to
OPTIONS for more information.)
For the Bourne shell:
export TERM; TERM= 'tset - options ...'
or using the C-Shell:
setenv TERM 'tset - options ...'
With the C-Shell, it is convenient to make an alias in your .cshrc file:
alias tset 'setenv TERM 'tset - \!*" to allow the command:
tset2621
to be invoked at any time from your login csh. Note to Bourne Shell users: It is not possible to get this
aliasing effect with a shell script, because shell scripts cannot set the environment of their parent. If a process could set its parent's environment, none of this nonsense would be necessary in the first place.
Once the terminal type is known, tset sets the terminal driver mode. This normally involves sending an initialization sequence to the terminal, setting the single character erase (and optionally the line-kill (full line
erase» characters, and setting special character delays. Tab and newline expansion are turned off during

Sun Release 3.2

Last change: 17 February 1986

463

TSET( 1)

USER COMMANDS

TSET( 1)

transmission of the terminal initialization sequence.
On terminals that can backspace but not overstrike (such as a CRT), and when the erase character is '#', the
erase character is changed as if -e had been used.
OPTIONS

The name of the terminal finally decided upon is output on the standard output This is intended
to be captured by the shell and placed in the TERM environment variable.
-ec

Set the erase character to be the named character c on all terminals. Default is the backspace key
on the keyboard, usually AH. The character c can either be typed directly, or entered using the
circumflex-character notation used here.

-I

Suppress transmitting terminal-initialization strings.

-kc

Set the line kill character to be the named character c on all terminals. Default is AU. The kill
character is left alone if -k is not specified. Control characters can be specified by prefixing the
alphabetical character with a circumflex (as in AU) instead of entering the actual control key itself.
This allows you to specify contol keys that are currently assigned.

-0

Specifies that the new tty driver modes should be initialized for this terminal. Probably useless
since stty new is the default

-Q

Suppress printing the "Erase set to" and "Kill set to" messages.

-r

In addition to other actions, reports the terminal type.

-s

Output setenv commands for TERM and TERMCAP. This can be used with
setnoglob
eval "'tset -s ......
unset noglob
to bring the terminal information into the environment Doing so makes programs such as vi start
up faster.

-S

Similar to the -s option, but produces two strings containing suitable values for the (environment)
variables TERM and TERMCAP, respectively, and can be used as followed:
set noglob
set t=('tset -S ...... )
setenv lERM $t[ 1]
setenv lERMCAP "$t[2]"
unsett
unset noglob
Since the -s loads these values, its use is preferred.

-m [port-ID[baudrate]:type] ...
Specify ("map") a terminal type when connected to a generic port (such as dialup or plugboard)
identified by port-ID . The baudrate argument can be used to check the baudrate of the port and
set the terminal type accordingly. The target rate is prefixed by any combination of the following
operators to specify the conditions under which the mapping is made:
>

is greater than

@

equals or "at"

<

is less than
it is not the case that (negates the above operators)

?

prompt for the terminal type. If no response is given, then type is selected by default.

In the following example, the terminal type is set to adm3a if the port is a dialup with a speed of
greater than 300 or to dw2 if the port is a dialup at 300 baud or less. In the third case, the question
mark preceding the terminal type indicates that the user is to verify the type desired. A null

464

Last change: 17 February 1986

Sun Release 3.2

TSET( 1)

USER COMMANDS

TSET( 1)

response indicates that the named type is correct. Otherwise, the user's response is taken to be the
type desired.
tset-m 'dialup>3OO:adm3a' -m 'dialup:dw2' -m 'plugboard:?adm3a'
To prevent interpretation as metacharacters, the entire argument to -m should be enclosed in single quotes. When using the C-Shell, exclamation points should be preceded by a backslash (\).
EXAMPLES
These examples all use the - option. A typical use of tset in a .profile or .login will also use the -e and-k
options, and often the -0 or -Q options as well. These options have been omitted here to keep the examples short.

To select a 2621, you might put the following sequence of commands in your .login file (or .profile for
Bourne shell users).
setnoglob
eval 'tset -s 2621'
unset noglob

If you have an h19 at home which you dial up on, but your office terminal is hardwired and known in
letc/ttytype, you might use:
setnoglob
eval 'tset -s -m dialup:h19'
unset noglob
If you have a switch which connects to various ports (making it impractical to identify which port you may
be connected to), and use various terminals from time to time, you can select from among those terminals
according to the speed or baud rate. In the example below, tset will prompt you for a terminal type if the
baud rate is greater than 1200 (say, 9600 for a terminal connected by an RS-232 line), and use a Wyse 50
by default. If the baud rate is less than or equal to 1200, it will select a 2621. Note the placement of the
question mark, and the quotes to protect the '>' and '?' from interpretation by the shell.
setnoglob
eval 'tset-s -m 'switch>1200:?wy' -m 'switch<=1200:2621"
unset noglob
All of the above entries will fall back on the terminal type specified in letclttytype if none of the conditions
hold. The following entry is appropriate if you always dial up, always at the same baud rate, on many different kinds of terminals, and the terminal you use most often is an adm3a.
setnoglob
eva! 'tset -s ?adm3 a'
unset noglob

If the file letclttytype is not properly installed and you want to make the selection based only on the baud
rate, you might use the following:
setnoglob
eval'tset-s -m '>1200:wy' 2621'
unset noglob
Here is a fancy example to illustrate the power of tset and to hopelessly confuse anyone who has made it
this far. It quietly sets the erase character to BACKSPACE, and kill to CTRL-U. If the port is switched, it
selects a Concept 100 for speeds less than or equal to 1200, and asks for the terminal type otherwise (the
default in this case is a Wyse 50). If the port is a direct dialup, it selects Concept 100 as the terminal type.
If logging in over the ARPANET, the terminal type selected is a Datamedia 2500 terminal or emulator.
(Note the backslash escaping the newline at the end of the first line in the example.)
set noglob
eval 'tset -e -k"U -Q -s -m 'switch<=1200:conceptlOO' -m \
dialup:conceptl 00 -m arpanet:dm2500'
unset noglob

Sun Release 3.2

Last change: 17 February 1986

'switch:?wy' -m

465

TSET( 1)

USER COMMANDS

TSET(I)

FILES
I etclttytype
I etc/terrncap
lusrnib/tabsetl*

port name to terminal type mapping database
terminal capability database
tab setting sequences for various terminals. Pointed to by termcap
entries.

SEE ALSO
csh(I), sh(l), stty(1 V), ttytype(5), terrncap(5), environ(5V)

BUGS
The tset command is one of the first commands a user must master when getting started on a UNIX system.
Unfortunately, it is one of the most complex, largely because of the extra effort the user must go through to
get the environment of the login shell set Something needs to be done to make all this simpler, either the
login program should do this stuff, or a default shell alias should be made, or a way to set the environment
of the parent should exist.
It could well be argued that the shell should be responsible for ensuring that the terminal remains in a sane
state; this would eliminate the need for the reset program.

466

Last change: 17 February 1986

Sun Release 3.2

TSORT(l)

USER COMMANDS

TSORT(1 )

NAME

tsort - topological sort
SYNOPSIS

tsort [file]
DESCRIPTION
Tsort produces on the standard output a totally ordered list of items consistent with a partial ordering of
items mentioned in the input file . If no file is specified, the standard input is understood.

The input consists of pairs of items (nonempty strings) separated by blanks. Pairs of different items indicate ordering. Pairs of identical items indicate presence, but not ordering.
SEE ALSO
lorder(l)
BUGS

Uses a quadratic algorithm; not worth fixing for the typical use of ordering a library archive file.

Sun Release 3.2

Last change: 8 August 1983

467

TTY(I)

USER COMMANDS

TTY(I)

NAME

tty - get terminal name
SYNOPSIS
tty [ -s]
DESCRIPTION
Tty prints the pathname of the user's terminal unless the -s (silent) option is given. In either case, the exit

value is zero if the standard input is a terminal, and one if it is not.

468

Last change: 26 April 1983

Sun Release 3.2

UL(l)

USER COMMANDS

UL(l)

NAME

ul- do underlining
SYNOPSIS

ul [ -i] [ -t terminal] [file ... ]
DESCRIPTION
VI 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 use, as specified by the environment variable
TERM. ul uses the letc!termcap file to determine the appropriate sequences for underlining. If the terminal is incapable of underlining, but is capable of a standout mode then that is used instead. If the terminal
can overstrike, or handles underlining automatically, ul degenerates to cat(l V). If the terminal cannot
underline, underlining is ignored.
OPTIONS
-t

-i

Override the terminal kind specified in the environment If the terminal cannot underline, underlining is ignored.
Indicate underlining onto by a separate line containing appropriate dashes '-'; this is useful when
you want to look at the underlining which is present in an nroff output stream on a crt-terminal.

SEE ALSO
man(1), nroff(1), colcrt(1)
BUGS

Nroffusually generates a series of backspaces and underlines intermixed with the text to indicate underlining. UI makes attempt to optimize the backward motion.

Sun Release 3.2

Last change: 13 April 1983

469

UNAME( IV)

USER COMMANDS

UNAME(IV)

NAME

uname - print name of current UNIX system
SYNOPSIS

uname [ -snrvma ]
DESCRIPTION

Note:

Optional Software (System V Option). Refer tolnstalling UNIX on the Sun Workstation for
information on how to install this command. Uname prints the current system name of the UNIX
system on the standard output It is mainly useful to determine which system one is using.

OPTIONS

The options cause selected information returned by uname (2V) to be printed:

-s

print the system name (default).

-n

print the nodename (the nodename may be a name that the system is known by to a communications network).

-r

print the operating system release.

-v

print the operating system version.

-m

print the machine hardware name.

-a

print all the above information.

SEE ALSO

uname(2V)

470

Last change: 18 July 1986

Sun Release 3.2

UNGET(1)

USER COMMANDS

UNGET(1)

NAME

unget - undo a previous get of an sees file
SYNOPSIS

lusrlsccs/uoget [ -r SID] [ -s ] [ -0] file •••
DESCRIPTION

Unget undoes the effect of a get -e done prior to creating the intended new delta. If a directory is named,
unget behaves as though each file in the directory were specified as a named file, except that non-sees
files and unreadable files are silently ignored. If a name of - is given, the standard input is read with each
line being taken as the name of an sees file to be processed.
OPTIONS

Options apply independently to each named file.
-r SID

Uniquely identifies which delta is no longer intended. (This would have been specified by get as
the "new delta"). The -r option is necessary only if two or more outstanding gets for editing on
the same sces file were done by the same person (login name). A diagnostic results if the
specified SID is ambiguous, or if it is necessary but omitted from the command line.

-s

Suppress displaying the intended delta's SID.

-0

Retain the gotten file -

it is normally removed from the current directory.

SEE ALSO

sccs(l), delta(l), get(1), sact(1).

Programming Utilities/or the Sun Workstation.
DIAGNOSTICS

Use help(l) for explanations.

Sun Release 3.2

Last change: 6 March 1984

471

UNIFDEF( 1)

USER COMMANDS

UNIFDEF(1 )

NAME

unifdef - resolve and remove ifdef ed lines
SYNOPSIS

unifdef [ -t] [ -I] [ -c ] [ -Dname ] [ -Uname ] [ -idname ] [ -iuname ] ... [filename ]
DESCRIPTION

unifdef removes ifdef ed lines from a file while otherwise leaving the file alone. It is smart enough to deal
with the nested ifdefs, comments, single and double quotes of C syntax, but it doesn't do any including or
interpretation of macros. Neither does it strip out comments, though it recognizes and ignores them. You
specify which symbols you want defined with -D options, and which you want undefined with -U options.
Lines within those ifdefs will be copied to the output, or removed, as appropriate. Any ifdef, ifndef, else,
and endif lines associated with name will also be removed.
Ifdefs involving symbols you don't specify are untouched and copied out along with their associated ifdef,
else, and endif lines.
If an ifdef X occurs nested inside another ifdef X, then the inside ifdef is treated as if it were an unrecognized symbol. If the same symbol appears in more than one argumen4 only the first occurrence is
significant.

unifdef copies its output to the standard output and will take its input from the standard input if no filename
argument is given.
OPTIONS
-t
-I

Plain text option. uniJdeJrefrains from attempting to recognize comments and single and double
quotes.
Replace lines removed lines with blank lines.

-idname
Ignore, but print OU4 lines associated with the defined symbol name. If you use ifdefs to delimit
non-C lines, such as comments or code which is under construction, then you must tell unifdef
which symbols are used for that purpose so that it won't try to parse for quotes and comments
within them.

-iuname
Ignore, but print OU4 lines associated with the undefined symbol name.

-c

Complement the normal operation. Lines that would have been removed or blanked are retained,
and vice versa.

SEE ALSO
diff(l)
DIAGNOSTICS
Premature EOF, inappropriate else or endif.

Exit status is 0 if output is exact copy of inPU4 1 if n04 2 if trouble.
BUGS

Does not know how to deal with cpp constructs such as

#if

472

defined(X) II defined(Y)

Last change: 11 April 1986

Sun Release 3.2

UNIQ( 1)

USER COMMANDS

UNIQ( 1)

NAME

uniq - report repeated lines in a file
SYNOPSIS

uniq [ -ude [ +n ] [ -n ] ] [input [ output] ]
DESCRIPTION
Uniq reads the input file comparing adjacent lines. In the normal case, the second and succeeding copies of
repeated lines are removed; the remainder is written on the output file. Note that repeated lines must be
adjacent in order to be found; see sort(lV).
OPTIONS
-u

-d

Copy only those lines which are not repeated in the original file.
Write one copy of just the repeated lines.

The normal output of uniq is the union of the -u and -d options

-c

supersedes -u and -d and generates an output report in default style but with each line preceded
by a count of the number of times it occurred.

The n arguments specify skipping an initial portion of each line in the comparison:

-n

The first n fields together with any blanks before each are ignored. A field is defined as a string
of non-space, non-tab characters separated by tabs and spaces from its neighbors.

+n

The first n characters are ignored. Fields are skipped before characters.

SEE ALSO
sort(l), comm(l)

Sun Release 3.2

Last change: 30 April 1983

473

UNITS(l)

USER COMMANDS

UNITS(l)

NAME

units - conversion program
SYNOPSIS
units
DESCRIPTION
units converts quantities expressed in various standard scales to their equivalents in other scales. It works
interactively in this fashion:

You have:-inch
You want--cm
* 2.540000e-tOO
I 3.937008e-01
A quantity is specified as a multiplicative combination of units optionally preceded by a numeric multiplier.
Powers are indicated by suffixed positive integers, division by the usual sign:
You have:-15 Ibs forcelin2
You want--atm
* 1.02068ge+OO
19.79729ge-01

units only does multiplicative scale changes. Thus it can convert Kelvin to Rankine, but not Celsius to
Fahrenheit Most familiar units, abbreviations, and metric prefixes are recognized, together with a generous leavening of exotica and a few constants of nature including:
pi
ratio of circumference to diameter,
c
speed of light,
e
charge on an electron,
g
acceleration of gravity,
force
same as g,
mole
Avogadro's number,
water pressure head per unit height of water,
au
astronomical unit
pound is not recognized as a unit of mass; Ib is. pound refers to a British pound. Compound names are
run together (e.g., lightyear). British units that differ from their u.s. counterparts are prefixed thus: brgalIon. Currency is denoted belgiumrranc, britainpound, For a complete list of units, type:
cat lusr/lib/units
FILES

lusrllib/units

BUGS
Don't base your financial plans on the currency conversions.

474

Last change: 17 February 1986

Sun Release 3.2

UPTIME(I)

USER COMMANDS

UPTIME(I)

NAME

uptime - show how long system has been up
SYNOPSIS
uptime
DESCRIPTION
Uptime prints the current time, the length of time the system has been up, and the average number of jobs
in the run queue over the last 1,5 and 15 minutes. It is, essentially, the first line of a w(l) command.
EXAMPLE

angel% uptime
6:47am up 6 days, 16:38, 1 users, load average: 0.69,0.28,0.17
angel%
FILES

/vrnunix system name list
SEE ALSO
w(l)

Sun Release 3.2

Last change: 2 June 1983

475

USERS ( 1)

USER COMMANDS

USERS(I)

NAME

users - compact list of users who are on the system
SYNOPSIS

users
DESCRIPTION
users lists the login names of the users currently on the system in a compact, one-line format:

tutorial% users
paul george ringo
tutorial%
FILES

letclutmp
SEE ALSO
who(1)

476

Last change: 23 September 1985

Sun Release 3.2

UUCP( IC)

USER COMMANDS

UUCP(IC)

NAME

uucp, uulog, uuname - unix to unix copy
SYNOPSIS

uucp [ -acCdfmr ] [ -esystem] [ -ouser ] [ -ggrade ] [ -sspool ] [ -xdebug ] source yle ...
destination yle
uulog [ -ssys] [ -uuser]
uuoame [ -I ] [ -v ]
DESCRIPTION
uucp copies each source-file to the named destination-file. A filename may be a path name on your
machine, or may have the form

system-name!pathname
where system-name is taken from a list of system names that uucp knows about Shell metacharacters
? * [ ] appearing in the pathname part will be expanded on the appropriate system.
Pathnames may be one of
(I)

a full pathname;

(2)

a pathname preceded by -userl; where user is a usemame on the specified system and is replaced
by that user's login directory;

(3)

a pathname preceded by -I; such a pathname will be replaced by the "public uucp" directory on
the remote machine;

(4)

anything else is prefixed by the pathname of the current directory.

If the result is an erroneous pathname for the remote system, the copy will fail. If the destination-file is a
directory, the last component of the source-file name is used.

uucp preserves execute permissions across the transmission and gives 0666 read and write permissions (see
chmod(2».
uulog maintains a summary log of uucp and uux transactions in the file lusrlspool/uucpILOGFILE, by gathering information from partial log files named lusrlspoolluucpILOG.*.? It removes the partial log files.
uuname lists the uucp names of systems that can be accessed using uucp.
OPTIONS
UUCP Options
-a
Avoid doing a getwd to find the current directory. This is sometimes used for efficiency.

-c

Use the source file when copying out rather than copying the file to the spool directory. This is
the default

-C

Make a copy of outgoing files in the uucp spool directory, rather than copying the source file
directly to the target system. This lets you remove the source file after issuing the uucp command.

-d

Make all necessary directories for the file copy.

-f

Do not make intermediate directories for the file copy.

-m

Send mail to the requester when the copy is complete.

-r

Do not start the transfer, just queue the job.

-ouser Notify user on remote system (Le., send user mail) that a file was sent
-esystem
Send the uucp command to the system system to be executed there. This works only when the
remote machine allows uucp to be executed by lusrllibluucpluuxqt.
-ggrade
grade is a single letter or number; lower ASCII values will cause a job to be transmitted earlier

Sun Release 3.2

Last change: 9 July 1986

477

UUCP( lC)

USER COMMANDS

UUCP(IC)

during a particular conversation. The default grade is 'n'. By way of comparison, uux(IC)
defaults to 'A'; mail is usually sent at grade 'C'.

-sspool Use spool as the spool directory instead of the default.
-xdebug
Turn on the debugging at level debug.
UULOG Options
-ssys Print information about wolk involving system sys.

-uuser Print information about wolk done for the specified user.
UUNAME options
-I
Display the local system-name.
-v

Verbose. Display a description of each known system.

FILES

lusrlspoolluucp
spool directory
lusrllibluucplADMIN list of known systems and descriptions
lusrllibluucpl*
other data and program files
SEE ALSO

uux(IC), mail(l)
An Overview of Uucp in System Adminsitration for the Sun Workstation.
WARNING
The domain of remotely accessible files can (and for obvious security reasons, usually should) be severely
restricted. You will very likely not be able to fetch files by pathname; ask a responsible person on the
remote system to send them to you. For the same reasons you will probably not be able to send files to
arbitrary pathnames.
BUGS
All files received by uucp will be owned by the userid uucp.
The -m option will only work sending files or receiving a single file. Receiving multiple files specified by
special shell characters ? * [] will not activate the -m option.

478

Last change: 9 July 1986

Sun Release 3.2

UUENCODE ( lC)

USER COMMANDS

UUENCODE ( lC)

NAME

uuencode, uudecode - encode/decode a binary file for transmission using mail
SYNOPSIS

uuencode [source-file] destination-file / mail host![host! ... ]decode
uudecode [ source-file ]
DESCRIPTION

uuencode and uudecode are used to send a binary file using uucp(lC) (or other) mail. This combination of
commands can be used over indirect mail links even when uusend (1 C) is not available.
uuencode takes the named source-file (or standard input if no source-file is given) and produces an encoded
version on the standard output-displaying only ASCII characters. The permission modes of source-file
and the destination-file are included so that the file can be recreated with the same ownership and permissions on the remote system.
uudecode reads an encoded file, strips off any leading and trailing lines added by mailers, and recreates the
original file with the specified mode and owner.

The intent is that all mail to the user decode should be filtered through the uudecode program. This way
the file is created automatically without human intervention. This requires that the mail system on the
receiving host must support mail aliases that cause mail to particular users to be filtered through a program.
UNIX systems with sendmail support this; on Sun systems, the file lusr/lib/aliases has such an alias for the
user decode.
If these facilities are not available, the file can be sent to a user on the remote machine who can uudecode it
manually.

The encoded file has an ordinary text form and can be edited by any text editor to change the mode or
remote name.
SEE ALSO

uusend(IC), uucp(IC), uux(IC), mail(I), uuencode(5)

BUGS
The file is expanded by 35% (3 bytes become 4 plus control information) causing it to take longer to
transmit.
The user on the remote system who is invoking uudecode (often uucp) must have write permission on the
specified file.

Sun Release 3.2

Last change: 21 July 1986

479

UUSEND(lC)

USER COMMANDS

UUSEND(IC)

NAME

uusend - send a file to a remote host
SYNOPSIS
uusend [-m mode] sourcefile sysl!sys2! .. !remotefile
DESCRIPTION
uusend sends a file to a given location on a remote system. The system need not be directly connected to
the local system, but a chain of uucp links needs to connect the two systems.

The sourcefile can be "-" , meaning to use the standard input Both of these options are primarily intended
for internal use of uusend.
The remotefile can include the -username or -, syntax.
OPTIONS
-mmode
Take the mode of the file on the remote end from the octal number specified as mode. The mode
of the input file is used if the -m option is not specified.
DIAGNOSTICS
If anything goes wrong any further away than the first system down the line, you will never hear about it.
SEE ALSO
uux(IC), uucp(IC), uuencode(IC)
BUGS

This command shouldn't exist, since uucp should handle it.
All systems along the line must have the uusend command available and allow remote execution of it
Some UUCP systems have a bug where binary files cannot be the input to a uux command. If this bug
exists in any system along the line, the file will show up severely munged.

480

Last change: 23 September 1985

Sun Release 3.2

UUX( IC)

USER COMMANDS

UUX(IC)

NAME
uux - unix to unix command execution
SYNOPSIS
DUX [ - ] [

-gx ] [ -0] [ -r] [ -xn] [ -z ] command-string

DESCRIPTION
uux will gather 0 or more files from various systems, execute a command on a specified system and send
standard output to a file on a specified system.
The command-string is made up of one or more arguments that look like a shell command line, except that
the command and file names may be prefixed by system-nameL A null system-name is interpreted as the
local system.
File names may be one of
(I) a full pathname;
(2) a patbname preceded by -xxxI; where xxx is a username on the specified system and is replaced
by that user's login directory;
(3) a patbname preceded by -I; such a pathname is replaced by the "public uucp" directory on the
remote machine.
(4) anything else is prefixed by the current directory.
The '-' option will cause the standard input to the uux command to be the standard input to the commandstring.
For example, the command
uux "!diff usg!/usr/dan/fl pwba!/a4/dan1fl > !fi.diff'
will get the fl files from the usg and pwba machines, execute a diffcommand and put the results in fl.diff
in the local directory.
Any special shell characters such as <>;1 should be quoted either by quoting the entire command-string, or
quoting the special characters as individual arguments.
OPTIONS

-gx

set service grade or classification to x. The default is A.

-0

don't return any indication by mail of success or failure of the job.

-r

don't start uucico , just queue the job.

-xn

set debugging level to n. (5, 7, and 9 are good numbers to try; they give increasing amounts of
detail.)

-z

return an indication by mail only if the job fails.

FILES
lusrlspool/uucp
lusrllib/uucp/*

spool directory
other data and programs

SEE ALSO
uucp(IC), mail(l), sendmail(8)

Uucp Implementation Description in System Administration for the Sun Workstation
WARNING
An installation may, and for security reasons generally will, limit the list of commands executable on
behalf of an incoming request from uux. Typically, a restricted site will permit little other than the receipt
of mail via uux.

Sun Release 3.2

Last change: 23 September 1985

481

UUX( lC)

USER COMMANDS

UUX(lC)

BUGS

Only the first command of a shell pipeline may have a system-name!. All other commands are executed on
the system of the first command.
The use of the shell metacharacter * will probably not do what you want it to do.
The shell tokens « and » are not implemented
There is no notification of denial of execution on the remote machine.

482

Last change: 23 September 1985

Sun Release 3.2

VACATION ( 1)

USER COMMANDS

VACATION ( 1 )

NAME

vacation - reply to mail automatically
SYNOPSIS
vacation -I l-tN
vacation user
DESCRIPTION

vacation automatically replies to incoming mail. The reply is contained in the file .vacation.msg, that you
create in your home directory (or the file lusrlliblvacation.defby default).
This file should include a header with at least a "Subject" line. For example:
From: John Smith 
Subject: I am on vacation
Delivered-automatically-by: the Vacation Program
I am on vacation until July 22. If you have something urgent,
please contact Joe Jones (jones@sun).
--john
USAGE

To start vacation, create a forward file in your home directory containing a line of the form:

\ name , "I vacation name"
where name is your login name.
Then type in the command
vacation -I
To stop vacation, remove the forward file, or move it to a new name.
OPTIONS
-I

initialize the .vacation.pag and. vacation.dir files and start vacation.
If the -I flag is not specified, vacation reads the first line from the standard input (for a "From"
line, no colon). If absent, it produces an error message.

-tN

Change the interval between repeat replies to the same sender. The default is 1 week. A trailing
's', 'm', 'h', 'd', or ow' scales N to seconds, minutes, hours, days, or weeks respectively.
A list of senders is kept in the files .vacation.pag and .vacation.dir in your home directory.

SEE ALSO
send.mail(8)

Sun Release 3.2

Last change: 30 September 1985

483

VAL ( 1)

USER eOMMANDS

VAL(l)

NAME

val- validate sees file
SYNOPSIS

/usr /sees/val /usr/sees/val [ -s ] [ -r SID] [ -m name] [ -y type] file •••
DESCRIPTION
Val determines if the specified file s are SCCS files meeting the characteristics specified by the optional
argument list Arguments to val may appear in any order. Val can process up to 50 files on a single com-

mandline.
Val has a special argument, -, which causes reading of the standard input until an end-of-file condition is
detected. Each line read is independently processed as if it were a command line argument list
Val generates diagnostic messages on the standard output for each command line and file processed and
also returns a single 8-bit code upon exit as described below.
OPTIONS

Options apply independently to each named file on the command line.

-s

Silence diagnostic messages normally generated for errors detected while processing the specified
files.

-r SID

The argument value SID (SeeS IDentification String) is an sees delta number. A check is made
to determine if the SID is ambiguous (for instance, rl is ambiguous because it physically does not
exist but implies 1.1, 1.2, etc. which may exist) or invalid (for instance, rI.O or r1.1.0 are invalid
because neither case can exist as a valid delta number). If the SID is valid and not ambiguous, a
check is made to determine if it actually exists.

-mname
name is compared with the sees %M% keyword in file .

-y type type is compared with the sees %Y% keyword infile .
The 8-bit code returned by val is a disjunction of the possible errors, that is, can be interpreted as a bit
string where (moving from left to right) set bits are interpreted as follows:
bit 0 =
bit 1 =
bit 2 =
bit 3 =
bit 4 =
bit 5 =
bit 6 =
bit 7 =

missing file argument;
unknown or duplicate option;
corrupted sees file;
can't open file or file not sees;
SID is invalid or ambiguous;
SID does not exist;
%Y%, -y mismatch;
%M%, -m mismatch;

Note that val can process two or more files on a given command line and in tum can process multiple command lines (when reading the standard input). In these cases an aggregate code is returned -logical OR
of the codes generated for each command line and file processed.
SEE ALSO

sccs(1), admin(1), delta(1), get(1), prs(1).

Programming Utilities/or the Sun Workstation.
DIAGNOSTICS
Use help(1) for explanations.

484

Last change: 6 March 1984

Sun Release 3.2

VFONTINFO ( 1 )

USER COMMANDS

VFONTINFO ( 1 )

NAME
vfontinfo - inspect and print out information about UNIX fonts
SYNOPSIS
Yfontinfo [ -Y ] fontna1lU! [ characters]
DESCRIPTION

vfontinfo allows you to examine a font in the UNIX format. It prints out all the information in the font
header and information about every non-null (width> 0) glyph. This can be used to make sure the font is
consistent with the format.
The fontna1lU! argument is the name of the font you wish to inspect. It writes to standard output. If it can't
find the file in your working directory, it looks in lusrlliblvfont (the place most of the fonts are kept).
The characters, if given, specify certain characters to show. If omitted, the entire font is shown.

If the -Y (verbose) :O.ag is used, the bits of the glyph itself are shown as an array of X's and spaces, in addition to the header information.
SEE ALSO
vpr(l), vfont(5), vswap(l), vwidth(l)

Sun Release 3.2

Last change: 23 September 1985

485

VGRIND( 1)

USER COMMANDS

VGRIND(I)

NAME

vgrind - grind nice program listings
SYNOPSIS

vgrind [ -f] [ - ] [ -t] [ -8] [ -X] [ -w] [-w] [ -sn] [-b header] [ -d defs-file] [ -nanguage] file ...
DESCRIPTION

Vgrindformats the program sources named by thefile arguments in a nice style using troJf(I). Comments
are placed in italics, keywords in bold face, and as each function is encountered its name is listed on the

page margin.
V grind runs in two basic modes, filter mode or regular mode. In filter mode vgrind acts as a filter in a
manner similar to tbl(I). The standard input is passed directly to the standard output except for lines
bracketed by the troff-like macros:

.vS

- starts processing

.vE

- ends processing

These lines are formatted as described above. The output from this filter can be passed to trolf for output.
There need be no particular ordering with eqn(l) or tbl.
In regular mode vgrind accepts inputfiles, processes them, and passes them to troJffor output
In both modes vgrind passes any lines beginning with a decimal point without conversion.
OPTIONS

Note that arguments to the -I and -s options follow the option names immediately, with no intervening
space. All other arguments and options must be separated with white space.
-f

Force filter mode.
Take from standard input (default if -f is specified).

-t

Similar to the same option in troff; that is, formatted text goes to the standard output.

-8

Do not make keywords boldface.

-x

Output the index file in a 'pretty' format The index file itself is produced whenever vgrind is run
with a file called index present in the current directory. The index of function definitions can then
be run off by giving vgrind the -x option and the file index as argument

-W

Force output to the (wide) Versatec printer rather than the (narrow) Varian.

-w

Consider tabs to be spaced four columns apart instead of the usual eight.

-s

Specifies a point size to use on output (exactly the same as the argument of a troff' _ps' point size
request).

-b

Specifies a particular header to put on every output page (default is the current file name).

-d

Specifies an alternate language definitions file (default is lusrlliblvgrindefs).

-I

Specifies the language to use. Among the languages currently known are: Bourne shell (-Ish), C
(-Ie, the default), C-shell (-Icsb), emacs MLisp, (-Iml), FORTRAN (-If), Icon (-ll), ISP (-i), LDL
(-ILDL), Model (-1m), Pascal (-Ip), and RATFOR (-lr).

ENVIRONMENT

In regular mode vgrind feeds its intermediate output to the text formatter given by the value of the TROFF
environment variable, or to 'trofr if this variable is not defined in the environment This mechanism
allows for local variations in troif's name.
FILES

index
lusrllib/vgrindefs
lusrllib/vfontedpr
lusrllib/ttnac/tmac. vgrind

486

file where source for index is created
language descriptions
preprocessor
macro package

Last change: 11 July 1986

Sun Release 3.2

VGRIND(I)

USER COMMANDS

VGRIND(I)

SEE ALSO

troff(l), vgrindefs(5)
BUGS

V grind assumes that a certain programming style is followed:

c

Function names can be preceded on a line only by spaces, tabs, or an asterisk. The
parenthesized arguments must also be on the same line.

FORTRAN

Function names need to appear on the same line as the keywords function or subroutine .

MLisp

Function names should not appear on the same line as the preceding defun.

Model

Function names need to appear on the same line as the keywords is beginproc .

Pascal

Function names need to appear on the same line as the keywords function or procedure.

If these conventions are not followed, the indexing and marginal function name comment mechanisms will
fail.
More generally, arbitrary formatting styles for programs mostly look bad. The use of spaces to align
source code fails miserably; if you plan to vgrind your program you should use tabs. This is somewhat
inevitable since the fonts vgrind uses are variable width.
The mechanism of ctags(l) in recognizing functions should be used here.
The -w option is a crock, but there's no other way to achieve the desired effect.
The macros defined in tmac.vgrind do not coexist gracefully with those of other macro packages, making
filter mode difficult to use effectively.

Sun Release 3.2

Last change: II July 1986

487

VI(l)

VI(l)

USER COMMANDS

NAME

vi - screen oriented (visual) display editor based on ex
SYNOPSIS
vi [ -R] [ -r] [ -t tag] [ +command] [ -x] [ -wnnn] [ -I] file ...
DESCRIPTION
Vi (visual) is a display oriented text editor based on ex. ex and vi are in fact the same text editor; it is possible to get to the command mode of ex from within vi and vice-versa.
OPTIONS
-R

edit the file in read-only state. You can achieve the same effect with the view command.

-r

recover the indicated file s after a crash.

-t tag

edit the file containing the tag tag. A tags database must have been built previously using the
ctags(1) command

+ command
start the editing session by executing command.

-wnnn set the default window (number of lines on your terminal) to nnn- this is useful if you are dialling into the system over a slow 'phone line.

-x

prompt for a key to be used in encrypting the file being edited.

-I

set up for editing LISP programs.

FILES

See ex(l).
SEE ALSO
ex(l)

Getting Started With UNIX: Beginner's Guide
Editing Text Files on the Sun Workstation
BUGS

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.
Repeating a change which wraps over the margin when wrapmargin is in effect doesn't generally work
well: sometimes it just makes a mess of the change, and sometimes even leaves you in insert mode. A way
to work around the problem is to replicate the changes using yank and put.
Insert/delete within a line can be slow if tabs are present on intelligent terminals, since the terminals need
help in doing this correctly.
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 ex command mode, execute them, and then reenter the screen editor with vi or open.
When using the -r option to recover a file, you must write the recovered text before quitting or you will
lose it. Vi does not prevent you from exiting without writing unless you make changes.
RESTRICTIONS

488

Last change: 1 February 1985

Sun Release 3.2

USER COMMANDS

VI( 1)

VI( 1)

The encryption facilities of vi are not available on software shipped outside the U.S.

Sun Release 3.2

Last change: 1 February 1985

489

VIEW(I)

USER COMMANDS

VIEW ( 1)

NAME

view - view a file without changing it using the vi visual editor
SYNOPSIS

view [ -t tag] [ -r ] [ +command] [ -I] [ -wn ] name ...
DESCRIPTION
View uses the vi (visual) or display oriented text editor to browse through a file interactively without actually making any changes to the file. It is possible to get to the command mode of ex from within view and
vice-versa, just as when using vi.
SEE ALSO
ex(l), vi(l)

Editing Text Files on the Sun Workstation

490

Last change: 5 December 1985

Sun Release 3.2

VPLOT( 1)

USER COMMANDS

VPLOT( 1)

NAME

vplot - plot graphics on the Versatec
SYNOPSIS

vpJot [ -W] [ -V] [ -b lpr-arg] file
DESCRIPTION

Note:

Optional Software (Versatec Printer Option). Refer to Installing UNIX on the Sun Workstation for
information on how to install this command.

vplot reads plot(S) format graphics input from the file specified by file (standard input if no file is specified)
and produces a plot on the Varian or Versatec.
OPTIONS

-W

force output to the (wide) Versatec printer rather than the standard Versatec printer.

-V

force output to the standard Versatec printer.

-b lpr-arg
arg (the next argument on the command line) specifies extra arguments to Ipr(1).
SEE ALSO

plot(lG), lpr(l), plot(S)

Sun Release 3.2

Last change: 17 April 1986

491

VPR( 1)

USER COMMANDS

VPR( 1)

NAME

vpr, vprm, vpq, vprint - raster printer/plotter spooler
SYNOPSIS
vpr [-W] [-I] [-v] [-t [ -1234 font]] [-w] [-wwidth] [-m] [name ... ]
vprm [ id ... ] [filename... ] [owner ... ]
vpq
vprint [ - W ] file ...
DESCRIPTION
Note:

Optional Software (Versatec Printer Option). Refer to Installing UNIX on the Sun Workstation for
information on how to install this command.

vpr causes the named files to be queued for printing or typeset simulation on one of the available raster
printer/plotters. If no files are named, the standard input is read. By default the input is assumed to be line
printer-like text. For very wide plotters, the input is run through the filter lusrlliblsidebyside giving it an
argument of -wl06 which arranges it four pages adjacent with 90 column lines (the rest is for the left margin). Since there are 8 lines per inch in the default printer font, vpr thus produces 86 lines per page (the top
and bottom lines are left blank).
The following options are available:
-I

Print the input in a more literal manner. Page breaks are not inserted, and most control
characters (except format effectors: \n, \f, etc.) are printed (many control characters
print special graphics not in the ASCII character set) Tab and underline processing is
still done. If this option is not given, control characters which are not format effectors
are ignored, and page breaks are inserted after an appropriate number of lines have been
printed on a page.

-W

Queues files for printing on a wide output device, if available. Normally, files are
queued for printing on a narrow output device.

-1234

Specifies a font to be mounted on font position i. The daemon will construct a .railmag
file referencing lusrlliblvfontlname .size.

-m
-w

Report by mail (1) when printing is complete.

-wwidth

Use width width rather than 90 for sidebyside.

-v

Use the filter lusrlliblvrast to convert the vectors to raster. The named files must be a
parameter and vector file (in that order) created by plot(3X) routines.

-t

Use the filter lusrlliblvcat to typeset the input on the printer/plotter. The input must have
been generated by troff(l) run with the -t option. This is not normally run directly to
wide output devices, since it is wasteful to run only one page across. The program
vtroff( 1) is normally used and arranges, using vsort for printing to occur four pages
across, conserving paper.

(Applicable only to wide output devices.) Do not run the input through sidebyside.
Such processing has been done already, or full (440 character) printer width is desired.

Vprm removes entries from the raster device queues. The id, filename or owner should be that reported by
vpq. All appropriate files will be removed. Both queues are always searched. The id of each file removed
from the queue will be printed.
Vpq prints the queues. Each entry in the queue is printed showing the owner of the queue entry, an
identification number, the size of the entry in characters, and the file which is to be printed. The id is useful
for removing a specific entry from the printer queue using vprm
Vprint is a shell script which pr' s a copy of each named file on one of the electrostatic printer/plotters. The
files are normally printed on a narrow device; - W option causes them to be printed on a wide device.

492

Last change: 17 April 1986

Sun Release 3.2

VPR( 1)

USER COMMANDS

VPR( 1)

FILES

/usr/spool!v?dI*
/usrllib/v?d
/usrllib/vpd
/usrllib/vpf
/usrllib/*vcat
/usrllib/vrast
/usrllib/sidebyside

device spool areas
daemons
Versatec daemon
filter for printer simulation
filter for typeset simulation
filter for plot
filter for wide output

SEE ALSO
troff(I), vfont(5), vp(4), pti(I), vtroff(l), plot(3X)

BUGS
The 1's (one's) and l's (lower-case el's) in a Benson-Varian's standard character set look very similar; caution is advised
A versatec's hardware character set is rather ugly. Vprint should use one of the constant width fonts to
produce prettier listings.

Sun Release 3.2

Last change: 17 Apri11986

493

VSWAP(1 )

USER COMMANDS

VSWAP(I)

NAME

vswap - convert a foreign font file
SYNOPSIS

lusrllib/vswap [ -r ]
DESCRIPTION
Note:

Optional Software (Versatec Printer Option). Refer to Installing UNIX on the Sun Workstation for
information on how to install this command.

Without the -r option, vswap translates its standard input (which must be a vfont file in the reversed-byte
order) into a locally correct vfont file on its standard output. With the -r option, vswap translates its standard input (which must be a vfont file in the local-byte order) into a byte-reversed vfont file on its standard
output.
The UNIX vfont representation for fonts is a binary file containing machine-dependent elements - short
(16-bit) integers, in particular. There are (at least) two common ways of representing a 16-bit integer. A
program compiled on a V AX will expect the VAX format, while the same program compiled on a
Motorola 68000 will expect 68000 format. V swap can be used to convert font files created on a V AX to
the format required to use them on the Sun. It can also convert Sun-format font files to VAX format (with
the -r option). Since the font files are in the byte order of the local machine, programs which access the
font files don't need to be concerned with byte-swapping issues. This could be considered a bug.
SEE ALSO
troff(I), vfont(5)

BUGS
A machine-independent font format should be defined.

494

Last change: 17 April 1986

Sun Release 3.2

VTROFF(I)

USER COMMANDS

VTROFF(I)

NAME

vtroff - troff to a raster plotter
SYNOPSIS

vtrotT [ -w] [ -F majorfont] [ -123 minorfont] [ -llength ] [ -x ] troff arguments
DESCRIPTION

Note:

Optional Software (Versatec Printer Option). Refer to Installing UNIX on the Sun Workstation for
information on how to install this command.

vtroffruns troff(l) sending its output through various programs to produce typeset output on a raster plotter
such as a Benson-Varian or or a Versatec. The -W option specifies that a wide output device be used; the
default is to use a narrow device. The -I (lower case 1) option causes the output to be split onto successive
pages every length inches rather than the default 11".
The default font is a Hershey font. If some other font is desired you can give a -F argument and then the
font name. This will place normal, italic and bold versions of the font on positions 1,2, and 3. To place a
font only on a single position, you can give an argument of the form -n and the minor font name. A.r will
be added to the minor font name if needed. Thus' 'vtroff -ms paper" will set a paper in the Hershey font,
while "vtroff -F nonie -ms paper" will set the paper in the (sans serit) nonie font. The -x option asks for
exact simulation of photo-typesetter output. (I.e. using the width tables for the C.A.T. photo-typesetter)
FILES

lusrllib/tmac/tmac. vcat
lusrllib/fontinfo/*
lusrllib/vfont

default font mounts and bug fixes
fixes for other fonts
directory containing fonts

SEE ALSO

troff(I), vfont(5), vpr(l)
BUGS

Since some macro packages work correctly only if the fonts named R, I, B, and S are mounted, and since
the Versatec fonts have different widths for individual characters than the fonts found on the typesetter, the
following dodge was necessary: If you don't use the ".fp" troff directive then you get the widths of the
standard typesetter fonts suitable for shipping the output of troff over the network to the computer center A
machine for phototypesetting. If, however, you remount the R, I, B and S fonts, then you get the width
tables for the Versatec.

Sun Release 3.2

Last change: 17 April 1986

495

USER COMMANDS

VWIDTH(I)

VWIDTH(I)

NAME

vwidth - make a troff width table for a font
SYNOPSIS
lusrlIib/vwidthfonljile pointsize > ftxx.c

cc -c ftxx.c
mv ftxx.o lusr/lib/fontlfb:x
DESCRIPTION
Note:

Optional Software (Versatec Printer Option). Refer to Installing UNIX on the Sun Workstation for
information on how to install this command.

vwidth translates from the width information stored in the vfont style format to the format expected by
troff(l) - an object file in a.out(5) format. trolf should look directly in the font file but it doesn't.
vwidth should be used after editing a font withfontedit(l). It is not necessary to use vwidth unless you have
made a change that would affect the width tables. Such changes include numerically editing the width
field, adding a new character, and moving or copying a character to a new position. It is not always necessary to use vwidth if the physical width of the glyph (e.g. the number of columns in the bit matrix) has
changed, but if it has changed much the logical width should probably be changed and vwidth run.
vwidth produces a C program on its standard output. This program should be run through the C compiler
and the object (that is, the .0 file) saved. The resulting file should be placed in IUSTllibl/ont in the file ftxx
where is a one or two letter code that is the logical (internal to trolf) font name. This name can be found by
looking in the file /usrllib/fontinfo(fname * where fname is the external name of the font.
SEE ALSO
fontedit(l), vfont(5), troff(I), vtroff(l)

496

Last change: 17 April 1986

Sun Release 3.2

W( 1)

USER COMMANDS

W(I)

NAME

w - who is on, and what are they doing
SYNOPSIS

w [ -h] [ -s ] [ user]
DESCRIPTION

W displays a summary of the current activity on the system, including what each user is doing. The heading line shows the current time of day, how long the system has been up, the number of users logged into
the system, and the load averages. The load average numbers give the number of jobs in the run queue
averaged over 1, 5 and 15 minutes.
The fields displayed are: the users login name, the name of the tty the user is on, the time of day the user
logged on (in hours:minutes), the idle time - that is, the number of minutes since the user last typed anything (in hours:minutes), the CPU time used by all processes and their children on that terminal (in
minutes:seconds), the CPU time used by the currently active processes (in minutes:seconds), the name and
arguments of the current process.
If a user name is included, output is restricted to that user.
OPTIONS

-b

Suppress the heading.

-s

Produce a short form of output. In the short form, the tty is abbreviated, the login time and cpu
times are left off, as are the arguments to commands.

-I

Produce a long form of output, which is the default.

EXAMPLE

angel% w
7:36am up 6 days, 16:45, 1 users, load average: 0.20,0.23,0.18
User
tty
login@ idle
JCPU PCPU what
10:05 4:31
w
henry console 7:10am 1
angel%
FILES

/etc!utmp
/devlkmem
/dev/drum
SEE ALSO

who(I), ps(1), utmp(5)
BUGS

The notion of the 'current process' is muddy. The current algorithm is 'the highest numbered process on
the terminal that is not ignoring interrupts, or, if there is none, the highest numbered process on the terminal'. This fails, for example, in critical sections of programs like the shell and editor, or when faulty programs running in the background fork and fail to ignore interrupts. In cases where no process can be
found, w prints '-'.
The CPU time is only an estimate, in particular, if someone leaves a background process running after logging out, the person currently on that terminal is 'charged' with the time.
Background processes are not shown, even though they account for much of the load on the system.
Sometimes processes, typically those in the background, are printed with null or garbaged arguments. In
these cases, the name of the command is printed in parentheses.

W does not know about the new conventions for detecting background jobs. It will sometimes find a background job instead of the right one.

Sun Release 3.2

Last change: 28 September 1984

497

WAIT ( 1)

USER COMMANDS

WAIT( 1)

NAME

wait - await completion of a process
SYNOPSIS

wait
DESCRIPTION
Wait until all processes started with & or bg have completed, and report on abnormal terminations.

Because the wait(2) system call must be executed in the parent process, the Shell itself executes wait,
without creating a new process.
SEE ALSO
sh(1), csh(1)

BUGS
Not all the processes of a 3- or more-stage pipeline are children of the Shell, and thus can't be waited for.
(This bug does not apply to csh(1).)

498

Last change: 6 July 1983

Sun Release 3.2

WALL(1)

USER COMMANDS

WALL(1)

NAME

wall - write to all users
SYNOPSIS

wall [ -a] [file]
DESCRIPTION
Wall reads its standard input until an end-of-file. It then sends this message, preceded by 'Broadcast Message ... ' , to all logged in users. Normally, ptys that do not correspond to rlogin sessions are ignored. Thus
when in suntools(l}, the message appears only on the console window. However -a will send the message
even to such ptys.

The sender should be super-user to override any protections the users may have invoked.
FILES

/dev/tty?
/etc!utmp
SEE ALSO
nnesg(1),write(1)

Sun Release 3.2

Last change: 16 March 1983

499

WC(l)

WC(l)

USER COMMANDS

NAME

wc - word count
SYNOPSIS

we [ -Iwe] [filename ... ]
DESCRIPTION
we counts lines, words, and characters in filename s, or in the standard input if no filename appears. It also
keeps a total count for all named files. A word is a string of characters delimited by spaces, tabs, or newlines.
OPTIONS
I

Count lines.

w

Count words.

e

Count characters.

The default is -Iwe (count lines, words, and characters).

Whenfiles are specified on the command line, their names will be printed along with the counts.
EXAMPLE

angel% we /usr/manlmanll{csb.l,sb.l,telnet.l}
1876
11223
65895 lusr/man/manllcsh.1
674
3310
20338 lusr/manlmanllsh.1
260
1110
6834 lusr/manlmanlltelnet.1
2810
15643
93067 total
angel%

500

Last change: 17 February 1986

Sun Release 3.2

WHAT(l)

NAME

USER COMMANDS

WHAT(l)

what - identify the version of files under sees

SYNOPSIS

what files
DESCRIPTION
What searches the givenfiles for all occurrences of the pattern that get(l) substitutes for %Z% (this is
@(#) at this printing) and prints out what follows until the first", >, new-line, \, or null character. For
example, if the e program in file program.c contains

char ident[]

= "

@(#)identification information";

andprogram.c is compiled to yieldprogram.o and a.out, the command
what f.c f.o a.out
will print
f.c:
identification information
f.o:
identification information
a.out:
identification information

What is intended to be used in conjunction with the sees command get(l), which automatically inserts
identifying information, but it can also be used where the information is inserted manually.
SEE ALSO
sccs(l), get(l), help(l), file(l).

Programming Utilities/or the Sun System
DIAGNOSTICS
Use help (1) for explanations.
BUGS

It's possible that an unintended occurrence of the pattern @(#) could be found just by chance, but this
causes no harm in nearly all cases.

Sun Release 3.2

Last change: 16 February 1984

501

WHATIS(I)

USER COMMANDS

WHATIS(I)

NAME

whatis - describe what a command is
SYNOPSIS
whatis command •••
DESCRIPTION

Whatis looks up a given command and displays the header line from the manual section. You can then run
the man(l) 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 page for ed.
Whatis is actually just the -f option to the man (1) command.
FILES

lusr/manlwhatis

Data base

SEE ALSO
man(I),catman(8)

502

Last change: 1 February 1985

Sun Release 3.2

WHEREIS( 1)

USER COMMANDS

WHEREIS(I)

NAME

whereis -locate source, binary, and/or manual for program
SYNOPSIS

whereis [ -sbm ] [ -u ] [ -BMS dir ••• -r] filename •••
DESCRIPTION

whereis locates source/binary and manuals sections for specified files. The supplied names are first
stripped of leading pathname components and any (single) trailing extension of the form .ext. for example,
.c. Prefixes of s. resulting from use of source code control are also dealt with. where is then attempts to
locate the desired program in a list of standard places:
Ibin
lusrlbin
lusrl5bin
lusrlgames
lusrlhosts
lusrlinclude
lusrllocal
lusrletc
lusrllib
lusrlman
lusrlsrc
lusrlucb
OPTIONS

-b
-s
-m

Search only for binaries.

-u

Search for unusual entries. A file is said to be unusual if it does not have one entry of each
requested type. Thus whereis -m -u • asks for those files in the current directory which have
no documentation.

-B
-M
-S
-r

Change or otherwise limit the places where whereis searches for binaries.

Search only for sources.
Search only for manual sections.

Change or otherwise limit the places where whereis searches for manual sections.
Change or otherwise limit the places where whereis searches for sources.
Terminates the last directory list and signals the start of file names, and must be used when any of
the -B, -M, or -S options are used.

EXAMPLE

Find all files in lusrlbin which are not documented in lusrlmanlman} with source in lusrlsrclcmd:
angel% cd /usr/ucb
angel% whereis -u -M /usr/manlmanl-S /usr/src/cmd -f •
FILES

lusrlsrc/·
lusr/{doc,man}/*

llib, letc, lusr/{lib,bin,ucb,old,new,local}
BUGS

Since whereis uses chdir(2) to run faster, pathnames given with the -M, -S, or -B must be full; that is,
they must begin with a 'I'.

Sun Release 3.2

Last change: 1 February 1985

503

WHICH(l)

USER COMMANDS

WHICH(l)

NAME

which - locate a program file, including any aliases or paths
SYNOPSIS

which [ name ] •••
DESCRIPTION

Which takes a list of names and looks for the files which would be executed had these names been given as
commands. Each argument is expanded if it is aliased, and searched for along the user's path. Both aliases
and path are taken from the user's .cshrc file.
FILES
-I.cshrc

source of aliases and path values

DIAGNOSTICS

A diagnostic is given for names which are aliased to more than a single word, or if an executable file with
the argument name was not found in the path.
BUGS

Only aliases and paths from -I.cshrc are used; importing from the current environment is not attempted.
Must be executed by a csh, since only csh's know about aliases.
To compensate for -1.C8hrC files in which aliases depend upon the prompt variable being set, which sets
this variable. H the 7.cshrc produces output or prompts for input when prompt is set, which may produce
some strange results.

504

Last change: 25 March 1983

Sun Release 3.2

WHO ( 1)

USER COMMANDS

WHO(I)

NAME

who - who is logged in on the system
SYNOPSIS

who [ who-file] [ am i ]
DESCRIPTION

Used without arguments, who lists the login name, terminal name, and login time for each current UNIX
user. who gets this information from the letclutmp file.
If a filename argument is given, the named file is examined instead of letclutmp. Typically the named file
is lusrladmlwtmp, which contains a record of alilogins since it was created. In this case, who lists logins,
logouts, and crashes. Each login is listed with user name, terminal name (with '!devl' suppressed), and

date and time. Logouts produce a similar line without a user name. Reboots produce a line with ,-, in
place of the device name, and a fossil time indicating when the system went down. Finally, the adjacent
pair of entries 'I' and '}' indicate the system-maintained time just before and after a date command
changed the system's idea of the time.
With two arguments, as in 'who am i' (and also 'who is who'), who tells who you are logged in as: it
displays your hosttlame, login name, terminal name, and login time.
EXAMPLES

angel% who am i
angel!henry
ttypO
angel%

Apr 27 11 :24

krypton% who
rnktg
ttymO Apr 27 11: 11
shannon ttypO Apr 27 11 :25
henry
ttyp 1 Apr 27 11 :30
krypton%
FILES
letc/utrnp lusr/admlwtrnp

SEE ALSO

whoami(I), wtrnp(5), w(l)

Sun Release 3.2

Last change: 23 September 1985

505

WHOAMI(l)

USER COMMANDS

WHOAMI(l)

NAME

whoami - display effective current username
SYNOPSIS
whoami
DESCRIPTION
whoami displays the username of whoever is currently logged in. whoami works even if you've used su to
pick up another username, while 'who am i' does not since it gets its information from the letclutmp file.

In other words,

whoami shows who you are now, while
who am i shows who you where when you logged in.
FILES

letclpasswd

usemame data base

SEE ALSO
who(l)

506

Last change: 23 September 1985

Sun Release 3.2

USER COMMANDS

WHOIS(l)

WHOIS(l)

NAME

whois - DARPA Internet user name directory service
SYNOPSIS
whois [ -h host] identifier
DESCRIPTION
whois searches for an ARPAnet directory entry for an identifier which is either a name (such as "Smith")
or a handle (such as "SRI-NIC' '). You can force a name-only search by preceeding the name with a
period; you can force a handle-only search by preceeding the handle with an exclamation point For example, typing:

whois Smith

looks for name or handle SMITII.

whois !SRI-NIC

looks for handle SRI-NIC only.

whois .Smith, John

looks for name JOHN SMITH only.

Adding" ... " to the name or handle argument will match anything from that point; that is, "W ... " will
match WL, WM, etc.
If you are searching for a group or organization entry, you can have the entire membership list of the group
displayed with the record by preceeding the argument with an astersik ("*").
You may of course use an exclamation point and asterisk, or a period and asterisk together.

Sun Release 3.2

Last change: 21 January 1985

507

USER COMMANDS

WRITE ( 1)

WRITE ( 1)

NAME

write - write to another user
SYNOPSIS

write user [ ttyname ]
DESCRIPTION

Write copies lines from your standard input to user's screen.

When you type a write command, the person you're writing to sees a message like this:
Message from hostname!yourname on yourttyname at hh:rnrn ...
After typing the write command, enter the text of your message. What you type appears line-by-line on the
other user's screen. Conclude by typing an end of file indication CD) or an interrupt. At this point write
displays 'EOT' on your recipient's screen and exits.
To write to a user who is logged in more than once, use the ttyname argument to indicate the appropriate
terminal name.
You can grant or deny other users permission to write to you by using the mesg command (default allows
writing). Certain commands, nroff and pr(l) in particular, don't allow anyone to write to you while you
are using them in order to prevent messy output.
If write finds the character '!' at the beginning of a line, it calls the shell to execute the rest of the line as a
command.

Two people can carry on a conversation by write'ing to each other. When the other person receives the
message indicating you are writing to him, he can then write back to you if he wishes. However, since you
are now simultaneously typing and receiving messages, you end up with garbage on your screen unless you
work out some sort of scheduling scheme with your partner. You might try the following conventional
protocol: when you first write to another user, wait for him to write back before starting to send. Each person should end each message with a distinctive signal- -0- (for 'over') is standard - so that the other
knows when to begin a reply. To end your conversation, type -00- (for 'over and out') before finishing the
conversation.
EXAMPLE

Here is an example of a short dialog between two people on different terminals. Two users called Horace
and Eudora are logged in on a system called jones. To illustrate the process, both users' screens are shown
side-by-side:
Eudora's Terminal
Horace's Terminal
Horace is staring at his screen

jones% write horace
how about a squash game tonight? -0-

Message from jones !eudora on tty09 at 17:05 ...
how about a squash game tonight? -0jones% write eudora
I'm playing tiddlywinks with Carmeline -0-

Message from jones !horace on tty03 at 17 :06 ...
r m playing tiddlywinks with Carmeline -0How about the beach on Sunday? -0How about the beach on Sunday? -0Sorry, I'm washing my tent that day -0Sorry, I'm washing my tent that day -oSee you when I get back from Peru -00See you when I get back from Peru -00-

AD

EOF
I hear rack of llama is very tasty -00-

jones%

AD

I hear rack of llama is very tasty -00EOF

508

jones%

Last change: 7 March 1984

Sun Release 3.2

WRITE ( 1)

USER COMMANDS

WRITE(l)

FILES

/etclutmp
/binlsh

to find user
to execute '!'

SEE ALSO
mesg(I), who(I), mail(I), ta1k(l)

Sun Release 3.2

Last change: 7 March 1984

509

XARGS( 1)

USER COMMANDS

XARGS(I)

NAME

xargs - construct argument list(s) and execute command
SYNOPSIS

xargs [ -In umber ] [ -ireplstr] [ -nnumber] [ -t ] [ -p ] [ -x] [ -ssize ] [ -eeofstr ]
[ command [ initial-arguments] ]
DESCRIPTION
xargs combines the fixed initial-arguments with arguments read from standard input, to execute the
specified command one or more times. The number of arguments read for each command invocation, and
the manner in which they are combined are determined by the options specified.

command, which may be a shell file, is searched for using one's $PATH. If command is omitted, !bin/echo
is used
Arguments read in from standard input are defined to be contiguous strings of characters delimited by
white space. Empty lines are always discarded. Blanks and tabs may be embedded as part of an argument
if they are escaped or quoted. Characters enclosed in quotes (single or double) are taken literally, and the
delimiting quotes are removed. Outside of quoted strings, a backslash (\) will escape the character it precedes.
Each arguments-list is constructed starting with the initial-arguments, followed by some number of arguments read from standard input (Exception: see -i option). Options -i, -1, and -0 determine how arguments are selected for each command invocation. When none of these options are coded, the initialarguments are followed by arguments read continuously from standard input until an internal buffer is full,
and then command is executed with the accumulated arguments. This process is repeated until there are
none left When there are option conflicts (e.g., -I vs. -0), the last option takes precedence.

xargs will terminate if it receives a return code of -1, or if it cannot execute command. When command is
a shell script, it should explicitly exit (see sh(I» with an appropriate value to avoid accidentally returning
with-I.
OPTIONS

-Inumber

command is executed for each nonempty number lines of arguments from standard input. The
last invocation of command will be with fewer lines of arguments if fewer than number
remain. A line is considered to end with the first new-line unless the last character of the line
is a blank or a tab; a trailing blank/tab signals continuation through the next non-empty line. If
number is omitted, 1 is assumed. Option -x is forced.

-ireplstr

Insert mode: command is executed for each line from standard input, taking the entire line as a
single arg, inserting it in initial-arguments for each occurrence of replstr. A maximum of 5
arguments in initial-arguments may each contain one or more instances of replstr. Blanks and
tabs at the beginning of each line are thrown away. Constructed arguments may not grow
larger than 255 characters, and option -x is also forced. {} is assumed for replstr if not
specified.

-on umber Execute command using as many standard input arguments as possible, up to number arguments maximum. Fewer arguments will be used if their total size is greater than size characters, and for the last invocation if there are fewer than number arguments remaining. If option
-x is also coded, each number arguments must fit in the size limitation, else xargs terminates
execution.

510

-t

Trace mode: The command and each constructed argument list are echoed to file descriptor 2
just prior to their execution.

-p

Prompt mode: The user is asked whether to execute command each invocation. Trace mode
(-t) is turned on to print the command instance to be executed, followed by a 1 ••• prompt. A
reply of y (optionally followed by anything) will execute the command; anything else, including just a carriage return, skips that particular invocation of command.

-x

Causes xargs to terminate if any argument list would be greater than size characters; -x is

Last change: 6 June 1986

Sun Release 3.2

XARGS(1)

USER COMMANDS

XARGS(l)

forced by the options -i and -I. When neither of the options -i, -I, or -0 are coded, the total
length of all arguments must be within the size limit.

-ssize

The maximum total size of each argument list is set to size characters; size must be a positive
integer less than or equal to 470. If -s is not coded, 470 is taken as the default Note that the
character count for size includes one extra character for each argument and the count of characters in the command name.

-eeofstr

eofstr is taken as the logical end-of-file string. Underbar (_) is assumed for the logical EOF
string if -e is not coded. The value -e with no eofstr coded turns off the logical EOF string
capability (underbar is taken literally). xargs reads standard input until either end-of-file or the
logical EOF string is encountered.

EXAMPLES
The following will move all files from directory $1 to directory $2, and echo each move command just
before doing it:

Is $1

I xargs -i -t mv

$1I{} $2/{}

The following will combine the output of the parenthesized commands onto one line, which is then echoed
to the end of file log:
(logname; date; echo $0 $*)

I xargs »log

The user is asked which files in the current directory are to be archived and archives them into arch (1.)
one at a time, or (2.) many at a time.

1. Is
2. Is

I xargs -p -1 ar r arch
I xargs -p -1 I xargs ar r arch

The following will execute diff(l) with successive pairs of arguments originally typed as shell arguments:
echo $*

I xargs -n2 diff

SEE ALSO

sh(l)

Sun Release 3.2

Last change: 6 June 1986

511

XSEND( 1)

USER COMMANDS

XSEND(l)

NAME

xsend, xget, enroll- secret mail
SYNOPSIS

xsend username
xget

enroll
DESCRIPTION

These commands implement a secure communication channel, which is like mail(l), but no one can read
the messages except the intended recipient. The method embodies a public-key cryptosystem using knapsacks.
To receive messages, use enroll; it asks you for a password that you must subsequently quote in order to
receive secret mail.
To receive secret mail, use xget. It asks for your password, then gives you the messages.
To send secret mail, use xsend in the same manner as the ordinary mail command. Unlike mail, xsend
accepts only one target. A message announcing the receipt of secret mail is also sent by ordinary mail.
FILES

lusrlspool/secretmail/* .key
lusrlspool/secretmail/* .[0-9]

keys
messages

SEE ALSO

mail (1)
BUGS

The knapsack public-key cryptosystem is known to be breakable.
Secret mail should be integrated with ordinary mail.
The announcement of secret mail makes "traffic analysis" possible.
RESTRICTIONS

These facilities are not available on software shipped outside the U.S.

512

Last change: 7 March 1986

Sun Release 3.2

XSTR( 1)

USER COMMANDS

XSTR( 1)

NAME

xstr - extract strings from C programs to implement shared strings
SYNOPSIS

xstr [ -v ] [ -c] [ - ] [ file]
DESCRIPTION

Xstr maintains a file called strings into which strings in component parts of a large program are hashed.
These strings are replaced with references to this common area. This serves to implement shared constant
strings, which are most useful if they are also read-only.
The command

xstr -c name
extracts the strings from the C source in name, replacing string references by expressions of the form
(&xstr[number]) for some number. An appropriate declaration of xstr is prepended to the file. The resulting C text is placed in the file x.c, to then be compiled. The strings from this file are placed in the strings
data base if they are not there already. Repeated strings and strings which are suffixes of existing strings
do not cause changes to the data base.
After all components of a large program have been compiled a file xs. c declaring the common xstr space
can be created by a command of the form

xstr
This xs.c file should then be compiled and loaded with the rest of the program. If possible, the array can be
made read-only (shared) saving space and swap overhead.

Xstr can also be used on a single file. A command

xstr name
creates files x.c and xs.c as before, without using or affecting any strings file in the same directory.
It may be useful to run xstr after the C preprocessor if any macro definitions yield strings or if there is conditional code which contains strings which may not, in fact, be needed. Xstr reads from its standard input
when the argument '-' is given. An appropriate command sequence for running xstr after the C preprocessor is:

cc -E name.c I xstr -c cc-c x.c
mv x.o name.o

Xstr does not touch the file strings unless new items are added; thus make can avoid remaking xs.o unless
truly necessary.
OPTIONS

-cfile

Take C source text fromfile.

-v

Verbose: display a progress report indicating where new or duplicate strings were found.

FILES

strings
x.c
xs.c
Itmplxs*

data base of strings
Massaged C source
C source for definition of array "xstr"
temp file when "xstr name" doesn't touch strings

SEE ALSO

mkstr(l)
BUGS

If a string is a suffix of another string in the data base, but the shorter string is seen first by xstr both strings
will be placed in the data base, when just placing the longer one there would do.

Sun Release 3.2

Last change: 13 March 1984

513

YACC(l)

USER COMMANDS

YACC(l)

NAME

yacc - yet another compiler-compiler
SYNOPSIS
yacc [ -vd ] grammar

DESCRIPTION
Yace converts a context-free grammar into a set of tables for a simple automaton which executes an LR(1)
parsing algorithm. The grammar may be ambiguous; specified precedence rules are used to break ambiguities.

The output file, y.tab.e, must be compiled by the C compiler to produce a function named yyparse. The
yyparse function must be loaded with the lexical analyzer yylex, as well as main and yyerror, an error handling routine. These routines must be supplied by the user; lex(l) is useful for creating lexical analyzers
usable by yace -produced parsers.
OPTIONS
-v

-d

Prepare the file y.output containing a description of the parsing tables and a report on .confiicts
generated by ambiguities in the grammar.
Generate the file y .tab.h with the define statements that associate the yace -assigned 'token codes'
with the user-declared 'token names' so that source files other than y •tab .e can access the token
codes.

FILES

y.output
y.tab.c
y.tab.h
yacc. tmp, yacc.acts
lusrnib/yaccpar

description of parsing tables and conflict report
output parser
defines for token names
temporary files
parser prototype for C programs

SEE ALSO

lex(l)
LR Parsing by A. V. Aho and S. C. Johnson, Computing Surveys, June, 1974
Yace- Yet Another Compiler Compiler in Programming Utilities/or the Sun Workstation
DIAGNOSTICS
The number of reduce-reduce and shift-reduce conflicts is reported on the standard output; a more detailed
report is found in the y.output file. Similarly, if some rules are not reachable from the start symbol, this is
also reported
BUGS

Because file names are fixed, at most one yaee process should be active in a given directory at a time.

514

Last change: 8 October 1984

Sun Release 3.2

YES ( 1)

USER COMMANDS

YES ( 1)

NAME

yes - be repetitively affirmative
SYNOPSIS
yes [ expletive]
DESCRIPTION
Yes repeatedly outputs "y", or if expletive is given, that is output repeatedly. Termination is by typing an
interrupt character.

Sun Release 3.2

Last change: 14 December 1983

515

YPCAT(I)

USER COMMANDS

YPCAT(l)

NAME

ypcat - print values in a yP data base
SYNOPSIS

ypcat [ -k ] [ -t] [ -d domainname ] mname
ypcat-x
DESCRIPTION
ypcat prints out values in a yellow pages (YP) map specified by mname, which may be either a mapname
or a map nickname. Since ypcat uses the yP network services, no yP server is specified.

To look at the network-wide password database, passwd.byname, (with the nickname passwd). type in:

ypcat passwd
Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages.
OPTIONS
-k

Display the keys for those maps in which the values are null or the key is not part of the value.
(None of the maps derived from files that have an ASCII version in fete fall into this class.)

-t

Inhibit translation of mname to mapname. For example, ypcat -t passwd will fail because there is
no map named passwd, whereas ypcat passwd will be translated to ypcat passwd.byname.

-d

Specify a domain other that the default domain. The default domain is returned by domain name.

-x

Display the map nickname table. This lists the nicknames (mnames) the command knows of, and
indicates the mapname associated with each nickname.

SEE ALSO
ypfiles(5), ypserv(8), ypmatch(l), domainname(8)

516

Last change: 8 July 1985

Sun Release 3.2

YPMATCH( 1)

USER COMMANDS

YPMATCH(I)

NAME

ypmatch - print the value of one or more keys from a yp map
SYNOPSIS

ypmatch [ -d domain] [ -k ] [ -t ] key . .. mname
ypmatch -x
DESCRIPTION
ypmatch prints the values associated with one or more keys from the yellow pages (YP) map specified by
a mname, which may be either a mapname or an map nickname .

Multiple keys can be specified; the same map will be searched for all. The keys must be exact values
insofar as capitalization and length are concerned. No pattern matching is available. If a key is not
matched, a diagnostic message is produced.
OPTIONS

-d

Specify a domain other that the default domain.

-k

Before printing the value of a key, print the key itself, followed by a colon (':'). This is useful
only if the keys are not duplicated in the values, or you've specified so many keys that the output
could be confusing.

-t

Inhibit translation of nickname to mapname. For example, ypmatch -t zippy passwd will fail
because there is no map named passwd, while ypmatch zippy passwd will be translated to ypmatch
zippy passwd.byname .

-x

Display the map nickname table. This lists the nicknames (mnames) the command knows of, and
indicates the mapname associated with each nickname.

SEE ALSO
ypfiles(5), ypcat(l)

Sun Release 3.2

Last change: 19 August 1985

517

YPPASSWD ( 1 )

USER COMMANDS

YPPASSWD(I)

NAME

yppasswd - change login password in yellow pages
SYNOPSIS

yppasswd [ name ]
DESCRIPTION

Yppasswd changes (or installs) a network password associated with the user name (your own name by
default) in the yellow pages. The yellow pages password may be different from the one on your own
machine.
Yppasswd prompts for the old yellow pages password, and then for the new one. You must type in the old
password correctly for the change to take effect The new password must be typed twice, to forestall mistakes.

New passwords must be at least four characters long, if they use a sufficiently rich alphabet, and at least six
characters long if monocase. These rules are relaxed if you are insistent enough. Only the owner of the
name or the super-user may change a password; in either case you must prove you know the old password.
The yellow-pages password daemon, yppasswdd (8C) must be running on your yP server in order for the
new password to take effect
SEE ALSO

passwd(I), ypfiles(5), yppasswdd(8C)
BUGS

The update protocol passes all the information to the server in one RPC call, without ever looking at it.
Thus if you type in your old password incorrectly, you will not be notified until after you have entered your
new password.

518

Last change: 21 August 1985

Sun Release 3.2

YPWHICH(1)

USER COMMANDS

YPWHICH(1)

NAME

ypwhich - which host is the yP server or map master?
SYNOPSIS

ypwhich [ -d [ domain] ] [ -VI I - V2 ] [ hostname ]
ypwhich [ -t mapname] [ -d domain] -m [ mname ]
ypwhich-x
DESCRIPTION

ypwhich tells which yP server supplies yellow pages services to a yP client, or which is the master for a
map. If invoked without arguments, it gives the yP server for the local machine. If hostname is specified,
that machine is queried to find out which yP master it is using.
Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages.
OPTIONS
-d

Use domain instead of the default domain.

-VI

Which server is serving v.1

-V2

Which server is serving v.2 yP protocol client processes?

yP protocol-speaking

client processes?

If neither version is specified, ypwhich attempts attempts to locate the server that supplies the
(current) v.2 services. If there is no v.2 server currently bound, ypwhich then attempts to
locate the server supplying the v.1 services. Since yP servers and yP clients are both backward compatible, the user need seldom be concerned about which version is currently in use.
-t mapname Inhibit nickname translation; useful if there is a mapname identical to a nickname. This is
not true of any Sun-supplied map.
-m

Find the master YP server for a map. No hostname can be specified with -me mname can
be a mapname, or a nickname for a map. When mname is omitted, produce a list available
maps.

-x

Display the map nickname table. This lists the nicknames (mnames) the command knows
of, and indicates the mapname associated with each nickname.

SEE ALSO
ypfiles(5), rpcinfo(8), ypset(8), ypserv(8)

Sun Release 3.2

Last change: 19 February 1986

519

I

INTRO(6)

GAMES AND DEMOS

INTRO(6)

NAME

intro - introduction to games and demos
DESCRIPTION
This section describes games and demos in alphabetical order.
SEE ALSO

Games, Demos and Other Pursuits: Beginner's Guide

Sun Release 3.2

Last change: 26 December 1985

521

BOGGLETOOL ( 6 )

GAMES AND DEMOS

BOGGLETOOL ( 6 )

NAME

boggletool- playa game of boggle
SYNOPSIS
boggletool [number] [ + [+]] [ 16-character string]
DESCRIPTION
Boggletool allows you to play the game of Boggle (TM Parker Bros.) against the computer. The number
argument specifies the time limit in minutes (the default is 3 minutes). If a 16 character long string is
placed on the command line, it is interpreted as a Boggle board: the first four letters form the top row, the
next four letters the second row, etc. If no letters are specified, a board is randomly rolled by the computer
from a set of Boggle cubes. The +[+] argument is explained below under Advanced Play.
PLAYING THE GAME
Rules of the Game The object of Boggle is to find as many words as possible in a 4 by 4 grid of letters
within a certain time limit. Words may be formed from any sequence of 3 or more adjacent letters in the
grid. The letters may join horizontally, vertically, or diagonally. Normally, no letter in the grid may be
used more than once in a word (see Advanced Play for exceptions).

Playing the Game When invoked, boggletool displays a grid of letters and an hourglass. To enter words,
simply type in lower case letters to spell the word you want. Use any whitespace (space, tab, or newline)
to finish a word. To correct mistakes you make, use backspace or DEL to delete the last character, or use
CTRL-U to delete an entire word.
Boggletool verifies that words you enter are both in the grid and are valid English words. If you type in a
character which would form a word which is not in the grid, the display will flash and the character you
typed will not be echoed. When you type any whitespace to end the current word, boggletool will verify
that the word is three or more letters long and that it appears in the dictionary. If the word you typed is illegal for either reason, the display will flash and you will have to either erase the word or change it. If you
try to enter a valid word which you have already entered, the display will flash and the previous occurance
of the word will be highlighted. Again, you will have to erase the word before continuing.
As you enter words, the "sand" in the hourglass will fall. At the end of the time limit, the display will flash
and you will no longer be allowed to enter words. After a moment, the computer will display two lists of
words: the words you found, and other words which also appear in the grid. To play another game, just
type any capital letter (or use the pop-up menu).

Using the Menu The pop-up menu is invoked by pressing the right button. There are four items in it, and
they work as follows. Restart Game causes boggletool to create a new board, reset the timer, and allow
you to start from scratch. Restart Timer allows you to cheat by reseting the hourglass timer to zero. Give
Up causes boggletool to end the game and print the results immediately. Quit allows you to quit running
the boggletool program. A prompt appears asking you to confirm the quit; when it does, click the left button to quit or the right button to abort the quit.
Advanced Play There are two options for advanced players. If a single + appears on the command line,
letters in the grid may be reused. If two +' s are on the command line, letters may also be considered adjacent to themselves as well as to their neighbors. Although it is far easier to find words with these two
options, there are also many more possible words in the grid and it is therefore difficult to find them all.
FILES

lusr/gameslboggledict

522

dictionary file for computer's words

Last change: 14 May 1985

Sun Release 3.2

CANFIELD ( 6 )

GAMES AND DEMOS

CANFIELD ( 6 )

NAME

canfield, canfieldtool, cfscores - Canfield solitaire card game
SYNOPSIS

lusr/gameslcanfield
lusr/games/canfieldtool
lusr/gameslcfscores
DESCRIPTION

canfield can be played on any terminal. canfieldtool is the SunView version with attractive graphics.
If you have never played solitaire before, it is recommended that you consult a solitaire instruction book. In
Canfield, tableau cards may be built on each other downward in alternate colors. An entire pile must be
moved as a unit in building. Top cards of the piles are available to be able to be played on foundations, but
never into empty spaces.
Spaces must be filled from the stock. The top card of the stock also is available to be played on foundations
or built on tableau piles. After the stock is exhausted, tableau spaces may be filled from the talon and the
player may keep them open until he wishes to use them.
Cards are dealt from the hand to the talon by threes and this repeats until there are no more cards in the
hand or the player quits. To have cards dealt onto the talon the player types 'ht' for his move. Foundation
base cards are also automatically moved to the foundation when they become available.
Canfieldtool

Once you understand the rules, canfieldtool is self-explanatory.
Canfield

The command 'c' causes canfield to maintain card counting statistics on the bottom of the screen. When
properly used this can greatly increase ones chances of winning.
The rules for betting are somewhat less strict than those used in the official version of the game. The initial
deal costs $13. You may quit at this point or inspect the game. Inspection costs $13 and allows you to
make as many moves as is possible without moving any cards from your hand to the talon. (the initial deal
places three cards on the talon; if all these cards are used, three more are made available.) Finally, if the
game seems interesting, you must pay the final installment of $26. At this point you are credited at the rate
of $5 for each card on the foundation; as the game progresses you are credited with $5 for each card that is
moved to the foundation. Each run through the hand after the first costs $5. The card counting feature
costs $1 for each unknown card that is identified. If the information is toggled on, you are only charged for
cards that became visible since it was last turned on. Thus the maximum cost of information is $34. Playing time is charged at a rate of $1 per minute.
With no arguments, the program cfscores prints out the current status of your canfield account If a user
name is specified, it prints out the status of their canfield account If the -a flag is specified, it prints out
the canfield accounts for all users that have played the game since the database was set up.
FILES

/usr/games/canfield
/usr/games/cfscores
/usr/games/lib/cfscores

the game itself
the database printer
the database of scores

BUGS

It is impossible to cheat

Sun Release 3.2

Last change: 27 May 1986

523

CHESS(6)

GAMES AND DEMOS

CHESS(6)

NAME

chess - the game of chess
SYNOPSIS
lusr/gameslchess
DESCRIPTION

Chess is a computer program that plays class D chess. Moves may be given either in standard (descriptive)
notation or in algebraic notation. The symbol' +' is used to specify check; '0-0' and '0-0-0' specify castling. To play black, type 'first'; to print the board, type an empty line.
Each move is echoed in the appropriate notation followed by the program's reply.
DIAGNOSTICS
The most cryptic diagnostic is 'eh?' which means that the input was syntactically incorrect.
FILES

lusr/games/lib/chess.book book of opening moves
BUGS

Pawns may be promoted only to queens.

524

Last change: 30 September 1984

Sun Release 3.2

CHESSTOOL ( 6 )

GAMES AND DEMOS

CHESSTOOL ( 6)

NAME

chesstool- window-based front-end to chess program
SYNOPSIS
chesstool [ chessyrogram]
DESCRIPTION

Chesstool is a window-based front-end to the chess(6) program. Used without options, chesstool uses
/usr/games/chess; you can designate any alternate program which uses the same command syntax as
chess(6) with the chessYTogram argument.
When chesstool starts up, it displays a large window with three subwindows. The first subwindow displays
messages - "Illegal move", for example. The second subwindow is an options subwindow; options are
described below. The final subwindow is a chessboard display with white and black pieces and two
(advisory only) timekeeping clocks.
Make your moves with the mouse: select a piece by positioning the arrow cursor over the piece and pressing the left mouse button down, then drag the piece to the destination square, and release the button. The
cursor will then turn to an hourglass icon while the system plays.
Options in the options subwindow may be selected with either the left or middle mouse buttons. These
options are:
Last Play

Show the last play made.

Undo

Undo your last move and the machine's response.
Once the game is over, it is not possible to restart it, so undo will update the board,
but the game cannot be continued from that position.

Machine White

Start a new game with the machine playing white.

Human White

Start a new game with the machine playing black.

Quit

Exit from chesstool.

Flash

Flash when the machine has completed its move.
When this command is selected, a check mark will appear next to the word Flash.
In flash mode, if chesstool is open, the piece moved by the system on its play will
flash until you make your move. If chesstool is iconic, the entire icon will flash
when the machine has made its move. Thus you can 'Close' chesstool and be alerted
when it's your turn to move. To turn flash mode off, select flash again.

There are two moves which are special: castling and capturing a pawn en passant. To castle, move the
king only. The position of the rook will automatically be updated. Since the king moves two squares when
castling, the move is unambiguous. To capture en passant, move the pawn to the square occupied by the
opposing pawn which will be captured.
SEE ALSO
chess(6)

Sun Release 3.2

Last change: 20 August 1984

525

GAMM:ONTOOL ( 6 )

GAMES AND DEMOS

GAMMONTOOL ( 6 )

NAME
gamrnontool- playa game of backgammon

SYNOPSIS
gammontool [ path ]
DESCRIPTION
Gammontool paints a backgammon board on the screen, and then lets you play against the computer. It
must be run in SunWindows. The optional path argument specifies an alternate move-generating program,
which must be specially designed to run with gammontool.
The game has three subwindows: an option window on top, a message window in the middle, and a large
board on the bottom. The buttons in the option window are used to restart, double, etc. The message window has two lines: the first tells whose turn it is, and the second displays any errors that occur.

The initial roll. To start the game, roll the dice to determine who goes first. Move the mouse arrow onto
the board and click the left button. One die appears on each side of the board: the die on the left is yours,
and the die on the right is the computer's. If your roll is greater, then you move; if not, the computer
makes a move.
Making your move. When it is your turn, "Your move" appears in the message window. Place the mouse
over any piece of your color, and click the left button. While holding down the button, move the mouse to
drag the piece; the piece follows the mouse until you release the button. The tool checks each move and
does not allow illegal moves. When you have made as many moves as you can, the computer takes its
turn; after it finishes, you may either roll again, or double.
Doubling. To double, click the Double button in the option window and wait for the computer's response.
If the computer doubles you, a message is displayed and you must answer with the Accept Double or
Refuse Double buttons. The Forfeit button can also be used to refuse a double. If the game is doubled, a
doubling cube with the proper value is displayed on the bar strip. If the number is facing up, then you may
double next. If the number is upside down, it is the computer's tum to double.
Other buttons. If you want to change your move before you have finished it, use the Redo Move or
Redo Entire Move buttons in the option window. Redo Entire Move replaces all of the pieces you have
moved so that you can redo them all. Redo Move only replaces the last piece you moved, so it is useful
when you roll doubles and want to redo only the last piece you moved. Note that once you have made all
of the moves your roll permits, play passes immediately to the computer, so you cannot redo the very last
move. The Show Last Move button allows you to see the last move again.
Leaving the game. If you want to quit playing backgammon, use the Quit button. If you want to forfeit the
game, use the Forfeit button. The computer penalizes you by taking a certain number of points, but the
program does not terminate.
To play another game after winning, losing, or forfeiting, click the New Game button. To change the color
of your pieces, click the mouse button while pointing at either the White or Black checkboxes. You may
change colors at any time, even in the middle of a game. Changing colors in the middle of a game does not
mean that you trade places with the computer; your pieces stay where they are, but they are repainted with
the new color. Your pieces always move from the top right to the bottom right of the board, regardless of
your color. As an additional cue as to your color, your dice are always displayed on the left half of the
board.

Log file. If a there is a gammon log file your home directory, gammontool keeps a log of the games played.
Each move and double gets recorded, along with the winners and accumulated scores.
FILES
7gammonlog

log of games played

lusrlgameslliblgammonscores
log of wins and losses

526

Last change: 15 May 1986

Sun Release 3.2

GAMMONTOOL (6)

GAMES AND DEMOS

GAMMONTOOL ( 6)

BUGS
The default strategy used by the computer is very poor.

If a single move uses more than one die (for instance if you roll 5, 6 and move 11 spaces without touching
down in the middle) it is unpredictable where the program will make the piece touch down. This may be
important if there is a blot on one of these middle points. The program will always make the move if possible, but if two midpoints would work and there is a blot on one of them, it is much better to explicitly hit
the blot and then move the piece the rest of the way.

Sun Release 3.2

Last change: 15 May 1986

527

GAMES AND DEMOS

NAME

gp_demos, flight, rotobj - demonstration programs for the Graphics Processor
SYNOPSIS
Bight

rotobj [object ]
DESCRIPTION

These demos only run in windows running on a Graphics Processor surface.
Note:

Optional Software (Games and Demos Option). Refer to Installing UNIX on the Sun Workstation
for information on how to install these demos.

Flight

flight is a mouse-driven flight simulator.
Interactive Commands
Middle-Button

Restart the program.

Right-Button

Increase speed.

Left-Button

Decrease speed.

Move-Mouse-Forward
The airplane dives.
Move-Mouse-Backward
The airplane climbs.
Move-Mouse-LeftJRight
The airplane banks.
LeftlRight-With-Right-Button
The airplane rolls without banking.
Rotobj

rotobj rotares an object. Object files are locared in lusr/demo/DATA and have the suffix .vecs.
SEE ALSO

graphics_ demos( 6)

528

Last change: 29 May 1986

Sun Release 3.2

GRAPHICS_DEMOS ( 6 )

GAMES AND DEMOS

GRAPHICS_DEMOS ( 6 )

NAME

graphics_demos, bouncedemo, cframedemo, framedemo, goban, jumpdemo, maze, shaded, show,
showmap, spheresdemo, stringart, suncube - graphics demonstration programs
SYNOPSIS

bouncedemo [ -d dev] [ -ox] [ -r ] [ -q ]
cframedemo [ -d dev] [ -ox] [ -r ] [ -q ]
framedemo [ -d dev] [ -nx] [ -r ] [ -q ]
goban game
jumpdemo [ -c] [ -d dev] [ -ox] [ -r] [ -q ]
maze
shaded object [ -d dev ]
show rasterfile [rasterftie ... ]
showmap [ -d dev ] [ -q ]
spheresdemo [ -d dev ] [ -ox] [ -r ] [ -q ]
stringart [ -d dev] [ -q ]
sun cube [ -d dev] [ -q ]
DESCRIPTION

Note:

Optional Software (Games and Demos Option). Refer to Installing UNIX on the Sun Workstation
for infonnation on how to install these demos.

Bouncedemo

bouncedemo displays a bouncing square.
Cframedemo

cframedemo displays a series of color frames, each of which contains a 256 by 256 image of eight-bit-deep
pixels. cframedemo looks for the frames in the filesframe.l throughframe.n in the current working directory, and displays them in numerical order. When run in the directory lusrldemolglobeframes, cframedemo
displays a rotating view of the world.
Framedemo

framedemo displays a series of frames, each of which contains a 256 by 256 image one-bit-deep pixels
(that is, the image is a square monochrome bitmap, with 256 bits on a side). framedemo looks for the
frames in the files frame. 1 throughframe.n in the current working directory, and displays them in numerical order. A set of sample frames is available in the directory lusrldemolglobeframesl*. Interactive Commands

If you move the cursor onto the image surface, you can type certain commands to affect the rate at which
the frames are displayed. The initial rate is one frame per second:
f

removes 1I20th of a second from the interval.

F

removes one second from the interval. Ff makes the interval as small as possible.

s

adds 1I20th of a second.

S

adds one second.

Goban

goban is Japanese for "go board". It is an automatic board, but does not play go. If you invoke it with no
game argument, goban reads from the file masterofgo. This is a transcript of an important historical game
written about by the Nobel Prize winning author, Yasunari Kawabata in The Master of Go, a book which
conveys the ancient and facinating game.

Sun Release 3.2

Last change: 29 May 1986

529

LIFE(6)

GAMES AND DEMOS

LIFE (6)

NAME

life - John Conway's game of life
SYNOPSIS
life
DESCRIPTION
Life is a program that plays John Conway's game of life. It only runs under suntools(I).

When invoked, life will display a window with a small control panel at the top, and a large drawing area at
the bottom. You can create pieces in the drawing area with the left button, and erase them with the middle
button. When you select Run in the control panel, the pieces will begin to evolve, and the drawing region
will update itself at a speed controlled by the slider labeled with Fast and Slow. Life keeps track of all the
pieces even if they are not visible. The scroll bars surrounding the drawing region can be used to see
pieces that have moved out of view. There are some standard patterns that can be drawn by popping up a
menu in the drawing subwindow.
The meaning of the items in the first row of the control panel (from left to right) are as follows. If you
click on the picture which looks like a tic-tac-toe board, a grid will appear in the drawing region. If you
click on Step, the mode will change from run mode (where the pieces update continuously) to step mode
(where an update is only done when you click on Step). Following Gen is a number indicating the number
of generations that have occured. The button marked Find will scroll so that at least one piece is in view.
This is useful when all the pieces dissappear from view. The button marked Clear will clear the drawing
region, but leave the other controls unchanged. Reset will reset all the panel controls, but will not erase
any of the pieces, and Quit causes the tool to exit. The second row contains two sliders. The first controls
the update speed when in run mode, the second controls the size of the pieces.

532

Last change: 2 May 1986

SUD

Release 3.2

SUNVIEW_DEMOS ( 6 )

GAMES AND DEMOS

NAME

sunview_demos, canvas_demo, cursor_demo - Window-System demonstration programs
SYNOPSIS

lusr/demo/canvas_demo
lusr/demo/cursor demo
DESCRIPTION
Canvas Demo
canvas_demo demonstrates the capabilities of the canvas subwindow package. It consists of two subwin-

dows: a control panel and a canvas. By adjusting the items on the control panel, you can manipulate the
attributes of the canvas, and see the results.
Cursor Demo
cursor_demo demonstrates what you can do with cursors. A single control panel is provide for adjusting

the various cursor attributes. As you adjust the items on the control panel, the panel's cursor changes in
appearance.

Sun Release 3.2

Last change: 29 May 1986

533

USER COMMANDS

YPMATCH( 1)

YFMATCH(I)

NAME

ypmatch - print the value of one or more keys from a yp map
SYNOPSIS
ypmatch [ -d domain] [ -k] [ -t ] key . .. mname
ypmatch-x
DESCRIPTION

ypmatch prints the values associated with one or more keys from the yellow pages (YP) map specified by
a mname, which may be either a mapname or an map nickname .
Multiple keys can be specified; the same map will be searched for all. The keys must be exact values
insofar as capitalization and length are concerned. No pattern matching is available. If a key is not
matched, a diagnostic message is produced.
OPTIONS

-d

Specify a domain other that the default domain.

-k

Before printing the value of a key, print the key itself, followed by a colon (':'). This is useful
only if the keys are not duplicated in the values, or you've specified so many keys that the output
could be confusing.

-t

Inhibit translation of nickname to mapname. For example, ypmatch -t zippy passwd will fail
because there is no map named passwd, while ypmatch zippy passwd will be translated to ypmatch
zippy passwd.byname .

-x

Display the map nickname table. This lists the nicknames (mnames) the command knows of, and
indicates the mapname associated with each nickname.

SEE ALSO

ypfiles(5), ypcat(l)

Sun Release 3.2

Last change: 19 August 1985

517

YPPASSWD ( 1 )

USER COMMANDS

YPPASSWD(I)

NAME

yppasswd - change login password in yellow pages
SYNOPSIS

yppasswd [ name ]
DESCRIPTION

Yppasswd changes (or installs) a network password associated with the user name (your own name by
default) in the yellow pages. The yellow pages password may be different from the one on your own
machine.
Yppasswd prompts for the old yellow pages password, and then for the new one. You must type in the old
password correctly for the change to take effect The new password must be typed twice, to forestall mistakes.
New passwords must be at least four characters long, if they use a sufficiently rich alphabet, and at least six
characters long if monocase. These rules are relaxed if you are insistent enough. Only the owner of the
name or the super-user may change a password; in either case you must prove you know the old password.
The yellow-pages password daemon, yppasswdd(8C) must be running on your yP server in order for the
new password to take effect
SEE ALSO

passwd(I), ypfiles(5), yppasswdd(8C)
BUGS

The update protocol passes all the information to the server in one RPC call, without ever looking at it.
Thus if you type in your old password incorrectly, you will not be notified until after you have entered your
new password.

518

Last change: 21 August 1985

Sun Release 3.2

YPWHICH(l)

YPWHICH(l)

USER COMMANDS

NAME

ypwhich - which host is the yP server or map master?
SYNOPSIS

ypwhich [ -d [ domain] ] [ -VII - V2 ] [ hostname ]
ypwhich [ -t mapname ] [ -d domain] -m [ mname ]
ypwhich-x
DESCRIPTION

ypwhich tells which yP server supplies yellow pages services to a yP client, or which is the master for a
map. If invoked without arguments, it gives the yP server for the local machine. If hostname is specified,
that machine is queried to find out which yP master it is using.
Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages.
OPTIONS

-d

Use domain instead of the default domain.

-VI

Which server is serving v.l

-V2

Which server is serving v.2 yP protocol client processes?

yP protocol-speaking

client processes?

If neither version is specified, ypwhich attempts attempts to locate the server that supplies the
(current) v.2 services. If there is no v.2 server currently bound, ypwhich then attempts to
locate the server supplying the v.l services. Since yP servers and yP clients are both backward compatible, the user need seldom be concerned about which version is currently in use.
-t mapname Inhibit nickname translation; useful if there is a mapname identical to a nickname. This is
not true of any Sun-supplied map.
-m

Find the master YP server for a map. No hostname can be specified with -m. mname can
be a mapname, or a nickname for a map. When mname is omitted, produce a list available
maps.

-x

Display the map nickname table. This lists the nicknames (mnames) the command knows
of, and indicates the mapname associated with each nickname.

SEE ALSO

ypfiles(5), rpcinfo(8), ypset(8), ypserv(8)

Sun Release 3.2

Last change: 19 February 1986

519

I

INTRO(6)

GAMES AND DEMOS

INTRO(6)

NAME

intro - introduction to games and demos
DESCRIPTION

This section describes games and demos in alphabetical order.
SEE ALSO
Games, Demos and Other Pursuits: Beginner's Guide

Sun Release 3.2

Last change: 26 December 1985

521

BOGGLETOOL ( 6 )

GAMES AND DEMOS

BOGGLETOOL ( 6)

NAME

boggletool- playa game of boggle
SYNOPSIS
boggletool [number] [+ [+]] [ 16-character string]
DESCRIPTION

Boggletool allows you to play the game of Boggle (TM Parker Bros.) against the computer. The number
argument specifies the time limit in minutes (the default is 3 minutes). If a 16 character long string is
placed on the command line, it is interpreted as a Boggle board: the first four letters form the top row, the
next four letters the second row, etc. If no letters are specified, a board is randomly rolled by the computer
from a set of Boggle cubes. The +[+] argument is explained below under Advanced Play.
PLAYING THE GAME

Rules of the Game The object of Boggle is to find as many words as possible in a 4 by 4 grid of letters
within a certain time limit. Words may be formed from any sequence of 3 or more adjacent letters in the
grid. The letters may join horizontally, vertically, or diagonally. Normally, no letter in the grid may be
used more than once in a word (see Advanced Play for exceptions).
Playing the Game When invoked, boggletool displays a grid of letters and an hourglass. To enter words,
simply type in lower case letters to spell the word you want. Use any whitespace (space, tab, or newline)
to finish a word. To correct mistakes you make, use backspace or DEL to delete the last character, or use
CTRL-U to delete an entire word.
Boggletool verifies that words you enter are both in the grid and are valid English words. If you type in a
character which would form a word which is not in the grid, the display will flash and the character you
typed will not be echoed. When you type any whitespace to end the current word, boggletool will verify
that the word is three or more letters long and that it appears in the dictionary. If the word you typed is illegal for either reason, the display will flash and you will have to either erase the word or change it. If you
try to enter a valid word which you have already entered, the display will flash and the previous occurance
of the word will be highlighted. Again, you will have to erase the word before continuing.
As you enter words, the .. sand" in the hourglass will fall. At the end of the time limit, the display will flash
and you will no longer be allowed to enter words. Mter a moment, the computer will display two lists of
words: the words you found, and other words which also appear in the grid. To play another game, just
type any capital letter (or use the pop-up menu).

Using the Menu The pop-up menu is invoked by pressing the right button. There are four items in it, and
they work as follows. Restart Game causes boggletool to create a new board, reset the timer, and allow
you to start from scratch. Restart Timer allows you to cheat by reseting the hourglass timer to zero. Give
Up causes boggletool to end the game and print the results immediately. Quit allows you to quit running
the boggletool program. A prompt appears asking you to confirm the quit; when it does, click the left button to quit or the right button to abort the quit
Advanced Play There are two options for advanced players. If a single + appears on the command line,
letters in the grid may be reused. If two +'s are on the command line, letters may also be considered adjacent to themselves as well as to their neighbors. Although it is far easier to find words with these two
options, there are also many more possible words in the grid and it is therefore difficult to find them all.
FILES

lusr/games/boggledict

522

dictionary file for computer's words

Lastchange: 14 May 1985

Sun Release 3.2

CANFIELD ( 6)

GAMES AND DEMOS

CANFIELD (6)

NAME

canfield, canfieldtool, cfscores - Canfield solitaire card game
SYNOPSIS

/usr/games/canfieJd
/usr/games/canfieJdtooJ
/usr/gameS/cfscores
DESCRIPTION

canfield can be played on any terminal. canfieldtool is the SunView version with attractive graphics.

If you have never played solitaire before, it is recommended that you consult a solitaire instruction book. In
Canfield, tableau cards may be built on each other downward in alternate colors. An entire pile must be
moved as a unit in building. Top cards of the piles are available to be able to be played on foundations, but
never into empty spaces.
Spaces must be filled from the stock. The top card of the stock also is available to be played on foundations
or built on tableau piles. After the stock is exhausted, tableau spaces may be filled from the talon and the
player may keep them open until he wishes to use them.
Cards are dealt from the hand to the talon by threes and this repeats until there are no more cards in the
hand or the player quits. To have cards dealt onto the talon the player types 'ht' for his move. Foundation
base cards are also automatically moved to the foundation when they become available.
Canfieldtool

Once you understand the rules, canfieldtool is self-explanatory.
Canfield

The command 'c' causes canfield to maintain card counting statistics on the bottom of the screen. When
properly used this can greatly increase ones chances of winning.
The rules for betting are somewhat less strict than those used in the official version of the game. The initial
deal costs $13. You may quit at this point or inspect the game. Inspection costs $13 and allows you to
make as many moves as is possible without moving any cards from your hand to the talon. (the initial deal
places three cards on the talon; if all these cards are used, three more are made available.) Finally, if the
game seems interesting, you must pay the final installment of $26. At this point you are credited at the rate
of $5 for each card on the foundation; as the game progresses you are credited with $5 for each card that is
moved to the foundation. Each run through the hand after the first costs $5. The card counting feature
costs $1 for each unknown card that is identified. If the information is toggled on, you are only charged for
cards that became visible since it was last turned on. Thus the maximum cost of information is $34. Playing time is charged at a rate of $1 per minute.
With no arguments, the program cfscores prints out the current status of your canfield account If a user
name is specified, it prints out the status of their canfield account. If the -a flag is specified, it prints out
the canfield accounts for all users that have played the game since the database was set up.
FILES

/usr/games/canfield
/usr/games/cfscores
/usr/garnesllib/cfscores

the game itself
the database printer
the database of scores

BUGS

It is impossible to cheat

Sun Release 3.2

Last change: 27 May 1986

523

CHESS(6)

GAMES AND DEMOS

CHESS (6)

NAME

chess - the game of chess
SYNOPSIS

lusr/gameslchess
DESCRIPTION
Chess is a computer program that plays class D chess. Moves may be given either in standard (descriptive)
notation or in algebraic notation. The symbol '+' is used to specify check; '0-0' and '0-0-0' specify castling. To play black, type 'first'; to print the board, type an empty line.

Each move is echoed in the appropriate notation followed by the program's reply.
DIAGNOSTICS
The most cryptic diagnostic is 'eh?' which means that the input was syntactically incorrect.
FILES

/usr/games/lib/chess.book book of opening moves
BUGS

Pawns may be promoted only to queens.

524

Last change: 30 September 1984

Sun Release 3.2

GAMES AND DEMOS

CHESSTOOL ( 6)

CHESSTOOL (6)

NAME

chesstool - window-based front-end to chess program
SYNOPSIS
chess tool [ chess'yro gram]
DESCRIPTION

Chesstool is a window-based front-end to the chess(6) program. Used without options, chesstool uses
lusrlgameslchess; you can designate any alternate program which uses the same command syntax as
chess(6) with the chess'yrogram argument.
When chesstool starts up, it displays a large window with three subwindows. The first sub window displays
messages - "Illegal move" , for example. The second subwindow is an options subwindow; options are
described below. The final subwindow is a chessboard display with white and black pieces and two
(advisory only) timekeeping clocks.
Make your moves with the mouse: select a piece by positioning the arrow cursor over the piece and pressing the left mouse button down, then drag the piece to the destination square, and release the button. The
cursor will then turn to an hourglass icon while the system plays.
Options in the options subwindow may be selected with either the left or middle mouse buttons. These
options are:
Last Play

Show the last play made.

Undo

Undo your last move and the machine's response.
Once the game is over, it is not possible to restart it, so undo will update the board,
but the game cannot be continued from that position.

Machine White

Start a new game with the machine playing white.

Human White

Start a new game with the machine playing black.

Quit

Exit from chesstool.

Flash

Flash when the machine has completed its move.
When this command is selected, a check mark will appear next to the word Flash.
In flash mode, if chesstool is open, the piece moved by the system on its play will
flash until you make your move. If chesstool is iconic, the entire icon will flash
when the machine has made its move. Thus you can 'Close' chesstool and be alerted
when it's your turn to move. To turn flash mode off, select flash again.

There are two moves which are special: castling and capturing a pawn en passant. To castle, move the
king only. The position of the rook will automatically be updated. Since the king moves two squares when
castling, the move is unambiguous. To capture en passant, move the pawn to the square occupied by the
opposing pawn which will be captured.
SEE ALSO
chess(6)

Sun Release 3.2

Last change: 20 August 1984

525

GAMMONTOOL (6)

GAMES AND DEMOS

GAMMONTOOL ( 6 )

NAME

gammontool- playa game of backgammon
SYNOPSIS
gammontool [path ]
DESCRIPTION
Gammontool paints a backgammon board on the screen, and then lets you play against the computer. It
must be run in SunWindows. The optional path argument specifies an alternate move-generating program,
which must be specially designed to run with gammontool.

The game has three subwindows: an option window on top, a message window in the middle, and a large
board on the bottom. The buttons in the option window are used to restart, double, etc. The message window has two lines: the first tells whose turn it is, and the second displays any errors that occur.
The initial roll. To start the game, roll the dice to determine who goes first. Move the mouse arrow onto
the board and click the left button. One die appears on each side of the board: the die on the left is yours,
and the die on the right is the computer's. If your roll is greater, then you move; if not, the computer
makes a move.
Making your move. When it is your tum, "Your move" appears in the message window. Place the mouse
over any piece of your color, and click the left button. While holding down the button, move the mouse to
drag the piece; the piece follows the mouse until you release the button. The tool checks each move and
does not allow illegal moves. When you have made as many moves as you can, the computer takes its
turn; after it finishes, you may either roll again, or double.
Doubling. To double, click the Double button in the option window and wait for the computer's response.
If the computer doubles you, a message is displayed and you must answer with the Accept Double or
Refuse Double buttons. The Forfeit button can also be used to refuse a double. If the game is doubled, a
doubling cube with the proper value is displayed on the bar strip. If the number is facing up, then you may
double next. If the number is upside down, it is the computer's turn to double.
Other buttons. If you want to change your move before you have finished it, use the Redo Move or
Redo Entire Move buttons in the option window. Redo Entire Move replaces all of the pieces you have
moved so that you can redo them all. Redo Move only replaces the last piece you moved, so it is useful
when you roll doubles and want to redo only the last piece you moved. Note that once you have made all
of the moves your roll permits, play passes immediately to the computer, so you cannot redo the very last
move. The Show Last Move button allows you to see the last move again.
Leaving the game. If you want to quit playing backgammon, use the Quit button. If you want to foneit the
game, use the Forfeit button. The computer penalizes you by taking a certain number of points, but the
program does not terminate.

To play another game after winning, losing, or foneiting, click the New Game button. To change the color
of your pieces, click the mouse button while pointing at either the White or Black checkboxes. You may
change colors at any time, even in the middle of a game. Changing colors in the middle of a game does not
mean that you trade places with the computer; your pieces stay where they are, but they are repainted with
the new color. Your pieces always move from the top right to the bottom right of the board, regardless of
your color. As an additional cue as to your color, your dice are always displayed on the left half of the
board.
Log file. If a there is a gammonlog file your home directory, gammontool keeps a log of the games played.
Each move and double gets recorded, along with the winners and accumulated scores.
FILES

-Igammon log

log of games played

lusrlgameslliblgammonscores
log of wins and losses

526

Last change: 15 May 1986

Sun Release 3.2

GAMMONTOOL (6)

GAMES AND DEMOS

GAMMONTOOL (6)

BUGS
The default strategy used by the computer is very poor.
If a single move uses more than one die (for instance if you roll 5, 6 and move 11 spaces without touching
down in the middle) it is unpredictable where the program will make the piece touch down. This may be
important if there is a blot on one of these middle points. The program will always make the move if possible, but if two midpoints would work and there is a blot on one of them, it is much better to explicitly hit
the blot and then move the piece the rest of the way.

Sun Release 3.2

Last change: 15 May 1986

527

GAMES AND DEMOS

NAME

gp_demos, flight, rotobj - demonstration programs for the Graphics Processor
SYNOPSIS
8ight

rotobj [object]
DESCRIPTION

These demos only run in windows running on a Graphics Processor surface.
Note:

Optional Software (Games and Demos Option). Refer to Installing UNIX on the Sun Workstation
for information on how to install these demos.

Flight

flight is a mouse-driven flight simulator.
Interactive Commands

Middle-Button

Restart the program.

Right-Button

Increase speed.

Left-Button

Decrease speed.

Move-Mouse-Forward
The airplane dives.
Move-Mouse-Backward
The airplane climbs.
Move-Mouse-LeftJRight
The airplane banks.
LeftJRight-With-Right-Button
The airplane rolls without banking.
Rotobj

rotobj rotates an object. Object files are located in lusrldemolDATA and have the suffix .vecs.
SEE ALSO

graphics_ demos( 6)

528

Last change: 29 May 1986

Sun Release 3.2

GRAPHICS_DEMOS ( 6)

GAMES AND DEMOS

GRAPHICS_DEMOS (6 )

NAME

graphics_demos, bouncedemo, cframedemo, framedemo, goban, jumpdemo, maze, shaded, show,
showmap, spheresdemo, stringart, suncube - graphics demonstration programs
SYNOPSIS

bouncedemo [ -d dev] [ -ox] [ -r ] [ -q ]
cframedemo [ -d dev] [ -ox] [ -r ] [ -q ]
framedemo [ -d dey ] [ -ox] [ -r ] [ -q ]
goban game
jumpdemo [ -c] [ -d dev] [ -ox] [ -r ] [ -q ]
maze
shaded object [ -d dev ]
show raster/tie [ rasterfile ... ]
showmap [ -d dey ] [ -q ]
spheresdemo [ -d dey ] [ -ox] [ -r ] [ -q ]
stringart [ -d dey ] [ -q ]
sun cube [ -d dev] [ -q ]
DESCRIPTION
Note:

Optional Software (Games and Demos Option). Refer to Installing UNIX on the Sun Workstation
for information on how to install these demos.

Bouncedemo

bouncedemo displays a bouncing square.
Cframedemo

cframedemo displays a series of color frames, each of which contains a 256 by 256 image of eight-bit-deep
pixels. cframedemo looks for the frames in the filesframe.l throughframe.n in the current working directory, and displays them in numerical order. When run in the directory lusrldemolglobeframes, cframedemo
displays a rotating view of the world.
Framedemo

framedemo displays a series of frames, each of which contains a 256 by 256 image one-bit-deep pixels
(that is, the image is a square monochrome bitmap, with 256 bits on a side). framedemo looks for the
frames in the filesframe.l throughframe.n in the current working directory, and displays them in numerical order. A set of sample frames is available in the directory lusrldemolglobeframesl*. Interactive Commands
If you move the cursor onto the image surface, you can type certain commands to affect the rate at which
the frames are displayed. The initial rate is one frame per second:
f

removes 1!20th of a second from the interval.

F

removes one second from the interval. Ff makes the interval as small as possible.

s

adds 1I20th of a second.

S

adds one second.

Goban

goban is Japanese for "go board". It is an automatic board, but does not play go. If you invoke it with no
game argument, goban reads from the file masterofgo. This is a transcript of an important historical game
written about by the Nobel Prize winning author, Yasunari Kawabata in The Master of Go, a book which
conveys the ancient and facinating game.

Sun Release 3.2

Last change: 29 May 1986

529

GRAPHICSYEMOS ( 6 )

GAMES AND DEMOS

GRAPHICS_DEMOS ( 6)

Stones are placed on the board by selecting a grid point with the cursor and pressing the left-button. As
stones are played, the color to play next alternates between black and white. The center-button, when
pressed in the board area, backs up a move (undo it). The right-button moves forward in the game.
Stepping backwards and forwards does not alter the game until the left-button is pressed to place a stone, at
which time any moves beyond the current position are discarded.
Jumpdemo
jumpdemo simulates the famous Star Wars jump to light-speed-sequence using vector drawing. Colored

stars are drawn on color surfaces.
Maze
maze creates a random maze-pattern and tries a depth-first solution. If used in lockscreen, remember to run

in "nice" mode since this demo consumes lots of cpu cycles.
Shaded
shaded displays shaded objects. Objects are located in usr/demo/DATA and include an icosahedron, glass,

soccer ball, space shuttle, egg and pyramid. This demo can take up to 40 seconds to start up with som
objects. Mouse input is required:
Interactive Commands

Click the left- and middle-buttons on the left grid to set the x-y orientation. Click the middle-button on the
right grid to set the z orientation. Click the left-button away from either grid to open the features menu,
from which you can make selections using the left-button.
After selecting the desired features, click the left-button away from all objects to exit the features menu.
Click the right-button to begin drawing the object When the figure is finished, click the right-button to
return to the grids and menu, or type q to exit.
Show
show displays rasterfiles in a window or on a raw screen. Sample files are contained in the directory
/usr/demo/COLORPIX. Running

show COLORPIX/*
from /usr/demo will continuously cycle through the sample images.
Spberesdemo
spheresdemo computes a random collection of shaded spheres. Colored spheres are drawn on color sur-

faces.
Showmap
showmap displays 10 map projections continuously until interrupted. Each map is displayed for about 5
seconds. The maps are in the directory lusr/demoIMAPS.
Stringart
stringart continuously displays a different "work of art" every 5 seconds. A total of 24336 different

designs are possible. On color surfaces the designs will loop through the colors: red, olive, green, turquoise, blue, and violet
Suncube

Displays a cube with the SUN logo mapped to each face. Will run continuously until interrupted. On color
surfaces the colors of logo segments change gradually. On monochrome surfaces the logo segments
remain hollow.
OPTIONS

-c

Rotate the color map to produce a sparkling effect.

-dsurface
Run the demo on a surface other than the window or system console, for instance:
bouncedemo -d /dev/cgoneO

-ox

530

Draw x items, or repeat a sequence x times.

Last change: 29 May 1986

Sun Release 3.2

GRAPHICS _DEMOS ( 6)

GAMES AND DEMOS

GRAPIDCS_DEMOS (6)

-r

Retain the window. This allows the image to reappear when uncovered instead of restarting the
demo.

-q

Quick exit. Useful for running several demos from within a shell script

SEE ALSO

gp_demos(6), gfxtool(l)

Sun Release 3.2

Last change: 29 May 1986

531

LIFE(6)

GAMES AND DEMOS

LIFE (6)

NAME

life - John Conway's game of life
SYNOPSIS

life
DESCRIPTION

Life is a program that plays John Conway's game of life. It only runs under suntools(1).
When invoked, life will display a window with a small control panel at the top, and a large drawing area at
the bottom. You can create pieces in the drawing area with the left button, and erase them with the middle
button. When you select Run in the control panel, the pieces will begin to evolve, and the drawing region
will update itself at a speed controlled by the slider labeled with Fast and Slow. Life keeps track of all the
pieces even if they are not visible. The scroll bars surrounding the drawing region can be used to see
pieces that have moved out of view. There are some standard patterns that can be drawn by popping up a
menu in the drawing subwindow.
The meaning of the items in the first row of the control panel (from left to right) are as follows. If you
click on the picture which looks like a tic-tac-toe board, a grid will appear in the drawing region. If you
click on Step, the mode will change from run mode (where the pieces update continuously) to step mode
(where an update is only done when you click on Step). Following Gen is a number indicating the number
of generations that have occured. The button marked Find will scroll so that at least one piece is in view.
This is useful when all the pieces dissappear from view. The button marked Clear will clear the drawing
region, but leave the other controls unchanged. Reset will reset all the panel controls, but will not erase
any of the pieces, and Quit causes the tool to exit. The second row contains two sliders. The first controls
the update speed when in run mode, the second controls the size of the pieces.

532

Last change: 2 May 1986

Sun Release 3.2

SUNVIEW_DEMOS ( 6 )

GAMES AND DEMOS

SUNVIEW_DEMOS ( 6 )

NAME

sunview_ demos, canvas_demo, cursor_demo - Window-System demonstration programs
SYNOPSIS

lusr/demo/canvas_demo
lusr/demo/cursor_demo
DESCRIPTION
Canvas Demo
canvas_demo demonstrates the capabilities of the canvas subwindow package. It consists of two subwindows: a control panel and a canvas. By adjusting the items on the control panel, you can manipulate the
attributes of the canvas, and see the results.
Cursor Demo
cursor_demo demonstrates what you can do with cursors. A single control panel is provide for adjusting
the various cursor attributes. As you adjust the items on the control panel, the panel's cursor changes in
appearance.

Sun Release 3.2

Last change: 29 May 1986

533

INTRO(7)

TABLES

INTRO(7)

NAME

miscellaneous - miscellaneous useful information pages
DESCRIPTION

This section contains miscellaneous documentation, mostly in the area of text processing macro packages
for troff(l).

ascii(7)
eqnchar(7)
hier(7)
rnan(7)

me(7)
ms(7)

Sun Release 3.2

map of ASCII character set
special character definitions for eqn
file system hierarchy
macros to format manual pages
macros for formatting papers
macros for formatting manuscripts

Last change: 9 February 1983

535

ASCII(7)

TABLES

ASCII (7 )

NAME

ascii - map of ASCII character set
SYNOPSIS

cat /usr/pub/ascii
DESCRIPTION
Ascii is a map of the ASCII character set, to be printed as needed. It contains:

Decimal- Character
I 000
1010
1020
I 030
1040
1050
1060
1070
1100
1110
1120
1130
1140
1150
1160
1170

NUL 100 1
BS 1011
DLEI021
CAN I 031
SP 1041
( 1051
o 1061
8 1071
@ 1101
H 1111
p 1121
X 1131
.. 1141
h 1151
p 1161
x 1171

nI 1002
HT 1012
OCII 022
:EM I 032
1042
) 1052
1 1062
9 1072
A 1102
I 1112
Q 1122
y 1132
a 1142
1152
q 1162
y 1172

S1X1 003
NL 1013
OC21 023
SUB I 03 3
" 1043
* 1053
2 1063
1073
B 1103
J 1113
R 1123
Z 1133
b 1143
j 1153
r 1163
z 1173

E1X1 004
VT 1014
OC31 024
E~ I 034
# 1044
+ 1054
3 1064
; 1074
C 1104
K 1114
S 1124
[ 1134
c 1144
k 1154
s 1164
{ 1174

HJf 100 5
NP 1015
OC41025
FS I 035
$ 1045
, 1055
4 1065
< 1075
D 1105
L 1115
T 1125
\ 1135
d 1145
I 1155
t 1165
I 1175

~I 006 A(K I 007
OR 1016 SO 1017
NAKI026 SYNI027
GS I 036 RS I 037
%1046 & 1047
- 1056
1057
5 1066 6 1067
= 1076 > 1077
E 1106 F 1107
M 1116 N 1117
U 1126 V 1127
1137
] 1136
e 1146 f 1147
m 1156 n 1157
u 1166 v 1167
} 1176 - 1177
A

BELl
SI I
Eml
US I

' I
I I
7 I
? I
GI
01

WI
- I
g I
o I
wi
DELI

Hexadecimal- Character
00
08
10
18
20
28
30
38
40
48
50
58

60
68
70
78

NULl
BS I
DLEI
CAN
SP
(
0
8
@

H
P
X

..

h

P
x

01
09
11
19
21
29
31
39
41
49
51
59
61
69
71
79

nI 02 S1X1 03 E1X 04 IDTI 05 Eml 06 ACKI 07 BEL
lIT
OCI
W

OANL I
12 OC21
1A SUB
22
2A *
32 2
3A
42 B
4A J
52 R
5A Z
62 b
6A j
72 r
7A z
It

)

1
9
A
I

Q
y

a
i
q
y

OB VT
13 OC3
IB E~
23 #
2B +
33 3
3B
43 C
4B K
53 S
5B [
63 c
6B k
73 s
7B {

OCNPI
14 OC41
lC FS I
24 $ I
2C , I
34 4 I
3C < I
44 D I
4C L I
54 T I
5C \ I
64 d I
6C I I
74 t I
7C I I

ODOR I
15 NAKI
ID GS I
25 %1
2D - I
35 5 I
3D = I
45 EI
4D M I
55 UI
50 ] I
65 e I
6D m I
75 u I
7D } I

OE SO I
16 SYN
IE RS
26 &
2E
36 6
3E >
46 F
4E N
56 V
5E
66 f
6E n
76 v
7E
A

-

OF
17
IF
27
2F
37
3F
47
4F
57
5F
67
6F
77
7F

SI
Em
US
I
7
?
G
0

W
g
0

w
DELI

FILES

lusr/pub/ascii

536

Last change: 2 June 1986

Sun Release 3.2

EQNCHAR(7)

TABLES

EQNCHAR(7)

NAME

eqnchar - special character definitions for eqn
SYNOPSIS

I troff [ options]
neqn lusr/pub/eqnchar [files] I nrotT [options]

eqn lusr/pub/eqnchar [files]

DESCRIPTION

Eqnchar contains troff and nroff character definitions for constructing characters that are not available on
the Graphic Systems typesetter. These definitions are primarily intended for use with eqn and neqn. It
contains definitions for the following characters
()
ciplus
0
citimes
wig
-wig
> wig
~

<=>
1<

I>

II
I
\
\
I

1i
.J-

+-+

......

*

;f
ang
L
rang
I;3dot
thf
quarter 1/4
3quarter %
0
degree

square
0
circle
0
blot
0
bullet
oc
prop
(0
empty
member E
nomem fiE.
cup
u
cap
n
incl
k
subset
c
supset
::J
!subset ~
!supset ~

FILES

/usr/pub/eqnchar
SEE ALSO

troff( 1), eqn( 1)

Sun Release 3.2

Last change: 1 February 1983

537

HIER(7)

TABLES

HIER(7 )

NAME

bier - file system hierarchy
DESCRIPTION
The following outline gives a quick tour through a typical directory hierarchy.
I
root directory

Ibin

utilitiy pro grams

Ibin/ar
Ibin/as
Ibin/awk
Ibin/cat
Ibin/cc
Ibin/who

ldev
Idev/consol.e
Idev/drum

devices and special files
console terminal
memory paging device

ldev/*mem
ldev/nul.l.

memory special files
system wastebasket

Idev/pty[p-z]*

pseudo-terminal driver(s)

Idev/tty*
ldev/tty[p-z]*
Idev/vme*

terminals
pseudo-terminals
VME bus special files

Idev/win*

window system special files

letc

system administration files & pro grams

letc/cron
letc/fastboot
letc/fasthalt

538

letc/fsck
letc/fstab
letc/group

table of mountable filesystems
system group membership table

letc/hosts
letc/hosts.equiv

list of systems on the network
list of trusted systems

letc/motd
letc/mount
letc/mtab

message-of-the-day file

letc/passwd
letc/printcap

password file
table of printers and capabilities

letc/termcap

table of terminal devices and capabilities

letc/ttys

terminal initialization info

table of mounted file systems

Last change: 1 February 1985

Sun Release 3.2

HIER(7)

TABLES

HIER(7)

/etc/ttytype

table of connected terminals

/etc/utmp
/etc/yp

table of users logged in
system yellow-pages directory

/l.ost+found

detachedfilesystemsfor fsck

/private
/private/usr2

client workstation files
directory for guest accounts

/stand

standalone programs (not run under UNIX)

/usr

general-purpose directory
/usr/name

home directory for name

/usr/name/.cshrc
/usr/name/.1ogin
/usr/name/.1ogout
/usr/name/.exrc
/usr/name/.mai1rc
/usr / name / filename
/usr / name / directory
/ usr / name / directory / filename

/usr/host

/usr directory mountedfrom another host

/usr/adm

system administration files

/usr/adm/lastlog

/usr/bin
/usr/bin/addbib
/usr/bin/adjacentscreens
/usr/bin/align_equals
/usr/bin/at
/usr/bin/basename
/usr/bin/bc
/usr/bin/cal

table of most recent 10gins

more utility programs

/usr/bin/ypwhich
/usr/crash

system crashfiles & programs

/usr/dict

dictionary files

/usr/dict/words

Sun Release 3.2

Last change: 1 February 1985

dictionary wordlist

539

HIER(7)

TABLES

/usr/etc
/usr/etc/ac

HIER(7 )

more system administration files and pro gra

/usr/etc/catman
/usr/etc/yp

yellow pages directory

/usr/games

games and demos

/usr/include

standard C *includefiles

/usr/include/f77

Fortran include files

/usr/include/images

icon images

/usr/include/nfs

NFS include files

/usr/include/pasca1
/usr/include/pixrect

Pascal include files
pixrect include files

/usr/inc1ude/sys

system internals include files

/usr/lib
/usr/lib/.rootmenu
/usr/lib/.suntools
/usr/lib/.textswrc
/usr/1ib/Cshrc
/usr/lib/Ezrc
/usr/lib/Loqin
/usr/lib/Logout
/usr/1ib/Mailrc

library routines and other useful stuff
sample setup files for suntools

sample setup files for for csh, mail and v

/usr/1ib/atrun
/usr/lib/calendar
/usr/1ib/crontab

540

/usr/lib/defaults

directory for window-system defaults

/usr/lib/font

trofffonts

/usr/lib/tmac

troff macro-package files

/usr/loca1

local utility pro grams

/usr/man
/usr/man/cat[1-8]
/usr/man/man[1-8]

Manual Page Sources
formatted pages
source files

Last change: 1 February 1985

Sun Release 3.2

HIER(7)

TABLES

HIER(7)

/usr/preserve

preserves editor files from crashes

/usr/sccs

sces programs

/usr/spool.
/usr/spool./mail.
/usr/spool./l.pd

delayed execution files
system mailboxes
printer queue(s)

/usr/tmp

temporary files

/usr/ucb
/usr/ucb/Mail.
/usr/ucb/biff
/usr/ucb/ccat
/usr/ucb/checknr
/usr/ucb/chsh

programs developed at U.C. Berkeley

SEE ALSO

Is(I), whatis(I), whereis(I), which(I), ncheck(8), find(I), grep(l)

BUGS
The position of files is subject to change without notice.

Sun Release 3.2

Last change: 1 February 1985

541

MAN(7)

TABLES

MAN(7)

NAME

man - macros to format Reference Manual pages
SYNOPSIS

nrotT -man file .. .
trotT -man file .. .
DESCRIPTION

These macros are used to layout the reference pages in this manual.
Any text argument t may be zero to six words. Quotes may be used to include blanks in a 'word'. If text is
empty, the special treatment is applied to the next input line with text to be printed. In this way .I may be
used to italicize a whole line, or .SM followed by .B to make small bold letters.
A prevailing indent distance is remembered between successive indented paragraphs, and is reset to default
value upon reaching a non-indented paragraph. Default units for indents i are ens.
Type font and size are reset to default values before each paragraph, and after processing font and size setting macros.
These strings are predefined by -man:

\*R

'®', '(Reg)' in nroff.

\*S

Change to default type size.

FILES

lusr/lib/tmac/tmac.an
SEE ALSO

troff(I), nroff(I), man(l)
The -man Macro Package, in Formatting Documents on the Sun Workstation.
REQUESTS

Request

.B t
.BI t
.BRt
.DT
.HPi
.It
.IB t

.IPxi
.IR t

LP
.PDd

.PP
.RE
.RBt
.RI t
.RS i
.SRt
.SMt
.TH ned

.TP i

542

Cause If no
Explanation
Break Argument
no
t=n.t.I.* Textt is bold.
no
t=n.t.1.
Join words of t alternating bold and italic .
no
t=n.t.1.
Join words of t alternating bold and Roman .
Restore default tabs .
no
.5i li...
Set prevailing indent to i. Begin paragraph with hanging indent
yes i=p.i.*
no
Text t is italic.
t=n.t.1.
Join words of t alternating italic and bold.
no
t=n.t.1 .
Same as .TP with tag x.
yes x= ""
Join words of t alternating italic and Roman.
no
t=n.t.1 .
yes
Same as .PP.
Interparagraph distance is d.
no
d=.4v
Begin paragraph. Set prevailing indent to .5i.
yes
End of relative indent. Set prevailing indent to amount of starting .RS .
yes
Join words of t alternating Roman and bold.
no
t=n.t.1.
Join words of t alternating Roman and italic.
no
t=n.t.1.
Start relative indent, move left margin in distance i. Set prevailing indent to .5i for
yes i=p.i .
nested indents.
Subhead.
yes
t=n.t1.
Text
t is small.
t=n.t.1.
no
Begin page named n of chapter c; d is the date of the most recent change. Sets preyes
vailing indent and tabs to .5i.
Set prevailing indent to i. Begin indented paragraph with hanging tag given by next
yes i=p.i .
text line. If tag doesn't fit, place it on separate line.

Last change: 5 June 1986

Sun Release 3.2

MAN(7)

TABLES

MAN(7)

* n.tl. = next text line; p.i. = prevailing indent
CONVENTIONS

A typical manual page for a command or function is laid out as follows:
.TH TITLE [1-8]
The name of the command or function in upper-case, which serves as the title of the manual page.
This is followed by the number of the section in which it appears .
.SH NAME name (or comma-separated list of names) - one-line summary
The name, or list of names, by which the command is called, followed by a dash and then a oneline summary of the action performed. All in roman font, this section contains no troff(l) commands or escapes, and no macro requests. It is used to generate the whatis(l) database.
.SH SYNOPSIS
Commands:
The syntax of the command and its arguments as typed on the command line. When in
boldface, a word must be typed exactly as printed. When in italics, a word can be
replaced with text that you supply. Syntactic symbols appear in roman face:
[]

An argument, when surrounded by brackets is optional.

Arguments separated by a vertical bar are exclusive. You can supply only item
from such a list.
Arguments followed by an elipsis can be repeated. When an elipsis follows a
bracketed set, the expression within the brackets can be repeated.
Functions:
If required, the data declaration, or #include directive, is shown first, followed by the
function declaration. Otherwise, the function declaration is shown .
.SH DESCRIPTION
A narrative description of the command or function in detail, including how it interacts with files
or data, and how it handles the standard input, standard output and standard error.
Filenames, and references to commands or functions described elswhere in the manual, are italicised. The names of options, variables and other literal terms are in boldface.
.SHOPTIONS
The list of options along with a description of how each affects the commands operation .
.SHFILES
A list of files associated with the command or function .
.SH "SEE ALSO"
A comma-separated list of related manual pages, followed by references to other published
materials. This section contains no troff(1) escapes or commands, and no macro requests .
.SH DIAGNOSTICS
A list of diagnostic messages and an explanation of each .
.SHBUGS
A description of limitations, known defects, and possible problems associated with the command
or function.

Sun Release 3.2

Last change: 5 June 1986

543

TABLES

ME(7)

ME(7)

NAME

me - macros for formatting papers
SYNOPSIS

BrotT -me [ options] file ...
trotT -me [ options ] file .. .
DESCRIPTION

This package of nroff and troff macro definitions provides a canned formatting facility for technical papers
in various formats. When producing 2-column output on a terminal, filter the output through col (I).
The macro requests are defined below. Many nroff and troffrequests are unsafe in conjunction with this
package, however these requests may be used with impunity after the. first .pp:
.bp
.br
.sp n
.Is n
.na
.ce n
.ul n
.sz +n

begin new page
break output line here
insert n spacing lines
(line spacing) n= I single, n=2 double space
no alignment of right margin
center next n lines
underline next n lines
add n to point size

Output of the eqn, neqn, refer, and tbl(l) preprocessors for equations and tables is acceptable as input
FILES

lusrllib/tmac/tmac.e
lusrllib/me/*
SEE ALSO

eqn( I), nroff( I), troff(l), refer( I), tbl( I)
The -me Macro Package, in Formatting Documents on the Sun Workstation.
REQUESTS

In the following list, "initialization" refers to the first .pp, .Ip, .ip, .np, .sh, or .uh macro. This list is incomplete; see The -me Reference Manual for interesting details.
Request
.(c
.(d
.(f
.(1
.(q
.(xx

.(z
.)c

.)d
.)f
.)1

.)q
.)x
.)z
.++mH

.+cT
. Ic
.2c

544

Initial Cause Explanation
Value Break
yes Begin centered block
no
Begin delayed text
no
Begin footnote
yes Begin list
yes Begin major quote
no
Begin indexed item in index x
no
Begin floating keep
yes End centered block
yes End delayed text
yes End footnote
yes End list
yes End major quote
yes End index item
yes End floating keep
no
Define paper section. m defines the part of the paper, and can be C (chapter), A (appendix), P (preliminary, e.g., abstract, table of contents, etc.), B (bibliography), RC (chapters
renumbered from page one each chapter), or RA (appendix renumbered from page one).
yes Begin chapter (or appendix, etc., as set by .++). Tis the chapter title .
I
yes One column format on a new page .
I
yes Two column format.

Last change: 5 June 1986

Sun Release 3.2

ME(7)

TABLES

.EN
.EQxy

yes
yes

.TE
.TH
.TSx
.acAN

yes
yes
yes
no

.bx
.ba +n

no

0

no
yes

no
.bc
.bix
no
.bxx
no
.ef 'x'y'z'
.eh 'x'y'z'
.fo 'x'y'z'
.hx
.he 'x'y'z'
.hl
.ix
no
.ipxy
no
.1p
yes
.10
.np
1
.of 'x'y'z'
.oh x'y'z'
.pd
.pp
no
.r
yes
.re
no
.sc

yes
no
no
no
no
no
no
no
yes
no
yes
yes
no
yes
no
no
yes
yes
no
no
no

.shnx
.sk
.sz +n
.th
.tp
.ux
.uh
.xpx

yes
no
no
no
yes
no
yes
no

no

lOp
no
no

Sun Release 3.2

ME(7)

Space after equation produced by eqn or neqn .
Precede equation; break out and add space. Equation number is y. The optional argument
x may be I to indent equation (default), L to left-adjust the equation, or C to center the
equation.
End table .
End beading section of table .
Begin table; if x is H table has repeated heading.
Set up for ACM style output. A is the Author's name(s), N is the total number of pages .
Must be given before the first initialization.
Print x in boldface; if no argument switch to boldface.
Augments the base indent by n. This indent is used to set the indent on regular text (like
paragraphs) .
Begin new column
Print x in bold italics (nofill only)
Print x in a box (nofill only) .
Set even footer to x y z
Set even header to x y z
Set footer to x y z
Suppress headers and footers on next page.
Set header to x y z
Draw a horizontal line
Italicize x; if x missing, italic text follows .
Start indented paragraph, with hanging tag x. Indentation is yens (default 5) .
Start left-blocked paragraph .
Read in a file of local macros of the form. *x. Must be given before initialization.
Start numbered paragraph.
Set odd footer to x y z
Set odd header to x y z
Print delayed text.
Begin paragraph. First line indented.
Roman text follows.
Reset tabs to default values.
Read in a file of special characters and diacritical marks. Must be given before initialization.
Section head follows, font automatically bold. n is level of section, x is title of section.
Leave the next page blank. Only one page is remembered ahead .
Augment the point size by n points.
Produce the paper in thesis format. Must be given before initialization .
Begin title page .
Underline argument (even in trofJ). (Nofill only).
Like .sh but unnumbered.
Print index x.

Last change: 5 June 1986

545

MS(7)

TABLES

MS(7)

NAME
InS -

text formatting macros

SYNOPSIS
nrotT -ms [options] file .. .
trotT -ms [options] file .. .
DESCRIPTION
This package of nroff and troff macro definitions provides a formatting facility for various styles of articles, theses, and books. When producing 2-colurnn output on a terminal or lineprinter, or when reverse line
motions are needed, filter the output through col(I). All external-ms macros are defined below.

Note that this -ms macro package is an extended version written at Berkeley and is a superset of the standard - ms macro packages as supplied by Bell Labs. Some of the Bell Labs macros have been removed;
for instance, it is assumed that the user has little interest in producing headers stating that the memo was
generated at Whippany Labs.
Many nroff and troff requests are unsafe in conjunction with this package. However, the first four requests
below may be used with impunity after initialization, and the last two may be used even before initialization:
.bp
begin new page
.br
break output line
.sp n
insert n spacing lines
.ce n
center next n lines
.Is n
line spacing: n= 1 single, n=2 double space
.na
no alignment of right margin
Font and point size changes with \f and \s are also allowed; for example, "\flword\fR" will italicize word.
Output of the tbl(I), eqn(l) and refer(1) preprocessors for equations, tables, and references is acceptable
as input.
FILES

lusr/lib/tmac/tmac.s
lusr/lib/mslms. ?1?
SEE ALSO
eqn(I), refer(I), tbl(I), troff(l)

The -ms Macro Package, in Formatting Documents on the Sun Workstation.
REQUESTS
Macro
Name

Initial
Value

.AB.x
.AE
.AI
.AM
.AU

.Bx
.Bl
.B2
.BT

date

.BXx
.CM
.CT

ift

.DAx

ifn

.DE

.DSxy
.IDy

546

I
8n,.5i

Break?
Reset?
y
y
y
n
y
n
y
y
n
n
n
y,y
n
y
y
y

Explanation
begin abstract; if x=no don't label abstract
end abstract
author's institution
better accent mark definitions
author's name
embolden x; if no x, switch to boldface
begin text to be enclosed in a box
end boxed text and print it
bottom title, printed at foot of page
print word x in a box
cut mark between pages
chapter title: page number moved to CF (TM only)
force date x at bottom of page; today if no x
end display (unfilled text) of any kind
begin display with keep; x =I,L,C,B; y =indent
indented display with no keep; y =indent

Last change: 5 June 1986

Sun Release 3.2

MS(7)

TABLES

.LD
.CD
.BD

.EFx
.EHx
.EN
.EQxy

.FE
.FP
.FSx
.HD

undef

.Ix
.IPxy
.IXxy
.KE
.KF
.KS

LG
LP
.MCx
NDx
NHxy
.NL
.OFx
.OHx

ift

lOp

.PI
.PP

ifTM

.PT
.PXx
.QP
.R

- %-

.RE
.RPx
.RS
.SH
.SM
.TA
.TCx
.TE
.TH
.TL
.TM
.TSx
.ULx
.UXx
.XAxy
.XE
.XP
.XSxy
.1C
.2C
.].[0

Sun Release 3.2

on
5n
5n

8n,5n

off

on

y
y
y
n
n
y
y
n
n
n
n
n
y,y
y
n
n
y
n
y,y
y,y
n
y,y
n
n
n
n
y,y
n
y
y,y
n
y,y
n
y,y
y,y
n
n
y
y
y
y
n
y,y
n
n
y
y
y,y
y
y,y
y,y
n
n

MS(7)

left display with no keep
centered display with no keep
block display; center entire block
even page footer x (3 part as for .tl)
even page header x (3 part as for .tl)
end displayed equation produced by eqn
break out equation; x =L,I,C; y =equation number
end footnote to be placed at bottom of page
numbered footnote paragraph; may be redefined
start footnote; x is optional footnote label
optional page header below header margin
italicize x ; if no x, switch to italics
indented paragraph, with hanging tag x ; y =indent
index words x y and so on (up to 5 levels)
end keep of any kind
begin Boating keep; text fills remainder of page
begin keep; unit kept together on a single page
larger; increase point size by 2
left (block) paragraph.
multiple columns; x =column width
no date in page footer; x is date on cover
numbered header; x =level, x =0 resets, x =S sets to y
set point size back to normal
odd page footer x (3 part as for .tl)
odd page header x (3 part as for .tl)
print header on 1st page
paragraph with first line indented
page title, printed at head of page
print index (table of contents); x =no suppresses title
quote paragraph (indented and shorter)
return to Roman font
retreat: end level of relative indentation
released paper format; x =no stops title on 1st page
right shift: start level of relative indentation
section header, in boldface
smaller; decrease point size by 2
set tabs to 8n 16n ... (nroft) 5n IOn ... (troft)
print table of contents at end; x =no suppresses title
end of table processed by tbl
end multi-page header of table
title in boldface and two points larger
UC Berkeley thesis mode
begin table; if x =H table has multi-page header
underline x, even in trolf
UNIX; trademarlc message first time; x appended
another index entry; x =page or no for none; y =indent
end index entry (or series of .IX entries)
paragraph with first line exdented, others indented
begin index entry; x =page or no for none; y =indent
one column format, on a new page
begin two column format
beginning of refer reference
end of unc1assifiable type of reference

Last change: 5 June 1986

547

MS(7)

TABLES

.[N

n

MS(7)

N= l:journal-artic1e, 2:book, 3:book-article, 4:report

REGISTERS

Formatting distances can be controlled in -ms by means of built-in number registers. For example, this
sets the line length to 6.S inches:
.m LL 6.Si
Here is a table of number registers and their default values:
Name Register Controls Takes Effect Default
PS
point size
paragraph 10
VS
vertical spacing paragraph 12
LL
line length
paragraph 6i
LT
title length
next page same as LL
FL
footnote length
next .FS
S.5i
PD
paragraph distance paragraph 1v (if n), .3v (if t)
DD display distance displays
1v (if n), .Sv (if t)
PI
paragraph indent paragraph Sn
QI
quote indent
next .QP
Sn
FI
footnote indent
next .FS
2n
PO
page offset
next page 0 (if n), -Ii (if t)
HM header margin
next page
Ii
PM footer margin
next page
Ii
FF
footnote format next .FS
0 (1, 2, 3 available)
When resetting these values, make sure to specify the appropriate units. Setting the line length to 7, for
example, will result in output with one character per line. Setting FF to 1 suppresses footnote superscripting; setting it to 2 also suppresses indentation of the first line; and setting it to 3 produces an .IP-like footnote paragraph.
Here is a list of string registers available in -ms; they may be used anywhere in the text:
Name
String's Function
\*Q
quote (" in nroff, " in troff)
\*U
unquote (" in nroff, " in troff)
\ *dash (-- in nroff, - in troff)
\*(MO
month (month of the year)
\*(DY
day (current date)
\**
automatically numbered footnote
\*'
acute accent (before letter)
\*'
grave accent (before letter)
\*,.
circumflex (before letter)
\*,
cedilla (before letter)
\*:
umlaut (before letter)
\*_
tilde (before letter)
When using the extended accent mark definitions available with .AM, these strings should come after,
rather than before, the letter to be accented.
BUGS

Floating keeps and regular keeps are diverted to the same space, so they cannot be mixed together with
predictable results.

548

Last change: S June 1986

Sun Release 3.2

I

INTRO(8)

MAINTENANCE COMMANDS

INTRO(8)

NAME

intro - introduction to system maintenance and operation commands
DESCRIPTION
This section contains information related to system bootstrapping, operation and maintenance. It describes
all the server processes and daemons that run on the system, as well as standalone (PROM monitoR) programs.

Disk formatting and labelling is done by diag(8S). Bootstrapping of the system is described in boot(8S)
and init(8). The standard set of commands run by the system when it boots is described in Tc(8). Related
commands include those that check the consistency of file systems,fsck(8); those that mount and unmount
file systems, mount(8); add swap devices, swapon(8); force completion of outstanding disk I/O, sync(8);
shutdown or reboot a running system shutdown(8), halt(8), and reboot(8); and, set the time on a machine
from the time on another machine rdate(8).
Creation of file systems is discussed in mJifs(8) and newfs(8). File system performance parameters can be
adjusted with tunefs(8). File system backups and restores are described in dump(8) and restore (8).
Procedures for adding new users to a system are described in adduser(8), using vipw(8) to lock the passowrd file during editing.
Other programs that are useful when the system crashes or hardware is broken include gxtest(8S) which
tests the frame buffer on a workstation, imemtest(8S) which tests the memory, crash(8S) which describes
what happens when the system crashes, savecore (8) and analyze (8), which can be used to analyze system
crash dumps. Occasionally useful as adjuncts to the fsck(8) file system repair program are ciri(8),
dcheck(8), icheck(8), and ncheck(8).
Configuring a new version of the UNIX kernel requires using the program config(8); major system
bootstraps often require the use of mkproto(8). New devices are added to the /dev directory (once device
drivers are configured into the system) using makedev(8) and mknod(8). The install(8) command can be
used to install freshly compiled programs. The catman (8) command preformats the on-line manual pages.
Resource accounting is enabled by the accton(8) command, and summarized by sa(8). Login time
accounting is performed by ac(8).
A number of servers and daemon processes are described in this section. The update(8) daemon forces
delayed disk I/O to occur and cron(8) runs periodic events (such as removing temporary files from the disk
periodically). The dmesg(8) process is invoked by cron and keeps the system error log. The init(8) process is the initial process created when UNIX boots. It manages the reboot process and creates the initial
login prompts on the various system terminals, using getty(8). The Internet super-server inetd(8C) invokes
all other internet servers as needed. These servers include the remote shell servers rshd (8C) and
rexecd(8C), the remote login server riogind(8C), the FTP and TELNET daemons /tpd(8C), and
telnetd(8C), the TFTP daemon t/tpd(8C), and the mail arrival notification daemon comsat(8C). Other network daemons include the 'load average/who is logged in' daemon rwhod(8C), the routing daemon
routed (8C), and the mail daemon sendmail (8).
If network protocols are being debugged, then the protocol debugging trace program trpt(8C) is often useful. Remote magnetic tape access is provided by rsh and rmt(8C). Remote line printer access is provided
by lpd(8), and control over the various print queues is provided by Ipc(8). Printer cost-accounting is done
through pac(8).

Network host tables may be gotten from the ARPA NIC using gettable(8C) and converted to UNIX-usable
format using htable(8).
RCP and NFS daemons include:
/ect/portmap
used by rpc based services.
letclypbind
used by the yellowpages to locate the yellowpages server.

Sun Release 3.2

Last change: 1 February 1985

551

INTRO(8)

MAINTENANCE COMMANDS

INTRO(8)

letclbiod
used by NFS clients to read ahead to, and write behind from, network file systems.

lectlnfsd
only on NFS servers, the server's counterpart to letclbiod.

Ietclypserv
implements the yellowpages server, typically on each nd server.
lusrletclrpc.rstatd
the server counterpart ofthe remote speedometer tools.
lusrletc.mountd
the server counterpart to mount.
lusrletclrcp.rwalld
used for broadcasting messages over the network.
LIST OF PROGRAMS
Program
Appears on Page

ac
adbgen
accton
adbgen
adduser
analyze
arp
biod
boot
catman
chown
chroot
clri
comsat
config
crash
cron
dcheck
diag
dkinfo
dmesg
dump
dumpfs
edquota
eeprom
etherd
fastboot
fasthalt
fparel
fpaversion
fsck
fsirand
ftpd
gettable
getty
gpconfig

552

ac(8)
adbgen(8)
sa(8)
adbgen(8)
adduser(8)
analyze(8)
arp(8C)
nfsd(8)
boot(8S)
catman(8)
chown(8)
chroot(8)
clri(8)
comsat(8C)
config(8)
crash(8S)
cron(8)
dcheck(8)
diag(8S)
dkinfo(8)
dmesg(8)
dump(8)
dumpfs(8)
edquota(8)
eeprom(8)
etherd(8)
fastboot(8)
fastboot(8)
fparel(8)
fpaversion(8)
fsck(8)
fsirand(8)
ftpd(8C)
gettable(8C)
getty(8)
gpconfig(8)

Description
login accounting
generate adb script
system accounting
generate adb script
procedure for adding new users
Virtual UNIX postmortem crash analyzer
address resolution display and control
NFSdaemon
start UNIX or a standalone program
create the cat files for the manual
change owner
change root directory for a command
clear i-node
biffserver
build system configuration files
what happens when the system crashes
clock daemon
file system directory consistency check
General-purpose stand-alone utility package
report information about a disk's geometry and partitioning
collect system diagnostic messages to form error log
incremental file system dump
dump file system information
edit user quotas
Sun-3 EEPROM display and load utility
Ethernet statistics server
reboot/halt the system without checking the disks
reboot/halt the system without checking the disks
Sun FPA online reliability tests
print FPA version
file system consistency check and interactive repair
install random inode generation numbers
DARPA Internet File Transfer Protocol server
get NIC format host tables from a host
set terminal mode
initialize the Graphics Processor

Lastchange: 1 February 1985

Sun Release 3.2

INTRO(8)

grpck
pwck(8)
gxtest
gxtest(8S)
halt(8)
halt
htable
htable(8)
icheck
icheck(8)
ifconfig
ifconfig(8C)
imemtest
imemtest(8S)
inetd
inetd(8C)
init(8)
init
iostat
iostat(8)
kadb
kadb(8S)
kgmon
kgmon(8)
link
link(8)
lockd
lockd(8C)
Ipc(8)
lpc
lpd
Ipd(8)
mails tats
mailstats(8)
makedbm
makedbm(8)
MAKEDEV makedev(8)
makekey
makekey(8)
mc68881 version
mconnect
mconnect(8)
mkfs
mkfs(8)
rnknod
rnknod(8)
mkproto
mkproto(8)
monitor
monitor(8S)
mount
mount(8)
named
named(8C)
ncheck
ncheck(8)
nd(8C)
nd
nets tat
netstat(8C)
new aliases
newaliases(8)
newfs
newfs(8)
nfsd(8)
nfsd
nfsstat
nfsstat(8)
pac(8)
pac
ping
ping(8)
pstat(8)
pstat
pwck(8)
pwck
quot(8)
quot
quotacheck(8)
quotacheck
quotaoff
qoutaon(8)
qoutaon(8)
quotaon
rarp(8C)
rarpd
rc(8)
rc
rc(8)
rc.boot
rc(8)
rc.1ocal
rdate(8)
rdate
reboot
reboot(8)
renice
renice(8)
repquota
repquota(8)
restore
restore(8)
rexd
rexd(8C)

Sun Release 3.2

MAINTENANCE COMMANDS

INTRO(8)

password file checker
stand alone test for the Sun video graphics board
stop the processor
convert NIC standard format host tables
file system storage consistency check
configure network interface parameters
stand alone memory test
internet services daemon
process control initialization
report I/O statistics
adb-like kernel and standalone-program debugger
generate a dump of the operating system's profile buffers
exercise link system calls
network lock daemon
line printer control program
line printer daemon
print statistics collected by sendmail(8)
make a Yellow Pages dbm file
make system special files
generate encryption key
mc68881 version(8)print the MC68881 mask number and approximate clock rate
connect to SMTP mail server socket
construct a file system
build special file
construct a prototype file system
PROM monitor and command interpreter
mount and unmount file system
Internet domain name server
generate names from i-numbers
network disk control
show network status
rebuild the data base for the mail aliases file
construct a new file system
NFSdaemon
NFS statistics
printer/plotter accounting information
network debugging
print system facts
password file checker
summarize file system ownership
check file system quota consistency
turn file system quotas off
turn file system quotas on
DARPA Reverse Address Resolution Protocol service
command script for multi-user reboot
command script for system boot
command script for multi-user reboot
set system date from a remote host
UNIX bootstrapping procedures
alter priority of running processes
summarize quotas for a file system
incremental file system restore
RPC-based remote execution server

Last change: 1 February 1985

553

INTRO(8)

rexecd
rlogind
rmail

rmt
route
routed
rpcinfo
rshd
rstatd
rusersd
rwalld
rwhod
sa
savecore
sendmail
setup
showmount
shutdown
skyversion
spray
sprayd
statd
sticky
swapon
sync
sysdiag
syslog
talkd
telnetd
tftpd

timed
tnamed
trpt
tunefs
umount
unlink
update
uuclean
vipw
vrnstat
ypinit
ypmake
yppasswd
yppoll
yppush
ypserv
ypset
ypwhich
ypxfr

554

MAIN1ENANCE COMMANDS

rexecd(8C)
rlogind(8C)
rmail(8)
rmt(8C)
route(8C)
routed(8C)
rpcinfo(8)
rshd(8C)
rstatd(8C)
rusersd(8C)
rwalld(8C)
rwhod(8C)
sa(8)
savecore(8)
sendmail(8)
setup(8S)
showmount(8)
shutdown(8)
skyversion(8)
spray(8C)
sprayd(8C)
statd(8C)
sticky(8)
swapon(8)
sync(8)
sysdiag(8)
syslog(8)
talkd(8C)
telnetd(8C)
tftpd(8C)
timed(8C)
tnamed(8C)
trpt(8C)
tunefs(8)
mount(8)
link(8)
update(8)
uuclean(8C)
vipw(8)
vmstat(8)
ypinit(8)
ypmake(8)
yppasswdd(8c)
yppoU(8)
yppush(8)
ypserv(8)
ypset(8)
ypwhich(8)
ypxfr(8)

INTRO(8)

remote execution server
remote login server
handle remote mail received via uucp
remote magtape protocol module
manually manipulate the routing tables
network routing daemon
report RPC information
remote shell server
kernel statistics server
network users name server
network rwall server
system status server
system accounting
save a core dump of the operating system
send mail over the internet
Sun UNIX installation program
show all remote mounts
close down the system at a given time
print the SKYFFP board microcode version number
spray network packets
spray server
network status monitor
executable files with persistent text
specify additional device for paging and swapping
update the super block
system diagnostics
log systems messages
server for talk program
DARPA TELNET protocol server
DARPA Trivial File Transfer Protocol server
DARPA Time server
DARPA Trivial name server
transliterate protocol trace
tune up an existing file system
mount and dismount file system
exercise unlink system calls
periodically update the super block
uucp spool directory clean-up
edit the password file
report virtual memory statistics
build and install yellow pages database
rebuild yellow pages database
server for modifying yellow pages password file
what version of a yP map is at a yP server host
force propagation of a changed yP map
yellow pages server and binder processes
point ypbind at a particular server
what machine is the yP server?
transfer a yP map from some yP server to here

Last change: 1 February 1985

Sun Release 3.2

AC(8)

MAINTENANCE COMMANDS

AC(8)

NAME

ac - login accounting
SYNOPSIS

lusr/etclac [ -w wtmp] [ -p ] [ -d ] [ people] ...
DESCRIPTION
Ac produces a printout giving connect time for each user who has logged in during the life of the current
wtmp file. A total is also produced.

The accounting file lusrladmlwtmp is maintained by init and login. Neither of these programs creates the
file, so if it does not exist no connect-time accounting is done. To start accounting, it should be created
with length O. On the other hand if the file is left undisturbed it will grow without bound, so periodically
any information desired should be collected and the file truncated.
OPTIONS
-w

specifies an alternate wtmp file.

-p

prints individual totals; without this option, only totals are printed.

-d

printout for each midnight to midnight period. Any people will limit the printout to only the
specified login names. If no wtmp file is given, lusrladmlwtmp is used.

FILES

lusr/adm!wtrnp
SEE ALSO

init(8), sa(8), 10gin(I), utrnp(5).

Sun Release 3.2

Last change: 4 February 1983

555

ADBGEN(8)

MAINTENANCE COMMANDS

ADBGEN(8)

NAME

adbgen - generate adb script
SYNOPSIS

lusrlIib/adb/adbgen file.adb ...
DESCRIPTION

Adbgen makes it possible to write adb(l) scripts that do not contain hard-coded dependencies on structure
member offsets. The input to adbgen is a file namedjile.adb which contains adbgen header information,
then a null line, then the name of a structure, and finally an adb script Adbgen only deals with one structure per file; all member names are assumed to be in this structure. The output of adbgen is an adb script in
jile. Adbgen operates by generating a C program which determines structure member offsets and sizes,
which in turn generates the adb script.
The header lines, up to the null line, are copied verbatum into the generated C program. Typically these
include C #include statements to include the header files containing the relevant structure declarations.
The adb script part may contain any valid adb commands (see adb(l», and may also contain adbgen
requests, each enclosed in {}s. Request types are:
1

Print a structure member. The request form is {member format}. Member is a member name of
the structure given earlier, and format is any valid adb format request For example, to print the
p yid field of the proc structure as a decimal number, you would write {pJlid,d}.

2

Reference a structure member. The request form is {*member,base}. Member is the member
name whose value is desired, and base is an adb register name which contains the base address of
the structure. For example, to get the p yid field of the proc structure, you would get the proc
structure address in an adb register, say  b [ device [ (c ,u,p) ] ] [filename] [ -a ] boot-flags
>b?
> b!
DESCRIPTION
The boot program is started by the PROM monitor and loads the UNIX kernel, or another executable program, into memory.

The form b? displays all boot devices and their device arguments.
The form b! boots, but does not perfonn a RESET.
Booting Standalone
When booting standalone, the boot program (/boot) is brought in by the PROM from the file system. This
program contains drivers for all devices.
Booting a Sun-3 Over the Network
When booting over the network, the Sun-3 PROM obtains a version of the boot program from a server using
tftp(I). The client broadcasts a RARP request containing its Ethernet address. A server responds with the
cli.ent's Internet address. The client then sends a tftp request for its boot program to that server (or if that
fails, it broadcasts the request). The filename requested (unqualified - not a pathname) is the hexadecimal, uppercase representation of the client's Internet address, for example:

Using IP Address 192.9.1.17

=

C0090111

When the Sun server receives the request, it looks in the directory /tftpboot for filename. That file is typically a symbolic link to the client's boot program, normally ndboot.sun3.pubO in the same directory. The
files ndboot.sun3.publ and ndboot.sun3.private are also valid (there may be others). These files can be
used to boot by default from an alternate public, or from a private nd (8C) partition. If you link to one of
these other files, then the client will boot from the corresponding partition by default.
The server then transfers the file to the client. When successfully read in by the client, the boot program
will jump to the load-point, and load vmunix (or a standalone program). If the program is not read in successfully, boot responds with a short diagnostic message.
Booting a Sun-2 Over the Network
The Sun-2 boots from its nd server directly. The "boot block" loads /pub/boot, which in tum loads and
runs vmunix, the system kernel.

UNIX Startup
Once it is loaded and running, the kernel performs some internal housekeeping, configuration of device
drivers and allocation of internal tables and buffers. It then starts process number 1 to run init(8), to perform file system housekeeping, start system daemons, initialize the system console, and begin multiuser
operation. Some of these activities can be skipped if init(8) is invoked when certain boot-flags, entered as
arguments to the boot command, are passed along to init(8) by the kernel.
OPTIONS
device

is one of:

ie
ec
Ie
sd

st
mt

xt
xy

562

Intel Ethernet
3Com Ethernet
Lance Ethernet (Sun 3-50)
SCSI disk
SCSI 114" tape
Tape Master 9-track 1/2" tape
Xylogics 112" tape
Xylogics 440/450 disk

Last change: 30 June 1986

Sun Release 3.2

BOOT(8S)

MAINTENANCE COMMANDS

BOOT(8S)

e

is a controller number,O if there only one controller for the indicated type of device.

u

is a unit number, 0 if only one driver. (Over the network, the unit number is the host portion of
the file server's IP address).

p

designates a partition. The value you supply is exclusive-or'd with that of the default partition
(indicated by the selected boot program, see Booting a Sun-3 Over the Network. above).

filename
is the name of a standalone program in the selected partition, such as standldiagor vmunix. Note
that filename is relative to the root of the selected device and partition. It never begins with /. If
filename is not given, the boot program uses a default value (normally vmunix). This is stored in
the "vmunix" variable in the boot executable file supplied by Sun, but can be patched to indicate
another standalone program loaded using adb(l).

-a

prompt interactively for the device and name of the file to boot.

boot-flags
The boot program passes all boot-flags to the kernel or standalone program. They are typically
arguments to that program or, as with those listed below, arguments to progams that it invokes.
-b

Pass the -b flag through the kernel to init(8) to skip execution of the re.loeal script

-b

Halt after loading UNIX.

-s

Pass the -s flag through the kernel to init(8) for single-user operation.

FILES

Iboot
Itftpbootl????????
Itftpbootlndboot.sun3.pub[OJJ
Itftpbootlndboot.sun3 .private
Itftpbootlndboot.sun2.*
lusrlmdeclinstallboot

the standalone boot program
a symbolic link to the boot program for a client
programs to boot from a public nd partition
program to boot from a private nd partition
Sun-2 boot programs (currently unusable)
script to install boot blocks from a remote host

SEE ALSO
init(8), kadb(8S), monitor(8s), rc(8), reboot(8)

System Administration for the Sun Workstation
Installing UNIX on the Sun Workstation
BUGS

On the Sun-2, the PROM passes in the default name "vrnunix", overriding the the boot program's patchable default.

Sun Release 3.2

Last change: 30 June 1986

563

MAThITENANCECO~ANDS

CATMAN(8)

CATMAN(8)

NAME

catman - create the cat files for the manual
SYNOPSIS

lusr/etc/catman [ -p] [ -n] [ -w] [-t] [ -M directory] [ - T tmac.an] [sections]
DESCRIPTION

Catman creates the preformatted versions of the on-line manual from the nroff input files. Each manual
page is examined and those whose preformatted versions are missing or out of date are recreated. If any
changes are made, catman recreates the whatis database.
If there is one parameter not starting with a '-', it is taken to be a list of manual sections to look in. For
example

catman 123
only updates manual sections 1,2, and 3.
If an unformatted source file contains only a line of the form ".so manx/yyy .x", a symbolic link is made in
the catx or fmtx directory to the appropriate preformatted manual page. This feature allows easy distribution of the preformatted manual pages among a group of associated machines with rdist(I), since it makes
the directories of preformatted manual pages self-contained and independent of the unformatted entries.
OPTIONS
-D

Do not (re)create the whatis database.

-p

Print what would be done instead of doing it

-w

Only create the wbatis database. No manual reformatting is done.

-t

Create troffed entries in the appropiate fmt subdirectories instead of nroffmg into the cat subdirectories.

-M

update manual pages located in the specified directory (Iusrlman by default).

-T

Use tmac.an in place of the standard manual page macros.

FILES
lusr/man
lusr/manlman?I*. *
lusr/manlcat?I*. *
lusr/manlfmt?I*. *

lusr/manlwhatis
lusr/lib/makewhatis

default manual directory location
raw (nroff input) manual sections
preformatted nroffed manual pages
preformatted troffed manual pages
whatis database location
command script to make whatis database

ENVIRONMENT
TROPP

The name of the formatter to use when the -t flag is given. If not set, 'troff' is used

DIAGNOSTICS
man?/xxx.? (.so'ed from man?/yyy.?): No such file or directory
The file outside the parentheses is missing, and is referred to by the file inside them.

target of .so in man?/xxx.? must be relative to lusr/man
catman only allows references to filenames that are relative to the directory lusrlman.
opendir:man?: No such file or directory
A warning message indicating that one of the directories catman normally looks for is not present
*.*: No such file or directory
A warning message indicating catman came across an empty directory while building the whatis
database.
SEE ALSO
man(1), whatis(l)

564

Last change: 8 July 1986

Sun Release 3.2

CHOWN(8)

MAINTENANCE COMMANDS

CHOWN(8)

NAME

chown - change owner
SYNOPSIS

letc/chown [ -f] [-R] owner[.group]file ...
DESCRIPTION
chown changes the owner of the files to owner. The owner may be either a decimal UID or a login name
found in the password file. An optional group may also be specified. The group may be either a decimal
GID or a group name found in the group-ID file.

Only the super-user can change owner, in order to simplify accounting procedures.
OPTIONS
-f

-R

Do not report errors.
Recursively descend into directories setting the ownership of all files in each directory encountered. When symbolic links are encountered, their ownership is changed, but they are not
traversed.

FILES

/etc/passwd
SEE ALSO
chgrp(l), chown(2), passwd(5), group(5)

Sun Release 3.2

Last change: 25 July 1986

565

CHROOT(8)

MAINTENANCE COMMANDS

CHROOT(8)

NAME

chroot - change root directory for a command
SYNOPSIS

lusr/etc/chroot newroot command
DESCRIPTION

The given command is executed relative to the new root. The meaning of any initial slashes (I) in path
names is changed for a command and any of its children to newroot. Furthermore, the initial working
directory is newroot.
Input and output redirections on the command line are made with respect to the original root:
chroot newroot command >x
creates the file x relative to the original root, not the new one.
This command is restricted to the super-user.
The new root path name is always relative to the current root: even if a chroot is already in effect; the
newroot argument is relative to the current root of the running process.
SEE ALSO

chdir(2)

BUGS
One should exercise extreme caution when referring to special files in the new root file system.

566

Last change: 25 July 1986

Sun Release 3.2

CLRI(8 )

MAINTENANCE COMMANDS

CLRI(8)

NAME

clri - clear i-node
SYNOPSIS

letc/clrifilesystem i-number . ..
DESCRIPTION

Note:

Clri has been superceded for normal file system repair work by fsck(8).

Clri writes zeros on the i-nodes with the decimal i-numbers on the filesystem. After clri, any blocks in the
affected file will show up as 'missing' in an icheck(8) of the filesystem.
Read and write permission is required on the specified file system device. The i-node becomes allocatable.
The primary purpose of this routine is to remove a file which for some reason appears in no directory. If it
is used to zap an i-node which does appear in a directory, care should be taken to track down the entry and
remove it. Otherwise, when the i-node is reallocated to some new file, the old entry will still point to that
file. At that point removing the old entry will destroy the new file. The new entry will again point to an
unallocated i-node, so the whole cycle is likely to be repeated again and again.
SEE ALSO

icheck(8)
BUGS

If the file is open, clri is likely to be ineffective.

Sun Release 3.2

Last change: 4 February 1983

567

COMSAT(8C)

MAINTENANCE COMMANDS

COMSAT(8C)

NAME

comsat - biff server
SYNOPSIS

lusr/etc/in.comsat
DESCRIPTION

Comsat is the server process which listens for reports of incoming mail and notifies users who have
requested to be told when mail arrives. It is invoked as needed by inetd(8C), and times out if inactive for a
few minutes.
Comsat listens on a datagram port associated with the "bifr' service specification (see services (5» for one
line messages of the form
user@mailbox-offset

If the user specified is logged in to the system and the associated terminal has the owner execute bit turned
on (by a "biff y"), the offset is used as a seek offset into the appropriate mailbox file and the first 7 lines or
560 characters of the message are printed on the user's terminal. Lines which appear to be part of the message header other than the "From", "To", "Date", or "Subject" lines are not printed when displaying
the message.
FILES

letclutmp

to find out who's logged on and on what terminals

SEE ALSO
biff(1)
BUGS

The message header filtering is prone to error.
The notification should appear in a separate window so it does not mess up the screen.

568

Last change: 1 February 1985

Sun Release 3.2

CONFIG(8)

MAINTENANCE COMMANDS

CONFIG(8)

NAME

config - build system configuration files
SYNOPSIS
letc/coofig [ -p ] [ -0] [ -f] [ -0 obj_dir ] configyle
DESCRIPTION

Config does the preparation necessary for building a new system kernel with make(l). The configyle
named on the command line describes the kernel to be made in terms of options you want in your system,
size of tables, and device drivers to be included. When you run config, it uses several input files located in
the current directory (typically the conf subdirectory of the system source including your configYle). The
format of this file is described below. The following options are understood by config.
-p

Configures the system for profiling (see kgmon (8) and gprof(l».

-0

Do not do the "make depend". Normally config will do the "make depend" automatically. If
this option is used config will print "Don'tforget to do a "make depend'''' before completing
as a reminder.

-f

Set up the makefile for fast builds. This is done by building a " vmunix.o" file which includes
all the .0 files which there is no source. This reduces the number of files which have to be
stat' ed during a system build. This is done by prelinking all the files for which no source
exists into another file which is then linked in place of all these files when the kernel is made.
This makefile is faster because it does not stat the object files during the build.

-oobj_dir

Use .Jobj_dir instead of .JOBJ as the directory to find the obj~ct files when the corresponding source file is not present in order to generate the files necessary to compile and link your
kernel.

If the directory named ••lconfigYle does not exist, config will create one. One of config's output files is a
makefile which you use with make to build your system. For a description of other input and output files,
see the FILES section below.
You use config as follows. Run config from the conf subdirectory of the system source (in a typical Sun
environment, from Isyslconf):
tutorial# letclcoofig configJt.le
Doing a "make depend"
tutorial# cd .JconfigYle
tutorial# make
.. .lots of output...
While config is running watch for any errors. Never use a kernel which config has complained about; the
results are unpredictable. If config completes successfully, you can change directory to the •.IconfigYle
directory, where it has placed the new makefile, and use make to build a kernel. The output files placed in
this directory include ioconfc, which contains a description of I/O devices attached to the system;
mbglue.s, which contains short assembly language routines used for vectored interrupts, a makefile, which
is used by make to build the system; a set of header files (device _name.h) which contain the number of
various devices that may be compiled into the system; and a set of swap configuration files which contain
definitions for the disk areas to be used for the root file system, swapping, and system dumps.
Now you can install your new kernel and try it out.
CONFIG FILE FORMAT
In the following descriptions, a number can be a decimal integer, a whole octal number or a whole hexadecimal number. Hex and octal numbers are specified to config in the same way they are specified to the C
compiler, a number starting with "Ox" is a hex number and a number starting with just a "a" is an octal
number. You can use a floating-point number to specify half-hour time zones.

Sun Release 3.2

Last change: 30 April 1986

569

CONFIG(8)

MAIN1ENANCE COMMANDS

CONFIG(8)

Comments are specified in a config file with the character "#". All characters from a "#" to the end of a
line are ignored.
Lines beginning with tabs are considered continuations of the previous line.
Lines of the configuration file can be one of two basic types. First, there are lines which describe general
things about your system:
machine type
This is system is to run on the machine type specified. Only one machine type can appear in the
config file. The legal types for a Sun system are "sun2" and "sun3" (note that the double quotes are
part of the designation).
cpu "type"
This system is to run on the cpu type specified. More than one cpu type can appear in the config file.
Legal types for a "sun2" machine are "SUN2_120" (generic for any Multibus based Sun-2 machine),
"SUN2_50" (generic for any VMEbus based Sun-2 machine), The legal types for a "sun3" machine
are "SUN3_160", and "SUN3_S0".
ident name
Gives the system identifier - a name for the machine or machines that run this kernel. name must
be enclosed in double quotes if it contains both letters and numbers (for example, "SDST120"), or
you will get a syntax error when you run letclconfig. Also, note that if name is GENERIC, you can
specify the unique config_clause swap generic in the config line described below. If you use any
other string for name, and you also include an options GENERIC line, you can still use the swap
generic line. However, if you use any other string for name and omit the options GENERIC line,
config will set up the makefile as if you had
timezone number [ dst ]
Specifies the timezone you are in, measured in the number of hours west of GMT. 5 is EST, 8 is
PST. Negative numbers indicate hours east of GMT. If you specify dst, the system will convert to
and from daylight savings time when appropriate.
maxusers number
The maximum expected number of simultaneously active user on this system is number. This
number is used to size several system data structures.
options optlist
Compile the listed options into the system. Options in this list are separated by commas. A line of
the form "options FUNNY,HARA" yields -DFUNNY -DHARA to the C compiler. An option may
be given a value, by following its name with "=" then the value enclosed in (double) quotes. None of
the standard options use such a value.
In addition, options can be used to bring in additional files if the option is listed in the files files. All
options should be listed in upper case. In this case, no corresponding option.h will be created as it
would be using the corresponding pseudo-device method.
con fig sysname config_clauses...
Generate a system with name sysname and configuration as specified in config-clauses . The
sysname is used to name the resultant binary image and per-system swap configuration files. The
config_clauses indicate the location for the root file system, one or more disk partitions for swapping
and paging, and a disk partition to which system dumps should be made. All but the root device
specification may be omitted; config will assign default values as described below.

570

root

A root device specification is of the form root on xyOd. If a specific partition is omitted for example, if only root on xyO is specified - the "a" partition is assumed. When a generic system is being built, no root specification should be given; the root device will be
defined at boot time by prompting the console.

swap

Swap device specifications have two possible forms. If a generic swap configuration is
required, the clause swap generic should be specifed. Otherwise, if a single partition is to

Last change: 30 April 1986

Sun Release 3.2

CONFIG(8)

MAINTENANCE COMMANDS

CONFIG(8)

be used for swapping, one may specify swap on xyOb. If multiple partitions are to be interleaved one should specify something of the form swap on xyO and xyl and xylg. If no
swap specification is given, config assumes swapping should be done on the "b" partition
of the root device. Swapping areas may be almost any size and multiple swap partitions of
varying size may be interleaved. Partitions used for swapping are sized at boot time by the
system; to override dynamic sizing of a swap area the number of sectors in the swap area
can be specified in the config file. For example, swap on xyOb size 99999 would configure
a swap partition with 99999 sectors.

dumps

The location to which system dumps are sent may be specified with a clause of the form
dumps on xyl. If no dump device is specified, the first swap partition specified is used. If a
device is specified without a particular partition, the "b" partition is assumed. If a generic
configuration is to be built, no dump device should be specified; the dump device will be
assigned to the swap device dynamically configured at boot time.
Dumps are placed at the end of the partition specified. Their size and location is recorded in
global kernel variables dumpsize and dump/o, respectively, for use by save core (8).

Device names specified in configuration clauses are mapped to block device major numbers with the
file devices. machine , where machine is the machine type previously specified in the configuration
file. If a device name to block device major number mapping must be overridden, a device
specification may be given in the form major x minor y.
The second group of lines in the configuration file describe which devices your system has and what they
are connected to (for example, I have a Xylogics 450 Disk Controller at address Oxee40 in the Multibus I/O
space). These lines have the following format:
dey_ type dey_name at con_ dey more_info

Dev_type is either tape, disk, controller, device, or pseudo-device. These types have the following meanings:
controller
is a disk or tape controller.
disk or tape
are devices connected to a controller.
device
is something 'attached' to the main system bus, like a cartridge tape interface.
pseudo-device
A software subsystem or driver treated like a device driver, but without any associated
hardware. Current examples are the pseudo-tty driver and various network subsystems. For
pseudo-devices, moreJnro may be specified as an integer, that gives the value of the symbol defined in the header file created for that device, and is generally used to indicate the
number of instances of the pseudo-device to create.

Dev_name is the standard UNIX device name and unit number (if the device is not a psuedo-device) of the
device you are specifying. For example, xycO is the dey_name for the first Xylogics controller in a system;
arO names the first quarter-inch tape controller.

Sun Release 3.2

Last change: 30 April 1986

571

CONFIG(8)

MAINTENANCE COMMANDS

CONFIG(8)

Con_dev is what the device you are specifying is connected to. It is either nexus?, a bus type, or a controller. There are several bus types which are used by config and the kernel.
The different possible bus types are:
obmem On board memory
On board io
obio
mbmem Multibus memory (sun2 only)
mbio
Multibus io (sun2 only)
vmel6d16 (vmeI6)
16 bit VMEbusl 16 bit data
vme24d16 (vme24)
24 bit VMEbusl 16 bit data
vme32d16
32 bit VMEbusl 16 bit data (sun3 only)
vmel6d32
16 bit VMEbus/ 32 bit data (sun3 only)
vme24d32
24 bit VMEbus/ 32 bit data (sun3 only)
vme32d32 (vme32)
32 bit VMEbus/ 32 bit data (sun3 only)
All of these bus types are declared to be connected to nexus. The devices are hung off these buses. If the
bus is wildcarded, then the autoconfiguation code will determine if it is appropriate to probe for the device
on the machine that it is running on. If the bus is numbered, then the autoconfiguation code will only look
for that device on machine type N. In general, the Multibus and VMEbus bus types are always wildcarded.

More_info is a sequence of the following:

csr addr
Specifies the address of the csr (command and status registers) for a device. The csr
addresses specified for the device are the addresses within the bus type specified.
The csr address must be specified for all controllers, and for all devices connected to a main
system bus.

drive number
For a disk or tape, specifies which drive this is.

ftagsnumber
These flags are made available to the device driver, and are usually read at system initialization time.

priority level
For devices which interrupt, specifies the interrupt level at which the device operates.

vector intr number [ intr number . .. ]
For devices which use vectored interrupts on VMEbus systems, intr specifies the vectored
interrupt routine and number the corresponding vector to be used (Ox40-0xFF).
A ? may be substituted for a number in two places and the system will figure out what to fill in for the ?
when it boots. You can put question marks on a con_dev (for example, at virtual ?), or on a drive number
(for example, drive ?). This allows redundancy, as a single system can be built which will boot on different
hardware configurations.
The easiest way to understand config files it to look at a working one and modify it to suit your system.
Good examples are provided in the Configuring the System Kernel chapter and second appendix of the
Installing UNIX on the Sun Workstation manual.

572

Last change: 30 April 1986

Sun Release 3.2

CONFIG(8)

MAINTENANCE COMMANDS

CONFIG(8)

FILES

Files in Isyslconfwhich may be useful for developing the configJt.le used by config are:
GENERIC

These are generic configuration files for
either a Sun-2 or Sun-3 system.
They contain all possible device
descriptions lines for the particular
architecture.

README

File describing how to make a new kernel

As shipped from Sun, the files used by letclconfig as input are in the Isyslconf directory:

configJt.le
makefile.sun[23]
files
files.sun[23]
devices.sun[23]

System-specific configuration file
Generic prototype make file for Sun-[23] systems
List of common files required to build a basic kernel
List of files for a Sun-[23] specific kernel
N arne to major device mapping file for Sun-[23] systems

letclconfig places its output files in the .JconfigJt.le directory:
mbglue.s
ioconf.c
makefile
device name.h

Short assembly language routines used for vectored interrupts
Describes I/O devices attached to the system
Used with make (1) to build the system
A set of header files (various device_name 's) containing devices
"
which can be compiled into the system.

SEE ALSO
The SYNOPSIS portion of each device entry in Section 4 of the UNIX Interface Reference Manual.

Configuring the System Kernel, and Sample Configuration Files in Installing UNIX on the Sun Workstation.
Kernel Configuration under Periodic Maintenance in System Administrationfor the Sun Workstation

Sun Release 3.2

Last change: 30 April 1986

573

CRASH(8S)

MAINTENANCE COMMANDS

CRASH(8S)

NAME

crash - what happens when the system crashes
DESCRIPTION

This section explains what happens when the system crashes and how you can analyze crash dumps.
When the system crashes voluntarily, it displays a message of the form
panic: why i gave up the ghost
on the console, takes a dump on a mass storage peripheral, and then invokes an automatic reboot procedure
as described in reboot(8). Unless some unexpected inconsistency is encountered in the state of the file systems due to hardware or software failure, the system will then resume multiuser operations.
The system has a large number of internal consistency checks; if one of these fails, it will panic with a very
short message indicating which one failed.
When the system crashes it writes (or at least attempts to write) an image of memory into the back end of
the primary swap area. Mter the system is rebooted, you can run the program save core (8) to preserve a
copy of this core image and kernel namelist for later perusal. See savecore (8) for details.
To analyze a dump you should begin by running adb(1) with the -k flag on the core dump, as described in
Program Debugging Tools/or the Sun Workstation.
The most common cause of system failures is hardware failure, which can reflect itself in different ways.
Here are some messages that you may encounter, with some hints as to causes. In each case there is a possibility that a hardware or software error produced the message in some unexpected way.
10 err in push
hard 10 err in swap The system encountered an error trying to write to the paging device or an error in
reading critical information from a disk drive. You should fix your disk if it is broken or unreliable.
timeout table overOow
This really shouldn't be a panic, but until we fix up the data structure involved, running out of entries causes a crash. If this happens, you should make the timeout
table bigger by changing the value of ncallout in the param.c file, and then rebuild
your system.
trap type type, pidprocess-id, pc =program-counter, sr =status-register, context context-number
A unexpected trap has occurred within the system; typical trap types are:
Bus error
Address error
lliegal instruction
Divide by zero
Chk instruction
Trapv instruction
Privilege violation
Trace
1010 emulator trap
1111 emulator trap
Stack format error
Unitialized interrupt
Spurious interrupt
The favorite trap types in system crashes are 'Bus error' or 'Address error', indicating a wild reference. The process-id is the id of the process running at the time of
the fault, program-counter is the hexadecimal value of the program counter, statusregister is the hexadecimal value of the status register, and context-number is the
context that the process was running in. These problems tend to be easy to track
down if they are kernel bugs since the processor stops cold, but random flakiness
seems to cause this sometimes.

574

Last change: 8 Apri11986

Sun Release 3.2

CRASH(8S)

init died

MAINTENANCE COMMANDS

CRASH(8S)

The system initialization process has exited. This is bad news, as no new users will
then be able to log in. Rebooting is the only fix, so the system just does it right
away.

SEE ALSO
adb(l), analyze(8), reboot(8) sa(8), savecore(8)
Program Debugging Tools/or the Sun
FILES
Ivmunix the UNIX system kernel
I etc/rc .local
script run when the local system starts up

Sun Release 3.2

Last change: 8 April 1986

575

MAThnENANCECO~ANDS

CRON(8)

CRON(8)

NAME

cron - clock daemon
SYNOPSIS

letc/cron
DESCRIPTION

Cron executes commands at specified dates and times according to the instructions in the file
lusrlliblerontab. Since eron never exits, it should only be executed once. This is best done by running
cron from the initialization process through the file letclre; see init(8).
lusrlliblerontab consists of lines of six fields each. The fields are separated by spaces or tabs. The first five
are integer patterns to specify the minute (0-59), hour (0-23), day of the month (1-31), month of the year
(1-12), and day of the week (1-7 with I=Monday). Each of these patterns may contain a number in the
range above; two numbers separated by a dash meaning a range inclusive; a list of numbers separated by
commas meaning any of the numbers; or an asterisk meaning all legal values. The sixth field is a string
that is executed by the shell at the specified times. A percent character in this field is translated to a newline character. Only the first line (up to a % or end of line) of the command field is executed by the shell.
The other lines are made available to the command as standard input.
Here are a few example lines from lusrlliblerontab, to give you a better sense of the file's format:

o0 * * * calendar 15 0 * * * lusr/etc/sa -s >/dev/null
0,30 * * * * letc/dmesg - »/usr/admlmessages
15 4 * * * find lusr/preserve -mtime +7 -a -exec rm -f {} ;
104 * * * egrep 'SYSERRlrefusedlunreachable' lusrlspool/log/syslog.O Imail Posttnaster
Cron examines lusrlliblerontab under the following conditions:
At least once per hour (on the hour).
When the next command is to be run -

cron looks ahead until the next command and sleeps until then.

When eron's process is sent a SIGHUP. This means that someone who changes lusrlliblerontab can get
eron to look at it right away.
You can also create the lusrladmleronlog file, if you wish. If the file exists, eron logs to it each time it executes an instruction from lusrlliblerontab. You can thus use the cronlog file to make sure eron is running
properly. The lines in the file consist of a timestamp, and process statement Lines look something like

this:
Thu Mar
Thu Mar
Thu Mar
Thu Mar

8 10:20:00 1984: letc/dmesg - »/usr/admlmessages
8 10:29:59 1984: letc/atrun
8 10:30:00 1984: letc/dmesg - »/usr/admlmessages
8 10:39:59 1984: letc/dmesg - »/usr/admlmessages

FILES

lusrllib/crontab Instruction file
lusr/adm/cronlog Log file
SEE ALSO
crontab(5)

576

Last change: 4 November 1985

Sun Release 3.2

DCHECK(8)

MAINTENANCE COMMANDS

DCHECK(8)

NAME

dcheck - file system directory consistency check
SYNOPSIS

lusr/etc/dcheck [ -i numbers] [filesystem]
DESCRIPTION
Note:

Dcheck has been superceded for normal consistency checking by fsck(8).

Dcheck reads the directories in a file system and compares the link-count in each inode with the number of
directory entries by which it is referenced. If the file system is not specified, dcheck checks a set of default
file systems.
Dcheck is fastest if the raw version of the special file is used, since the i-list is read in large chunks.
OPTIONS
-i numbers
Numbers is a list of i-numbers; when one of those i-numbers turns up in a directory, the number,
the i-number of the directory, and the name of the entry are reported.
FILES

Default file systems vary with installation.
SEE ALSO
fsck(8), icheck(8), fs(5), clri(8), ncheck(8)
DIAGNOSTICS
When a file turns up for which the link-count and the number of directory entries disagree, the relevant
facts are reported. Allocated files which have 0 link-count and no entries are also listed. The only
dangerous situation occurs when there are more entries than links; if entries are removed, so the link-count
drops to 0, the remaining entries point to thin air. They should be removed. When there are more links
than entries, or there is an allocated file with neither links nor entries, some disk space may be lost but the
situation will not degenerate.
BUGS

Since dcheck is inherently two-pass in nature, extraneous diagnostics may be produced if applied to active
file systems.
Inode numbers less than 2 are invalid.

Sun Release 3.2

Last change: 4 February 1983

577

MAThITENANCECO~ANDS

DIAG(8S)

DIAG(8S)

NAME

diag - stand-alone disk initialization and diagnosis
SYNOPSIS
>b stand!diag
DESCRIPTION
Diag is a general purpose stand-alone package for initializing, diagnosing, and repairing disks. It supports
the various SMD and SCSI disk controllers.

Note: Diag is not a system utility and can only be called from the Sun Workstation PROM monitor.
The most common use of diag is formatting and labelling a disk commands.

see the format, label, and partition

Immediately after startup, diag prompts for information about the particular disk drive(s) and controller(s)
it is to work with. There is a facility for specifying additional information about nonstandard disks.

Diag tries to access the disk controller you have defined. If the attempt succeeds, it gives you a status
report on the disk and issues the 'diag> , prompt. If the attempt fails (if the controller is ill-defined or
nonexistent), you get a bus error message, and return to the PROM monitor.
Once configured, diag accepts the comands listed below. Only enough characters to uniquely identify the
command need be typed.

578

abortdma

Aborts/does not abort the dmatest command when a data miscompare is detected. That is, if
the internal variable set by abortdma is 'on' (default), the dmatest command aborts as soon
as it finds an error; otherwise, the dmatest continues.

clear

Sends a restore command to a disk. This is needed to manually reset disk faults.

diag

Re-initializes the diag program itself described above.

dmatest

Begins a continuous DMA test. The test copies random data to and from the designated
controller, comparing data. If a miscompare is found, an error message is displayed and the
test aborts (unless the abortdma command is used - see abortdma, above). Note: this
command is available only with the Xylogics 450 Controller.

errors

Reports/does not report all errors as they occur (toggles; default is reporting ofO.

fix

Formats and verifies a range of tracks; any defective tracks/sectors found are automatically
corrected using mapping or slipping. Note: this command is available for SMD controllers
only.

format

For SMD disks, formats the entire disk; for SCSI disks, initiates the SCSI format program.

sformat

Initiates a special formatting program that allows manual manipulation of the defect list.
Note: this command is available for SMD controllers only. For SCSI controllers, use the
format command.

help or?

Displays a list of the available commands.

info

Reports/suppresses report of all disk activity as it completes (toggles; default is reporting
off).

label

Labels the disk.

map

Displays current mappings and allows you to explicitly map one track/sector to a different
track/sector. Usually used for manual bad sector mapping. The format andjix commands
usually do this automatically when a bad track/sector is found. Note: the map command is
disk controller-dependent you can map tracks with an Interphase controller, and sectors
with Xylogics controllers. This command is not available for use with SCSI disk controllers.

mapcheck

Enables/disables checking for overlapping mapped sectors/tracks during the position, read,

goes back to phase one of the initialization process

Last change: 25 July 1986

Sun Release 3.2

DIAG(8S)

MAINTENANCE COMMANDS

DIAG (8S)

test, or write commands. If the internal variable set by mapcheck is 'on' when an error
occurs (default), then the current mappings (if any) are read from the disk and checked to
see if there are overlapping mappings over the area of the disk where the transfer failed.
partition

Creates, assigns, or modifies logical partition tables for a disk. The UNIX operating system
requires logical partitions. The label command writes the partition map to the disk. There
are standard partition tables for each type of disk that diag knows about.

position

Continuously tests the disk by reading random sectors from the disk. To abort the test, type
a "C (CONTROL-C).

quit

Quits from diag and returns to the PROM monitor.

rhdr

Reads and displays the track headers for a specified track. Note: this command is available
for Xylogics controllers only.

read

Reads specified blocks from the disk. The read command prompts for the starting block
number, number of blocks, and the block increment. The read command doesn't report the
data it reads - it is intended for verifying that blocks are readable.

scan

Continuously scans over a range of sectors looking for defective sectors by
writing/reading/verifying various bit patterns to sequential sectors. Any data on the disk in
the range to be scanned is destroyed. Sectors previously mapped are not scanned, so any
errors reported will be newly found defective sectors. If used with a Xylogics controller,
defective sectors can be automatically mapped/slipped when they are found. To abort the
scan, type a "C (CONTROL-C).

seek

Performs a seek test on the disk: it can either continuously seek between two specified
blocks or seek to every cylinder and every possible cylinder distance.

slip

Explicitly slips one sector on a track. Usually used for manual bad sector slipping. Theformat and fix commands usually do this automatically when bad sectors are found and the
proper conditions exist Note: slipping is available only with Xylogics controllers, and only
when the disk has a spare data sector per track.

slipmsgs

Displays/suppresses display of track headers before and after each slip operation that occurs
during thefix,format, and slip commands (toggles; default is display oft).

status

Reports the ready status of each drive on the current controller.

test

Continuously tests the disk by writing random data to random sectors on the disk and then
verifying that the correct data can be read back. The test command destroys data on the
disk. To abort the test, type a "C (CONTROL-C).

time

Turns timing on/off. When timing is on, diag reports on how long certain operations take diag is less verbose in this state so it doesn't waste time displaying messages (toggles;
default is timing off).

translate

Translates a given block number into its decimal value, hexadecimal value, and logical disk
address.

verify

Reads and displays the label from the disk. Shows the logical partition assignments. This is
done automatically when the label command has labelled the disk.

version

Displays the SCCS identification string for this version of diag.

whdr

Modifies and writes the track headers for a specified track. Note: this command is available with Xylogics controllers only. Also, it should be used only for specialized patchingmisuse may destroy track data.

write

Verifies that blocks are writable by writing garbage data to specified blocks on the disk.
The write command prompts for the starting block number, number of blocks, and the block
increment.

Sun Release 3.2

Last change: 25 July 1986

579

DIAG(8S)

+

MAINTENANCE COMMANDS

DIAG(8S)

Adds two block numbers and reports the result in decimal, hexadecimal, and as a logical
disk address.
Subtracts two block numbers and reports the result in decimal, hexadecimal, and as a logical
disk address.

Block numbers may be entered either as an absolute decimal block number, or as a disk address of the form
cylinderlhead/sector.
Any diag command may be aborted by typing a "C (CONTROL-C).

580

Last change: 25 July 1986

Sun Release 3.2

DKINFO(8)

MAlNTENANCE COMMANDS

DKINFO(8)

NAME

dkinfo - report information about a disk's geometry and partitioning
SYNOPSIS
I etc!dkinfo disk [partition]
DESCRIPTION
Dkinfo gives the total number of cylinders, heads, and sectors or tracks on the specified disk, and gives this
information along with the starting cylinder for the specified partition. If no partition is specified on the
command line, dkinfo reports on all partitions.

The disk specification here is a disk name of the form xxn, where xx is the controller device abbreviation
(ip, xy, etc.) and n is the disk number. The partition specification is simply the letter used to identify that
partition in the standard UNIX nomenclature. For example, '/etc/dkinfo xyO' reports on the first disk in a
system controlled by a Xylogics controller; '/etc/dkinfo xyOg' reports on the seventh partition of such a
disk.
You must be be able to open /dev/rxxnp to run dkinfo. Usually, only the superuser can do so.
EXAMPLE
A request for information on my local disk, an 84 MByte disk controlled
by a Xylogics 450 controller, might look like this:
# letc/dkinfo xyO
xyO: Xylogics 450 controller at addr ee40, unit # 0
586 cylinders 7 heads 32 sectors/track
a: 15884 sectors (70 cyls, 6 tracks, 12 sectors)
starting cylinder 0
b: 33440 sectors (149 cyls, 2 tracks)
starting cylinder 71
c: 131264 sectors (586 cyls)
starting cylinder 0
d: No such device or address
e: No such device or address
f: No such device or address
g: 81760 sectors (365 cyls)
starting cylinder 221
h: No such device or address
#
SEE ALSO
dk(4), diag(8)

Sun Release 3.2

Last change: 1 February 1985

581

DMESG(8)

MAINTENANCE COMMANDS

DMESG(8)

NAME
dmesg - collect system diagnostic messages to form error log
SYNOPSIS

letcldmesg [ - ]
DESCRIPTION

Dmesg looks in a system buffer for recently printed diagnostic messages and prints them on the standard
output. The messages are those printed by the system when device (hardware) errors occur and (occasionally) when system tables overflow non-fatally. If the - flag is given, then dmesg computes (incrementally)
the new messages since the last time it was run and places these on the standard output. This is typically
used with cron(8) to produce the error log IUSTladm/messages by running the command

letcldmesg - » lusr/adm/messages
every 10 minutes.
FILES
lusr/adm/messages
lusr/adm/msgbuf

error log (conventional location)
scratch file for memory of - option

BUGS
The system error message buffer is of small finite size. As dmesg is run only every few minutes, not all
error messages are guaranteed to be logged. This can be construed as a blessing rather than a curse.
Error diagnostics generated immediately before a system crash will never get logged.

582

Last change: 4 February 1983

Sun Release 3.2

DUMP(8)

MAINTENANCE COMMANDS

DUMP(8)

NAME

dump, rdump - incremental file system dump
SYNOPSIS

/etc/dump [options [arguments] ]filesystem
DESCRIPTION
Dump backs up all files in filesystem, or files changed after a certain date, to magnetic tape. Options is a
string that specifies dump options, as shown below. Any arguments supplied for specific options are given
as subsequent words on the command line, in the same order as that of the options listed.

If no options are given, the default is 9u.
OPTIONS

0-9

The "dump level." All files in the filesystem that have been modified since the last dump at a
lower dump level are copied to the tape. For instance, if you did a "level 2" dump on Monday,
followed by a "level 4" dump on Tuesday, a subsequent "level 3" dump on Wednesday would
contain all files modified or added since the "level 2" (Monday) backup. A "level 0" dump copies
the entire filesystem to tape.

b factor Blocking factor. Specifies the blocking factor for tape writes. The default is 10 blocks per write.
Note that a tape block is 1024 bytes in size, or twice the size of a disk block. The highest blocking
factor available with some 6250bpi tape drives is 126.

c

Cartridge. Use a cartridge instead of the standard half-inch reel. This sets the density to 1000bpi
and the length to 1700 feet. When dumping to a high-density (9-track) cartridge, include the s
(size) option with the 3825 (feet) argument to properly fill each cartridge.

d bpi

Tape density. The density of the tape, expressed in BPI, is taken from bpi. This is used to keep a
running tab on the amount of tape used per reel. The default density is 1600. Unless a higher
density is specified explicitly, dump uses its default density--even if the tape drive is capable of
higher-densityoperation (for instance, 6250bpi).

f dump-file
Dump file. Use dump-file as the file to dump to, instead of Idevlrmt8. If dump-file is specified as
'-', dump to the standard output. If the filename argument is of the form machine:device, dump
to a remote machine. Since dump is normally run by root, the name of the remote machine must
appear in the .rhosts file of the local machine. If dump is called as rdump, the tape defaults to
dumphost:/dev/rmt8. To direct the output to a desired remote machine, set up an alias for dumphost in the file letelhosts.

o

Notify. When this option is specified, if dump requires attention, it sends a terminal message
(similar to wall (1» to all operators in the "operator" group.

s size

Specify the size of the tape or cartridge in feet. When the specified size is reached, dump waits for
you to change the reel or cartridge. The default size is 2300 feet, except when c (cartridge) is
specified, in which case the default is 1700. To estimate the size for a tape or cartridge of a nonstandard length, use the formula:
(length

* tracks) * .9

u

Update the dump record. Add an entry to the file letcldumpdates, for each filesystem successfully
dumped that includes the filesystem name, date, and dump level. This file can be edited by the
super-user.

w

List the filesystems that need backing up. This information is gleaned from the files
letcldumpdates and letc/fstab. When the w option is used, all other options are ignored. After
reporting, dump exits immediately.

W

Like w, but includes all filesystems that appear in letcldumpdates, along with information about
their most recent dump dates and levels. Filesystems that need backing up are highlighted.

Sun Release 3.2

Last change: 22 July 1986

583

DUMP(8)

MAINTENANCE COMMANDS

DUMP(8)

Operator Intervention
dump requires operator intervention on these conditions: end of tape, end of dump, tape write error, tape
open error or disk read error (if there are more than a threshold of 32). In addition to alerting all operators
implied by the n option, dump interacts with the operator on dump's control terminal at times when dump
can no longer proceed, or if something is grossly wrong. All questions dump poses must be answered by
typing "yes" or "no", as appropriate.

Since backing up a disk can involve a lot of time and effort, dump checkpoints at the start of each tape
volume. If writing that volume fails for some reason, dump will, with operator permission, restart itself
from the checkpoint after a defective tape has been rewound and replaced.

dump reports periodically, and in verbose fashion. Each report includes estimates of the percentage of the
dump completed and how long it will take to complete the dump.
Suggested Dump Schedule
It is vital to perform full, "level 0", dumps at regular intervals. When performing a full dump, bring the
machine down to single-user mode using shutdown (8). While preparing for a full dump, it is a good idea
to clean the drive and heads.

Incremental dumps allow for convenient backup and recovery on a more frequent basis of active files, with
a minimum of tape and time. However there are some tradeoffs. First, the interval between backups should
be kept to a minimum (once a day at least). To guard against data loss as a result of a media failure (a rare,
but possible occurrence), it is a good idea to capture active files on (at least) two dump tapes. Another consideration is the desire to keep unnecessary duplication of files to a minimum to save both operator time
and tape storage. A third consideration is the ease with which a particular backed-up version of a file can
be located and restored. The following four-week schedule offers a reasonable tradeoff between these
goals.
Wed Thu
Fri
Sun
Mon Tue
Week 1:
Full 5
5
5
5
3
Week 2:
5
5
5
3
5
Week 3:
5
5
5
3
5
Week 4:
5
5
5
3
5
Although the Tuesday-Friday incrementals contain "extra copies" of files from Monday, this scheme
assures that any file modified during the week can be recovered from the previous day's incremental dump.
FILES

Idevlrmt8
Ietc/dumpdates
letc!fstab
letc/group

default tape unit to dump to
new format dump date record
dump table: file systems and frequency
to find group operator

SEE ALSO
restore(8), dump(5), fstab(5)
DIAGNOSTICS
While running, dump emits many verbose messages.
Exit Codes

o
1

2
3

normal exit when w or W options are used.
normal exit
error - restart writing from last checkpoint
abort - no checkpoint attempted.

BUGS

Sizes are based on 1600 BPI blocked tape; the raw tape device has to be used to approach these densities.
Fewer than 32 read errors on the filesystem are ignored.
Each reel requires a new process; parent processes for completed reels remain until the entire dump is competed.

584

Last change: 22 July 1986

Sun Release 3.2

DUMPFS(8)

MAThITENANCECO~ANDS

DUMPFS(8)

NAME

dumpfs - dump file system information
SYNOPSIS

/usr/etc/dumpfs device
DESCRIPTION

Dumpfs prints out the super block and cylinder group information for the file system or special device
specified. The listing is very long and detailed. This command is useful mostly for finding out certain file
system information such as the file system block size and minimum free space percentage.
SEE ALSO

fs(5), tunefs(8), newfs(8), fsck(8)

Sun Release 3.2

Last change: 4 March 1983

585

EDQUOTA(8)

MAINTENANCE COMMANDS

EDQUOTA(8)

NAME

edquota - edit user quotas
SYNOPSIS

lusr/etc/edquota [ -p proto-user] users . ..
lusrletcledquota -t
DESCRIPTION

Edquota is a quota editor. One or more users may be specified on the command line. For each user a temporary file is created with an ASCII representation of the current disk quotas for that user and an editor is
then invoked on the file. The quotas may then be modified, new quotas added, etc. Upon leaving the editor, edquota reads the temporary file and modifies the binary quota files to reflect the changes made.
The editor invoked is vi(l) unless the EDITOR environment variable specifies otherwise.
Only the super-user may edit quotas.
OPTIONS

-p

duplicate the quotas of the prototypical user specified for each user specified. This is the normal
mechanism used to initialize quotas for groups of users.

-t

edit the soft time limits for each file system. If the time limits are zero, the default time limits in
 are used. Time units of sec(onds), min(utes), hour(s), day(s), week(s), and
month(s) are understood. Time limits are printed in the greatest possible time unit such that the
value is greater than or equal to one.

FILES

quotas
letc/mtab

quota file at the file system root
mounted file systems

SEE ALSO

quota(l), quotact1(2), quotacheck(8), quotaon(8), repquota(8)
BUGS

The format of the temporary file is inscrutable.

586

Last change: 15 April 1985

Sun Release 3.2

EEPROM (8S)

MAINTENANCE COMMANDS

EEPROM(8S)

NAME

eeprom - Sun-3 EEPROM display and load utility
SYNOPSIS

eeprom [ -i] [ - ] [ -r filename] [field[=value]] ...
eeprom [ -i] [ -c] [-r filename]
DESCRIPTION

eeprom displays or changes the values of fields in the EEPROM. It processes fields in the order given.
When processing afield accompanied by a value, eeprom makes the indicated alteration to the EEPROM;
otherwise it displays the field's value. When given no field specifiers, eeprom displays the values of all
EEPROM fields. A '-' flag specifies that fields and values are to be read from stdin (one field orfield=value
per line).
eeprom verifies the EEPROM checksums and complains if they are incorrect; if the -i flag is specified,
erroneous checksums are ignored. If the -c flag is specified, all incorrect checksums are recomputed and
corrected in the EEPROM.
OPTIONS
-i

ignore bad checksums.

-r filename

use filename as the EEPROM device.

-c

correct bad checksums.
read field names and values from stdin.

The field names and their possible values are:

hwupdate
memsize
memtest
scrsize
watchdog_reboot
default boot
bootdev
kbdtype
keyclick
console
custom_logo
banner
diagdev
diagpath
ttya_ no_rtsdtr
ttyb _no_rtsdtr
columns
rows

a valid date (including' 'today" and "now' ')
8 bit integer (megabytes of memory on machine)
8 bit integer (megabytes of memory to test)
"1024xl024", "1152x900", "1600x1280", or" 1440xl440"
"true" or "false"
"true" or "false"
%c%c(%x, %x, %x)
8 bit integer (0 for all Sun keyboards)
"true" or "false"
"b&w" or "ttya" or "ttyb" or "color"
"true" or "false"
banner string
%c%c(%x,%x,%x) - diagnostic boot device
diagnostic boot path
"true" or "false"
"true" or "false"
number of columns on screen (8-bit integer)
number of rows on screen (8-bit integer)

SEE ALSO


FILES

ldev/eeprom

Sun Release 3.2

Last change: 20 May 1986

587

ETHERD(8C)

MAINTENANCE COMMANDS

ETHERD(8C)

NAME

etherd - Ethernet statistics server
SYNOPSIS
lusr/etclrpc.etherd interface
DESCRIPTION

etherd is a server which puts interface into promiscuous mode, and keeps summary statistics of all the
packets received on that interface. It responds to rpc requests for the summary. You must be root to run
etherd.
interface is a networking interface such as ieO, iel, eeO, eel and leO.
traffic(l) displays the information obtained from etherd in graphical form.
SEE ALSO
traffic(l)

588

Last change: 28 Aug 1985

Sun Release 3.2

ETHERFIND (8C )

MAINTENANCE COMMANDS

ETHERFIND ( 8C)

NAME

etherfind - find packets on Ethernet
SYNOPSIS

etherfind [ -n ] [ -u] [ -x ] [ -c count] [ -i interface] [ -p ] expression
DESCRIPTION

Etherfind prints out the headers of packets on the ethemet that match the boolean expression. When an
internet packet is fragmented into more than one ethernet packet, all fragments except the first are marked
with an asterisk. You must be root to invoke etherfind.
OPTIONS
-n

Don't convert host addresses and port numbers to names.

-u

Make the output line buffered.

-x

Dump the header in hex, in addition to the line printed for each packet by default

-c

Exit after receiving count packets. This is sometimes useful for dumping a sample of ethernet
traffic to a file for later analysis.

-i

Etherfind listens on interface. The program netstat(8C) when invoked with the -i flag lists all the
interfaces that a machine has.

-p

Normally, the selected interface is put into promiscuous mode, so that etherfind has access to all
packets on the ethemet. However, when the -p flag is used, the interface will not go promiscuous.

expression
The syntax of of expression is similar to that used by find (1). Here are the allowable primaries.

-dst destination
True if the destination field of the packet is destination, which may be either an address
ora name.

-src source
True if the source field of the packet is source, which may be either an address or a name.

-between hostl host2
True if either the source of the packet is hostl and the destination host2, or the source is
host2 and the destination hostl.

-dstnet destination
True if the destination field of the packet has a network part of destination, which may be
either an address or a name.

-srcnet source
True if the source field of the packet has a network part of source, which may be either
an address or a name.

-srcport port
True if the packet has a source port value of port. It must be either upd or tcp (see
tcp (4P»,udp (4P». The port can be a number or a name used in tete/services.

-dstport port
True if the packet has a destination port value of port. The port can be a number or a
name.

-less length
True if the packet has a length less than or equal to length.

-greater length
True if the packet has a length greater than or equal to length.

-proto protocol
True if the packet is an ip packet (see ip(4P» of protocol type protocol. Protocol can be

Sun Release 3.2

Last change: 28 Aug 1985

589

ETHERFIND (8C )

MAINTENANCE COMMANDS

ETIIERFIND ( 8C)

a number or one of the names icmp, udp, nd, or tcp.

-byte byte op value
True if byte number byte of the packet is in relation op to value. Legal values for op are
+, <, >, &, and I. Thus 4=6 is true if the fourth byte of the packet has the value 6, and
20&Oxf is true if byte twenty has one of its four low order bits nonzero.

-broadcast
True if the packet is a broadcast packet.

-arp

True if the packet is a arp packet (see arp(4P».

-rarp

True if the packet is a rarp packet.

-ip

True if the packet is an ip packet

The primaries may be combined using the following operators (in order of decreasing precedence):
A parenthesized group of primaries and operators (parentheses are special to the Shell and must be
escaped).
The negation of a primary ('!' is the unary not operator).
Concatenation of primaries (the and operation is implied by the juxtaposition of two primaries).
Alternation of primaries ('-0' is the or operator).
EXAMPLE
To find all packets arriving at or departing from sundown
angel% etherfind -src sundown -0 -dst sundown
angel%

Note that the { } characters must be quoted when using the C shell.
SEE ALSO
traffic (1 C), nit(4P)
BUGS

The syntax is painful.

590

Last change: 28 Aug 1985

Sun Release 3.2

FASTBOOT ( 8)

MAINTENANCE COMMANDS

FASTBOOT (8 )

NAME

fastboot, fasthalt - reboot/halt the system without checking the disks
SYNOPSIS

letc/rastboot [boot-options]
letc/rasthalt [ halt-options]
DESCRIPTION

fastboot and Jasthalt are shell scripts that reboot and halt the system without checking the file systems.
This is done by creating a file Ifastboot, then invoking the reboot program. The system startup script,
/etclrc, looks for this file and, if present, skips the normal invocation ofJsck(8).
SEE ALSO
halt(8), init(8), rc(8), reboot(8)

Sun Release 3.2

Last change: 30 June 1986

591

FPAREL(8)

MAIN1ENANCE COMMANDS

FPAREL(8)

NAME

fparel - Sun FPA online reliability tests
SYNOPSIS

(parel [ -pn ] [ -v ]
DESCRIPTION

[parel is a command to execute the Sun FPA online confidence and reliability test program. [parel tests
about 90% of the functions of the FPA board, and tests all FPA contexts not in use by other processes.
[parel runs under UNIX without disturbing other processes that may be using the FPA. [parel can only be
run by the super-user.
After a successful pass,[parel writes
time, date: Sun FPA Passed The contexts tested are: 0, 1, ... 31
to the file lusrladmldiaglog.

If a pass fails,[parel writes
time, date: Sun FPA failed
along with the test name and context number that failed, to the file lusrladmldiaglog.[parel then broadcasts
the message
time, date: Sun FPA failed, disabled, service required
to all users of the system. Next, [parel causes the kernel to disable the FPA. Once the kernel disables the
FPA, the system must be rebooted to make it accessible.
The file letclre.loeal should contain an entry to cause fparel to be invoked upon reboot to be sure that the
FPA remains unaccessible in cases where rebooting doesn't correct the problem. See rc(8).

lusrlliblerontab should contain an entry indicating that cron(8) is to run[parel daily, such as:

7 2 * * * lusr/etc/fpalfparel
which causes [parel to run at seven minutes past two, every day. See eron (8) and erontab(5) for details.
OPTIONS
-pn

-v

Perform n passes. Default is n=1. -pO means perform 2147483647 passes.
Run in verbose mode with detailed test results to standard output.

FILES

lusrladmldiaglog

592

Log of[parel diagnostics.

Last change: 30 June 1986

Sun Release 3.2

FPAVERSION (8 )

MAINTENANCE COMMANDS

FPAVERSION (8 )

NAME

fpaversion - print FPA version
SYNOPSIS

fpaversion [ --q ] [ -v ] [ -I ] [ -c ] [ -h ] [ -t[ sdrxctmMiuvCpSlh] ]
DESCRIPTION
Fpaversion perfonns various tests on the floating point accelerator (FPA). With no arguments, it prints the
version number of the microcode and constants that are currently installed on Idev!fpa, and performs a
quick test to ensure proper operation.
OPTIONS

-q Quiet output. Print out only error messages.
-v Verbose output.

-I Loop through tests infinitely.
-h Help. Print command-line summary.

-t Specify certain tests:
s

Single precision fonnat instructions.

d

Double precision fonnat instructions.

x

Extended format instructions.

c

Command register fonnat instructions.

r

User registers for all contexts.

M

Command register fonnat matrix instructions.

t

Status generation.

m

Mode register.
Imask register.

C

Check checksum for microcode, mapping RAM, and constant RAM.

p

Simple pipe sequencing.

S

Shadow registers.

v

Print version number and date of microcode and constants.

h

Help. Print summary of test specifiers.

FILES

ldev!fpa physical FPA device
SEE ALSO
fparel(8), sysdiag(8)

Sun Release 3.2

Last change: 10 March 1986

593

FSCK(8 )

MAINTENANCE COMMANDS

FSCK(8 )

NAME

fsck - file system consistency check and interactive repair
SYNOPSIS
I etc/fsck -p [ filesystem ... ]
letc/fsck [ -b block# ] [ -y ] [ -0 ]

[

filesystem] ...

DESCRIPTION
The first form of fsck preens a standard set of filesystems or the specified file systems. It is normally used
in the script letc/rc during automatic reboot. In this casefsck reads the table /etC!fstab to determine which
file systems to check. It uses the information there to inspect groups of disks in parallel taking maximum
advantage of i/o overlap to check the file systems as quickly as possible. Normally, the root file system
will be checked on pass 1, other "root" ("a" partition) file systems on pass 2, other small file systems on
separate passes (e.g. the "d" file systems on pass 3 and the "e" file systems on pass 4), and finally the
large user file systems on the last pass, e.g. pass 5. A pass number of 0 in fstab causes a disk to not be
checked; similarly partitions which are not shown as to be mounted "rw" or "ro" are not checked.

The system takes care that only a restricted class of innocuous inconsistencies can happen unless hardware
or software failures intervene. These are limited to the following:
Unreferenced inodes
Link counts in inodes too large
Missing blocks in the free list
Blocks in the free list also in files
Counts in the super-block wrong
These are the only inconsistencies which fsck with the -p option will correct; if it encounters other inconsistencies, it exits with an abnormal return status and an automatic reboot will then fail. For each corrected
inconsistency one or more lines will be printed identifying the file system on which the correction will take
place, and the nature of the correction. After successfully correcting a file system, fsck will print the
number of files on that file system and the number of used and free blocks.
Without the -p option, fsck audits and interactively repairs inconsistent conditions for file systems. If the
file system is inconsistent the operator is prompted for concurrence before each correction is attempted It
should be noted that a number of the corrective actions which are not fixable under the -p option will result
in some loss of data. The amount and severity of data lost may be determined from the diagnostic output.
The default action for each consistency correction is to wait for the operator to respond yes or no. If the
operator does not have write permissionfsck will default to a -0 action.

Fsck has more consistency checks than its predecessors check. dcheck.fcheck. and icheck combined.
The following flags are interpreted by fsck.
-b

Use the block specified immediately after the flag as the super block for the file system. Block 32 is
always an alternate super block.

-y

Assume a yes response to all questions asked by fsck; this should be used with great caution as this
is a free license to contir ue after essentially unlimited trouble has been encountered

-0

Assume a no response to all questions asked by fsck; do not open the file system for writing.

If no filesystems are given to fsck then a default list of file systems is read from the file letc!fstab.

594

Last change: 17 February 1986

Sun Release 3.2

FSCK( 8)

MAINTENANCE COMMANDS

FSCK(8 )

Inconsistencies checked are as follows:
1.

8.

Blocks claimed by more than one inode or the free list.
Blocks claimed by an inode or the free list outside the range of the file system.
Incorrect link counts.
Size checks:
Directory size not of proper format.
Bad inode format.
Blocks not accounted for anywhere.
Directory checks:
File pointing to unallocated inode.
Inode number out of range.
Super Block checks:

9.
10.

More blocks for inodes than there are in the file system.
Bad free block list format.
Total free block and/or free inode count incorrect.

2.
3.
4.
5.
6.
7.

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 inode 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 entries can be made. This is accomplished by making lost+found, copying a
number of files to the directory, and then removing them (before fsck is executed).
Checking the raw device is almost always faster.
FILES

/etclfstab

contains default list of file systems to check.

DIAGNOSTICS

The diagnostics produced by Isck are intended to be self-explanatory.
EXIT STATUS

o

Either no errors detected or all errors were corrected.

4

Root filesystem errors were corrected. The system must be rebooted.

8

Some uncorrected errors exist on one or more of the filesystems checked, there was a syntax error,
or some other operational error occurred.

12

A signal was caught during processing.

SEE ALSO

fstab(5), fs(5), newfs(8), mkfs(8), crash(8S), reboot(8)
BUGS

Inode numbers for. and •• in each directory should be checked for validity.
There should be some way to start a fsek -p at pass n.

Sun Release 3.2

Last change: 17 February 1986

595

MAThnENANCECO~ANDS

FSIRAND(8)

FSIRAND(8)

NAME

fsirand - install random inode generation numbers
SYNOPSIS
fsirand [ -p ] special
DESCRIPTION

Fsirand installs random inode generation numbers on all the inodes on device special, and also installs a
filesystem ID in the superblock. This helps increase the security of filesystems exported by NFS.
Fsirand must be used only on an unmounted filesystem that has been checked with fsck(8). The only
exception is that it can be used on the root filesystem in single-user mode, if the system is immediately rebooted afterwords.
OPTIONS

-p

596

Print out the generation numbers for all the inodes, but do not change the generation numbers.

Last change: 1 February 1985

Sun Release 3.2

FTPD(8C)

MAINTENANCE COMMANDS

FfPD(8C)

NAME

ftpd - DARPA Internet File Transfer Protocol server
SYNOPSIS

lusr/etc/in.ftpd host socket
DESCRIPTION

Ftpd is the DARPA Internet File Transfer Prototocol server process. The server is invoked by the Internet
daemon inetd(8C) each time a connection to the ftp service (see services(5» is made, with the connection
available as descriptor 0 and the host and socket the connection originated from (in hex and decimal
respectively) as argument

Inactive connections are timed out after 60 seconds.
The ftp server currently supports the following ftp requests; case is not distinguished.
Request
ACCT
ALLO
APPE
CWD
DELE
HELP
LIST
MODE
NLST
NOOP
PASS
PORT
QUIT
RETR
RNFR
RNTO
STOR
STRU
TYPE
USER
XCUP
XCWD
XMKD
XPWD
XRMD

Description
specify account (ignored)
allocate storage (vacuously)
append to a file
change working directory
delete a file
give help information
give list files in a directory ("Is -lg")
specify data transfer mode
give name list of files in directory (' 'Is")
do nothing
specify password
specify data connection port
terminate session
retrieve a file
specify rename-from file name
specify rename-to file name
store a file
specify data transfer structure
specify data transfer type
specify user name
change to parent of current working directory
change working directory
make a directory
print the current working directory
remove a directory

The remaining ftp requests specified in Internet RFC 765 are recognized, but not implemented.
Ftpd interprets file names according to the "globbing" conventions used by csh(1). This allows users to
utilize the metacharacters "*?O{r".
Ftpd authenticates users according to three rules.

1)

The user name must be in the password data base, letc/passwd, and not have a null password. In
this case a password must be provided by the client before any file operations may be performed.

2)

The user name must not appear in the file lusrletclftpusers.

3)

If the user name is "anonymous" or "ftp", an anonymous ftp account must be present in the
password file (user "ftp"). In this case the user is allowed to log in by specifying any password
(by convention this is given as the client host's name).

Sun Release 3.2

Last change: 23 October 1984

597

FTPD(8C)

MAINTENANCE COMMANDS

FTPD(8C)

In the last case, ftpd takes special measures to restrict the client's access privileges. The server performs a
chroot(2) command to the home directory of the "ftp" user. In order that system security is not breached,
it is recommended that the "ftp" subtree be constructed with care; the following rules are recommended.
-ftp

Make the home directory owned by "ftp" and unwritable by anyone.

-ftp/bin

Make this directory owned by the super-user and unwritable by anyone. The program Is(lV)
must be present to support the list commands. This program should have mode 111.

-ftp/etc

Make this directory owned by the super-user and unwritable by anyone. The files passwd(5) and
group(5) must be present for the Is command to work properly. These files should be mode 444.

-ftp/pub Make this directory mode 777 and owned by "ftp". Users should then place files which are to
be accessible via the anonymous account in this directory.
SEE ALSO

ftp(lC), ftpusers(5)
BUGS

There is no support for aborting commands.
The anonymous account is inherently dangerous and should avoided when possible.
The server must run as the super-user to create sockets with privileged port numbers. It maintains an effective user id of the logged in user, reverting to the super-user only when binding addresses to sockets. The
possible security holes have been extensively scrutinized, but are possibly incomplete.

598

Last change: 23 October 1984

Sun Release 3.2

GEITABLE ( 8C )

MAINTENANCE COMMANDS

GETTABLE ( 8C)

NAME

gettable - get NIC format host tables from a host
SYNOPSIS

letc/gettable host
DESCRIPTION

Gettable is a simple program used to obtain the NIC standard host tables from a "nicname" server. The
indicated host is queried for the tables. The tables, if retrieved, are placed in the file hosts. txt .
Gettable operates by opening a TCP connection to the port indicated in the service specification for' 'nicname". A request is then made for" ALL" names and the resultant information is placed in the output
file.
Gettable is best used in conjunction with the htable(8) program which converts the NIC standard file format to that used by the network library lookup routines.
SEE ALSO

intro(3N), htable(8)
BUGS

Should allow requests for only part of the database.

Sun Release 3.2

Last change: 4 March 1983

599

GETIY(8)

MAINTENANCE COMMANDS

GETIY(8)

NAME

getty - set terminal mode
SYNOPSIS

fetc/getty [char]
DESCRIPTION
Getty is invoked by init(8) immediately after a terminal is opened, following the making of a connection.
While reading the name getty attempts to adapt the system to the speed and type of terminal being used.

Init calls getty with an argument specified by the ttys file entry for the terminal line. Arguments other than
'0' can be used to make getty treat the line specially. Refer to ttys(5) and gettytab (5) for descriptions of
how getty uses the data in gettytab to set up the terminal. Normally, it sets the speed of the interface to 300
baud, specifies that raw mode is to be used (break on every character), that echo is to be suppressed, and
either parity allowed. It types a banner identifying the system (from gethostname(2» and the 'login:' message. Then the user's name is read, a character at a time. If a null character is received, it is assumed to be
the result of the user pushing the 'break' ('interrupt') key. The speed is then changed to 1200 baud and the
'login:' is typed again; a second 'break' changes the speed to 150 baud and the 'login:' is typed again.
Successive 'break' characters cycle through the speeds 300, 1200, and 150 baud.
The user's name is terminated by a new-line or carriage-return character. The latter results in the system
being set to treat carriage returns appropriately (see tty(4».
The user's name is scanned to see if it contains any lower-case alphabetic characters; if not, and if the
name is nonempty, the system is told to map any future upper-case characters into the corresponding
lower-case characters.
Finally, login is called with the user's name as argument.
SEE ALSO
init(8), login(l), ioctl(2), tty(4), ttys(5), gettytab(5)

600

Last change: 28 October 1983

Sun Release 3.2

GPCONFIG ( 8 )

MAINTENANCE COMMANDS

GPCONFIG ( 8 )

NAME

gpconfig - initialize the Graphics Processor
SYOPNSIS

lusr/etc/gpconfig gpunit [ [ -b ] [ -f ]fbunit ... ]
DESCRIPTION
gpeonfig binds egtwo frame buffers to the Graphics Processor (GP), and loads and starts the appropriate

microcode in the GP. For example, the command line:
lusr/etc/gpconfig gponeO cgtwoO cgtwo1

will bind the fra~e buffer boards egtwoO and egtwol to the Graphics Processor gponeO. The devices
IdevlgponeOa and IdevlgponeOb will then refer to the combination of gpone and egtwoO or egtwol respectively.
The same egtwo frame buffer cannot be bound to more than one GP.
All egtwo frame buffer boards bound to a GP must be configured to the same width and height.
The standard version of the file letclre.loeal contains the following gpeonfig command line:
"/usr/etc/gpconfig gponeO -f -b cgtwoO"

This binds gponeO and egtwoO as gponeOa, causes gponeOa to use the Graphics Buffer Board if it is
present, and redirects Idev!Jb to be IdevlgponeOa. If another configuration is desired, edit the command line
in letclre.loeal to do the appropriate thing.
It is inadvisable to run the gpeonfig command while the GP is being used. Unpredictable results may
occur. If it is neccessary to change the frame buffer bindings to the GP (or to stop using the GP altogether), bring the system down gently, boot single user, edit the gpeonfig line in the letclrc.loeal file, and
bring the system back up multiuser.
OPTIONS

-b

Configure the GP to use the Graphics Buffer as well. Currently only one GP-to-frame-buffer
binding is allowed to use the graphics buffer at a time. Only the last -b option· in the command
line takes effect

-f

Redirect Idev!Jb to the device formed by binding gpunit withfbunit. Only the last -f option in the
command line takes effect

FILES

Idevlegtwo[O-9J
ldevlfb
Ide vIgpone[O-3JIabed]
lusrlliblgpleg2.1024.ueode
lusrlliblgpl cg2.1152.ueode
letclre.loeal
SEE ALSO

cgtwo(4S), gpone(4S)

Sun Release 3.2

Last change: 25 July 1986

601

GXTEST(8S)

MAINTENANCE COMMANDS

GXTEST(8S)

NAME

gxtest - stand alone test for the Sun video graphics board
SYNOPSIS

b Istand/gxtest
DES CRIPT ON

Gxtest runs stand alone, not under control of the UNIX operating system. With the PROM resident monitor in control of the system, type the command:
> b Istandlgxtest

and the monitor boots the video test program into memory. Gxtest is completely self-explanatory and runs
under its own steam. It reports any errors it finds on the screen.

602

Last change: 23 March 1983

Sun Release 3.2

HALT(8)

MAINTENANCE COMMANDS

HALT(8)

NAME

halt - stop the processor
SYNOPSIS

letclhalt [ -0 ] [ -q] [ -y ]
DESCRIPTION
Halt writes out sandbagged information to the disks and then stops the processor.
OPTIONS
-0

Prevents the sync before stopping.

-q

Do a quick halt, no graceful shutdown is attempted.

-y

Needed if you are trying to halt the system from a dialup.

SEE ALSO
reboot(8), shutdown(8)

Sun Release 3.2

Last change: 1 April 1983

603

HTABLE(8)

MAINTENANCE COMMANDS

HTABLE(8)

NAME

htable - convert NIC standard format host tables
SYNOPSIS

lusr/etc/htable file
DESCRIPTION

Htable is used to convert host files in the format specified in Internet RFC 810 to the format used by the
network library routines. Three files are created as a result of running htable: hosts, networks, and gateways. The hosts file is used by the gethostent(3N) routines in mapping host names to addresses. The networks file is used by the getnetent(3N) routines in mapping network names to numbers. The gateways file
is used by the routing daemon in identifying "passive" Internet gateways; see routed(8C) for an explanation.
If any of the files loealhosts, loealnetworks, or loealgateways are present in the current directory, the file's
contents is prepended to the output file without interpretation. This allows sites to maintain local aliases
and entries which are not normally present in the master database.

Htable is best used in conjunction with the gettable(8C) program which retrieves the NIC database from a
host.
SEE ALSO

intro(3N), gettable(8C)

BUGS
Does not properly calculate the gateways file.

604

Last change: 19 August 1983

Sun Release 3.2

ICHECK(8)

MAINTENANCE COMMANDS

ICHECK(8)

NAME

icheck - file system storage consistency check
SYNOPSIS

lusr/etc/icbeck [ -s] [-b numbers] [filesystem]
DESCRIPTION
Note: [check has been superceded for normal consistency checking by fsck(8).

[check examines a file syste~ builds a bit map of used blocks, and compares this bit map against the free
list maintained on the file system. If the file system is not specified, a set of default file systems is checked.
The normal output of icheck includes a report of
The total number of files and the numbers of regular, directory, block special and character special
files.
The total number of blocks in use and the numbers of single-, double-, and triple-indirect blocks
and directory blocks.
The number of free blocks.
The number of blocks missing; i.e. not in any file nor in the free list.
The -s option causes icheck to ignore the actual free list and reconstruct a new one by rewriting the superblock of the file system. The file system should be dismounted while this is done; if this is not possible (for
example if the root file system has to be salvaged) care should be taken that the system is quiescent and that
it is rebooted immediately afterwards so that the old, bad in-core copy of the super-block will not continue
to be used. Notice also that the words in the super-block which indicate the size of the free list and of the
i-list are believed. If the super-block has been curdled these words will have to be patched. The -s option
causes the normal output reports to be suppressed.
Following the -b option is a list of block numbers; whenever any of the named blocks turns up in a file, a
diagnostic is produced.

[check is faster if the raw version of the special file is used, since it reads the i-list many blocks at a time.
FILES

Default file systems vary with installation.
SEE ALSO
fsck(8), dcheck(8), ncheck(8), fs(5), clri(8)
DIAGNOSTICS
For duplicate blocks and bad blocks (which lie outside the file system) icheck announces the difficulty, the
i-number, and the kind of block involved. If a read error is encountered, the block number of the bad block
is printed and icheck considers it to contain O. 'Bad freeblock' means that a block number outside the
available space was encountered in the free list. 'n dups in free' means that n blocks were found in the free
list which duplicate blocks either in some file or in the earlier part of the free list
BUGS

Since icheck is inherently two-pass in nature, extraneous diagnostics may be produced if applied to active
file systems.
It believes even preposterous super-blocks and consequently can get core images.
The system should be fixed so that the reboot after fixing the root file system is not necessary.

Sun Release 3.2

Last change: 4 February 1983

605

IFCONFIG ( 8C )

MAINTENANCE COMMANDS

IFCONFIG ( 8C)

NAME

ifconfig - configure network interface parameters
SYOPNSIS

/etc/ifconfig interface [ Ethernet_address] [ hostname] [parameters]
DESCRTPTION

lfconfig is used to assign an address to a network interface and/or to configure network interface parameters. Ifconfig must be used at boot time to define the network address of each interface present on a
machine; it may also be used at a later time to redefine an interface's address. Used without options,
ifconfig displays the current configuration for a network interface. Only the super-user may modify the
configuration of a network interface.
The interface parameter is a string of the form "name unit", for example "ieO".
OPTIONS

Ethernet_address is the hardware Ethernet address of a given machine. The address is a 6-byte hexadecimal value; each byte of the address is separated by a colon. A typical Ethernet adddress is
'8:0:20:1:1:A3'. This address is contained in the ID PROM on the Sun-2 CPU Board, and is reported at
boot time as one of the PROM monitor's sign-on messages. The Ethernet_address option is normally not
used - the hardware supplies the default; the option is used only when trying to talk to a device which
does not support ARP.
hostname may be either the hostname of a given machine (present in the hostname database, hosts(5», or
the complete Internet address consisting of your system's network number and the machine's unique host
number. A typical Internet address might be "192.9.200.44", where "192.9.200" is the network number
and "44" is the machine's hostnumber. To find a machine's Internet address, consult the local/etc/hosts
file.
The following parameters may be set with ifconfig:
up

Mark an interface "up".

down

Mark an interface "down". When an interface is marked "down", the system will not
attempt to transmit messages through that interface.

trailers

Enable the use of a "trailer" link level encapsulation when sending (default). If a network interface supports trailers, the system will, when possible, encapsulate outgoing
messages in a manner which minimizes the number of memory to memory copy operations performed by the receiver.

-trailers

Disable the use of a "trailer" link level encapsulation.

arp

Enable the use of the Address Resolution Protocol in mapping between network level
addresses and link level addresses (default). This is currently implemented for mapping
between DARPA Internet addreses and 10Mb/s Ethernet addresses.

-arp

Disable the use of the Address Resolution Protocol.

EXAMPLE

If your workstation is not attached to an Ethernet, the ieO interface should be marked "down" as follows:
ifconfig ieO down
DIAGNOSTICS

Messages indicating the specified interface does not exit, the requested address is unknown, the user is not
privileged and tried to alter an interface's configuration.
SEE ALSO

rc(8), intro(3N), netstat(8C)

606

Last change: 9 March 1986

Sun Release 3.2

IMEMTEST (8S)

MAINTENANCE COMMANDS

IMEMTEST (8S )

NAME

imemtest - stand alone memory test
SYNOPSIS

b Istand/imemtest
DESCRIPTON
]memtest runs stand alone, not under control of the UNIX operating system. With the PROM resident
monitor in control of the system, type the command:

> b Istandlimemtest

and the monitor boots the memory test program into memory. ]memtest is completely self-explanatory. It
prompts for all start and end addresses, and after that it runs under its own steam. It reports any errors it
finds on the screen.

Sun Release 3.2

Last change: 23 March 1983

(fJ7

INETD(8)

INETD(8)

MAINTENANCE COMMANDS

NAME

inetd - internet services daemon
SYNOPSIS
lete/inetd [ -d ]
DESCRIPTION
[netd is the internet super-server which invokes all internet server processes as needed. Connectionoriented services are invoked each time a connection is made, by creating a process. This process is passed
the connection as file descriptor 0 and an argument of the form "sourcehost.sourceport" where sourcehost
is hex and sourceport is decimal.

Datagram oriented services are invoked when a datagram arrives; a process is created and passed the connection as file descriptor O. Inetd will look at the socket where datagrarns arrive again only after this process completes. The paradigms for such- proceses are either to read off the incoming datagram and then
fork and exit, or to process the arriving datagram and then time out
[netd consults servers(5) when it is invoked, and supports whatever services are in that file.
An rpc server can be started from inetd. The only differences from the usual code are that svcudp_create
should be called as:

transp = scvudp_ create(O)
since inet passes a socket file as descriptor 0, and svc_register should be called as:
svc_register{PROGNUM, VERSNUM, service, transp, 0)
with the final flag as 0, since the program will already have been registered by inetd. If you want to exit
from the server process and return control to inet, you must explicitly exit since scv_run never returns.
The format of entries in fetclservers for rpc services is:
rpe udp server-program program-number version-number
where server-program is the C code implementing the server, and program-number, version-number are
the program, and version numbers, respectively of the service. The keyword udp can be replaced by tep
for tep -based services.

If the same program handles multiple versions, the version number can be specified as a range:
rpe udp lusr/ete/rstatd 1000011-2
OPTIONS

-d

Specifies that debugging traces are to be turned on for connection-oriented (TCP) services.

FILES
f etc/servers

list of internet server processes

SEE ALSO
servers(5), comsat(8C), ftpd(8C), rexecd(8C), rlogind(8C), syslog(8), rshd(8C), talkd(8C), telnetd(8C),
tftpd(8C)
BUGS

There is no provision for selectively invoking TCP debugging packet tracing per-service.
Should reread the fetclservers file on receipt of a SIGHUP signal. The fetc/servers file can have no more
than 26 lines.

608

Last change: 28 February 1985

Sun Release 3.2

INIT(8)

MAINTENANCE COMMANDS

INIT(8)

NAME

init - process control initialization
SYNOPSIS

letc/init
DESCRIPTION
init is invoked inside UNIX as the last step in the boot procedure. It normally runs the sequence of commands in the script lete!rc.boot (see rc(8» to check the file system. If passed the -b flag from the boot
program, init skips this step. If the file system check succeeds or is skipped, init runs the commands in
letclrc and lete!rc.local to begin multiuser operation; otherwise it commences single-user operation by giving the super-user a shell on the console. It is possible to pass the -s parameter from the boot program to
init so that single-user operation is commenced immediately.

Whenever single-user operation is terminated (for instance by killing the single-user shell) init runs the
scripts mentioned above.
In multi-user operation, init's role is to create a process for each terminal port on which a user may log in.
To begin such operations, it reads the file lete!ttys and forks several times to create a process for each terminal specified in the file. Each of these processes opens the appropriate terminal for reading and writing.
These channels thus receive file descriptors 0, 1 and 2, the standard input and output and the diagnostic output. Opening the terminal will usually involve a delay, since the open is not completed until someone is
dialed up and carrier established on the channel. If a terminal exists but an error occurs when trying to
open the terminal init complains by writing a message to the system console; the message is repeated every
10 minutes for each such terminal until the terminal is shut off in letc/ttys and init notified (by a hangup, as
described below), or the terminal becomes accessible (init checks again every minute). After an open
succeeds, lete! getty is called with argument as specified by the second character of the ttys file line.
getty(8) reads the user's name and invokes login(l) to log in the user and execute the shell.
Ultimately the shell will terminate because it received end-of-file, either explicitly, as a result of hanging
up, or from the user logging out. The main path of init, which has been waiting for such an event, wakes
up and removes the appropriate entry from the file utmp, which records current users. init then makes an
entry in lusrladmlwtmp, which maintains a history of logins and logouts. The wtmp entry is made only if a
user logged in successfully on the line. Then the appropriate terminal is reopened and getty is reinvoked.

init catches the hangup signal (SIGHUP) and interprets it to mean that the file lete!ttys should be read
again. The shell process on each line which used to be active in ttys but is no longer there is terminated; a
new process is created for each added line; lines unchanged in the file are undisturbed. Thus it is possible
to drop or add phone lines without rebooting the system by changing the ttys file and sending a hangup signal to the init process: use "kill-HUP 1".
init terminates multi-user operations and resumes single-user mode if sent a terminate (TERM) signal: "kill
-TERM 1". If there are processes outstanding which are deadlocked (due to hardware or software failure),
init does not wait for them all to die (which might take forever), but times out after 30 seconds and prints a
warning message.
init ceases creating new getty(8) processes, and allows the system to slowly die away, when sent a terminal
stop (TSTP) signal: "kill - TSTP 1". A later hangup will resume full multi-user operations, or a terminate
will initiate a single user shell. This hook is used by reboot(8) and halt(8).
init's role is so critical that if it dies, the system will reboot itself automatically. If, at bootstrap time, the
init process cannot be located, the system will loop in user mode at location Ox13.
DIAGNOSTICS

init: tty: cannot open. A terminal listed in the the letclttys file cannot be opened, typically because the
requisite lines are either not configured into the system or the associated device was not attached during
boot-time system configuration.

Sun Release 3.2

Last change: 30 October 1983

609

MAINTENANCE COMMANDS

INIT(8)

INIT(8)

WARNING: Something is hung (wont die); ps axl advised. A process is hung and could not be killed
when the system was shutting down. This is usually caused by a process which is stuck in a device driver
due to a persistent device error condition.
FILES

ldev/console, Idev/tty*, letc/utmp, lusr/admlwtmp, letc/ttys, letc/rc
SEE ALSO
login(l), kill(l), sh(l), ttys(5), getty(8), rc(8), reboot(8), halt(8), shutdown(8)
BUGS

When coming up single-user, the system does not require the super-user to log in. To force a login when
running single-user, add the line:
login root
to the file I.profile.

610

Last change: 30 October 1983

Sun Release 3.2

IOSTAT(8)

MAINTENANCE COMMANDS

IOSTAT(8)

NAME

iostat - report I/O statistics
SYNOPSIS
iostat [ interval [ count] ]
DESCRIPTION
fostat iteratively reports the number of characters read and written to terminals, and, for each disk, the
number of seeks and transfers per second, and the milliseconds per average seek. It also gives the percentage of time the system has spent in user mode, in user mode running low priority (niced) processes, in system mode, and idling.

To compute this information, for each disk, seeks and data transfer completions and number of words
transferred are counted; for terminals collectively, the number of input and output characters are counted.
Also, each fiftieth of a second, the state of each disk is examined and a tally is made if the disk is active.
From these numbers and given the transfer rates of the devices it is possible to determine average seek
times for each device.
The optional interval argument causes iostat to report once each interval seconds. The first report is for all
time since a reboot and each subsequent report is for the last interval only.
The optional count argument restricts the number of reports.
FILES

ldevlkrnem
Ivmunix
SEE ALSO
vrnstat(8)

Sun Release 3.2

Last change: 1 February 1985

611

MAThITENANCECO~ANDS

KADB(8S)

KADB(8S)

NAME

kadb - adb-like kernel and standalone-program debugger
SYNOPSIS

LI-A
> b kadb [ -d] [boot-flags]

DESCRIPTION

kadb is an interactive debugger that is similar in operation to adb(l), and runs as a standalone program
under the PROM monitor. You can use kadb to debug the UNIX kernel, or to debug the standalone program
of your choice.
Unlike adb, kadb runs in the same supervisor virtual address space as the program being debuggedalthough it maintains a separate context. The debugger runs as a coprocess that cannot be killed (no :k) or
rerun (no :r). There is no signal control (no :i, :t, or $i), although the UNIX keyboard facilities ("C,"S and
"Q) are simulated.
While the kernel is running under kadb, the abort sequence (LI-A or BREAK) causes UNIX to drop into kadb
for debugging - as will a system panic. With other standalone programs, you can invoke kadb from the
monitor (after entering the abort sequence) by jumping to the starting address for kadb found in
 (currently this can be done for both Sun-2 and Sun-3 machines by typing the command g
fdOOOOO). kadb' s user interface is. similar to adb, except that kadb prompts with
kadb>

Most adb commands work as expected Typing an abort sequence in response to the prompt returns you to
the PROM monitor, from which you can examine control spaces that aren't accessible within adb or kadb.
The monitor command c returns you to kadb. As with "adb -k", $p works when debugging UNIX kernels
(by actually mapping in new user pages). The adb verbs? and I are equivalent, since there is only one
address space in use.
KERNEL MACROS

As with adb, kernel macros are supported With kadb, however the macros are compiled into the debugger
itself, rather than being read in from the file system. The kadb command $M lists macros known to kadb.
AUTOMATIC REBOOTING WITH KADB
You can set up a Sun-3 to automatically reboot kadb by patching the "vmunix" variable in Iboot with the

string "kadb" instead of "vmunix". (Refer to adb in Program Debugging Tools/or the Sun Workstation
for details on how to patch executables.) If, however, your Workstation is set up to boot over the network
from a partition other than pubO, then you must patch the short kadb variable "ndbootdev" to be "OxO",
for the private nd partition, or "Ox41" for the pub1 nd partition.
OPTIONS

kadb is booted from the PROM monitor as a standalone program. If you omit the -d flag, kadb automatically loads and runs vmunix from the filesystem kadb was loaded from. The kadb "vmunix" variable can
be patched to change the default program to be loaded
-d

Interactive startup. Prompts with
kadb:

for a file to be loaded. From here, you can enter a boot sequence line to load a standalone program. Boot flags entered in response to this prompt are included with those already set and passed
to the program. If you type a carriage return only, kadb loads vmunix (from the filesystem that
kadb was loaded from).
boot-flags
You can specify boot flags as arguments when invoking kadb. Note that kadb always sets the -d
(debug) boot flag, and passes it to the program being debugged.

612

Last change: 2 July 1986

Sun Release 3.2

KADB(8S)

MAINTENANCE COMMANDS

KADB(8S)

SETTING BREAKPOINTS

Self-relocating programs such as the Sun-3 kernel need to be relocated before breakpoints can be used. To
set the first breakpoint for such a program, start it with :s; kadb is then entered after the program is relocated (when UNIX initializes its interrupt vectors). Thereafter,:s single-steps as with adb. Otherwise, use
:c to start up the program.
USAGE

Refer to adb in Program Debugging Toolsfor the Sun Workstation.
FILES

Ivrnunix
lboot
lkadb
lusr/include/debugldebug.h
SEE ALSO
adb(l), boot(8S)

Program Debugging Tools for the Sun Workstation
Writing Device Driversfor the Sun Workstation
BUGS

There is no fioating-point support.
kadb cannot reliably single-step over instructions that change the status register.

When sharing the keyboard with UNIX the monitor's input routines can leave the keyboard in a confued
state. If this should happen, disconnect the keybooard momentarily and then reconnect it This forces the
keyboard to reset as well as initiating an abort sequence.
Most of the bugs listed in adb( 1) also apply to kadb.

Sun Release 3.2

Last change: 2 July 1986

613

KGMON(8)

MAINTENANCE COMMANDS

KGMON(8)

NAME

kgmon - generate a dump of the operating system's profile buffers
SYNOPSIS

lusr/etc/kgmon [ -b] [ -b] [ -r] [ -p] [system] [memory]
DESCRIPTION
Kgmon is a tool used when profiling the operating system. When no arguments are supplied, kgmon indicates the state of operating system profiling as running, off, or not configured (see config(8». If the -p :flag
is specified, kgmon extracts profile data from the operating system and produces a gmon.out file suitable for
later analysis by gprof(I).
OPTIONS

-b

Resume the collection of profile data.

-b

Stop the collection of profile data.

-p

Dump the contents of the profile buffers into a gmon.out file.

-r

Reset all the profile buffers. If the -p flag is also specified, the gmon.out file is generated before
the buffers are reset

If neither -b nor -b is specified, the state of profiling collection remains unchanged. For example, if the
-p flag is specified and profile data is being collected, profiling is momentarily suspended, the operating
system profile buffers are dumped, and profiling is immediately resumed.
FILES

Ivmunix - the default system
ldevlkmem - the default memory
SEE ALSO
gprof (1), config(8)
DIAGNOSTICS
Users with only read permission on ldevlkmem cannot change the state of profiling collection. They can
get a gmon.out file with the warning that the data may be inconsistent if profiling is in progress.

614

Last change: 21 April 1983

Sun Release 3.2

LINK(8)

MAINTENANCE COMMANDS

LINK(8)

NAME

link, unlink - exercise link and unlink system calls
SYNOPSIS

/etclIinkfilel file2
/etc/unlink file
DESCRIPTION

link and unlink perform their respective system calls on their arguments, abandoning all error checking.
These commands may only be executed by the super-user.
SEE ALSO

rm( 1), link(2), unlink(2).

Sun Release 3.2

Last change: 25 July 1986

615

LOCKD.(8C)

MAINTENANCE COMMANDS

LOCKD(8C)

NAME

lockd - network lock daemon
SYNOPSIS

letc/rpc.lockd [ -t timeout] [ -g graeeperiod]
DESCRIPTION

Loekd processes lock requests that are either sent locally by the kernel or remotely by another lock daemon. £oekd forwards lock requests for remote data to the server site's lock daemon through the
RPC/XDR(3N) package. Loekd then requests the status monitor daemon, statd(8C), for monitor service.
The reply to the lock request will not be sent to the kernel until the status daemon and the server site's lock
daemon have replied.
If either the status monitor or server site's lock daemon is unavailable, the reply to a lock request for
remote data is delayed until all daemons become available.

When a server recovers, it waits for a grace period for all client site lockds to submit reclaim requests.
Client site lockds, on the other hand, are notified by the statd of the server recovery and promptly resubmit
previously granted lock requests. If a lockd fails to secure a previously granted lock at the server site, the
£oekd sends SIGLOST to a process.
OPTIONS
-t timeout Loekd uses timeout (seconds) as the interval instead of the default value (15 seconds) to
retransmit lock request to the remote server.

-g graeeperiod
Loekd uses graeeperiod (seconds) as the grace period duration instead of the default value (45
seconds).
SEE ALSO
fcnt1(2), lockf(3), signal(3), statd(8C)

616

Last change: 16 July 1986

Sun Release 3.2

LPC(8)

MAINTENANCE COMMANDS

LPC(8)

NAME

lpc - line printer control program
SYNOPSIS
/nsr/etc/lpc [ command [ command-parameter ... ] ]
DESCRIPTION
Lpc is the Line Printer Control program and is used by the system administrator to control the operation of
the line printer system. For each line printer configured in letclprintcap (the line printer description database), Ipc may be used to:
disable or enable a printer,
disable or enable a printer's spooling queue,
rearrange the order of jobs in a spooling queue,
find the status of printers, and their associated spooling queues and printer daemons.

Without any arguments, Ipc works interactively and prompts for commands from the standard input. If
arguments are supplied, Ipc interprets the first argument as a command and the remaining arguments as
parameters to the command. The standard input may be redirected so that Ipc reads commands from a file.
Commands may be abreviated; the following is the list of recognized commands. Note that the printer
parameter in the commands is specified just by the name of the printer (printronix for example), not by
-Pprintronix as you would specify it to the Ipr or Ipq commands.
Commands

? [command ... ]
help [command ... ]
Display a short description of each command specified in the argument list, or, if no arguments are
given, a list of the recognized commands.
abort [aU I printer ... ]
Terminate an active spooling daemon on the local host immediately and then disable printing
(preventing new daemons from being started by Ipr) for the specified printers. The abort command can only be used by the super-user.
clean [alii printer ... ]
Remove all files beginning with 'cf, 'tr, or 'df from the specified printer queue(s) on the local
machine. The clean command can only be used by the super-user.
enable [alii printer ... ]
Enable spooling on the local queue for the listed printers, so that lpr can put new jobs in the spool
queue. The enable command can only be used by the super-user.
exit
quit
Exit from Ipc.
disable [aU I printer . .. ]
Turn the specified printer queues off. This prevents new printer jobs from being entered into the
queue by Ipr. The disable command can only be used by the super-user.
restart [aU I printer ... ]
Attempt to start a new printer daemon. This is useful when some abnormal condition causes the
daemon to die unexpectedly leaving jobs in the queue. Lpq reports that there is no daemon
present when this condition occurs.
start [alii printer ... ]
Enable printing and start a spooling daemon for the listed printers. The start command can only
be used by the super-user.
status [aU I printer ... ]
Display the status of daemons and queues on the local machine.
stop [alii printer ... ]
Stop a spooling daemon after the current job completes and disable printing. The stop command
can only be used by the super-user.

Sun Release 3.2

Last change: 1 February 1985

617

LPC(8)

MAINTENANCE COMMANDS

LPC(8)

topqprinter Uobnum ... ] [user •.. ]
Move the printjob(s) specified by jobnum or thosejob(s) belonging to user to the top (head) of the
printer queue. The topq command can only be used by the super-user.
FILES

Ietclprintcap
lusrlspooll*
lusrlspooll*!lock

printer description file
spool directories
lock file for queue control

SEE ALSO
Ipd(8), lpr(l), lpq(l), lprm(l), printcap(5)
DIAGNOSTICS
?Ambiguous command
?Invalid command
?Privileged command

618

abreviation matches more than one command
no match was found
command can be executed by super-user only

Last change: 1 February 1985

Sun Release 3.2

LPD(8)

MAINTENANCE COMMANDS

LPD(8)

NAME

Ipd - line printer daemon
SYNOPSIS
lusrlIib/lpd [ -1] [ -L logfile ] [ port # ]
DESCRIPTION

Lpd is the line printer daemon (spool area handler) and is normally invoked at boot time from the rc(8) file.
It makes a single pass through the printcap(5) file to find out about the existing printers and prints any files
left after a crash. It then uses the system calls listen(2) and accept(2) to receive requests to print files in the
queue, transfer files to the spooling area, display the queue, or remove jobs from the queue. In each case, it
forks a child to handle the request so the parent can continue to listen for more requests. The Internet port
number used to rendezvous with other processes is normally obtained with getservent(3N) but can be
changed with the port# argument The -L option changes the file used for writing error conditions from the
system console to logftle. The -I flag causes lpd to log valid requests received from the network. This can
be useful for debugging purposes.
Access control is provided by two means. First, all requests must come from one of the machines listed in
the file letclhosts.equiv. Second, if the "rs" capability is specified in the printcap entry for the printer
being accessed, lpr requests will only be honored for those users with accounts on the machine with the
printer.
The file lock in each spool directory is used to prevent multiple daemons from becoming active simultaneously, and to store information about the daemon process for lpr(l), lpq(l), and lprm(l). Mter the daemon has successfully set the lock, it scans the directory for files beginning with cf. Lines in each cf file
specify files to be printed or non-printing actions to be performed. Each such line begins with a key character to specify what to do with the remainder of the line.
J

Job Name. String to be used for the job name on the burst page.

C

Classification. String to be used for the classification line on the burst page.

L

Literal. The line contains identification info from the password file and causes the banner page to
be printed.

T

Title. String to be used as the title for pr( 1V).

H

Host Name. Name of the machine where lpr was invoked.

P

Person. Login name of the person who invoked lpr. This is used to verify ownership by lprm.

M

Send mail to the specified user when the current print job completes.

f

Formatted File. Name of a file to print which is already formatted.
Like' 'f' but passes control characters and does not make page breaks.

p

Narne of a file to print using pr( 1V) as a filter.

t

Troff File. The file contains troff( 1) output (CI Aff phototypesetter commands).

d

DVI File. The file contains TEX output (DVI format from Stanford).

g

Graph File. The file contains data produced by plot(3X).

c

Cifplot File. The file contains data produced by cifplot.

v

The file contains a raster image.

r

The file contains text data with FORTRAN carriage control characters.

1

Troff Font R. Name of the font file to use instead of the default

2

Troff Font 1. Name of the font file to use instead of the default.

3

Troff Font B. Name of the font file to use instead of the default

4

Troff Font S. N arne of the font file to use instead of the default.

Sun Release 3.2

Last change: 28 October 1983

619

LPD(8)

MAINTENANCE COMMANDS

LPD(8)

W

Width. Changes the page width (in characters) used by pr(lV) and the text filters.

I

Indent. The number of characters to indent the output by (in ascii).

U

Unlink:. Name of file to remove upon completion of printing.

N

File name. The name of the file which is being printed, or a blank for the standard input (when lpr
is invoked in a pipeline).

If a file can not be opened, a message will be placed in the log file (normally the console). Lpd will try up
to 20 times to reopen a file it expects to be there, after which it will skip the file to be printed.

Lpd uses flock (2) to provide exclusive access to the lock file and to prevent multiple deamons from becoming active simultaneously. If the daemon should be killed or die unexpectedly, the lock file need not be
removed. The lock file is kept in a readable ASCII form and contains two lines. The first is the process id
of the daemon and the second is the control file name of the current job being printed. The second line is
updated to rellect the current status of lpd for the programs lpq(l) and lprm(l).
FILES

I etclprintcap

lusrlspooV*
ldevllp*

letc/hosts.equiv

printer description file
spool directories
line printer devices
lists machine names allowed printer access

SEE ALSO

Ipc(8), pac(8), lpr(l), Ipq(I), Iprm(I), printcap(5)

620

Last change: 28 October 1983

Sun Release 3.2

MAILSTATS (8)

MAINTENANCE COMMANDS

MAILSTATS(8)

NAME

mails tats - print statistics collected by sendmail
SYNOPSIS

lusr/etc/mailstats [filename ]
DESCRIPTION

Mailstats prints out the statistics collected by the sendmail program on mailer usage. These statistics are
collected if the file indicated by the S configuration option of sendmail exists. The mailstats program first
prints the time that the statistics file was created and the last time it was modified. It will then print a table
with one row for each mailer specified in the configuration file. The first column is the mailer number, followed by the symbolic name of the mailer. The next two columns refer to the number of messages
received by sendmail , and the last two columns refer to messages sent by sendmail . The number of messages and their total size (in 1024 byte units) is given. No numbers are printed ifno messages were sent (or
received) for any mailer.
You might want to add an entry to lusrllib/crontab to reinitialize the statistics file once a night Copy
ldev/null into the statistics file or otherwise truncate it to reset the counters.
FILES

lusrllib/sendmai1.st
lusr/lib/ sendmai1.cf

default statistics file
sendmail configuration file

SEE ALSO

sendmail(8)
BUGS

Mailstats should read the configuration file instead of having a hard-wired table mapping mailer numbers to
names.

Sun Release 3.2

Last change: 30 September 1985

621

MAKEDBM(8)

MAThnENANCECOMMANDS

MAKEDBM(8)

NAME

makedbm - make a yellow pages dbm file
SYNOPSIS
makedbm [-i yp_inputJtle] [-0 yp_output_name] [-d yp_domain_name] [-m yp_master_name]
in/de outfile
makedbm [ -u dbmfilename ]
DESCRIPTION
makedbm takes infile and converts it to a pair of files in dbm(3X) format, namely outfile .pag and outfile .dir.
Each line of the input file is converted to a single dbm record. All characters up to the first tab or space
form the key, and the rest of the line is the data. If a line ends with \, then the data for that record is continued on to the next line. It is left for the clients of the yellow pages to interpret #; makedbm does not itself
treat it as a comment character. infile can be -, in which case standard input is read.

makedbm is meant to be used in generating dbm files for the yellow pages, and it generates a special entry
with the key yp_last_modified, which is the date of infile (or the current time, if in/de is -).
OPTIONS
-i

Create a special entry with the key yp_inputJtte .

-0

Create a special entry with the key yp_output_name .

-d

Create a special entry with the key yp_domain_ name .

-m

Create a special entry with the key yp_master_name. If no master host name is specified,
yp_master--"ame will be set to the local host name.

-u

Undo a dbm file. That is, print out a dbm file one entry per line, with a single space separating
keys from values.

EXAMPLE

It is easy to write shell scripts to convert standard files such as /etclpasswd to the key value form used by
makedbm. For example,
f!/bin/awk -f
BEGIN { FS = ":"; OFS = "\t"; }
{ print $1, $0 }

takes the /etclpasswd file and converts it to a form that can be read by makedbm to make the yellow pages
file passwd.byname. That is, the key is a usemame, and the value is the remaining line in the /etc/passwd
file.
SEE ALSO
dbm(3X), yppasswd(l)

622

Last change: 17 September 1985

Sun Release 3.2

MAKEDEV(8)

MAINTENANCE COMMANDS

MAKEDEV(8)

NAME

makedev, MAKEDEV - make system special files
SYNOPSIS
IdevlMAKEDEV device ...
DESCRIPTION
MAKEDEV is a shell script normally used to install special files. It resides in the Idev directory, as this is
the normal location of special files. Arguments to MAKEDEV are usually of the form device-name? where
device-name is one of the supported devices listed in section 4 of the manual and '?' is a logical unit
number (0-9). A few special arguments create assorted collections of devices and are listed below.

std

Create the standard devices for the system; for example, /dev/console, /dev/tty.

local

Create those devices specific to the local site. This request runs the shell file
/dev/MAKEDEV.local. Site specific commands, such as those used to setup dialup lines as 'ttyd?'
should be included in this file.

Since all devices are created using mknod(8), this shell script is useful only to the super-user.
DIAGNOSTICS
Either self-explanatory, or generated by one of the programs called from the script. Use sh x MAKEDEV in case of trouble.
SEE ALSO
intro(4), config(8), mknod(8)

Sun Release 3.2

Last change: 4 March 1983

623

MAKEKEY(8)

MAINTENANCE COMMANDS

MAKEKEY(8)

NAME

makekey - generate encryption key
SYNOPSIS
lusrlIib/makekey
DESCRIPTION

Makekey improves the usefulness of encryption schemes depending on a key by increasing the amount of
time required to search the key space. It reads 10 bytes from its standard input, and writes 13 bytes on its
standard output. The output depends on the input in a way intended to be difficult to compute (that is, to
require a substantial fraction of a second).
The first eight input bytes (the input key) can be arbitrary ASCII characters. The last two (the salt) are best
chosen from the set of digits, upper- and lower-case letters, and '.' and '/'. The salt characters are repeated
as the first two characters of the output The remaining 11 output characters are chosen from the same set
as the salt and constitute the output key.
The transformation performed is essentially the following: the salt is used to select one of 4096 cryptographic machines all based on the National Bureau of Standards DES algorithm, but modified in 4096 different ways. Using the input key as key, a constant string is fed into the machine and recirculated a
number of times. The 64 bits that come out are distributed into the 66 useful key bits in the result

Makekey is intended for programs that perform encryption (for instance, ed and crypt(I». Usually
makekey's input and output will be pipes.
SEE ALSO
crypt(I), ed(l) @(#)mc68881version.8 1.1 86107110 SMI

624

Last change: 4 February 1983

Sun Release 3.2

MC68881 VERSION ( 8 )

MAThITENANCECOMMANDS

MC68881 VERSION ( 8 )

NAME

mc68881 version - print the MC68881 mask number and approximate clock rate
SYNOPSIS

lusr/etc/mc68881 version
DESCRIPTION

mc68881version determines whether an MC68881 floating-point coprocessor is available, and if so, determines its mask number and approximate clock rate and prints them on standard output. The clock rate is
derived by timing floating-point operations with getrusage(2) and is thus somewhat variable.

Sun Release 3.2

Last change: 28 April 1986

625

MCONNECf(8)

MAINTENANCE COMMANDS

MCONNECT (8 )

NAME

mconnect - connect to SMTP mail server socket
SYNOPSIS

lusr/etc/mconnect [ -p port] [-r] [ hostname]
DESCRIPTION

Mconnect opens a connection to the mail server on a given host, so that it can be tested indpendently of all
other mail software. If no host is given, the connection is made to the local host. Servers expect to speak
the Simple Mail Transfer Protocol (SMTP) on this connection. Exit by typing the "quit" command. Typing end-of-file will cause an end of file to be sent to the server. An interrupt closes the connection immediately and exits.
OPTIONS

-p

Specify the port number instead of the default SMTP port (number 25) as the next argument

-r

"Raw" mode: disable the default line buffering and input handling. This gives you a similar
effect as telnet to port number 25, not very useful.

FILES

/usrllib/sendmail.hf

Help file for SMTP commands

SEE ALSO

sendmail(8)
RFC821 - Simple Mail Transfer Protocol, by Jonathan B.Postel, August 1982, SRI Network Information
Center

626

Last change: 30 September 1985

Sun Release 3.2

MKFS(8)

MAINTENANCE COMMANDS

MKFS(8)

NAME

mkfs - construct a file system
SYNOPSIS
letc/mkfs [ -N] special size [ nsect ] [ntrack ] [blksize ] [/ragsize ] [ncpg ] [min/ree ] [rps ] [nbpi ] [

opt]
DESCRIPTION
N.B.: file system are normally created with the newfs(8) command.

mkfs constructs a file system by writing on the special file special unless the -N flag has been specified.
The numeric size specifies the number of sectors in the file system. mkfs builds a file system with a root
directory and a lost+/ound directory (see /sck(8». The number of i-nodes is calculated as a function of the
file system size. No boot program is initialized by mkfs (see newfs(8».
OPTIONS
The optional arguments allow fine tune control over the parameters of the file system.

nsect

The number of sectors per track on the disk

ntrack

The number of tracks per cylinder on the disk

blksize gives the primary block size for files on the file system. It must be a power of two, currently
selected from 4096 or 8192.
/ragsize gives the fragment size for files on the file system. The/ragsize represents the smallest amount of
disk space that will be allocated to a file. It must be a power of two currently selected from the
range 512 to 8192.
ncp g

The number of disk cylinders per cylinder group. This number must be in the range 1 to 32.

minfree specifies the minimum percentage of free disk space allowed. Once the file system capacity
reaches this threshold, only the super-user is allowed to allocate disk blocks. The default value is
10%.

rps

If a disk does not revolve at 60 revolutions per second, this parameter may be specified.

nbpi

Number of bytes for which one i-node block is allocated. This parameter is currently set at one inode block for every 2048 bytes.

opt

Space or time optimization preference; "s" specifies optimizatiion for space, "t" specifies optimization for time.

Users with special demands for their file systems are referred to the paper cited below for a discussion of
the tradeoffs in using different configurations.
SEE ALSO
fs(5), dir(5), fsck(8), newfs(8), tunefs(8)

McKusick, Joy, Leffler; A Fast File System/or Unix, System Internals Manual/or the Sun Workstation.

Sun Release 3.2

Last change: 11 April 1986

627

MKNOD(8)

MAINTENANCE COMMANDS

MKNOD(8)

NAME

mknod - build special file
SYNOPSIS

letc/mknod name [ c ] [b ] major minor
letc/mknod name p
DESCRIPTION

mknod makes a special file. The first argument is the name of the entry. In the first form, the second argument is b if the special file is block-type (disks, tape) or c if it is character-type (other devices). The last
two arguments are numbers specifying the major device type and the minor device (for example, unit,
drive, or line number). Only the super-user is permitted to invoke this form of the mknod command.

In the second form, mknod makes a named pipe (fifo).
The first form of mknod is only for use by system configuration people. Normally you should use
/dev/MAKED EV instead when making special files.
SEE ALSO

mknod(2),makedev(8)

628

Last change: 30 April 1986

Sun Release 3.2

MKPROTO(8)

MAINTENANCE COMMANDS

MKPROTO(8)

NAME

mkproto - construct a prototype file system
SYNOPSIS

lusr/ete/mkproto special proto
DESCRIPTION

Mkproto is used to bootstrap a new file system. First a new file system is created using newfs(8). Mkproto
is then used to copy files from the old file system into the new file system according to the directions found
in the prototype file proto. The prototype file contains tokens separated by spaces or new lines. The first
tokens comprise the specification for the root directory. File specifications consist of tokens giving the
mode, the user-id, the group id, and the initial contents of the file. The syntax of the contents field depends
on the mode.
The mode token for a file is a 6 character string. The first character specifies the type of the file. (The
characters -bed specify regular, block special, character special and directory files respectively.) The
second character of the type is either u or - to specify set-user-id mode or not. The third is g or - for the
set-group-id mode. The rest of the mode is a three digit octal number giving the owner, group, and other
read, write, execute permissions, see chmod(1 V).
Two decimal number tokens come after the mode; they specify the user and group ill's of the owner of the
file.

If the file is a regular file, the next token is a pathname whence the contents and size are copied.
If the file is a block or character special file, two decimal number tokens follow which give the major and
minor device numbers.
If the file is a directory, mkproto makes the entries. and •• and then reads a list of names and (recursively)
file specifications for the entries in the directory. The scan is terminated with the token $.

A sample prototype specification follows:
d-77731
usr
d-7773 1
-7553 Ilhinlsh
sh
ken
d-75561

bO
cO
$

$
b-644 3100
c-644 3 1 0 0

$
SEE ALSO
fs(5), dir(5), fsck(8), newfs(8)
BUGS

There should be some way to specify links.
There should be some way to specify bad blocks.
Mkproto can only be run on virgin file systems. It should be possible to copy files into existent file systems.

Sun Release 3.2

Last change: 10 May 1981

629

MONITOR (8S )

MAINTENANCE COMMANDS

MONITOR (8S)

NAME

monitor - system PROM monitor and command interpreter
SYNOPSIS

Ll-a
BREAK

DESCRIPTION

The CPU board of the Sun workstation contains a PROM (or set of PROMs), called the monitor, that controls the system during startup. The monitor tests the system and then searches for and attempts to boot
UNIX. If you interrupt the boot procedure, or by typing either Ll-a or BREAK, it issues the prompt
>

and accepts commands interactively.
COMMANDS

A[n] [action .. .]
open A-register (cpu address register) n, and perform indicated actions. n can be from 0 to 7. The
default is O. action is a data value in hex; a non-hex character terminates command input.

B [device [(c,u,p)]] [pathname]
boot. Resets appropriate parts of the system, then bootstraps. This allows bootstrap loading of
programs from various devices (such as a disk, tape, or Ethernet connection).
device is one of:

ie

Intel Ethernet

Ie

Lance Ethernet

sd

SCSI disk

st

SCSI 114" tape

mt

Tape Master 9-track 1/2" tape

xt

Xylogics 112" tape

xy

Xylogics 440/450 disk

c

is a controller number (0 if only one controller),

u

is a unit number (0 if only one driver), and,

p

is a partition.

pathname

is a pathname for a program such as Istandldiag. Ivrnunix is the default.
B with no arguments will cause a default boot, either from the disk, or from the Ethernet controller.
B? displays all boot devices and their device arguments.
C [addr]
continue a program. When given, addr is the address at which execution will begin. The default is
the current PC. Registers are restored to the values shown by A, D, and R commands.

D [n] [action . .. ]
open D-register (cpu data register) n, and perform indicated actions. n can be from 0 to 7. The
default is O.
E [addr] [param]
open the 16 bit word at addr (default zero) in the address space defined by the S command.

630

Last change: 9 April 1986

Sun Release 3.2

MAThnENANCECO~ANDS

MONITOR (8S )

F addr1 addr2 [pattern] [size]

MONITOR ( 8S )

Sun 3 only.

Fill address space from (lower) addr1 to (higher) addr2 with the constant, pattern, specified by
size:

b

byte format (the default),

w

word format, or
long word format.

For example, the following command fills the address block from Oxl000 to Ox2000 with the word
pattern, OxABCD:
F 1000 2000 ABeD W
G [addr]
Start the program by executing a subroutine call to the address addr if given, or else to the current
PC. The values of the address and data registers are undefined. The status register is set to Ox2700.

GO

When the monitor is running as a result of being interrupted, force a panic and produce a crash
dump.

G4

When the monitor is running as a result of being interrupted, force a kernel stack trace.

D

Sun 3 only

Display the menu of monitor commands, and their descriptions.

K [number]
If number is:
ocpu reset only. This is the default.

KB

1

reset cpu and mmu.

2

reboot. Resets and clears memory, as with a power-on reset. Runs the PROM-based
diagnostic self test, which can take from 5 to 180 seconds depending upon how much
memory is being tested.

display the system banner.

L [addr] [actions]
open the long (32 bit) word at memory address addr (default zero) in the address space defined by
the S command (below).
M [addr] [actions]
open the segment map entry that maps virtual address addr (default zero) in the address space
defined by the S command (below). The segment map address is the virtual address field from
address bit 27 thru bit 17 of the virtual address presented by the cpu to the mmu.

o [addr] [actions]
open the byte location specified by addr (default zero) in the address space defined by the S command below.
P [addr] [actions]
open the page map entry that maps virtual address addr (default zero) in the address space defined
by the S command.

Q [addr] [actions]

Sun 3 only.

open the EEPROM address addr (default zero) in the EEPROM address space. All addresses are
referenced from the beginning or base of the EEPROM in physical address space, and a limit
check is performed to insure that no address beyond the EEPROM physical space is accessed.
This command is used to examine/modify configuration parameters specifying such things as
amount of memory to test during self test, whether to display a standard or custom banner, if a
serial port (A or B) is to be the system console, etc.

Sun Release 3.2

Last change: 9 April 1986

631

MONITOR (8S )

MAINTENANCE COMMANDS

MONITOR (8S )

R [reg] [actions]
open the miscellaneous registers. reg can be one of:
SS

(68010 Supervisor Stack Pointer),

IS

(68020 Interrupt Stack Pointer),

MS

(68020 Master Stack Pointer),

US

(User Stack Pointer),

SF

(Source Function code),

DF

(Destination Function code),

VB

(Vector Base),

SC

(System Context),

UC

(User Context),

SR

(Status Register), and

PC

(Program Counter).

Alterations to these registers (except SC and UC) do not take effect until the next C command
S [code] set or query the address space to be used by subsequent memory access commands. code is one of:

o

undefined

1

user data space.

2

user program space.

3

user control space.

4

undefined

5

supervisor data space.

6

supervisor program space.

7

supervisor control space.

T[command]

Sun 3 only

trace command. Works with standalone programs that do not affect interrupt vectors.
U [arg] manipulate the serial ports and switches the current operator I/O device. arg can have any of the
following values ( [AB] indicates one of A or B):
[AB]

select serial port A or B as input and output device

[AB]io select serial port A or B as input and output device

632

[AB]i

select serial port A or B for input only

[AB]o

select serial port A or B for output only

k

select keyboard for iriput

ki

select keyboard for input

s

select screen for output

so

select screen for output

ks,sk

select keyboard for input and screen for output

[AB]#

set speed of serial port A (or B) to # (such as 1200,9600, ..)

e

echo input to output

ne

don't echo input to output

Last change: 9 April 1986

Sun Release 3.2

MONITOR (8S )

MAINTENANCE COMMANDS

MONITOR (8S )

u addr set virtual serial port address to addr .

If no serial port is specified when changing speeds, the current input device is changed.
At power-up, the following default settings are used: the default console input device is the Sun
keyboard or if the keyboard is unavailable, serial port A. The default console output device is the
Sun screen or if the graphics board is unavailable, serial port A. All serial ports are set to 9600
Baud.

Sun 3 only

Vaddr} addr2 [size]

display the contents of addresses from (lower) addr} to (higher) address addr2 in the format
specified by size:
b

byte format (the default),

w

word format, or
long word format.
Enter return to pause for viewing; enter another return character resume the display. To
terminate the display at any time, press the space bar. Or, you can use AS and "Q to stop
and start the display.
For example, the following command displays the contents of virtual address space from
address Ox 1000 to Ox2000 in word format:
V 1000 2000W

W [addr] [arg]

Sun 3 only.

Vector to addr. arg is one of:

X

print

prints the contents of virtual address addr as a string.

dump

initiates a crash dump.

trace

produces a stack trace.

Sun 3 only
display a menu of extended tests to be presented, with loop and print options also selectable.
These test commands are provided to permit additional testing of such things as the I/O port connectors at the handle edge of the CPU board, Video memory, workstation memory and the workstation keyboard, as well as permit the boot device paths to be tested.

Z [addr]

Sun 3 only.
set a breakpoint at addr in the address space selected by the S command.

Sun Release 3.2

~tchange:9April

1986

633

MOUNT(8)

MAINTENANCE COMMANDS

MOUNT(8)

NAME

mount, umount - mount and dismount filesystems
SYNOPSIS
letc/mount [-p]
letc/mount -a[fv] [-t type]
letc/mount [-frv] [-t type] [-0 options ]fsname dir
letc/mount [ -vr] [ -0 options ]fsnarne I dir

letc/umount [ -t type] [ -h host]
letc/umount -a[v]
letdumount [ -v ]
DESCRIPTION

mount announces to the system that a filesystemfsname is to be attached to the file tree at the directory dir.
The directory dir must already exist It becomes the name of the newly mounted root The contents of dir
are hidden until the filesystem is unmounted. If fsname is of the form host:path the filesystem type is
assumed to be nfs.
umount announces to the system that the filesystemfsname previously mounted on directory dir should be
removed. Either the filesystem name or the mounted-on directory may be used.
mount and umount maintain a table of mounted filesystems in letclmtab. described in mtab(5). If invoked
without an argument, mount displays the table. If invoked with only one of fsname or dir mount searches
the file letclfstab (see fstab(5» for an entry whose dir or fsname field matches the given argument For
example, if this line is in letclfstab:
Idev/xyOg lusr 4.2 rw 11
then the commands mount lusr and mount Idev/xyOg are shorthand for mount Idev/xyOg lusr
MOUNT OPTIONS
-p
Print the list of mounted filesystems in a format suitable for use in letclfstab.

-a

Attempt to mount all the filesystems described in letc!Jstab. (In this case,fsname and dir are taken
from letc!Jstab.) If a type is specified all of the filesystems in letc!Jstab with that type is mounted.
Filesystems are not necessarily mounted in the order listed in letc!Jstab.

-r

Fake a new letclmtab entry, but do not actually mount any filesystems.

-v

Verbose -

-t

The next argument is the filesystem type. The accepted types are: 4.2, and nrs; see fstab(5) for a
description of these filesystem types.

-r

Mount the specified filesystem read-only. This is a shorthand for:

mount displays a message indicating the filesystem being mounted.

mount -0 ro fsnarne dir
Physically write-protected and magnetic tape filesystems must be mounted read-only, or errors
occur when access times are updated, whether or not any explicit write is attempted.
-0

Specify options. a list of comma seperated words from the list below. Some options are valid for
all filesystem types, while others apply to a specific type only.

options valid on all file systems (the default is rw,suid):

634

rw

read/write.

ro

read-only.

suid

set-uid execution allowed.

nosuid

set-uid execution not allowed.

noauto

do not mount this file system automatically (mount -a).

Last change: 16 May 1986

Sun Release 3.2

MOUNT (8)

MAINTENANCE COMMANDS

MOUNT(8)

options specific to 4.2 file systems (the default is noquota).
quota

usage limits enforced.

noquota

usage limits not enforced.

options specific to nfs (NFS) file systems (the defaults are:
fg,retry=1,timeo=7 ,retrans=3,port=NFS_PORT ,bard
with defaults for rsize and wsize set by the kernel):
bg

if the first mount attempt fails, retry in the background.

fg

retry in foreground

retry=n

set number times to retry mount to n.

rsize=n

set read buffer size to n bytes.

wsize=n

set write buffer size to n bytes.

timeo=n

set NFS timeout to n tenths of a second.

retrans=n

set number of NFS retransmissions to n.

port=n

set server IP port number to n.

soft

return error if server doesn't respond.

bard

retry request until server responds.

intr

allow keybourd interrupts on hard mounts.

The bg option causes mount to run in the background if the server's mountd (8) does not respond.
mount attempts each request retry=n times before giving up. Once the filesystem is mounted,
each NFS request made in the kernel waits timeo=n tenths of a second for a response. If no
response arrives, the time-out is multiplied by 2 and the request is retransmitted. When retrans=n
retransmissions have been sent with no reply a soft mounted filesystem returns an error on the
request and a bard mounted filesystem prints a message and retries the request. Filesystems that
are mounted rw (read-write) should use the bard option. The intr option allows keybourd interrupts to kill a process that is hung waiting for a response on a hard mounted filesystem. The
number of bytes in a read or write request can be set with the rsize and wsize options.

UMOUNT OPTIONS
-b host Unmount all filesystems listed in letclmtab that are remote-mounted from host.
-a

Attempt to unmount all the filesystems currently mounted (listed in letclmtab). In this case,

fsname is taken from letclmtab.
-v

Verbose -

umount displays a message indicating the filesystem being unmounted.

EXAMPLES
mount Idev/xyOg lusr
mount -ft 4.2/dev/ndO I
mount -at 4.2
mount -t nfs serv:/usrlsrc lusrlsrc
mount serv:/usrlsrc lusrlsrc
mount -0 hard serv:/usrlsrc lusrlsrc
mount -p > letc/fstab

mount a local disk
fake an entry for nd root
mount all 4.2 filesystems
mount remote filesystem
same as above
same as above but hard mount
save current mount state

FILES
letc/mtab
letc/fstab

Sun Release 3.2

table of mounted filesystems
table of filesystems mounted at boot

Last change: 16 May 1986

635

MOUNT(8)

MAINTENANCE COMMANDS

MOUNT(8)

SEE ALSO

mount(2), unmount(2), fstab(5), mountd(8C), nfsd(8C)
BUGS

Mounting filesystems full of garbage crashes the system.
No more than one NO client should mount an ND disk partition "read-write" or the file system may
become corrupted
If the directory on which a filesystem is to be mounted is a symbolic link, the filesystem is mounted on the
directory to which the symbolic link refers, rather than being mounted on top of the symbolic link itself.

636

Last change: 16 May 1986

Sun Release 3.2

MOUNTD(8C)

MAINTENANCE COMMANDS

MOUNTD(8C)

NAME

mountd - NFS mount request server
SYNOPSIS

lusr/etc/rpc.mountd
DESCRIPTION

mountd is an rpc server that answers file system mount requests. It reads the file fetc/exports, described in
exports(5), to determine which file systems are available to which machines and users. It also provides
information as to which clients have file systems mounted. This information can be printed using the
showmount(8) command.
The mountd daemon is normally invoked by inetd(8C).
SEE ALSO
exports(5), services(5), inetd(8), showmount(8)

Sun Release 3.2

Last change: 17 February 1986

637

NAMED(8)

MAINTENANCE COMMANDS

NAMED(8)

NAME

named - Internet domain name server
SYNOPSIS

lusr/etc/in.named [ -d level] [ -p port] [ {-b} bootftie ]
DESCRIPTION
named is the Internet domain name server. With no arguments named reads tetc/named.boot, for any initial
data, and listens for queries on the standard Internet port that requires root privilege.
OPTIONS
-d

-p

Print debugging information. level is a number indicating the level of messages printed.
Use a different port number.

-b
Use bootfile rather than tetclnamed.boot.
EXAMPLE

boot file for name server
; type

domain

domain
primary
secondary
cache

berkeley.edu
berkeley.edu named.db
cc.berkeley.edu 10.2.0.78 128.32.0.10
named.ca

source file or host

The 'domain' line specifies that 'berkeley.edu' is the domain of the given server.
The 'primary' line states that the file 'named.db' contains authoritative data for 'berkeley.edu'. The file
'named.db' contains data in the master file format, except that all domain names are relative to the origin;
in this case, 'berkeley.edu' (see below for a more detailed description).
The 'secondary' line specifies that all authoritative data under 'cc.berkeley.edu' is to be transferred from
the name server at '10.2.0.78'. If the transfer fails it will try '128.32.0.10', and continue for up to 10 tries
at that address. The secondary copy is also authoritative for the domain.
The 'cache' line specifies that data in 'named.ca' is to be placed in the cache (i.e., well known data such as
locations of root domain servers). The file 'named.ca' is in the same format as 'named.db' .
The master file consists of entries of the form:
$INCLUDE 
$ORIGIN 
    
where domain is "." for root, "@" for the current origin, or a standard domain name. If domain is a standard domain name that does not end with'.', the current origin is appended to the domain. Domain names
ending with '.' are unmodified.
The opt_ttl field is an optional integer number for the time-to-live field. It defaults to zero.
The opt_class field is currently one token, 'IN' for the Internet.
The type field is one of the following tokens; the data expected in the resource_record_data field is in
parentheses.

638

A

a host address (dotted quad)

NS

an authoritative name server (domain)

MX

a mail exchanger (domain)

Last change: 25 April 1986

Sun Release 3.2

NAMED(8)

MAINTENANCE COMMANDS

NAMED (8)

CNAME the canonical name for an alias (domain)
SOA

marks the start of a zone of authority (5 numbers)

MB

a mailbox domain name (domain)

MG

a mail group member (domain)

MR

a mail rename domain name (domain)

NULL

a null resource record (no format or data)

WKS

a well know service description (not implemented yet)

PTR

a domain name pointer (domain)

HINFO host information (cpu_type OS_type)
MINFO mailbox or mail list information (request_domain error_domain)
NOTES

The following signals have the specified effect when sent to the server process using the kill( 1) command.
SIGHUP Causes server to read named. boot and reload database.
SIGQUIT

Dumps current data base and cache to lusr/tmp/named_dump.db
SIGEMT

Turns on debugging and each SIGEMT increments debug level.
SIGFPE
Turns off debugging completely
FILES
letclnamed.boot

name server configuration boot file

letclnamed.pid

the process id

lusr/tmp/named.run

debug output

lusr/tmp/named_dump.db

dump of the name servers database
SEE ALSO
kill(l), signal(3), resolver(5)

Sun Release 3.2

Last change: 25 April 1986

639

NCHECK(8)

MAINTENANCE COMMANDS

NCHECK(8)

NAME

ncheck - generate names from i-numbers
SYNOPSIS

lusr/etclncheck [ -i numbers] [-8] [ -s] [filesystem]
DESCRIPTION

Note:

For most normal file system maintenance, the function of ncheck is subsumed by fsck(8).

Ncheck with no argument generates a pathnarne versus i-number list of all files on a set of default file systems. Names of directory files are followed by '/.'.
A file system may be specified by the optionalfilesystem argument
The report is in no useful order, and probably should be sorted.
OPTIONS

-inumbers
Report only those files whose i-numbers follow.

-a

Print the names '.' and' •• ', which are ordinarily suppressed.

-s

Report only special files and files with set-user-ID mode. This is intended to discover concealed
violations of security policy.

SEE ALSO

sort(l V), dcheck(8), fsck(8), icheck(8)
DIAGNOSTICS

When the filesystem structure is improper, '11' denotes the 'parent' of a parentIess file and a pathname
beginning with' ••• ' denotes a loop.

640

Last change: 15 November 1983

Sun Release 3.2

ND(8C)

MAINTENANCE COMMANDS

ND(8C)

NAME

nd - network disk control
SYNOPSIS

letc/nd [ command ]
DESCRIPTION

The nd command controls the network disk service of the kernel as described in nd(4P). A single command may be given on the command line; if none is given then the standard input is read for a list of commands. Typically, the file letclnd.local is used for input. Lines beginning with '#' are considered to be
comments.
The available commands are:
user hostname hisunit mydev myoff mysize mylunit maxpkts
For the client hostname transform incoming requests for hisunit into server device mydev at offset
myoff and size mysize sectors. When responding to a read reequest, allow at most maxpkts packets
to be outstanding at one time without a reply. Idev/ndlmylunit provides a local name for this disk
"subpartition". If mysize is -1, then this user unit is equivalent to the entire filesystem partition
mydev (no subpartioning is done.) If mylunit is -1 then no local name is needed for this user unit;
this is usually the case with a swap unit, or a unit represented by an entire filesystem. If hostname
is a numeric zero, hisunit refers to a public unit. Since nd assists diskless clients in booting, the
files (or their equivalent yP maps) letclhosts and letclethers are used to map the users' hostnames
to their IP addresses and ethernet addresses, respectively. If maxpkts is not specified, the default
value is 6.
version versionnumber
The version command gives the level of configuration of the server. Occasionally the need arises
to reorganize or reload the diskless partitions. Since the clients will rewrite locally cached blocks,
they must be kept from writing their filesystems until they reboot Before such a reorganization
occurs, the system manager should warn diskless users to save files and halt their machines.
Modification of the partitions should occur with the disk server off. After modification is complete, versionnumber should be incremented to force users to reboot.
son
Starts the network disk server. This command should be issued after all user, version, and ether
commands.
soft
Stops the disk server until a subsequent son command.
clear
Stops the disk server and clears all user and ether information.
serverat hostname
Systems with disks may use the serverat command to specify a disk server if they wish to use a
network disk in addition to their locally attached disk. Even then, this command is only necessary
if they wish to use a public network disk, or if they wish to change network disk servers.
FILES

letc/ndlocal
letc/hosts
I etc/ ethers
SEE ALSO

nd(4P)
BUGS

No sanity checking of disk partitions is done.

Sun Release 3.2

Last change: 1 February 1985

641

NETSTAT (8C)

MAINTENANCE COMMANDS

NETSTAT(8C)

NAME

nets tat - show network status
SYNOPSIS
netstat [ -ml-il -bl-r ] [ -a ] [ -0 ]

[

-s] [ -t ] [ -A ] [ interval] [system] [ core]

DESCRIPTION

Netstat symbolically displays the contents of various network-related data structures.
The arguments, system and core allow substitutes for the defaults '/vmunix' and '/devlkmem'.
If an interval is specified, netstat continuously displays the information regarding packet traffic on the
configured network interfaces, pausing interval seconds before refreshing the screen.

There are a number of display formats, depending on the information that netstat presents. The display formats are conttolled by the options listed below and are described there.
For each active socket, the internal TPC state is indicated as follows:
CWSED

Dosed - socket not being used

LISTEN

Listening for incoming connections

SYN SENT

Actively trying to establish connection

SYN RECEIVED Initial synchronization of the connection
ESTABLISHED

Connection has been established

CWSE WAIT

Remote shut down, waiting for socket to close

FIN- WAIT- 1
CWSING

Socket closed, shutting down connection
Dosed, then remote shutdown, awaiting acknowledgement

LAST ACK

Remote shutdown, then closed, awaiting acknowledgement

FIN- WAIT- 2
TIME WAIT

Socket closed, waiting for shutdown from remote
Wait after close for remote shutdown retransmission

OPTIONS

Not all of the options listed here can be used in combination. Some of select the information to be
displayed, and others further qualify that specific display. Netstat checks its options in the order -m
(memory management statistics), -i (interface statistics), -b (host table state), and -r (routing tables), and
presents a display for only one of these options.
The default display for active sockets shows the local and remote addresses, send and receive queue sizes
(in bytes), protocol, and the internal state of the protocol. Other display formats are conttolled by the
options listed below.

642

-m

Show statistics recorded by the memory management routines (the network manages a "private
share" of memory)

-i

Show the state of interfaces which have been auto-configured (interfaces statically configured into
a system, but not located at boot time are not shown) The interface display provides a table of
cumulative statistics regarding packets transferred, errors, and collisions. The network address
(currently Internet specific) of the interface and the maximum ttansmission unit ("mtu") are also
displayed.

-b

Show the state of the IMP host table. This does not work in an environment where the IMP host
tables do not exist

-r

Show the routing tables. The routing table display indicates the available routes and their status.
Each route consists of a destination host or network and a gateway to use in forwarding packets.
Thejlags field shows the state of the route ("U" if "up"), and whether the route is to a gateway
("G"). Direct routes are created for each interface attached to the local host. The relent field

Last change: 18 June 1986

Sun Release 3.2

NETSTAT(8C)

MAINTENANCE COMMANDS

NETSTAT(8C)

gives the current number of active uses of the route. Connection oriented protocols normally hold
on to a single route for the duration of a connection while connectionless protocols obtain a route
then discard it. The use field provides a count of the number of packets sent using that route. The
interface entry indicates the network interface utilized for the route.
Options listed below provide further qualification for the display formats listed above.
-A

Show the address of any associated protocol control blocks; used for debugging.

-a

Show the state of all sockets; normally sockets used by server processes are not shown

-n

Show network addresses as numbers (normally netstat interprets addresses and attempts to display
them symbolically).

-s

Show per-protocol statistics. When used with the -r option, the -s option displays routing statistics.

-t

Add timer information to the interface display.

FURTHER NOTES

Address formats are of the form "host.port" or "network.port" if a socket's address specifies a network
but no specific host address. When known the host and network addresses are displayed symbolically
according to the data bases fetc/hosts and fetc/networks, respectively. If a symbolic name for an address is
unknown, or if the -n option is specified, the address is printed in the Internet "dot format"; refer to
inet(3N) for more information regarding this format. Unspecified, or "wildcard", addresses and ports
appear as "*".
When netstat is invoked with an interval argument, it displays a running count of statistics related to network interfaces. This display consists of a column summarizing information for all interfaces, and a
column for the interface with the most traffic since the system was last rebooted. Every 24th line of each
screen of information contains a summary since the system was last rebooted. Subsequent lines of output
show values accumulated over the preceding interval.
SEE ALSO

iostat(8), vmstat(8), hosts(5), networks(5), protocols(5), services(5), trpt(8C)
BUGS

The notion of errors is ill-defined. Collisions mean something else for the IMP.
The kernel's tables can change while netstat is examining them, creating incorrect or partial displays.

Sun Release 3.2

Last change: 18 June 1986

643

NEWALIASES (8 )

MAThITENANCECO~ANDS

NEWALIASES (8 )

NAME

new aliases - rebuild the data base for the mail aliases file
SYNOPSIS
newaliases
DESCRIPTION

Newaliases rebuilds the random access data base for the mail aliasesfilelusrlliblaliases.Itis run automatically by sendmail (8) (in the default configuration) whenever a message is sent.
SEE ALSO
aliases(5),sendmail(8)

644

Last change: 5 June 1986

Sun Release 3.2

NEWFS(8)

MAINTENANCE COMMANDS

NEWFS(8)

NAME

newfs - construct a new file system
SYNOPSIS

fetc/newls [ -N] [ -v] [ -D] [mlifs-options] block-special-file
DESCRIPTION
newfs is a Hfriendly" front-end to the mkfs(8) program. On the Sun, the disk type is determined by reading
the disk label for the specified block-special-file.

block-special-file is the name of a block special device residing in /dev. If you want to make a file system
on sdO, you can specify sdO rsdO or IdevfrsdO; if you only specify sdO, newfs will find the proper device.
newfs then calculates the appropriate parameters to use in calling mkfs, builds the file system by forking
mkfs and, if the file system is a root partition, installs the necessary bootstrap programs in its initial 16 sectors.
OPTIONS
-D

Do not install the bootstrap programs.

-N

Print out the file system parameters without actually creating the file system.

-v

Verbose. newfs prints out its actions, including the parameters passed to mkfs.

mJifs-options
Options that override the default parameters passed to mkfs(8) are:
-b block-size
The block size of the file system in bytes.

-c #cylinders/group
The number of cylinders per cylinder group in a file system. The default value used is
16.

-fJrag-size
The fragment size of the file system in bytes.

-i bytes/inode
This specifies the density of inodes in the file system. The default is to create an inode
for each 2048 bytes of data space. If fewer inodes are desired, a larger number should be
used; to create more inodes a smaller number should be given.

-mfree-space %
The percentage of space reserved from normal users; the minimum free space threshhold.
The default value used is 10%.
-r revolutions/minute
The speed of the disk in revolutions per minute (normally 3600).

-s size The size of the file system in sectors.
-t #tracks/cylinder
FILES

/etc/mkfs
/usr/mdec

to actually build the file system
for boot strapping programs

SEE ALSO
fs(5), fsck(8), tunefs(8)

System Administration for the Sun Workstation

Sun Release 3.2

Last change: 11 April 1986

645

NFSD(8)

MAINTENANCE COMMANDS

NFSD(8)

NAME

nfsd, biod - NFS daemons
SYNOPSIS
letc/nfsd [nservers]

letclbiod [nservers]
DESCRIPTION
nfsd starts the daemons that handle client filesystem requests. nservers is the number of file system request
daemons to start. This number should be based on the load expected on this server. Four seems to be a

good number.
biod starts nservers asynchronous block 110 daemons. This command is used on a NFS client to buffer
cache handle read-ahead and write-behind. The magic number for nservers in here is also four.

When a file that is opened by a client is unlinked (by the server), a file with a name of the form .nfsXXX
(where XXX is a number) is created by the client When the open file is closed, the .nfsXXX file is removed.
If the client crashes before the file can be closed, the .nfsXXX file is not removed.
FILES

.nfsXXX

client machine pointer to an open-but-unlinked file

SEE ALSO

mountd(8C), exports(5)

646

Last change: 26 June 1986

Sun Release 3.2

NFSSTAT(8)

MAINTENANCE COMMANDS

NFSSTAT(8)

NAME

nfsstat - Network File System statistics
SYNOPSIS
nfsstat [ -csnrdz ]
DESCRIPTION
Nfsstat displays statistical information about the Network File System (NFS), Remote Procedure Call
(RPC), and Network Disk (ND) interfaces to the kernel. It can also be used to reinitialize this information.
If no options are given the default is

nfsstat -csnr
That is, print everything except ND information, and reinitialize nothing.
OPTIONS
-c

Display client information. Only the client side NFS and RPC information will be printed. Can
be combined with the -n and -r options to print client NFS or client RPC information only.

-s

Display server information. Works like the -c option above.

-n

Display NFS information. NFS information for both the client and server side will be printed
Can be combined with the -c and -s options to print client or server NFS information only.

-r

Display RPC information. Works like the -n option above.

-d

Display Network Disk (ND) information.

-z

Zero (reinitialize) statistics. This option is for use by the superuser only, and can be combined
with any of the above options to zero particular sets of statistics after printing them.

FILES
Ivmunix

ldevlkmem

Sun Release 3.2

system namelist
kernel memory

Last change: 17 February 1986

647

PAC(8)

MAINTENANCE COMMANDS

PAC(8)

NAME

pac - printer/plotter accounting information
SYNOPSIS
/usr/etc/pac [ -Pprinter ] [ -pprice ] [ -s] [ -r] [ -c ] [name ... ]
DESCRIPTION
Pac reads the printer/plotter accounting files, accumulating the number of pages (the usual case) or feet
(for raster devices) of paper consumed by each user, and printing out how much each user consumed in
pages or feet and dollars. If any names are specified, then statistics are only printed for those users; usually, statistics are printed for every user who has used any paper.
OPTIONS

-Pprinter
Do accounting for the named printer. Normally, accounting is done for the default printer (site
dependent) or the value of the PRIN1ER environment variable is used.

-pprice Use the value price for the cost in dollars instead of the default value of 0.02.

-c

Sorted the output by cost; usually the output is sorted alphabetically by name.

-r

Reverse the sorting order.

-s

Summarize the accounting information on the summary accounting file; this summary is necessary
since on a busy system, the accounting file can grow by several lines per day.

FILES

/usr/adml?acct
/usr/adml? sum

raw accounting files
summary accounting files

BUGS

The relationship between the computed price and reality is as yet unknown.

648

Last change: 19 August 1983

Sun Release 3.2

PING(8)

MAINTENANCE COMMANDS

PING(8)

NAME

ping - network debugging
SYNOPSIS

lusr/etc/ping host [ timeout]
DESCRIPTION
Ping repeatedly sends an icmp echo packet to host and reports whether or not a reply was received. It
keeps trying until timeout seconds have elapsed, or an answer is received The default timeout is 20
seconds. The host argument can be a name or an internet address.
SEE ALSO
icmp(4P)

Sun Release 3.2

Last change: 1 February 1985

649

PORTMAP( 8C)

MAINTENANCE COMMANDS

PORTMAP (8C)

NAME
portmap - DARPA port to RPC program number mapper
SYNOPSIS

lusr/etc/rpc.portmap
DESCRIPTION

Portmap is a server that converts RPC program numbers into DARPA protocol port numbers. It must be
running in order to make RPC calls.

When an RPC server is started, it will tell portmap what port number it is listening to, and what RPC program numbers it is prepared to serve. When a client wishes to make an RPC call to a given program
number, it will first contact portmap on the server machine to determine the port number where RPC packets should be sent.
Normally, standard RPC servers are started by inetd (8C), so portmap must be started before inetd is
invoked.
SEE ALSO

servers(5),rpcinfo(8),inetd(8)
BUGS

If portmap crashes, all servers must be restarted.

650

Last change: 1 February 1985

Sun Release 3.2

PSTAT(8)

MAINTENANCE COMMANDS

PSTAT(8)

NAME

pstat - print system facts
SYNOPSIS

letc/pstat -aixptuIT [ suboptions] [system [corefile ] ]
DESCRIPTION

pstat interprets the contents of certain system tables. If corefile is given, the tables are sought there, otherwise in Idevlkmem. The required namelist is taken from Ivmunix unless system is specified.
OPTIONS

-a

Under -p, describe all process slots rather than just active ones.

-i

Print the inode table including the associated vnode entries with these headings:
LOC
IFLAG

The core location of this table entry.
Miscellaneous inode state variables encoded thus:
A
inode access time must be corrected
C
inode has been changed
L
inode is locked
R
inode is being referenced
T
inode contains a pure text prototype
U
update time (fs(5)) must be corrected
W
wanted by another process (L flag is on)
IDE VICE Major and minor device number of file system in which this· inode resides.
INO
I-number within the device.
MODE
Mode bits in octal, see chmod(2).
NLK
Number of links to this inode.
UID
User ID of owner.
SIZE/DEV
Number of bytes in an ordinary file, or major and minor device of special file.
VFLAG Miscellaneous vnode state variables encoded thus:
R
root of its file system
S
shared lock applied
E
exclusive lock applied
T
vnode is a pure text prototype
Z
process is waiting for a shared or exclusive lock
Number of open file table entries for this vnode.
CNT
Reference count of shared locks on the vnode.
SHC
Reference count of exclusive locks on the vnode (this may be > 1 if, for example, a file
EXC
descriptor is inherited across a fork).
Vnode file type, either VNON (no type), VREG (regular), VDIR (directory), VBLK
TYPE
(block device), VCHR (character device), VLNK (symbolic link), VSOC (socket), or
VBAD (bad).

-x

Print the text table with these headings:
LOC
The core location of this table entry.
FLAGS Miscellaneous state variables encoded thus:
P
resulted from demand-page-from-inode exec format (see execve(2)
T
ptrace (2) in effect
W
text not yet written on swap device
L
loading in progress
K
locked
w
wanted (L flag is on)

Sun Release 3.2

Last change: 4 June 1986

651

PSTAT(8)

MAINTENANCE COMMANDS

PSTAT(8)

DADDR
Disk address in swap, measured in multiples of 512 bytes.
CADDR Head of a linked list of loaded processes using this text segment.

-p

RSS

Resident set size of text segment, measured in pagesize units (2048 for a Sun-2; 8192 for a
Sun-3).

SIZE

Size of text segment, measured in pagesize units.

VPTR

Core location of corresponding vnode.

CNT

Number of processes using this text segment.

CCNT

Number of processes in core using this text segment.

Print process table for active processes with these headings:
LOC
S

F

POIP
PRJ
SJG
UID
SLP
TIM
CPU

652

The core location of this table entry.
Run state encoded thus:
o no process
1
awaiting an event
2
(abandoned state)
3
runnable
4
being created
5
being terminated
6
stopped (by signal or under trace)
Miscellaneous state variables, or'ed together (hexadecimal):
0000001 loaded
0000002 a system process (scheduler or page-out daemon)
0000004 locked for swap out
0000008 swapped out during process creation
00000 10 traced
0000020 used in tracing
0000040 user settable lock in core
()()()()()80 in page-wait
0000100 prevented from swapping duringfork(2)
0000200 will restore old mask after taking signal
0000400 exiting
0000800 doing physical 110
0001000 process resulted from a vfork(2) which is not yet complete
0002000 another flag for vfork (2)
0004000 process has no virtual memory, as it is a parent in the context of vfork (2)
0008000 process is demand paging data pages from its text inode
0010000 process has advised of sequential VM behavior with vadvise(2)
0020000 process has advised of random VM behavior with vadvise (2)
0100000 using old 4. I-compatible signal semantics
0200000 process needs a profiling tick
0400000 process is scanning descriptors during select
1000000 page tables for this process have changed (tlb is dirty)
number of pages currently being pushed out from this process.
Scheduling priority, see setpriority(2).
Signals received (signals 1-32 coded in bits 0-31),
Real user ID.
Amount of time process has been blocked.
Time resident in seconds; times over 127 coded as 127.
Weighted integral of CPU time, for scheduler.

Last change: 4 June 1986

Sun Release 3.2

PSTAT(8)

MAINTENANCE COMMANDS

NI
PGRP
PID
PPID
ADDR
RSS

SRSS
SIZE
WCHAN

PSTAT(8 )

Nice level, see setpriority(2).
Process number of root of process group.
The process ID number.
The process ID of parent process.
If in core, the page frame number of the first page of the 'u-area' of the process. If
swapped out, the position in the swap area measured in multiples of 512 bytes.
Resident set size - the number of physical page frames allocated to this process.
RSS at last swap (0 if never swapped).
Virtual size of process image (data+stack) in multiples of 512 bytes.

Wait channel number of a waiting process.
LINK
Link pointer in list of runnabIe processes.
TEXTP If text is pure, pointer to location of text table entry.
-t

Print table for terminals with these headings:
RAW Number of characters in raw input queue.
CAN Number of characters in canonicalized input queue.
OUT Number of characters in putput queue.
MODE See tty(4).
ADDR Physical device address.
DEL Number of delimiters (newlines) in canonicalized input queue.
COL Calculated column position of terminal.
STATE
Miscellaneous state variables encoded thus:
T
delay timeout in progress
W
waiting for open to complete
o open
F
outq has been flushed during DMA
C
carrier is on
B
busy doing output
A
process is awaiting output
X
open for exclusive use
S
output stopped
H
hangup on close
PGRP Process group for which this is controlling terminal.
DISC Line discipline; blank is old tty OTTYDISC or "new tty" for NTIYDISC or "net" for
NETLDISC (see bk(4».

-u

print information about a user process; the next argument is its address as given by ps(l). The process must be in main memory.

-f

Print the open file table with these headings:
LOC

The core location of this table entry.

TYPE
FLG

The type of object the file table entry points to.
Miscellaneous state variables encoded thus:
R
open for reading
W
open for writing
A
open for appending
S
shared lock present
X
exclusive lock present
I
signal pgrp when data ready

Sun Release 3.2

Last change: 4 June 1986

653

PSTAT(8)

MAINTENANCE COMMANDS

PSTAT(8)

CNT
Number of processes that know this open file.
MSG
Number of references from message queue.
DATA The location of the vnode table entry or socket for this file.
OFFSET
The file offset (see Iseek(2».

-s

print information about swap space usage:
avail:

The total number of (kilobyte) blocks in the swap area.

used:

The number of blocks in use.

(text:)

The number of blocks containing program text

free:

The number of free blocks.

wasted: The number of blocks allocate~ but not currently in use. (Additional text blocks are allocated to a process by a fixed number of blocks, the number data blocks is doubled for each
successive allocation.)
missing:
Blocks that are neither free, nor allocated at the moment A nonzero value may indicate that
swapping occurred while pstat was running.
-T

prints the number of used and free slots in the several system tables and is useful for checking to see
how full system tables have become if the system is under heavy load.

FILES

Ivmunix
namelist
ldevlkmem default source of tables
SEE ALSO

iostat(I), ps(I), vrnstat(I), stat(2), fs(5)
K. Thompson, UNIX Implementation
BUGS

It would be very useful if the system recorded "maximum occupancy" on the tables reported by - T; even
more useful if these tables were dynamically allocated.

654

Last change: 4 June 1986

Sun Release 3.2

PWCK(8)

MAINTENANCE COMMANDS

PWCK(8)

NAME

pwck, grpck - password/group file checkers
SYNOPSIS

letc/pwck [file]
letc/grpck [file ]
DESCRIPTION
pwck scans the password file and notes any inconsistencies. The checks include validation of the number
of fields, login name, user ID, group ID, and whether the login directory and optional program name exist.
The default password file is letclpasswd.

grpck verifies all entries in the group file. This verification includes a check of the number of fields, group
name, group ID, and whether all login names appear in the password file. The default group file is

letc/group.
FILES

fete/group
fetc/passwd
SEE ALSO
groupe4), passwd(4).

Sun Release 3.2

Last change: 25 July 1986

655

QUOT(8)

MAINTENANCE COMMANDS

QUOT(8)

NAME

quot - summarize file system ownership
SYNOPSIS

lusr/etc/quot [ -aetbov] Lfilesystem]
DESCRIPTION
Quot displays the number of blocks (1024 bytes) in the namedfilesystem currently owned by each user.
OPTIONS
-a

Generate are report for all mounted file systems.

-c

Display three columns giving file size in blocks, number of files of that size, and cumulative total
of blocks in that size or smaller file.

-f

Display count of number of files as well as space owned by each user.

-b

Estimate the number of blocks in the file - this doesn't account for files with holes in them.

-n

Run the pipeline nebeck fiIesystem
and their owners.

-v

Display three columns containing the number of blocks not accessed in the last 30, 60, and 90
days.

I sort +00 I quot -0 filesystem

to produce a list of all files

FILES

letc/mtab
letclpasswd

mounted file systems
to get user names

SEE ALSO
Is(1 V), du(l)

656

Last change: 28 August 1985

Sun Release 3.2

QUOTACHECK( 8)

MAINTENANCE COMMANDS

QUOTACHECK(8)

NAME

quotacheck - check file system quota consistency
SYNOPSIS

lusr/etc/quotacheck [ -v] filesystem...
lusr/etc/quotacheck [ -v ] -a
DESCRIPTION

Quotacheck examines each file system, builds a table of current disk usage, and compares this table against
that stored in the disk quota file for the file system. If any inconsistencies are detected, both the quota file
and the current system copy of the incorrect quotas are updated (the latter only occurs if an active file system is checked).
Quotacheck expects each file system to be checked to have a quota file named quotas in the root directory.
If none is present, quotacheck will ignore the file system.
Quotacheck is normally run at boot time from the letc!rc.local file, see rc(8), before enabling disk quotas
with quotaon(8).
Quotacheck accesses the raw device in calculating the actual disk usage for each user. Thus, the file systems checked should be quiescent while quotacheck is running.
OPTIONS

-v

indicate the calculated disk quotas for each user on a particular file system. Quotacheck Normally
reports only those quotas modified.

-a

check all the file systems indicated in letc/fstab to be read-write with disk quotas.

FILES

quotas
letc/mtab
letclfstab

quota file at the file system root
mounted file systems
default file systems

SEE ALSO

quotact1(2), quotaon(8)

Sun Release 3.2

Last change: 15 April 1985

657

MAThnENANCECO~ANDS

QUOTAON(8)

QUOTAON(8)

NAME

quotaon, quotaoff - turn file system quotas on and off
SYNOPSIS

lusr/etc/quotaon [ -v ]filsys...
lusr/etc/quotaon [-v]-a
lusr/etc/quotaoff [ -v ]filsys...
lusr/etc/quotaoff [ -v]-a
DESCRIPTION OF QUOTAON
Quotaon announces to the system that disk quotas should be enabled on one or more file systems. The file
systems specified must be mounted at the time. The file system quota files must be present in the root
directory of the specified file system and be named quotas .
OPTIONS TO QUOTAON
-v
display a message for each file system where quotas are turned on.

-a

all file systems in letc/fstab marked read-write with quotas will have their quotas turned on. This
is normally used at boot time to enable quotas.

DESCRIPTION OF QUOTAOFF
Quotaoff announces to the system that file systems specified should have any disk quotas turned off.
OPTIONS TO QUOTA OFF
-v
display a message for each file system affected.

-a

force all file systems in letclfstab to have their quotas disabled.

These commands update the status field of devices located in letclmtab to indicate when quotas are on or
off for each file system.
FILES

quotas
letc/mtab
letc/fstab

quota file at the file system root
mounted file systems
default file systems

SEE ALSO
quotact1(2), mtab(5), fstab(5)

658

Last change: 15 April 1985

Sun Release 3.2

RARPD(8C)

MAINTENANCE COMMANDS

RARPD(8C)

NAME

rarpd - DARPA Reverse Address Resolution Protocol service
SYNOPSIS
I etc/rarpd if hostname
DESCRIPTION
Rarpd starts a daemon that responds to reverse-arp requests. The daemon forks a copy of itself, and

requires root privileges.
The reverse-arp protocol is used by machines at boot time to discover their (32 bit) IP address given their
(48 bit) Ethernet address. In order for the request to be answered, a machine's name-to-IP-address entry
must exist in the fetc!hosts file and its name-to-Ethernet-address entry must exist in the fetc!ethers file.
Furthermore, the server that runs the rarpd daemon must have entries in both files. Note that if the server
machine is using the Yellow Pages service, the server's files are ignored, and the appropriate yellow pages
maps queried
The first argument if is the interface parameter string in the form of "name unit", for example' 'ieO". The
second argument hostname is the interface's corresponding host name. The if, hostname pair should be the
same as the arguments passed to the ifconfig command. As with ifconfig, rarpd must be invoked for each
interface that the server wishes to support. Therefore a gateway machine may invoke the rarpd multiple
times, for example:
fetefrarpd ieO krypton
fetefrarpd iel krypton-backbone
FILES
fetc!ethers
fetc!ypfdomainnamefethers.byaddr.*
fetcfypl domainnamefethers.byname. *

fetclhosts
fetclypf domainnamefhosts.byname. *
SEE ALSO
ethers(5), hosts(5), ifconfig(8C)

Sun Release 3.2

Last change: 30 September 1985

659

RC(8)

MAINTENANCE COMMANDS

RC(8)

NAME

rc, rc.boot, rc.local- command scripts for auto-reboot and daemons
SYNOPSIS
letc/re

I etc/reo boot

I etc/re.local
DESCRIPTION
re and rc .boot are command scripts that are invoked by init (8) to perform file system housekeeping and to
start system daemons. rc.loeal is a script for commands that are pertinent only to a specific site or client
machine.

re.boot sets the machine name, and then, if corning up multiuser, runs fsck(8) with the -p option. This
"preens" the disks of minor inconsistencies resulting from the last system shutdown and checks for serious
inconsistencies caused by hardware or software failure. Iffsek(8) detects a serious disk problem, it returns
an error and init(8) brings the system up in single-user mode. When corning up single-user, when init(8) is
invoked by fastboot(8), or when it is passed the -b flag from boot(8S), functions performed in the re.local
file, including this disk check, are skipped.
Next, re runs. If the system came up single-user, rc runs when the single-user shell terminates (see init(8».
It mounts 4.2 filesystems and spawns a shell for letclrc.loeal, which mounts NFS filesystems, and starts
local daemons. Mter rc.local returns, rc continues by starting standard daemons, preserves editor files,
clearing Itmp, starting system accounting (if applicable), starting the network (where applicable), and if
enabled, running savecore (8) to preserve the core image after a crash.
FILES
letc/rc

letc/rc.boot
letc/rc.local

SEE ALSO
boot(8), fastboot(8), init(8), reboot(8), savecore(8)

660

Last change: 30 June 1986

Sun Release 3.2

RDATE(8)

MAINTENANCE COMMANDS

RDATE(8)

NAME

rdate - set system date from a remote host
SYNOPSIS

lusr/ucb/rdate hostname
DESCRIPTION

Rdate sets the local date and time from the hostname given as argument You must be super-user on the
local system. Typically rdate can be inserted as part of your letclrc.local startup script
SEE ALSO

timed(8C)
BUGS

Could be modified to accept a list of hostnames and try each until a valid date returned. Better yet would
be to write a real date server that accepted broadcast requests.

Sun Release 3.2

Last change: 1 February 1985

661

REBOOT(8)

MAINTENANCE COMMANDS

REBOOT(8)

NAME

reboot - restarting the UNIX operating system
SYNOPSIS
/ etc/reboot [ -0 ] [ -q ]
DESCRIPTION

reboot runs the reboot(2) system call to restart the UNIX kernel. The kernel is loaded into memory by the
PROM monitor, which transfers control to it. Since the system cannot be reentered, it is read in from disk
or tape each time it is bootstrapped. See boot(8S) for details.
Although reboot can be run by the super-user at any time, shutdown(8) is normally used first to warn all
users logged in of the impending loss of service. See shutdown(8) for details.

reboot performs a sync(l) operation on the disks, and then a multiuser reboot is initiated. See init(8) for
details.
OPTIONS
-0

Avoid the sync(I). It can be used if a disk or the processor is on fire.

-q

Quick. Reboots quickly and ungracefully, without first shutting down running processes.

Power Fail and Crash Recovery
Normally, the system will reboot itself at power-up or after crashes.
SEE ALSO
boot(8S), crash(8S), fsck(8), init(8), shutdown(8), halt(8), sync(1)

662

Last change: 30 June 1986

Sun Release 3.2

RENICE(8)

MAINTENANCE COMMANDS

RENICE(8)

NAME

renice - alter priority of running processes
SYNOPSIS

letc/renice priority pid ...
letc/renice priority [ -p pid '" ] [ -g pgrp ... ] [ -u user ... ]
DESCRIPTION

Renice alters the scheduling priority of one or more running processes.
OPTIONS

By default, the processes to be affected are specified by their process IDs. priority is the new priority value.
-ppid ...
Specify a list of process IDs.
-gpgrp ...
Specify a list of process group IDs. The processes in the specified process groups have their
scheduling priority altered.
-u user ...

Specify a list of user IDs or usemames. All processes owned by each user have their scheduling
altered.
Users other than the super-user may only alter the priority of processes they own, and can only monotonically increase their "nice value" within the range 0 to 20. (This prevents overriding administrative fiats.)
The super-user may alter the priority of any process and set the priority to any value in the range -2020. Useful priorities are: 19 (the affected processes will run only when nothing else in the system wants
to), 0 (the "base" scheduling priority) and any negative value (to make things go very fast).

If no who parameter is specified, the current process (alternatively, process group or user) is used.
FILES

/etc/passwd

to map user names to user id's

SEE ALSO

pstat(8)
BUGS

If you make the priority very negative, then the process cannot be interrupted.
To regain control you must make the priority greater than zero.
Users other than the super-user cannot increase scheduling priorities of their own processes, even if they
were the ones that decreased the priorities in the first place.

Sun Release 3.2

Last change: 28 May 1986

663

REPQUOTA (8 )

MAThITENANCECO~ANDS

REPQUOTA(8)

NAME

repquota - sumniarize quotas for a file system
SYNOPSIS

lusr/etc/repquota [ -v ] filesys . ..
lusr/etc/repquota [ -v ] -a
DESCRIPTION

Repquota prints a summary of the disc usage and quotas for the specified file systems. For each user the
current number of files and amount of space (in kilobytes) is printed, along with any quotas created with
edquota(8).
OPTIONS
-v

report all quotas, even if there is no usage.

Only the super-user may view quotas which are not their own.

-a

report on all file systems indicated in letc/fstab to be read-write with quotas.

FILES

quotas
/etc/fstab

quota file at the file system root
default file systems

SEE ALSO

quota(I), quotactl(2), quotacheck(8), quotaon(8), edquota(8)

664

Last change: 15 April 1985

Sun Release 3.2

RESTORE(8)

MAINTENANCE COMMANDS

RESTORE(8)

NAME

restore, rrestore - incremental file system restore
SYNOPSIS

jete/restore options [filename . .. ]
DESCRIPTION
restore restores files from backup tapes created with the dump (8) command. options is a string of at least

one of the options listed below, along with any modifiers and arguments you supply. Remaining arguments
to restore are the names of files (or directories whose files) are to be restored to disk. Unless the h modifier
is in effect, a directory name refers to the files it contains, and (recursively) its subdirectories and the files
they contain.
OPTIONS

r

Restore the entire tape. Load the tape's full contents into the current directory. This option should
only be used to restore a complete dump tape onto a clear filesystem, or to restore an incremental
dump tape after a full "level 0" restore. For example:
# /etc/newfs /dev/rxyOg
# /etc/mount /dev/xyOg /mnt
# cd/mot
# restore r
is a typical sequence to restore a level 0 dump. Another restore can be done to get an incremental
dump in on top of this.

R

Resume restoring. restore requests a particular tape of a multivolume set from which to resume a
full restore (see the r option above). This allows restore to start from a checkpoint when it is interrupted in the middle of a full restore.

x

Extract the named files from the tape. If a named file matches a directory whose contents were written onto the tape, and the h modifier is not in effect, the directory is recursively extracted. The
owner, modification time, and mode are restored (if possible). If no filename argument is given, the
root directory is extracted. This results in the entire tape being extracted unless the h modifier is in
effect.

t

Table of contents. List each filename that appears on the tape. If no filename argument is given, the
root directory is listed. This results in a list of all files on the tape, unless the h modifier is in effect.
(The t option replaces the function of the old dumpdir program).
Interactive. After reading in the directory information from the tape, restore invokes an interactive
interface that allows you to browse through the dump tape's directory hierarchy, and select individual files to be extracted. See Interactive Commands, below, for a description of available commands.

Modifiers

Some of the following modifiers take arguments that are given as separate words on the command line.
When more than one such modifier appears within options, the arguments must appear in the same order as
the modifiers that they apply to.
b/actor

Blocking factor. Specifies the blocking factor for tape reads. The default is 10 blocks per read. Note
that a tape block is 1024 bytes in size, or twice the size of a disk block.
d

Debug. Turns on debugging output.

v

Verbose. restore displays the name of each file it restores, preceded by its file type.

f dump-file
Use dump-file instead of /dev/rmt? as the file to restore from. If dump-file is specified as '-', restore

Sun Release 3.2

Last change: 22 July 1986

665

RESTORE (8)

MAINTENANCE COMMANDS

RESTORE (8)

reads from the standard input This allows, dump (8) and restore to be used in a pipeline to dump and
restore a file system:
# dump Of -/dev/rxyOg

I (cd Imnt; restore xf-)

If the name of the file is of the form machine:device the restore is done from the specified machine
over the network using rmt(8C). Since restore is normally run by root, the name of the remote
machine must appear in the .rhosts file of the local machine. If restore is called as "estore, the tape
defaults to dumphost:/dev/rmt8. To direct the input from a desired remote machine, set up an alias
for dumphost in the file /etclhosts.

sn

Skip to the n' th file when there are multiple dump files on the same tape. For example, a command
like
# restore xfs Idev/nrarO 5

would position you at the fifth file on the tape.

y

Do not ask whether to abort the restore in the event of tape errors. restore tries to skip over the bad
tape block(s) and continue as best it can.

m

Extract by inode numbers rather than by filename to avoid regenerating complete pathnames. This is
useful if only a few files are being extracted.

h

Extract the actual directory, rather than the files that it references. This prevents hierarchical restoration of complete subtrees from the tape.

c

Convert the contents of the dump tape to the new filesystem format.

INTERACTIVE COMMANDS
restore enters interactive mode when invoked with the i option. Interactive commands are reminiscent of
the shell. For those commands that accept an argument, the default is the current directory.

Is [dir]

List files in dir or the current directory .. Directories are appended with a I. Entries marked for
extraction are prefixed with a *. If the verbose option is in effect, inode numbers are also
listed.

cddir

Change to directory dir (within the dump-tape).

pwd

Print the full pathname of the current working directory.

add rftlename]
Add the current directory, or the named file or directory dir to the list of files to extract. If a
directory is specified, add that directory and its files (recursively) to the extraction list (unless
the h modifier is in effect).

delete rftlename]
Delete the current directory, or the named file or directory from the list of files to extract. If a
directory is specified, delete that directory and all its descendents from the extraction list
(unless the h modifier is in effect). The most expedient way to extract a majority of files from
a directory is to add that directory to the extraction list, and then delete specific files to omit.

666

extract

Extract all files on the extraction list from the dump tape. restore asks which volume the user
wishes to mount. The fastest way to extract a small number of files is to start with the last tape
volume and work: toward the first.

verbose

Toggle the status of the v modifier. While v is in effect, the Is command lists the inode
numbers of all entries, and restore displays information about each file as it is extracted.

help

Display a summary of the available commands.

quit

restore exits immediately, even if the extraction list is not empty.

Last change: 22 July 1986

Sun Release 3.2

RESTORE(8)

MAINTENANCE COMMANDS

RESTORE(8)

DIAGNOSTICS
restore complains about bad option characters.

Read errors result in complaints. If y has been specified, or the user responds 'y', restore will attempt to
continue.

If the dump extends over more than one tape, restore asks the user to change tapes. If the x or i option has
been specified, restore also asks which volume the user wishes to mount
There are numerous consistency checks that can be listed by restore. Most checks are self-explanatory or
can 'never happen'. Common errors are given below.
Converting to new file system format.
A dump tape created from the old file system has been loaded. It is automatically converted to the
new file system format.

filename: not found on tape
The specified file name was listed in the tape directory, but was not found on the tape. This is
caused by tape read errors while looking for the file, and from using a dump tape created on an
active file system.
expected next file inumber, got in umber
A file that was not listed in the directory showed up. This can occur when using a dump tape
created on an active file system.
Incremental tape too low
When doing an incremental restore, a tape that was written before the previous incremental tape,
or that has too Iowan incremental level has been loaded.
Incremental tape too high When doing incremental restore,
a tape that does not begin its coverage where the previous incremental tape left off, or one that has
too high an incremental level has been loaded.
Tape read error while restoring filename
Tape read error while skipping over inode inumber
Tape read error while trying to resynchronize
A tape read error has occurred.
If a file name is specified, then its contents are probably partially wrong. If an inode is being
skipped or the tape is trying to resynchronize, then no extracted files have been corrupted, though
files may not be found on the tape.
resync restore, skipped num blocks
After a tape read error, restore may have to resynchronize itself. This message lists the number of
blocks that were skipped over.
FILES

Idevlrmt8
Itmplrstdir*
Itmplrstmode*
.Irestoresymtable

the default tape drive
file containing directories on the tape.
owner, mode, and timestamps for directories.
information passed between incremental restores .

SEE ALSO
dump(8), newfs(8), mount(8), mkfs(8), rmt(8C)
BUGS

restore can get confused when doing incremental restores from dump tapes that were made on active file
systems.
A level zero dump must be done after a full restore. Because restore runs in user mode, it has no control
over inode allocation; this means that restore repositions the files, although it does not change their contents. Thus, a full dump must be done to get a new set of directories reflecting the new file positions, so

Sun Release 3.2

Last change: 22 July 1986

667

RESTORE(8)

MAINTENANCE COMMANDS

RESTORE(8)

that later incremental dumps will be correct.

668

Last change: 22 July 1986

Sun Release 3.2

REXD(8C)

MAINTENANCE COMMANDS

REXD(8C)

NAME

rexd - RPC-based remote execution server
SYNOPSIS

lusr/etclrpc.rexd
DESCRIPTION
Rexd is the Sun RPC server for remote program execution. This daemon is started by inetd(8) whenever a
remote execution request is made, if the following line is placed in tete/servers:
rpc tep /usr/etclrpc.rexd 100017 1
For non-interactive programs standard file descriptors are connected directly to TCP connections. Interactive programs involve pseudo-terminals, similar to the login sessions provided by rlogin(J) . This daemon
may use the NFS to mount file systems specified in the remote execution request
FILES

ldev/ttypn

pseudo-terminals used for interactive mode

letclpasswd

authorized users

SEE ALSO
on(1), rexd(3), exports(5), servers(5), inetd(8)
DIAGNOSTICS
Diagnostic messages are normally printed on the console, and returned to the requestor.
BUGS

Should be better access control.

Sun Release 3.2

Last change: 21 January 1986

669

REXECD(8C)

MAINTENANCE COMMANDS

REXECD(8C)

NAME

rexecd - remote execution server
SYNOPSIS

lusrletc/in.rexecd hos t. port
DESCRIPTION
Rexecd is the server for the rexec (3N) routine. The server provides remote execution facilities with
authentication based on user names and encrypted passwords. It is invoked automatically as needed by
inetd(8C), and then executes the following protocol:

1)

The server reads characters from the socket up to a null ('\0') byte. The resultant string is interpreted as an ASCn number, base 10.

2)

If the number received in step 1 is non-zero, it is interpreted as the port number of a secondary
stream to be used for the stderr. A second connection is then created to the specified port on the
client's machine.

3)

A null terminated user name of at most 16 characters is retrieved on the initial socket.

4)

A null terminated, encrypted, password of at most 16 characters is retrieved on the initial socket.

5)

A null terminated command to be passed to a shell is retrieved on the initial socket. The length of
the command is limited by the upper bound on the size of the system's argument list.

6)

Rexecd then validates the user as is done at login time and, if the authentication was successful,
changes to the user's home directory, and establishes the user and group protections of the user. If
any of these steps fail the connection is aborted with a diagnostic message returned.

7)

A null byte is returned on the connection associated with the stderr and the command line is
passed to the normal login shell of the user. The shell inherits the network connections established by re:xecd.

DIAGNOSTICS
All diagnostic messages are returned on the connection associated with the stderr, after which any network
connections are closed. An error is indicated by a leading byte with a value of 1 (0 is returned in step 7
above upon successful completion of all the steps prior to the command execution).

"username too long"
The name is longer than 16 characters.

"password too long"
The password is longer than 16 characters.

"command too long"
The command line passed exceeds the size of the argument list (as configured into the system).

"Login incorrect."
No password file entry for the user name existed.

"Password incorrect."
The wrong password was supplied.

"No remote directory."
The chdir command to the home directory failed.

"Try again."
A fork by the server failed.

"lbinlsh: ..."
The user's login shell could not be started.
BUGS

Indicating "Login incorrect" as opposed to "Password incorrect" is a security breach which allows people to probe a system for users with null passwords.

670

Last change: 28 October 1983

Sun Release 3.2

REXECD(8C)

MAINTENANCE COMMANDS

REXECD(8C)

A facility to allow all data exchanges to be encrypted should be present
SEE ALSO
inetd(8C)

Sun Release 3.2

Last change: 28 October 1983

671

MAINTENANCE COMMANDS

RLOGIND ( 8C)

RLOGIND (8C)

NAME

rlogind - remote login server
SYNOPSIS

/etC/in.rlogind hostport
DESCRIPTION
Rlogind is the server for the rlogin(lC) program. The server provides a remote login facility with authenti-

cation based on privileged port numbers.
Rlogind is invoked by inetd(8C) when a remote login connection is established, and executes the following

protocol:
1)

The server checks the client's source port. If the port is not in the range 0-1023, the server aborts
the connection. The client's address and port number are passed as arguments to rlogind by inetd
in the form "hostport" with host in hex and port in decimal.

2)

The server checks the client's source address. If the address is associated with a host for which no
corresponding entry exists in the host name data base (see hosts(5», the server aborts the connection.

Once the source port and address have been checked, rlogind allocates a pseudo terminal (see pty(4», and
manipulates file descriptors so that the slave half of the pseudo terminal becomes the stdin , stdont , and
stderr for a login process. The login process is an instance of the login(l) program, invoked with the-r
option. The login process then proceeds with the authentication process as described in rshd(8C), but if
automatic authentication fails, it reprompts the user to login as one finds on a standard tenninalline.
The parent of the login process manipulates the master side of the pseudo terminal, operating as an
intermediary between the login process and the client instance of the riogin program. In normal operation,
the packet protocol described in pty(4) is invoked to provide AStQ type facilities and propagate interrupt
signals to the remote programs. The login process propagates the client terminal's baud rate and terminal
type, as found in the environment variable, "TERM"; see environ (5V).
DIAGNOSTICS

All diagnostic messages are returned on the connection associated with the stderr, after which any network
connections are closed. An error is indicated by a leading byte with a value of 1.
Hostname for your address unknown.
No entry in the host name database existed for the client's machine.
Try again.
A/ork by the server failed.

/binlsh: ...
The user's login shell could not be started.
BUGS

The authentication procedure used here assumes the integrity of each client machine and the connecting
medium. This is insecure, but is useful in an "open" environment.
A facility to allow all data exchanges to be encrypted should be present
SEE ALSO

inetd(8C)

672

Last change: 28 December 1983

Sun Release 3.2

RMAIL(8)

MAINTENANCE COMMANDS

RMAIL(8)

NAME

rmail- handle remote mail received via uucp
SYNOPSIS

rmail user ...
DESCRIPTION

Rmail interprets incoming mail received via uucp (1 C), collapsing "From" lines in the form generated by
binmail(l) into a single line of the fonn "retum-path!sender", and passing the processed mail on to sendmail (8).
Rmail is explicitly designed for use with uucp and sendmail.
SEE ALSO

binmail(l), uucp(lC), sendmail(8)
BUGS

Rmail should not reside in tbin.

Sun Release 3.2

Last change: 2 April 1983

673

RMT(8C)

MAINTENANCE COMMANDS

RMT(8C)

NAME

rmt - remote magtape protocol module
SYNOPSIS
fetc/rmt
DESCRIPTION
Rmt is a program used by the remote dump and restor programs in manipulating a magnetic tape drive
through an interprocess communication connection. Rmt is normally started up with an rexec (3N) or
rand (3N) call.

The rmt program accepts requests specific to the manipulation of magnetic tapes, performs the commands,
then responds with a status indication. All responses are in ASCn and in one of two forms. Successful
commands have responses of
Anumber\n

where number is an ASCII representation of a decimal number. Unsuccessful commands are responded to
with
Eerror-number\nerror-message\n,

where error-number is one of the possible error numbers described in intro(2) and error-message is the
corresponding error string as printed from a call to perror(3). The protocol is comprised of the following
commands (a space is present between each token).

o device mode

Open the specified device using the indicated mode. Device is a full patbnarne and mode
is an ASCII representation of a decimal number suitable for passing to open(2V). If a
device had already been opened, it is closed before a new open is performed.

C device

Close the currently open device. The device specified is ignored

L whence offset Perform an Iseek(2) operation using the specified parameters. The response value is that
returned from the lseek call.

W count

Write data onto the open device. Rmt reads count bytes from the connection, aborting if
a premature end-of-file is encountered. The response value is that returned from the
write (2V) call.

R count

Read count bytes of data from the open device. Rmt performs the requested read (2V)
and responds with Acount-reatf...n if the read was successful; otherwise an error in the
standard format is returned If the read was successful, the data read is then sent

I operation count
Perform a MTIOCOP ioctl (2) command using the specified parameters. The parameters
are interpreted as the ASCII representations of the decimal values to place in the mt_op
and mt count fields of the structure used in the ioctl call. The return value is the count
parameter when the operation is successful.

s

Return the status of the open device, as obtained with a MTIOCGET ioctl call. If the
operation was successful, an "ack" is sent with the size of the status buffer, then the
status buffer is sent (in binary).

Any other command causes rmt to exit.
DIAGNOSTICS
All responses are of the form described above.
SEE ALSO
rcmd(3N), rexec(3N), mtio(4), dump(8), restore(8)
BUGS

People tempted to use this for a remote file access protocol are discouraged.

674

Last change: 1 February 1985

Sun Release 3.2

ROUTE(8C)

MAINTENANCE COMMANDS

ROUTE(8C)

NAME

route - manually manipulate the routing tables
SYNOPSIS

lusr/etc/route [ -f] [command args ]
DESCRIPTION

Route is a program used to manually manipulate the network routing tables. It normally is not needed, as
the system routing table management daemon, routed (8C), should tend to this task.
Route accepts three commands: add, to add a route; delete, to delete a route; and change, to modify an
existing route.
All commands have the following syntax:

lusr/etc/route command destination gateway [ metric]
where destination is a host or network for which the route is "to", gateway is the gateway to which packets should be addressed, and metric is an optional count indicating the number of hops to the destination.
If no metric is specified, route assumes a value of O. Routes to a particular host are distinguished from
those to a network by interpreting the Internet address associated with destination. If the destination has a
"local address part" of INADDR_ANY, then the route is assumed to be to a network; otherwise, it is
presumed to be a route to a host. If the route is to a destination connected via a gateway, the metric should
be greater than O. All symbolic names specified for a destination or gateway are looked up first in the host
name database, hosts (5). If this lookup fails, the name is then looked for in the network name database,
networks (5).

Route uses a raw socket and the SIOCADDRT and SIOCDELRT ioctl's to do its work. As such, only the
super-user may modify the routing tables.
If the -f option is specified, route will "flush" the routing tables of all gateway entries. If this is used in
conjunction with one of the commands described above, the tables are flushed prior to the command's
application.
DIAGNOSTICS

"add %s: gateway %s Hags %x"
The specified route is being added to the tables. The values printed are from the routing table entry supplied in the ioctl call.

"delete %s: gateway %s Hags %x"
As above, but when deleting an entry.

"%s %s done"
When the -f flag is specified, each routing table entry deleted is indicated with a message of this fonn.

"not in table"
A delete operation was attempted for an entry which wasn't present in the tables.

"routing table overHow"
An add operation was attempted, but the system was low on resources and was unable to allocate memory
to create the new entry.
SEE ALSO
routing(4N), routed(8C)
BUGS

The change operation is not implemented, one should add the new route, then delete the old one.

Sun Release 3.2

Last change: 25 October 1983

675

ROUTED(8C)

MAINTENANCE COMMANDS

ROUTED(8C)

NAME

routed - network routing daemon
SYNOPSIS

/ etc/in.routed [ -s ] [ -q ] [ -t ] [ 10gfile ]
DESCRIPTION

Routed is invoked at boot time to manage the network routing tables. The routing daemon uses a variant of
the Xerox NS Routing Information Protocol in maintaining up to date kernel routing table entries.
In normal operation routed listens on udp(4P) socket 520 (decimal) for routing information packets. If the
host is an internetwork router, it periodically supplies copies of its routing tables to any directly connected
hosts and networks.
When routed is started, it uses the SIOCGIFCONF ioctl to find those directly connected interfaces
configured into the system and marked "up" (the software loopback interface is ignored). If multiple
interfaces are present, it is assumed the host will forward packets between networks. Routed then transmits .
a request packet on each interface (using a broadcast packet if the interface supports it) and enters a loop,
listening for request and response packets from other hosts.
When a request packet is received, routed formulates a reply based on the information maintained in its
internal tables. The response packet generated contains a list of known routes, each marked with a "hop
count" metric (a count of 16, or greater, is considered "infinite"). The metric associated with each route
returned provides a metric relative to the sender.

Request packets received by routed are used to update the routing tables if one of the following conditions
is satisfied:
(1)

No routing table entry exists for the destination network or host, and the metric indicates the destination is "reachable" (that is, the hop count is not infinite).

(2)

The source host of the packet is the same as the router in the existing routing table entry. That is,
updated information is being received from the very internetwork router through which packets
for the destination are being routed.

(3)

The existing entry in the routing table has not been updated for some time (defined to be 90
seconds) and the route is at least as cost effective as the current route.

(4)

The new route describes a shorter route to the destination than the one currently stored in the routing tables; the metric of the new route is compared against the one stored in the table to decide
this.

When an update is applied, routed records the change in its internal tables and generates a response packet
to all directly connected hosts and networks. Routed waits a short period of time (no more than 30
seconds) before modifying the kernel's routing tables to allow possible unstable situations to settle.
In addition to processing incoming packets, routed also periodically checks the routing table entries. If an
entry has not been updated for 3 minutes, the entry's metric is set to infinity and marked for deletion. Deletions are delayed an additional 60 seconds to insure the invalidation is propagated throughout the internet.
Hosts acting as internetwork routers gratuitously supply their routing tables every 30 seconds to all directly
connected hosts and networks.
Supplying the -s option forces routed to supply routing information whether it is acting as an internetwork
router or not The -q option is the opposite of the -s option. If the -t option is specified, all packets sent
or received are printed on the standard output In addition, routed will not divorce itself from the controlling terminal so that interrupts from the keyboard will kill the process. Any other argument supplied is
interpreted as the name of file in which routed's actions should be logged. This log contains information
about any changes to the routing tables and a history of recent messages sent and received which are
related to the changed route.

676

Last change: 26 February 1985

Sun Release 3.2

ROUTED(8C)

MAINTENANCE COMMANDS

ROUTED (8C)

In addition to the facilities described above, routed supports the notion of "distant" passive and active
gateways. When routed is started up, it reads the file fetc!gateways to find gateways which may not be
identified using the SIOGIFCONF ioctl. Gateways specified in this manner should be marked passive if
they are not expected to exchange routing information, while gateways marked active should be willing to
exchange routing information (that is, they should have a routed process running on the machine). Passive
gateways are maintained in the routing tables forever and information regarding their existence is included
in any routing information transmitted. Active gateways are treated equally to network interfaces. Routing
information is distributed to the gateway and if no routing information is received for a period of the time,
the associated route is deleted.
The fetcl gateways is comprised of a series of lines, each in the following format:
< net I host> namel gateway name2 metric value < passive I active >

The net or host keyword indicates if the route is to a network or specific host.

Namel is the name of the destination network or host. This may be a symbolic name located in
fetclnetworks or fetclhosts, or an Internet address specified in "dot" notation; see inet(3N).
Name2 is the name or address of the gateway to which messages should be forwarded.
Value is a metric indicating the hop count to the destination host or network.
The keyword passive or active indicates if the gateway should be treated as passive or active (as described
above).
FILES

fetc/gateways

for distant gateways

SEE ALSO
udp(4P)

BUGS
The kernel's routing tables may not correspond to those of routed for short periods of time while processes
utilizing existing routes exit; the only remedy for this is to place the routing process in the kernel.

Routed should listen to intelligent interfaces, such as an IMP, and to error protocols, such as ICMP, to
gather more information.

Sun Release 3.2

Last change: 26 February 1985

677

RPCINFO(8)

MAINTENANCE COMMANDS

RPCINFO(8)

NAME

rpcinfo - report RPC information
SYNOPSIS

rpcinfo -p [ host]
rpcinfo -u host pro gram [ version]
rpcinfo -t program [ verSion]
DESCRIPTION

rpcinfo makes an RPC call to an RPC server and reports what it finds.
OPTIONS

-p

Probe the portmapper on host, and print a list of all registered RPC programs. If host is not
specified, it defaults to the value returned by hostname(1).

-u

Make an RPC call to procedure 0 of pro gram on the specified host using UDP, and report whether
a response was received.

-t

Make an RPC call to procedure 0 of program on the specified host using TCP, and report whether
a response was received.

The program argument can be either a name or a number.

If a version is specified, rpcinfo attempts to call that version of the specified program. Otherwise, rpcinfo
attempts to find all the registered version numbers for the specified program by calling version 0 (which is
presumed not to exist; if it does exist, rpcinfo attempts to obtain this information by calling an extremely
high version number instead) and attempts to call each registered version.
FILES

/ete/rpc names for RPC program numbers
SEE ALSO

rpc(5), portmap(8)

RPC Programming Guide in Networking on the Sun Workstation
BUGS

In releases prior to Sun UNIX 3.0, the Network File System (NFS) did not register itself with the portmapper; rpcinfo cannot be used to make RPC calls to the NFS server on hosts running such releases.

678

Last change: 1 February 1985

Sun Release 3.2

MAINTENANCE COMMANDS

RQUOTAD(8C)

RQUOTAD(8C)

NAME

rquotad- remote quota server
SYNOPSIS

lusr/etc/rpc.rquotad
DESCRIPTION

Rquotad is an rpc(4) server which returns quotas for a user of a local file system which is mounted by a
remote machine over the NFS. The results are used by quota(l) to display user quotas for remote file systems. The rquotad daemon is normally invoked by inetd(8C).
FILES

quotas

quota file at the file system root

SEE ALSO
quota(I), services(5), inetd(8), rpc(4), nfs(4)

Sun Release 3.2

Last change: 15 April 1985

679

MAThITENANCECO~ANDS

RSHD(8C)

RSHD(8C)

NAME

rshd - remote shell server
SYNOPSIS

letc/in.rshd host.port
DESCRIPTION

Rshd is the server for the remd(3N) routine and, consequently, for the rsh(lC) program. The server provides remote execution facilities with authentication based on privileged port numbers.
Rshd is invoked by inetd (8C) each time a shell service is requested, and executes the following protocol:

1)

The server checks the client's source port. If the port is not in the range 0-1023, the server aborts
the connection. The clients host address (in hex) and port number (in decimal) are the argument
passed to rshd.

2)

The server reads characters from the socket up to a null ('\0') byte. The resultant string is interpreted as an ASCn number, base 10.

3)

If the number received in step 1 is non-zero, it is interpreted as the port number of a secondary
stream to be used for the stderr. A second connection is then created to the specified port on the
client's machine. The source port of this second connection is also in the range 0-1023.

4)

The server checks the client's source address. If the address is associated with a host for which no
corresponding entry exists in the host name data base (see hosts(5», the server aborts the connection.

5)

A null terminated user name of at most 16 characters is retrieved on the initial socket. This user
name is interpreted as a user identity to use on the server's machine.

6)

A null terminated user name of at most 16 characters is retrieved on the initial socket. This user
name is interpreted as the user identity on the client's machine.

7)

A null terminated command to be passed to a shell is retrieved on the initial socket. The length of
the command is limited by the upper bound on the size of the system's argument list.

8)

Rshd then validates the user according to the following steps. The remote user name is looked up
in the password file and a ehdir is performed to the user's home directory. If the lookup or fails,
the connection is terminated. If the ehdir fails, it does a ehdir to I (root). If the user is not the
super-user, (user id 0), the file letclhosts.equiv is consulted for a list of hosts considered
"equivalent". If the client's host name is present in this file, the authentication is considered successful. If the lookup fails, or the user is the super-user, then the file .rhosts in the home directory
of the remote user is checked for the machine name and identity of the user on the client's
machine. If this lookup fails, the connection is terminated.

9)

A null byte is returned on the connection associated with the stderr and the command line is
passed to the normal login shell of the user. The shell inherits the network connections established by rshd.

DIAGNOSTICS

All diagnostic messages are returned on the connection associated with the stderr, after which any network
connections are closed. An error is indicated by a leading byte with a value of 1 (0 is returned in step 9
above upon successful completion of all the steps prior to the command execution).
"Iocuser too long"
The name of the user on the client's machine is longer than 16 characters.
"remuser too long"
The name of the user on the remote machine is longer than 16 characters.
"command too long"
The command line passed exceeds the size of the argument list (as configured into the system).

680

Last change: 3 January 1984

Sun Release 3.2

RSHD(8C)

MAINTENANCE COMMANDS

RSHD(8C)

"Hostname for your address unknown."
No entry in the host name database existed for the client's machine.

"Login incorrect."
No password file entry for the user name existed.

"Permission denied."
The authentication procedure described above failed.

"Can't make pipe."
The pipe needed for the stderr, wasn't created.

"Try again."
Aiork by the server failed.

"lbinlsh: ..•"
The user's login shell could not be started.
SEE ALSO

rsh( 1C), rcmd(3N)
BUGS

The authentication procedure used here assumes the integrity of each client machine and the connecting
medium. This is insecure, but is useful in an "open" environment.
A facility to allow all data exchanges to be encrypted should be present

Sun Release 3.2

Last change: 3 January 1984

681

RSTATD(8C)

MAINTENANCE COMMANDS

RSTATD(8C)

NAME

rstatd - kernel statistics server
SYNOPSIS

lusr/etc/rpc.rstatd
DESCRIPTION

Rstatd is a server which returns performance statistics obtained from the kernel. These statistics are graphically displayed by perfmeter(l). The rstatd daemon is normally invoked by inetd(8C).
SEE ALSO

perfmeter(l), services(5), inetd(8)

682

Last change: 4 April 1985

Sun Release 3.2

RUSERSD(8C)

MAINTENANCE COMMANDS

RUSERSD (8C)

NAME

rusersd - network usemarne server
SYNOPSIS

lusr/etc/rpc.rusersd
DESCRIPTION

Rusersd is a server that returns a list of users on the network. The rusersd daemon is normally invoked by
inetd(8C).
SEE ALSO

perfmeter(I), rusers(IC), services(5), inetd(8)

Sun Release 3.2

Last change: 29 July 1986

683

RWALLD(8C)

MAThITENANCECO~ANDS

RWALLD(8C)

NAME

rwalld - network rwall server
SYNOPSIS

lusr/etc/rpc.rwalld
DESCRIPTION

Rwalld is a server that handles rwall(l) and shutdown(l) requests. It is implemented by calling wall(l) to
all the appropriate network machines. The rwalld daemon is normally invoked by inetd (8e).
SEE ALSO

rwall(I), wall(I), services(5), inetd(8), shutdown(8)

684

Last change: 1 February 1985

Sun Release 3.2

RWHOD(8C)

MAINTENANCE COMMANDS

RWHOD(8C)

NAME

rwhod - system status server
SYNOPSIS

letc/rwhod
DESCRIPTION

Rwhod is the server which maintains the database used by the rwho(IC) and ruptime(IC) programs. Its
operation is predicated on the ability to broadcast messages on a network.
Rwhod operates as both a producer and consumer of status information. As a producer of information it
periodically queries the state of the system and constructs status messages which are broadcast on a network. As a consumer of information, it listens for other rwhod servers' status messages, validating them,
then recording them in a collection of files located in the directory lusrlspoollrwho.
The rwho server transmits and receives messages at the port indicated in the "rwho" service specification,
see services(5). The messages sent and received, are of the form:
struct

outmp {
out_line[8];
char
out_name[8];
char
long
out_time;

1* tty name *1
1* user id *1
1* time on *1

};

struct

whod{
char
char
char
int
int
char
int
int
struct

wd_vers;
wd_type;
wd_ fill[2];
wd_ sendtime;
wd_recvtime;
wd_ hostnarne[32];
wd_loadav[3];
wd_ boottime;
whoent {
outmp we_utmp;
struct
we}d1e;
int
} wd_ we[1024 I sizeof (struct whoent)];

};

All fields are converted to network byte order prior to transmission. The load averages are as calculated by
the w(l) program, and represent load averages over the 5, 10, and 15 minute intervals prior to a server's
transmission. The host name included is that returned by the gethostname (2) system call. The array at the
end of the message contains information about the users logged in to the sending machine. This information includes the contents of the utmp(5) entry for each non-idle terminal line and a value indicating the
time since a character was last received on the terminal line.
Messages received by the rwho server are discarded unless they originated at a rwho server's port. In addition, if the host's name, as specified in the message, contains any unprintable ASCn characters, the message is discarded. Valid messages received by rwhod are placed in files named whod .hostname in the
directory lusrlspoollrwho. These files contain only the most recent message, in the format described
above.
Status messages are generated approximately once every 60 seconds. Rwhod performs an nlist(3) on
Ivrnunix every 10 minutes to guard against the possibility that this file is not the system image currently
operating.
SEE ALSO

rwho(lC), ruptime(lC)

Sun Release 3.2

Last change: 28 October 1983

685

RWHOD(8C)

MAThITENANCECO~ANDS

RWHOD(8C)

BUGS

Should relay status information between networks. People often interpret the server dying as a machine
going down.

686

Last change: 28 October 1983

Sun Release 3.2

SA(8)

MAINTENANCE COMMANDS

SA(8)

NAME

sa, accton - system accounting
SYNOPSIS

lusr/etc/sa [ -abcdDfijkKlnrstuv] [filename ]
lusr/etc/accton [filename]
DESCRIPTION

With an argument naming an existing file. accton causes system accounting information for every process
executed to be placed at the end of the file. If no argument is given, accounting is turned off.
sa reports on, cleans up, and generally maintains accounting files.
sa is able to condense the information in lusrladm/acct into a summary file lusrladmlsavacct which contains a count of the number of times each command was called and the time resources consumed. This
condensation is desirable because on a large system lusrladmlacct can grow by 500K bytes per day. The
summary file is normally read before the accounting file, so the reports include all available information.
If a file name is given as the last argument, that file will be treated as the accounting file; lusrladmlacct is
the default

Output fields are labelled: 'cpu' for the sum of user+system time (in minutes), 're' for real time (also in
minutes), 'k' for cpu-time averaged core usage (in lk units), 'avio' for average number of I/O operations
per execution. With options fields labelled 'tio' for total I/O operations, 'k*sec' for cpu storage integral
(kilo-core seconds), 'u' and's' for user and system cpu time alone (both in minutes) will sometimes
appear.
sa also breaks out accounting statistics by user. This information is kept in the file lusrladmlusracct.
OPTIONS

a

Place all command names containing unprintable characters and those used only once under the
name '***other.'

b

Sort output by sum of user and system time divided by number of calls. Default sort is by sum of
user and system times.

c

Besides total user, system, and real time for each command print percentage of total time over all
commands.

d

Sort by average number of disk I/O operations.

D

Print and sort by total number of disk I/O operations.

f

Force no interactive threshold compression with -v flag.
Don't read in summary file.

j

Instead of total minutes time for each category, give seconds per call.

k

Sort by cpu-time average memory usage.

K

Print and sort by cpu-storage integral.
Separate system and user time; normally they are combined.

m

Print number of processes and number of CPU minutes for each user.

n

Sort by number of calls.

r

Reverse order of sort

s

Merge accounting file into summary file lusrladm/savacct when done.

t

For each command report ratio of real time to the sum of user and system times.

u

Superseding all other flags, print for each record in the accounting file the user ID and command
name.

Sun Release 3.2

Last change: 27 March 1984

687

MAINTENANCE COMMANDS

SA(8)

v

SA(8)

Followed by a number n. types the name of each command used n times or fewer. Await a reply
from the terminal; if it begins with 'y', add the command to the category '**junk**.' This is used
to strip out garbage.

FILES

lusrladmlacct

raw accounting lusrladmlsavacct summary by command lusrladmlusracct summary by user ID

SEE ALSO

ac(8), acct(2), acct(5)

688

Last change: 27 March 1984

Sun Release 3.2

SAVECORE (8 )

MAINTENANCE COMMANDS

SAVECORE (8 )

NAME

savecore - save a core dump of the operating system
SYNOPSIS
lusr/etc/savecore dirname [ system]
DESCRIPTION
saveeore saves a core dump of the kernel (assuming that one was made) and writes a reboot message in the
shutdown log. It is meant to be called near the end of the letclre.loeal file after the system boots. However, it is not normally run by default. You must edit that file to enable it.

saveeore checks the core dump to be certain it corresponds with the version of the operating system
currently running. If it does, save core saves the core image in the file dirname Ivrncore.n and the kernel's
namelist, in dirname /vmunix.n The trailing .n in the pathnames is replaced by a number which grows every
time saveeore is run in that directory.

Before saveeore writes out a core image, it reads a number from the file dirname lminfree. If there is less
free space on the filesystem containing dirname than the number obtained from the minfree file, the core
dump is not done. If the minfree file does not exist, saveeore always writes out the core file (assuming that
a core dump was taken).
saveeore also writes a reboot message in the shutdown log. If the system crashed as a result of a panic,
save core records the panic string in the shutdown log too.
If the core dump was from a system other than Ivmunix, the name of that system must be supplied as
sysname.
FILES

Iusrladmlshutdownlog
Ivmunix

shutdown log
the UNIX kernel

SEE ALSO
crash(8s), sa(8)

BUGS
Can be fooled into thinking a core dump is the wrong size.
You must run saveeore very soon after booting -- before the swap space containing the crash dump is
overwritten by programs currently running.

Sun Release 3.2

Last change: 23 December 1985

689

SENDMAIL ( 8 )

MAINTENANCE COMMANDS

SENDMAIL ( 8 )

NAME

sendmail- send mail over the internet
SYNOPSIS
lusrlIib/seodmail [ -ba] [ -bd] [ -bi] [ -bm ] [ -bp ] [ -bs] [ -bt] [ -bv ] [ -bz ]
[ -Cfile] [ -dX] [ -Ffullname] [ -fname ] [ -bN] [ -0 ] [ -ox value] [ -q[ time] ]
[ -rname ] [ -t ] [ -v ] [ address ... ]
DESCRIPTION

Sendmail sends a message to one or more people, routing the message over whatever networks are necessary. Sendmail does internetwork forwarding as necessary to deliver the message to the correct place.
Sendmail is not intended as a user interface routine; other programs provide user-friendly front ends; sendmail is used only to deliver pre-formatted messages.
With no flags, sendmail reads its standard input up to an end-of-file, or a line with a single dot and sends a
copy of the letter found there to all of the addresses listed. It determines the network to use based on the
syntax and contents of the addresses.
Local addresses are looked up in the local aliases(5) file, or by using the Yellow Pages name service, and
aliased appropriately. In addition, if there is a forward file in a recipient's home directory, sendmail forwards a copy of each message to the list of recipients that file contains. Aliasing can be prevented by
preceding the address with a backslash. Normally the sender is not included in alias expansions, for example, if 'john' sends to 'group', and 'group' includes 'john' in the expansion, then the letter will not be
delivered to 'john' .

sendmail will also route mail directly to other known hosts in a local netowrk. The list of hosts to which
mail is directly sent is maintained in the file lusrlliblmailhosts.
OPTIONS
-ba

690

Go into ARPANET mode. All input lines must end with a CR-LF, and all messages
will be generated with a CR-LF at the end. Also, the "From:" and "Sender:" fields
are examined for the name of the sender.

-bd

Run as a daemon, waiting for incoming SMTP connections.

-bi

Initialize the alias database.

-bm

Deliver mail in the usual way (default).

-bp

Print a summary of the mail queue.

-bs

Use the SMTP protocol as described in RFC821. This flag implies all the operations of
the -ba flag that are compatible with SMTP.

-bt

Run in address test mode. This mode reads addresses and shows the steps in parsing;
it is used for debugging configuration tables.

-bv

Verify names only - do not try to collect or deliver a message. Verify mode is normally used for validating users or mailing lists.

-bz

Create the configuration freeze file.

-Cfile

Use alternate configuration file.

-
Successful completion on all addresses.
EX OK
EX NOUSER
User name not recognized.
EX UNAVAILABLE
Catchall meaning necessary resources were not available.
EX SYNTAX
Syntax error in address.
EX SOFTWARE
Internal software error, including bad arguments.
Temporary operating system error, such as "cannot fork" .
EX OSERR
Host name not recognized.
EX NOHOST
EX TEMPFAIL
Message could not be sent immediately, but was queued.
If invoked as newaliases, sendmail rebuilds the alias database. If invoked as mailq, sendmail prints the
contents of the mail queue.
FILES

Except for lusrlliblsendmail.cf, these pathnames are all specified in lusrlliblsendmail.cf. Thus, these values
are only approximations.
lusrllibl aliases
raw data for alias names
lusrlliblaliases.pag
data base of alias names
lusrlliblaUases.dir
list of hosts to which mail can be sent directly
lusrlliblmailhosts
lusrlliblsendmail.cf
configuration file
lusrlliblsendmailfc
frozen configuration
lusrllibl sendmail.hf
help file
Iusrllibl sendmail.st
collected statistics
to deliver uucp mail
lusrlbinluux
to deliver local mail
Ibinlmail
temp files and queued mail
lusrlspool!mqueuel*
-/.forward
list of recipients for forwarding messages
SEE ALSO

biff(I), binmail(I), mail(I), aliases(5),
DARPA Internet Request For Comments RFC819, RFC821, RFC822
Sendmail Installation and Operation, in System Administration for the Sun Workstation.
BUGS

Sendmail converts blanks in addresses to dots. This is incorrect according to the old ARPANET mail protocol RFC733 (NIC 41952), but is consistent with the new protocols (RFC822).

692

Last change: 14 June 1986

Sun Release 3.2

SETUP (8S)

MAINTENANCE COMMANDS

SETUP(8S)

NAME

setup - Sun UNIX installation program
SYNOPSIS

setup
DESCRIPTION

setup is the program supplied by Sun to install major Sun Unix releases such as 2.0 or 3.0. setup allows a
system administrator to install major Sun Unix release on new hardware, upgrade between major releases,
and add additional hardware to existing machines.
setup provide both a tty interlace for cursor addressable terminals and a SunWindows system interface for
use on bit mapped displays. The >1 "Setup Reference Manual" contains a detailed description of the use of
setup.
Initially, setup asks the following questions in a menu format before entering the tty or SunWindows interface. For all menus respond to the » prompt with the corresponding number of the menu item you choose.
The first question asked is the mode of use of setup.
Are you running setup:
1) to install on a new system
2) re-entrantly
3) to upgrade an existing system
4) in demonstration mode

»
The next question is to determine the type of interlace to be used. Note that the cursor addressable interface can be used within a shelltool(l) under SunWindows.
Will you be running setup from:
1) a Sun bit mapped display device
2) a cursor addressable terminal

»
If you have selected the tty interlace for cursor addressable terminals, setup asks for the terminal type.
Select your terminal type:
1) Televideo 925
2) Wyse Model 50
3) Sun Workstation
4) Other

»
If you select "Other", the name of the terminal must correspond to a name in the termcap (5) database.
Enter the terminal type (your terminal type must be in /etc/termcap):

»
setup begins running the interlace for the terminal-type you have selected.
FILES

letclhosts
letclnd.local
letc!ethers
letc!rc.local
letc!rc.boot
Ietc!setup.inJo
lusrlliblsendmail.cf
BUGS

setup will not run on tty devices that do not support cursor addressing and are not registered in the
tenncap(5) data base.

Sun Release 3.2

Last change: 8 April 1986

693

MAINTENANCE COMMANDS

SHOWMOUNT (8)

SHOWMOUNT(8)

NAME

showmount - show all remote mounts
SYNOPSIS

lusr/etc/showmount [ -a ] [ -d] [ -e ] [ host]
DESCRIPTION

Showmount lists all the clients that have remotely mounted a filesystem from host. This information is
maintained by the mountd(8C) server on host, and is saved across crashes in the file letclrmtab. The
default value for host is the value returned by hostname (1).
OPTIONS

-d

List directories that have been remotely mounted by clients.

-8

Print all remote mounts in the format
hostname:directory
where hostname is the name of the client, and directory is the root of the file system that has been
mounted.

-e

Print the list of exported file systems.

SEE ALSO

rmtab(5), mountd(8), exports(5)
BUGS

If a client crashes, its entry will not be removed from the list until it reboots and executes umount -a.

694

Last change: 1 February 1985

Sun Release 3.2

MAINTENANCE COMMANDS

SHUTDOWN ( 8 )

SHUTDOWN ( 8 )

NAME
shutdown - close down the system at a given time
SYNOPSIS
fete/shutdown [ -k] [ -r] [ -b] time [warning-message ... ]
DESCRIPTION

Shutdown provides an automated procedure to notify users when the system is to be shut down. time
specifies when shutdown will bring the system down; it may be" the word now (indicating an immediate
shutdown), or it may specify a future time in one of two formats: +number and hour:min. The first form
brings the system down in number minutes, and the second brings the system down at the time of day indicated in 24-hour notation.
At intervals that get closer as the apocalypse approaches, warning messages are displayed at terminals of
all logged-in users, and of users who have remote mounts on that machine. Five minutes before shutdown,
or immediately if shutdown is in less than 5 minutes, logins are disabled by creating letc/noiogin and writing a message there. If this file exists when a user attempts to log in, login(l) prints its contents and exits.
The file is removed just before shutdown exits.
At shutdown time a message is written in the file lusrladmlshutdownlog, containing the time of shutdown,
the instigator of the shutdown, and the reason. Then a terminate signal is sent to init, which brings the system down to single-user mode.
The time of the shutdown and the warning message are placed in fete/nologin, which should be used to
inform the users as to when the system will be back up, and why it is going down (or anything else).
OPTIONS
As an alternative to the above procedure, these options can be specified:
-r

Execute reboot(8).

-h

Execute halt(8).

-k

Make people think the system is going down, but do not actually take it down.

FILES
letcfnologin

tells login not to let anyone log in
list of remote hosts that have mounted this host
lusrfadmlshutdownlog
log file for succesful shutdowns.

letclrmtab

SEE ALSO
login(l), reboot(8)
BUGS

Only allows you to bring the system down between "now" and 23:59 if you use the absolute time for shutdown.

Sun Release 3.2

Last change: 1 July 1986

695

SKYVERSION ( 8 )

MAINTENANCE COMMANDS

SKYVERSION (8)

NAME

skyversion - print the SKYFFP board microcode version number
SYNOPSIS
lusr/etc/skyversion
DESCRIPTION

skyversion obtains from the SKYFFP board the Sky version number of the microcode currently loaded and
prints the result on the standard output.
DIAGNOSTICS
The Sky version number operation code used to implement this command is not available for microcode
releases earlier than Sky release 3.00. The result in this case is unpredictable and is either a nonmeaningful
version number or a message indicating that no version number is available. Meaningful version numbers
are of the form n.dd where n ~ 3.

696

Last change: 7 August 1984

Sun Release 3.2

SPRAY (8C)

MAINTENANCE COMMANDS

SPRAY(8C)

NAME

spray - spray packets
SYNOPSIS

/usr/etc/spray host [ -c count] [ -d delay] [ -i delay] [ -llength ]
DESCRIPTION

spray sends a one-way stream of packets to host using RPC, and then reports how many were received by
host and what the transfer rate was. The host name can be either a name or an internet address.
OPTIONS

-c count
Specifies how many packets to send. The default value of count is the numbers of packets
required to make the total stream size 100000 bytes.
-d delay

Specifies how may microseconds to pause between sending each packet The default is O.
-i

Use ICMP echo packets rather than RPC. Since ICMP automatically echos, this creates a two
way stream.

-llength
The length parameter is the numbers of bytes in the ethernet packet that holds the RPC call message. Since the data is encoded using XDR, and XDR only deals with 32 bit quantities, not all
values of length are possible, and spray rounds up to the nearest possible value. When length is
greater than 1514, then the RPC call can no longer be encapsulated in one Ethernet packet, so the
length field no longer has a simple correspondence to Ethernet packet size. The default value of
length is 86 bytes (the size of the RPC and UDP headers)
SEE ALSO

icmp(4P), ping(8), sprayd(8C)

Sun Release 3.2

Last change: 29 July 1986

697

SPRAYD(8C)

MAINTENANCE COMMANDS

SPRAYD(8C)

NAME

sprayd - spray server
SYNOPSIS

lusr/etdrpc.sprayd
DESCRIPTION
rpc.sprayd is a server which records the packets sent by spray(8). The rpc.sprayd daemon is normally
invoked by inetd(8C).
SEE ALSO
spray(8)

698

Last change: 19 February 1986

Sun Release 3.2

STATD(8C)

MAINTENANCE COMMANDS

STATD(8C)

NAME

statd - network status monitor
SYNOPSIS

/etc/rpc.statd
DESCRIPTION

Statd is an intermediate version of the status monitor. It interacts with lockd(8c) to provide the crash and
recovery functions for the locking services on NFS.
FILES

letc!statrrwnlcurrent
Ietc!statrrwnlbackup
Ietc!statrrwnlstate
SEE ALSO

lockd(8C), statmon(5)
BUGS

The crash of a site is only detected upon its recovery.

Sun Release 3.2

Last change: 16 July 1986

699

STICKY(8)

MAThITENANCECO~ANDS

STICKY (8)

NAME

sticky - executable files with persistent text
DESCRIPTION
While the 'sticky bit', mode 01000 (see chmod(2», is set on a sharable executable file, the text of that file
will not be removed from the system swap area. Thus the file does not have to be fetched from the file system upon each execution. As long as a copy remains in the swap area, the original text cannot be overwritten in the file system, nor can the file be deleted. Directory entries can be removed so long as one link:
remains.

Sharable files are made by the -z option of [d(l).
To replace a sticky file that has been used do: (1) Clear the sticky bit with chmod(lV). (2) Execute the old
program to flush the swapped copy. This can be done safely even if others are using it. (3) Overwrite the
sticky file. If the file is being executed by any process, writing will be prevented; it suffices to simply
remove the file and then rewrite it, being careful to reset the owner and mode with chmod and chown(2).
(4) Set the sticky bit again.
Only the super-user can set the sticky bit.

700

Last change: 28 October 1983

Sun Release 3.2

SWAPON(8)

MAINTENANCE COMMANDS

SWAPON(8)

NAME

swapon - specify additional device for paging and swapping
SYNOPSIS

lusr/etc/swapon -3
lusr/etc/swapon name ...
DESCRIPTION

Swapon specifies additional devices on which paging and swapping are to take place. The system begins
by swapping and paging on only a single device so that only one disk is required at bootstrap time. Calls to
swapon normally occur in the system multi-user initialization file letclrc making all swap devices available,
so that the paging and swapping activity is interleaved across several devices.

The second form gives individual block devices as given in the system swap configuration table. The call
makes only this space available to the system for swap allocation.
OPTIONS
-3

Make available all devices of type 'swap' in letc/fstab. Using swapon with the -a option is the
normal usage.

SEE ALSO

swapon(2), init(8)
FILES

/dev/[ru][pk]?b

normal paging devices

BUGS

There is no way to stop paging and swapping on a device. It is therefore not possible to make use of devices which may be dismounted during system operation.

Sun Release 3.2

Last change: 11 September 1985

701

SYNC(8)

MAINTENANCE COMMANDS

SYNC(8)

NAME

sync - update the super block
SYNOPSIS

sync
DESCRIPTION
Sync executes the sync system primitive. Sync can be called to insure all disk writes have been completed
before the processor is halted in a way not suitably done by reboot(8) or halt(8).

See sync (2) for details on the system primitive.
SEE ALSO

sync(2), fsync(2), halt(8), reboot(8)

702

Last change: 4 February 1983

Sun Release 3.2

SYSDIAG(8)

MAINTENANCE COMMANDS

SYSDIAG(8 )

NAME

sysdiag - system diagnostics
SYNOPSIS
lusr/diaglsysdiag/sysdiag
DESCRIPTION
Sysdiag is a general-purpose system diagnostic facility that tests the system and reports its findings. It concentrates on three areas of system functionality; memory, peripherals and disk.

To use sysdiag, log on as sysdiag, then enter the command sysdiag.

Sysdiag creates a Suntools environment with one window each for memory, peripherals, and disk error
messages, plus a window for the console. It also creates date/time and performance monitor graphs. It
places abbreviated error messages from the memory, disk, and peripherals in the appropriate windows, and
sends console messages to the console window.
When called from a terminal sysdiag interleaves all its messages on the screen.
With or without the windows, it places long error messages in files named log.xx.nn where:

xx

is the name of diagnostic

nn

is the pass number (increments each pass)

After it completes its test, sysdiag displays the error log files by executing the command more log*. These
files remain after sysdiag exits.

Sysdiag consists of a user account with a home directory, a collection of scripts, and executable files containing the actual test code.
To configure or change sysdiag, either change the shell commands in /usr/diag/sysdiag/sysdiag, or change
the sysdiag user configuration files .login, .suntools, and .cshrc.
SEE ALSO
See the appropriate Sun-2 or Sun-3 diagnostic manual.

Sun Release 3.2

Last change: 10 March 1986

703

SYSLOG(8)

MAIN1ENANCE COMMANDS

SYSLOG(8)

NAME

syslog - log systems messages
SYNOPSIS

lusr/etdin.syslog [ -mN] [ -fname ] [ -d ] [ -p port]
DESCRIPTION

Syslog reads a datagram socket and logs each message it reads into a set of files described by the
configuration file /etc!syslog.conf. Syslog configures when it starts up and whenever it receives a hangup
signal. Syslog logs to the host specified by 'loghost' in the letclhosts file. For details on running syslog in a
Sun network environment, see the section, "System Log Configuration" in the System Set-up and Operation chapter of the System Installation and Maintenance Guide.
Each message logged consists of one line. A message can contain a priority code, marked by a digit in
angle braces at the beginning of the line. Priorities are defined in , as shown below, with
LOG_ALERT having the highest priority (1), and LOG_DEBUG the lowest (9).
Priorities
LOG ALERT

this priority should essentially never be used. It applies only to messages that are so
important that every user should be aware of them, for example, a serious hardware
failure.

LOG SALERT

messages of this priority should be issued only when immediate attention is needed by
a qualified system person, for example, when some valuable system resource disappears. They get sent to a list of system people.

LOG EMERG

Emergency messages are not sent to users, but represent major conditions. An example might be hard disk failures. These could be logged in a separate file so that critical
conditions could be easily scanned.

LOG ERR

these represent error conditions, such as soft disk failures, etc.

LOG CRIT

such messages contain critical information, but which can not be classed as errors, for
example, 'su' attempts. Messages of this priority and higher are typically logged on
the system console.

LOG WARNING

issued when an abnormal condition has been detected, but recovery can take place.

LOG NOTICE

something that falls in the class of "important information;" this class is informational but important enough that you don't want to throw items in it away casually.
Messages without any priority assigned to them are typically mapped into this priority.

LOG INFO

information level messages. These messages could be thrown away without problems, but should be included if you want to keep a close watch on your system.

LOG DEBUG

it may be useful to log certain debugging information. Normally this will be thrown
away.

It is expected that the kernel will not log anything below LOG_ERR priority.
The syslog configuration file, etclsyslog.conf, consists of two sections separated by a blank line. The first
section defines files that syslog will log into. Each line contains a single digit which defines the lowest
priority (highest numbered priority) that this file will receive, an optional asterisk which guarantees that
something gets output at least every 20 minutes, and a pathname. The second part of the file contains a list
of users that will be informed on SALERT level messages. For example, the configuration file:
5*/dev/tty8
8/usr/spool! adm/syslog
3/usrl adm/critical
eric
kridle

704

Last change: 1 February 1985

Sun Release 3.2

MAThITENANCECONUMANDS

SYSLOG(8)

SYSLOG(8)

kalash
logs all messages of priority 5 or higher onto the system console, including timing marks every 20 minutes;
all messages of priority 8 or higher into the file lusrlspoolladm/syslog; and all messages of priority 3 or
higher into lusrladm/critical. The users 'eric', 'kridle', and 'kalash' will be informed on any subalert messages.
OPTIONS
-mN

Set the mark interval to N (default 20 minutes).

-f name Specify an alternate configuration file.
-d

Tum on debugging (if compiled in).

-p port Port number where syslog listens for incoming datagrams. The default port is defined in the
'syslog/udp' entry in the letc!services file.

To bring syslog down, it should be sent a terminate signal. It logs that it is going down and then waits
approximately 10 seconds for any additional messages to come in.
There are some special messages that cause control functions. '<*>N' sets the default message priority to
N. '<$>' causes syslog to reconfigure (equivalent to a hangup signal). This can be used in a shell file run
automatically early in the morning to truncate the log.
Syslog creates the file letc/syslog.pid if possible containing a single line with its process id. This can be
used to kill or reconfigure syslo g.
FILES
letc!hosts
Ietc!syslo g .con!
letc!syslog.pid
Ietc!services

the hosts file
the configuration file
the process ID
to find the syslog server's port number

BUGS
LOG_ALERT and LOG_SALERT messages should only be allowed to privileged programs.

Actually, syslog is not clever enough to deal with kernel error messages in the current implementation.
SEE ALSO

syslog(3), kill(2)

Sun Release 3.2

Last change: 1 February 1985

705

TALKD(8C)

MAINTENANCE COMMANDS

TALKD(8C)

NAME

taIkd - server for talk program
SYNOPSIS

lusr/etc/in.talkd
DESCRIPTION

Talkd is a server used by the talk(l) program. It listens at the udp port indicated in the UtaIk" service
description; see services(5). The actual conversation takes place on a tcp connection that is established by
negotiation between the two machines involved
SEE ALSO

services(5), taIk(I), inetd(8)
BUGS

The protocol is architecture dependent, and can't be relied upon to work between Suns and other machines.

706

Last change: 14 Mar 1984

Sun Release 3.2

TELNETD ( 8C)

MAINTENANCE COMMANDS

TELNETD ( 8C)

NAME

telnetd - DARPA TELNET protocol server
SYNOPSIS
lusr/etc/in.telnetd host.port
DESCRIPTION

telnetd is a server that supports the DARPA standard TELNEf virtual terminal protocol. The TELNET server
is invoked by inetd(8C) each time there is a connection to the telnet service; see services(5).
telnetd operates by allocating a pseudo-terminal device (see pty(4» for a client, then creating a login process which has the slave side of the pseudo-terminal as stdin, stdout, and stderr. telnetd manipulates the
master side of the pseudo terminal, implementing the TELNET protocol and passing characters between the
client and login process.
When a TELNET session is started up, telnetd sends a TELNET option to the client side indicating a willingness to do "remote echo" of characters. The pseudo terminal allocated to the client is configured to
operate in "cooked" mode, and with XTABS and CRMOD enabled (see tty (4». Aside from this initial
setup, the only mode changes telnetd will carry out are those required for echoing characters at the client
side of the connection.

telnetd supports binary mode, and most of the common TELNET options, but does not, for instance, support
timing marks.
SEE ALSO
telnet(lC)
BUGS

A complete list of the options supported should be given here.

telnetd can only support 16 psuedo terminals.

Sun Release 3.2

Last change: 28 October 1983

707

TFTPD{8C)

MAlNTENANCECO~ANDS

TFfPD{8C)

NAME

tftpd-DARPA Trivial File Transfer Protocol server
SYNOPSIS
lusr/etc/in.tftpd [ -d ] [port]
DESCRIPTION
Tftpd is a server which supports the DARPA Trivial File Transfer Protocol. The TFTP server operates at
the port indicated in the "tftp" service description; see services(5), and is invoked each time a datagram
reaches this port by the internet server inetd{8C).

Due to the lack of authentication information, tftpd will allow only publicly readable files to be accessed.
To do this, tftpd executes as uid -2 , gid -2 , assuming that no files exist with that owner or group. However, nothing check this assumption or enforces this restriction.
SEE ALSO
tftp{lC)
BUGS

This server is known only to be self consistent (i.e. it operates with the user TFTP program, tftp{IC».

708

Last change: 1 February 1985

Sun Release 3.2

TIMED(8C)

MAINTENANCE COMMANDS

TIMED(8C)

NAME

timed- DARPA Time server
SYNOPSIS

lusr/etc/in.timed
DESCRIPTION

Timed is a server which supports the DARPA Time Server Protocol. The time server operates at the port
indicated in the "time" service description; see services(5), and is invoked by inetd(8C) each time there is
a connection to the time server.
SEE ALSO
services(5),rdate(8),inetd(8)
BUGS

A more sophisticated facility that can accept broadcasts and synchronize clocks over an internet is needed.

Sun Release 3.2

Last change: 13 Dec 1983

709

TNAMED(8C)

MAINTENANCE COMMANDS

TNAMED(8C)

NAME

tnamed - DARPA Trivial name server
SYNOPSIS

lusr/etc/in.tnamed [-v]
DESCRIPTION

tnamed is a server that supports the DARPA Name Server Protocol. The name server operates at the port
indicated in the "name" service description (see services(5)), and is invoked by inetd(8C) when a request
is made to the name server.
Two known clients of this service are the MIT PC/IP software the Bridge boxes.
OPTIONS

-v

Invoke the deamon in verbose mode.

SEE ALSO

services(5), inetd(8C)
BUGS

The service only deals with the most trivial form of names like' 'krypton", and does support the uucp (1 C)
!host!net name format.

710

Last change: 19 MAr 1986

Sun Release 3.2

TRPT(8C)

MAINTENANCE COMMANDS

TRPT(8C)

NAME

trpt - transliterate protocol trace
SYNOPSIS

lusr/etc/trpt [ -a] [ -s] [-t] [ -j ] [ -phex-address ] [ system [ core] ]
DESCRIPTION

Trpt interrogates the buffer of TCP trace records created when a socket is marked for 'debugging' (see setsockopt(2», and prints a readable description of these records. When no options are supplied, trpt prints
all the trace records found in the system grouped according to TCP connection protocol control block
(PCB).
OPTIONS

-s

Print a detailed description of the packet sequencing information, in addition to the normal output.

-t

Print the values for all timers at each point in the trace, in addition to the normal output.

-j

Just give a list of the protocol control block addresses for which there are trace records.

-phex-address
Show only trace records associated with the protocol control block who's address follows.
-a

in addition to the normal output, print the values of the source and destination addresses for each
packet recorded.

The recommended use of trpt is as follows. Isolate the problem and enable debugging on the socket(s)
involved in the connection. Find the address of the protocol control blocks associated with the sockets
using the -A option to netstat(8C). Then run trpt with the -p option, supplying the associated protocol
control block addresses. If there are many sockets using the debugging option, the -j option may be useful
in checking to see if any trace records are present for the socket in question.
If debugging is being performed on a system or core file other than the default, the last two arguments may
be used to supplant the defaults.
FILES

Ivmunix
ldevlkmem
SEE ALSO

setsockopt(2), netstat(8C)
DIAGNOSTICS

'no namelist' when the system image doesn't contain the proper symbols to find the trace buffer; others
which should be self explanatory.
BUGS

Should also print the data for each input or output, but this is not saved in the trace record.
The output format is inscrutable, and should be described here.
The kernel must be compiled with the TCPDEBUG flag set in order for this command to work.

Sun Release 3.2

Last change: 17 February 1986

711

TUNEFS(8)

MAINTENANCE COMMANDS

TUNEFS(8)

NAME

tunefs - tune up an existing file system
SYNOPSIS

lusr/etc/tunefs [ -a maxcontig] [ -d rotdelay] [ -e maxbpg] [ -m minfree] speciallfilesys
DESCRIPTION

Tunefs is designed to change the dynamic parameters of a file system which affect the layout policies. The
parameters which are to be changed are indicated by the flags given below:
-3

maxcontig
This specifies the maximum number of contiguous blocks that will be laid out before forcing a
rotational delay (see -d below). The default value is one, since most device drivers require an
interrupt per disk transfer. Device drivers that can chain several buffers together in a single
transfer should set this to the maximum chain length.

-drotdelay
This specifies the expected time (in milliseconds) to service a transfer completion interrupt and
initiate a new transfer on the same disk. It is used to decide how much rotational spacing to place
between successive blocks in a file.
-emaxbpg
This indicates the maximum number of blocks any single file can allocate out of a cylinder group
before it is forced to begin allocating blocks from another cylinder group. Typically this value is
set to about one quarter of the total blocks in a cylinder group. The intent is to prevent any single
file from using up all the blocks in a single cylinder group, thus degrading access times for all files
subsequently allocated in that cylinder group. The effect of this limit is to cause big files to do
long seeks more frequently than if they were allowed to allocate all the blocks in a cylinder group
before seeking elsewhere. For file systems with exclusively large files, this parameter should be
set higher.
-m minfree

This value specifies the percentage of space held back from normal users; the minimum free space
threshold. The default value used is 10%. This value can be set to zero, however up to a factor of
three in throughput will be lost over the performance obtained at a 10% threshold. Note that if the
value is raised above the current usage level, users will be unable to allocate files until enough
files have been deleted to get under the higher threshold.
SEE ALSO

fs(5), newfs(8), mkfs(8), dumpfs(8)

System Administrationfor the Sun Workstation
BUGS

This program should work on mounted and active file systems. Because the super-block is not kept in the
buffer cache, the program will only take effect if it is run on dismounted file systems. (if run on the root
file system, the system must be rebooted)

712

Last change: 23 October 1984

Sun Release 3.2

UPDATE(8)

MAINTENANCE COMMANDS

UPDATE(8)

NAME

update - periodically update the super block
SYNOPSIS

/etc/update
DESCRIPTION
Update is a program that executes the sync (2) primitive every 30 seconds. This insures that the file system
is fairly up to date in case of a crash. This command should not be executed directly, but should be executed out of the initialization shell command file.
SEE ALSO
sync(2), sync(8), init(8)

Sun Release 3.2

Last change: 13 June 1983

713

MAThITENANCECO~ANDS

UUCLEAN ( 8C)

UUCLEAN(8C)

NAME

uuclean - uucp spool directory clean-up
SYNOPSIS

lusr lIib/uucp/uuc1ean [ -ppre ] [ -ntime ] [ -m ]
DESCRIPTION

Uuclean scans the spool directory for files with the specified prefix and deletes all those which are older
than the specified number of hours.
OPTIONS

-ppre

Scan for files with pre as the file prefix. Up to 10 -p arguments may be specified. A -p without
any pre following deletes all files older than the specified time.

-ntime

Files whose age is more than time hours are deleted if the prefix test is satisfied (default time is
72 hours).

-m

Send mail to the owner of the file when it is deleted.

Uuclean will typically be started by cron(8).
FILES

lusr/lib/uucp

directory with commands used by uuclean internally

lusr/lib/uucp/spool

spool directory

SEE ALSO
uucp( 1C), uux( 1C)

714

Last change: 14 April 1983

Sun Release 3.2

VIPW(8)

MAThnENANCECO~ANDS

VIPW(8)

NAME

vipw - edit the password file
SYNOPSIS

/etc/vipw
DESCRIPTION

Vipw edits the password file while setting the appropriate locks, and does any necessary processing after
the password file is unlocked. If the password file is already being edited, then you will be told to try again
later. The vi editor will be used unless the environment variable EDITOR indicates an alternate editor.
Vipw performs a number of consistency checks on the password entry for root, and will not allow a password file with a "mangled" root entry to be installed.
SEE ALSO

chsh(1), passwd(l), passwd(5), adduser(8)
FILES

/etc/ptmp

Sun Release 3.2

Last change: 4 July 1983

715

VMSTAT(8)

MAINTENANCE COMMANDS

VMSTAT(8)

NAME
vmstat - report virtual memory statistics
SYNOPSIS
vmstat [ -fsS ] [interval [ count] ]
DESCRIPTION

Vmstat delves into the system and normally reports certain statistics kept about process, virtual memory,
disk, trap and cpu activity.
Without options, vmstat displays a one-line summary of the virtual memory activity since the system has
been booted. If interval is specified, vmstat summarizes activity over the last interval seconds. If a count
is given, the statistics are repeated count times.
For example, the following command displays a summary of what the system is doing every five seconds.
This is a good choice of printing interval since this is how often some of the statistics are sampled in the
system.
hal% vmstat 5
procs
rbw
200
10 0
10 0
100

memory
avm fre re at
918 286 0 0
846 254 0 0
840 268 0 0
620 312 0 0

pi
0
0
0

po
0
0
0
0 0

fr
0
0
0
0

page
disk
faults
de sr xO xl x2 x3 in sy
0 0 1 0 0 0 4 12
0 0 6 0 1 0 42 153
0 0 5 0 0 0 27 103
0 0 6 0 0 0 26 76

cpu
cs us sy id
5 3 5 91
31 7 40 54
25 8 26 66
25 6 27 67

"C
hal%
The fields of vmstat's display are:
procs

Reports the number of processes in each of the three following states:
r
in run queue
b
blocked for resources (i/o, paging, etc.)
w
runnable or short sleeper « 20 secs) but swapped

memory Reports on usage of virtual and real memory. Virtual memory is considered active if it belongs
to processes which are running or have run in the last 20 seconds.
avm
number of active virtual Kbytes
fre
size of the free list in Kbytes

716

page

Reports information about page faults and paging activity. The information on each of the following activities is averaged each five seconds, and given in units per second.
re
page reclaims - but see the -S option for how this field is modified.
at
number of attaches - but see the -S option for how this field is modified.
pi
pages paged in
po
pages paged out
fr
pages freed per second
de
anticipated short term memory shortfall
sr
pages scanned by clock algorithm, per-second

disk

Reports number of disk operations per second (this field is system dependent). For Sun systems,
four slots are available for up to four drives: "xO" (or "sO" for SCSI disks), "xl", "x2", and
"x3" .

faults

Reports trap/interrupt rate averages per second over last 5 seconds.
in
(non clock) device interrupts per second
sy
system calls per second
cs
cpu context switch rate (switches/sec)

cpu

Gives a breakdown of percentage usage of CPU time.

Last change: 23 October 1984

Sun Release 3.2

VMSTAT(8)

MAINTENANCE COMMANDS

us
sy
id
OPTIONS
-f

VMSTAT(8)

user time for normal and low priority processes
system time
cpu idle

Report on the number of forks and vforks since system startup and the number of pages of virtual
memory involved in each kind of fork.

-s

Display the contents of the sum structure, giving the total number of several kinds of pagingrelated events which have occurred since boot.

-8

Report on swapping rather than paging activity. This option will change two fields in vmstat's
"paging" display: rather than the "re" and "at" fields, vmstat will report "si" (swap-ins), and
"so" (swap-outs).

FILES

ldevlkmem
Ivmunix

Sun Release 3.2

Last change: 23 October 1984

717

YPINIT(8)

MAINTENANCE COMMANDS

YPINIT(8)

NAME

ypinit - build and install yellow pages database
SYNOPSIS

/usr/etc/yp/ypinit -m
ypinit -s master_name
DESCRIPTION
ypinit sets up a yellow pages database on a yP server. It can be used to set up a master or a slave server.
You must be the superuser to run it It asks a few, self-explanatory questions, and reports success or
failure to the terminal.

It sets up a master server using the simple model in which that server is master to all maps in the data base.
This is the way to bootstrap the yP system; later if you want you can change the association of maps to
masters. All databases are built from scratch, either from information available to the program at runtime,
or from the ASCII data base files in fetc. These files are listed below under FILES. All such files should
be in their "traditional" form, rather than the abbreviated form used on client machines.
A yP database on a slave server is set up by copying an existing database from a running server. The
master_name argument should be the hostname of YP server (either the master server for all the maps, or a
server on which the data base is up-to-date and stable).
Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages.
OPTIONS
-m

-s

Indicates that the local host is to be the YP master.
Set up a slave database.

FILES

fetcfpasswd
fete/group
fete/hosts
/etc/networks
/etc/services
/etc/protocols
/etc/netgroup
/etc/ ethers
SEE ALSO

makedbm(8), ypfiles(5), yppush(8), ypxfr(8), ypmake(8), ypserv(8)

718

Last change: 4 June 1986

Sun Release 3.2

YPMAKE(8)

MAThnENANCECOMMANDS

YPMAKE(8)

NAME

ypmake - rebuild yellow pages database
SYNOPSIS

cd I etc/yp ; make [ map ]
DESCRIPTION

The file called Make/tie in fetcfyp is used by make to build the yellow pages database. With no arguments,
make creates dbm databases for any yP maps that are out-of-date, and then executes yppush to notify slave
databases that there has been a change.
If you supply a map on the command line, make will update that map only. Typing make passwd will
create and yppush the password database (assuming it is out of date). Likewise, make hosts and make networks will create and yppush the host and network files, fetc/hosts and fete/networks.

There are three special variables used by make: DIR, which gives the directory of the source files;
NOPUSH, which when non-null inhibits doing a yppush of the new database files; and DOM, used to construct a domain other than the master's default domain. The default for DIR is fetc, and the default for
NOPUSH is the null string.
Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages.
SEE ALSO

make(l), makedbm(8), ypserv(8)

Sun Release 3.2

Last change: 13 September 1985

719

YPPASSWDD(8C)

MAINTENANCE COMMANDS

YPPASSWDD(8C)

NAME

yppasswdd - server for modifying yellow pages password file
SYNOPSIS
lusr/etdrpc.yppasswddfile [-m argl arg2 ... ]
DESCRIPTION
yppasswdd is a server that handles password change requests from yppasswd(I). It changes a password
entry in file , which is assumed to be in the format of passwd(5). An entry infile will only be changed if the
password presented by yppasswd(l) matches the encrypted password of that entry.

If the -m option is given, then after file is modified, a make(l) will be performed in letclyp. Any arguments following the flag will be passed to make .

This server is not run by default, nor can it be started up from inetd(8). If it is desired to enable remote
password updating for the yellow pages, then an entry for yppasswdd should be put in the letclrc file of the
host serving as the master for the yellow pages passwd file.
EXAMPLE
If the yellow pages password file is stored as letclyplsrclpasswd, then to have password changes propagated immediately, the server should be invoked as
lusr/etc/rpc.yppasswdd letclyp/src/passwd -m passwd DIR=/etclyp/src
In this case, "src" is the yP domain name.
FILES

/ etclypiMakefile
SEE ALSO
yppasswd( 1), passwd(5), ypfiles(5), ypmake(8)

720

Last change: 16 March 1985

Sun Release 3.2

MAINTENANCE COMMANDS

YPPOLL(8)

YPPOLL(8)

NAME

yppoll - what version of a

yP

map is at a yP server host

SYNOPSIS
lusr/etc/yp/YPpoll [ -h host] [ -d domain] mapname
DESCRIPTION

yppoll asks a ypserv process what the order number is, and which host is the master yP server for the
named map. If the server is a v.l yP protocol server, yppoll uses the older protocol to communciate with it.
In this case, it also uses the older diagnostic messages in case of failure.
OPTIONS
-h host Ask the ypserv process at host about the map parameters. If host isn't specified, the YP server for
the local host is used. That is, the default host is the one returned by ypwhich(8).

-d domain
Use domain instead of the default domain.
SEE ALSO
ypserv(8), ypfiles(5)

Sun Release 3.2

Last change: 4 June 1986

721

YPPUSH(8)

MAINTENANCE COMMANDS

YPPUSH(8)

NAME

yppush - force propagation of a changed yP map
SYNOPSIS

lusr/etc/yp/yppush [ -d domain] [ -v ] mapname
DESCRIPTION

yppush copies a new version of a Yellow Pages (YP) map from the master yP server to the slave yP
servers. It is normally run only on the master yP server by the Makefile in lusrletclyp/ after the master
databases are changed. It first constructs a list of yP server hosts by reading the yP map ypservers within
the domain. Keys within the map ypservers are the ASCII names of the machines on which the yP servers
run.
A "transfer map" request is sent to the yP server at each host, along with the information needed by the
transfer agent (the program which actually moves the map) to call back the yppush . When the attempt has
completed (successfully or not), and the transfer agent has sent yppush a status message, the results may be
printed to stdout. Messages are also printed when a transfer is not possible; for instance when the request
message is undeliverable, or when the timeout period on responses has expired.
Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages.
OPTIONS

-d

Specify a domain.

-v

Verbose. This causes messages to be printed when each server is called, and for each response. If
this flag is omitted, only error messages are printed.

FILES

/etc/ypl domainnamelypservers. {dir, pag}
SEE ALSO

ypserv(8), ypxfr(8), ypfiles(5), YP protocol specification

BUGS
In the current implementation (version 2 yP protocol), the transfer agent is ypxfr, which is started by the
ypserv program. If yppush detects that it is speaking to a version 1 yP protocol server, it uses the older
protocol, sending a version 1 YPPROC_GET request and issues a message to that effect. Unfortunately,
there is no way of knowing if or when the map transfer is performed for version 1 servers. yppush prints a
message saying that an "old-style" message has been sent. The system administrator should later check to
see that the transfer has actually taken place.

722

Last change: 4 June 1986

Sun Release 3.2

YPSERV(8)

MAINTENANCE COMMANDS

YPSERV(8)

NAME

ypserv, ypbind - yellow pages server and binder processes
SYNOPSIS

/usr/etc/ypserv
/etc/ypbind
DESCRIPTION

The yellow pages (YP) provides a simple network lookup service consisting of databases and processes.
The databases are dbm(3) files in a directory tree rooted at letclyp. These files are described in ypfiles(5).
The processes are lusrletclypserv, the yP database lookup server, and letc/ypbind, the yP binder. The programmatic interface to yP is described in ypclnt(3N). Administrative tools are described in yppush(8),
ypxfr(8), yppoll(8), ypwhich(8), and ypset(8). Tools to see the contents of yP maps are described in
ypcat(1), and ypmatch(1). Database generation and maintenance tools are described in ypinit(8),
ypmake(8), and makedbm(8).
Both ypserv and ypbind are daemon processes typically activated at system startup time from letclrc.local.
ypserv runs only on yP server machines with a complete yP database. ypbind runs on all machines using
yP services, both yP servers and clients.
The ypserv daemon's primary function is to look up information in its local database of yP maps. The
operations performed by ypserv are defined for the implementor by the YP protocol specification, and for
the programmer by the header file . Communication to and fromypserv is by
means of RPC calls. Lookup functions are described in ypclnt(3N), and are supplied as C-callable funtions
in llibllibc. There are four lookup functions, all of which are performed on a specified map within some
yP domain: Match, GetJtrst, Get_next, and Get_all. The Match operation takes a key, and returns the
associated value. The GetJtrst operation returns the first key-value pair from the map, and Get_next can
be used to enumerate the remainder. Get_all ships the entire map to the requester as the response to a single RPC request
Two other functions supply information about the map, rather than map entries: Get_order_number, and
Get_master_name. In fact, both order number and master name exist in the map as key-value pairs, but the
server will not return either through the normal lookup functions. (If you examine the map with makedbm(8), however, they will be visible.) Other functions are used within the yP subsystem itself, and are
not of general interest to yP clients. They include Do you_serve _this_domain?, Transfer_map, and
Reinitialize- internal- state.
The function of ypbind is to remember information that lets client processes on a single node communicate
with some ypserv process. ypbind must run on every machine which has yP client processes; ypserv may
or may not be running on the same node, but must be running somewhere on the network.
The information ypbind remembers is called a binding - the association of a domain name with the internet address of the yP server, and the port on that host at which the ypserv process is listening for service
requests. The process of binding is driven by client requests. As a request for an unbound domain comes
in, the ypbind process broadcasts on the net trying to find a ypserv process that serves maps within that
domain. Since the binding is established by broadcasting, there must be at least one ypserv process on
every net. Once a domain is bound by a particular ypbind, that same binding is given to every client process on the node. The ypbind process on the local node or a remote node may be queried for the binding of
a particular domain by using the ypwhich(1) command.
Bindings are verified before they are given out to a client process. If yphind is unable to speak to the
ypserv process it's bound to, it marks the domain as unbound, tells the client process that the domain is
unbound, and tries to bind the domain once again. Requests received for an unbound domain will fail
immediately. In general, a bound domain is marked as unbound when the node running ypserv crashes or
gets overloaded. In such a case, ypbind will to bind any yP server (typically one that is less-heavily
loaded) available on the net

Sun Release 3.2

Last change: 6 December 1985

723

YPSERV(8)

MAINTENANCE COMMANDS

YPSERV(8)

ypbind also accepts requests to set its binding for a particular domain. The request is usually generated by
the yP subsystem itself. ypset(8) is a command to access the Set_domain facility. It is for unsnarling
messes, not for casual use.
FILES

If the file lusrletclyplypserv.log exists when ypserv starts up, log information will be written to this file
when error conditions arise.
SEE ALSO
ypclnt(3N), ypfiles(5), ypcat(l), ypmatch(1), yppush(8), ypwhich(8), ypxfr(8), ypset(8)

YP Protocol Specification in Networking on the Sun Workstation

724

Last change: 6 December 1985

Sun Release 3.2

YPSET(8)

MAINTENANCE COMMANDS

YPSET(8)

NAME

ypset - point ypbind at a particular server
SYNOPSIS

lusr/etc/yp/ypset [ - VII-V2 ] [ -h host] [ -d domain] server
DESCRIPTION
ypset tells ypbind to get yP services for the specified domain from the ypserv process running on server. If
server is down, or isn't running ypserv, this is not discovered until a yP client process tries to get a binding
for the domain. At this point, the binding set by ypset will be tested by ypbind. If the binding is invalid,
ypbind will attempt to rebind for the same domain.

ypset is useful for binding a client node which is not on a broadcast net, or is on a broadcast net which isn't
running a yP server host. It also is useful for debugging yP client applications, for instance where a yP
map only exists at a single yP server host.

In cases where several hosts on the local net are supplying yP services, it is possible for ypbind to rebind to
another host even while you attempt to find out if the ypset operation succeeded. That is, you can type
"ypset hostl", and then "ypwhich", which replies: "host2", which can be confusing. This is a function of
the yP subsystem's attempt to load-balance among the available yP servers, and occurs when hostl does
not respond to ypbind because it is not running ypserv (or is overloaded), and host2, running ypserv, gets
the binding.
server indicates the yP server to bind to, and can be specified as a name or an IP address. If specified as a
name, ypset will attempt to use yP services to resolve the name to an IP address. This will work only if the
node has a current valid binding for the domain in question. In most cases, server should be specified as an
IP address.

Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages.
OPTIONS

-VI

Bind server for the (old) v.l

-V2

Bind server for the (current) v.2 yP protocol.

yP protocol.

If no version is supplied, ypset, first attempts to set the domain for the (current) v.2 protocol.
If this attempt fails, ypset, then attempts to set the domain for the (old) v.l protocol.
-b host

Set ypbind's binding on host, instead of locally. host can be specified as a name or as an IP
address.

-d domain

Use domain, instead of the default domain.

SEE ALSO

ypwhich(I), ypserv(8), ypfiles(5)

Sun Release 3.2

Last change: 4 June 1986

725

YPWHICH(8)

MAINTENANCE COMMANDS

YPWHICH(8)

NAME

ypwhich - what machine is the yP server?
SYNOPSIS

ypwhich [ -d domainname ] [ hostname ]
ypwhich [ -d domainname ] [ -t ] -m [ mname ]
DESCRIPTION
Ypwhich tells which yP server supplies yellow pages to a yP client, and which yP server is the master for
a map. If invoked without arguments, it gives the yP server for the local machine. If hostname is
specified, that machine is queried to find out which yP master it is using.

If the -m switch is used without mname, a list of every map in the domain and the master of each will be
printed. If mname is specified, only the master yP server for that map is printed. Mname may be a mapname, or a nickname for a mapname. Mapnames and nicknames are described in ypcat(I).
OPTIONS

-d

Domainname specifies the name of a yP domain. The default is the default domain for the local
machine.

-m

Find the master yP server for a map, or for all maps in a domain. No hostname may be specified
with-m.

-t

Inhibit nickname translation; useful if there is a mapname identical to a nickname. This is not true
of any Sun-supplied map.

SEE ALSO
ypfiles(5), rpcinfo(8), yppush(8), ypserv(8)

726

Last change: 26 August 1985

Sun Release 3.2

YPXFR(8)

MAINTENANCE COMMANDS

YPXFR(8)

NAME

ypxfr, ypxfr_lperday, ypxfr_lperhour, ypxfr_2perday - transfer a yP map from some yP server to here
SYNOPSIS

lusr/etc/yp/ypxfr [ -f] [ -h host] [-d domain] [ -c ] [ -C tid prog ipadd port] mapname
DESCRIPTION

ypxfr moves a yP map to the local host by making use of normal yP services. It creates a temporary map
in the directory /etclyp/domain (which must already exist), fills it by enumerating the map's entries, fetches
the map parameters (master and order number), and loads them. It then deletes any old versions of the map
and moves the temporary map to the real mapname.
If ypxfr is run interactively, it writes its output to the terminal. However, if it is invoked without a controlling terminal, and if the log file /etclyp/ypxfr.log exists, it will append all its output to that file. Since ypxfr
is most often run from lusrlliblcrontab, or by ypserv, you can use the log file to retain a record of what was
attempted, and what the results were.
For consistency between servers, ypxfr should be run periodically for every map in the yP data base. Different maps change at different rates: the services .byname map may not change for months at a time, for
instance, and may therefore be checked only once a day in the wee hours. You may know that mail. aliases
or hosts.byname changes several times per day. In such a case, you may want to check hourly for updates.
A crontab(5) entry can be used to perform periodic updates automatically. Rather than having a separate
crontab entry for each map, you can group comands to update several maps in a shell script. Examples
(mnemonically named) are in letclyp: ypxfr_lperday.sh, ypxfr_2perday.sh, and ypxfr_lperhour.sh. They
can serve as reasonable first cuts.
Refer to ypfiles(5) and ypserv (8) for an overview of the yellow pages.
OPTIONS
-f

Force the transfer to occur even if the version at the master is not more recent than the
local version.

-c

Don't send a "Clear current map" request to the local ypserv process. Use this flag if
ypserv is not running locally at the time you are running ypxfr. Otherwise, ypxfr will
complain that it can't talk to the local ypserv, and the transfer will fail.

-h host

Get the map from host, regardless of what the map says the master is. If host is not
specified, ypxfr will ask the yP service for the name of the master, and try to get the map
from there. host may be a name or an internet address in the form a.b.c.d.

-ddomain

Specify a domain other than the default domain.

-C tid prog ipadd port
This option is only for use by ypserv. When ypserv invokes ypxfr, it specifies that ypxfr
should call back a yppush process at the host with IP address ipaddr, registered as program number pro g, listening on port port, and waiting for a response to transaction tid.
FILES

letclyplypxfr.log

log file

letclyplypxfr_lperday

script to run one transfer per day, for use with cron(8)

letclyplypxfr_2perday

script to run two transfers per day

letclyplypxfr_1 perhour

script for hourly transfers of volatile maps

SEE ALSO

cron(8), ypfiles(5), ypserv(8), yppush(8)

YP Protocol Specification, in Networldng on the Sun Workstation

Sun Release 3.2

Last change: 19 April 1986

727

Index
-

Special Characters

command separation, 76

<
less than operator - e sh, 80
redirect standard input, 77

history substitution - esh, 76
logical negation operator - e sh, 80
! mail command, 252
! = - not equal to operator esh, 80
! - globbing pattern mismatch operator e sh, 80
mail command, 252
! invoke shell to process script, 81
$ - variable substitution, 78
$* - word count for variable, 79
$ $ - process number of shell, 79
$< - read value from terminal- esh, 79
$ ? - variable set inquiry esh, 79

«
bitwise shift left - e sh, 80
parse and pass input to command, 77
<= -less than or equal to operator - esh, 80
= mail command, 252
- is equal to opefl!tor - esh,80
- globbing pattern match operator - e sh, 80

*
*

>
greater than operator - e sh, 80
redirect standard output, 77
> & - redirect standard output and standard error - e sh, 77
>= - greater than or equal to operator - esh, 80

%

job control, reference to current job - esh,81
job to foreground/background - esh,87
modular division operator - esh, 80

»
append standard output, 77
bitwise shift right - e sh, 80
»& - append standard output and standard error esh, 77
? - filename wild card, any single characters, 79
? mail command, 252
@ - arithmetic on variables esh,87
[ ] - filename substitution, any character in list or range, 79
" - suppress parsing, filename substitution, 76
\ - suppress special meaning, 76
\! * - alias substitution, include command-line argumentsesh,77

&
bitwise AND operator - e sh, 80
run command in background, 76

&&

,

execute on success - esh, 76
logical AND operator - esh, 80
- suppress parsing, variable, command and filename substitution, 76
)

command grouping - esh, 76
group operators - esh, 80

bitwise XOR operator - e sh, 80
quick substitution - esh,77
, - command substitution, 79
} - filename substitution, suc;cessiv~fStPmg.$ij(~1¢"fi~se.4J:ist
79,81

*

filename wild card, zero or more of any characters, 79
integer multiplication operator - esh,80
+ - integer addition operator - esh, 80
- - integer subtraction operator - e sh, 80
-d C-Shell file inquiry - directory, 80
-e C-Shell file inquiry - file exists, 80
- f C-Shell file inquiry - plain file, 80
- 0 C-Shell file inquiry ownership, 80
-r C-Shell file inquiry - read accessible, 80
-w C-Shell file inquiry - write accessible, 80
-x C-Shell file inquiry - execute accessible, 80
-z C-Shell file inquiry - zero length, 80
- read and execute file - sh, 382
/ - integer division operator - e sh, 80
: - null command, 82
: modifiers - history substitution - e sh, 77

bitwise OR operator - e sh,
pipe standard output, 76
I mail command, 254
I & - pipe standard output and standard emrlF:;.,;.;;;;;::::::t! sh:,::::./

II
execute on failure - esh,76
logical OR operator - esh. 80
filename substitution, home directory, 79
one's complement operator - esh, 80
- ! - mail tilde escape, 250

-729-

Index - Continued

_0

-<
-?

-I
-A
-b
-c
-d
-e
-f
-h
-i
-m
-p
-q
-r
-s
-t
-v
-w
-x

-

mail tilde escape, 250
mail tilde escape, 250
mail tilde escape, 251
mail tilde escape, 250
mail tilde escape, 250
mail tilde escape, 251
mail tilde escape, 250
mail tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251
mill tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251
mail tilde escape, 251

arp - address resolution display and control, 561
as - assembler, 15
ASCII dump file - od, 286
ascii - ASCII character set, 536
askcc mail environment variable, 256
asksub mail environment variable, 256
at - do job at specified time, 17
atq - display delayed execution queue, 19
atrm-remove delayed execution jobs, 20
autoboot procedures - boot, 562, 662
autoprint mail environment variable, 256
awk - scan and process patterns, 21

B
backquote substitution, 79
backspace magnetic tape files - mt, 277
backspace magnetic tape records - mt, 277
backup dumps - dump, 583
bang mail environment variable, 256
banner - make posters, 24
basename - deliver portions of path names, 25
bc - calculator language, 26
bg - job to background - csh, 82
bibliography
addbib - create or extend, 6
indxbib - make inverted index, 209
lookbib - find bibliographic references, 233
ref er - insert literature references, 340
roffbib -print literature references, 346
sortbib - sort bibliographic database, 395
biff - mail notifier, 28
binary file transmission
uudecode - decode binary file, 479
uuencode - encode binary file, 479
binmail-version 7 mail, 29
biod daemon, 646
block size for tape - 1024 bytes, 583
blocks, count, in file - sum, 409
boggletool-SunView game of boggle, 522
boot - system startup procedures, 562
bootstrap procedures - boot, 562, 662
bootstrap PROM monitor program, 630
bouncedemo - bouncing square graphics demo, 529
Bourne Shell- sh, 377 thrll384
Bourne Shell commands, 378, 382 thru 384
° ,382
: ,382
break,382
case, 378
cd, 382
continue, 382
do, 378
done, 378
echo, 382
elif,378
else, 378
esac, 378
eval,382
exec, 382
exit, 382

A
abort printer - lpc, 617
ac -login accounting, 555
accounting, display login record - ac, 555
process accounting, display record - sa, 687
process accounting, on or off - accton, 687
accton - processing accounting on or off, 687
adb - debugger, 2
adb scripts - adbgen, 556
adbgen - generate adb script, 556
addbib - create bibliography, 6
additional paging/swapping devices, specify - swapon, 701
address resolution display and control- arp, 561
adduser - add new user account, 558
adjacentscreens, 8
admin - adminster secs, 9
alias mail command, 252
alias - shell macros - csh, 82
alias substitution - in C-Shell, 77
allnet mail environment variable, 256
allow messages - mesg, 271
alter process priority - renice, 663
al ternates mail command, 252
alwaysignoremail environment variable, 256
analyze - crash analyzer, 560
append mail environment variable, 256
ar -library maintenance, 12
arch -display Sun architecture, 14
archive
ar -library maintenance, 12
archive tapes - tar, 429
cpio - copy archive, 67
argument list processing - in C-Shell, 74
argv - C-Shell variable, arguments list, 87

-730-

Index - Continued

Bourne Shell commands, continued
export, 382
fi,378
for, 378
hash, 382
if, 378
in, 378
login, 382
pwd, 382
read, 383
readonly, 383
return, 383
set, 383
shift, 383
test, 383
then, 378
times, 383
trap, 383
type, 383
umask,383
unset, 383
until,378
wait, 384
while, 378
Bourne Shell functions, 378
Bourne Shell variables, 379
CDPATH, 379
HOME, 379
IFS,379
MAIL, 379
MAl LCHECK, 379
MAILPATH, 379
PATH, 379
PS1, 379
PS2, 379
SHELL,379
Bourne shell, comparison with C-Shell, 74
branch - C-Shell control flow, 81
break shell command - sh, 382
break - exit loop - csh, 82
breaksw - exit switch - csh, 82
broadcast messages to all users on network - rwall, 357
build
programs - make, 262
random library - ranlib, 331
system configuration files - config,569
yellow pages database - ypinit, 718

c
C compiler, 35
C programming language
cflow - code flow graph, 42
cpp - C preprocessor, 69
ctags - create tags file, 93
cxref - cross reference C program, 100
indent - format C source, 205
lint - C program verifier, 225
mk s tr - create C error messages, 273
t cov - code coverage tool, 434
vgrind - make formatted listings, 486
xstr-extract strings from C code, 513
C-Shell
alias substitution, 77

C-Shell, continued
and Bourne shell scripts, 81
argument list processing, 74
arguments list - argv variable, 87
branch, 81
command execution, 81
command inquiry, 81
command substitution, 79
commands, 82 thTu 87
comparison with Bourne shell, 74
conditional exectution - &&, 76
conditional exectution - I I, 76
• cshrc file, 74
escape character, quotes and comments, 76
expressions, 80
file inquries,. 80
filename completion, 75
filename substitution, 79
history substitution, 76
110 redirection, 77
job control, 81
lexical structure, 76
• login file, 74
• logout file, 74
loop, 81
metacharacters, 76operators, 80
parentheses - command grouping, 76
pipeline, 76
quick substitution, 77
signal handling, 81
variable substitution, 78
C-Shell commands
% - job to foreground/background, 87
: - null command, 82
@ - arithmetic on variables, 87
alias - shell macros, 82
bg - job to background, 82
break - exit loop, 82
breaksw - exit switch, 82
case - selector in switch, 82
cd - change directory, 82
chdir - change directory, 82
continue - cycle loop, 82
default -catchallin switch, 82
di r s - print directory stack, 83
echo - echo arguments, 83
else - alternative commands, 84
end - end loop, 83
endif - end conditional, 84
endsw - end switch, 86
eval- re-evaluate shell data, 83
exec - execute command, 83
exi t - exit shell, 83
fg -job to foreground, 83
foreach -loop on list of names, 83
glob - filename expand wordlist, 83
goto - command transfer, 83
hashstat - display hashing statistics, 83
history - display history list, 83
if - conditional statement, 83
jobs - display job list, 84
kill-killjobs and processes, 84
1 imi t - alter resource limitations, 84
-731-

Index - Continued

C-Shell commands, continued
login -login new user, 84
logout - end session, 84
nice -run low priority process, 84
nohup - run command immune to hangups, 84
notify - request immediate notification, 85
onintr - handle interrupts in scripts, 85
popd - pop shell directory stack, 85
pu shd - push shell directory stack, 85
rehash - recompute command hash table, 85
repeat - execute command repeatedly, 85
set - change value of shell variable, 85
setenv - set or display variables in environment, 85
shift - shift argument list, 85
source - read commands from file, 85
stop - halt job or process, 86
suspend- suspend shell, 86
swi tch - multi-way branch, 86
time - time command, 86
umask - change/display file creation mask, 86
una lias - remove aliases, 86
unhash - discard hash table, 86
unlimit -remove resource limitations, 86
unset -discard shell variables, 86
unsetenv - remove environment variables, 86
wai t - wait for background process, 86
while - repeat commands, 86
C-Shell variables, 87 thnl 89
argv,87
cdpath, 87
cwd, 87
echo, 87
fignore,87
filec,87
hardpaths, 87
histchars, 87
history, 87
home, 87
ignoreeof, 87
mail, 87
nobeep,88
noclobber, 88
noglob,88
nonomatch,88
notify, 88
path, 88
prompt, 88
savehist, 88
shell, 88
status, 88
time, 88
verbose, 89
cal - display calendar, 31
calculator, 110
calendar -reminder service, 32
call-graph, display profile data - gprof, 188
canf ield - solitaire card game, 523
canvas_demo - canvas sub window demo, 533
case shell command - sh,378
case - selector in switch - csh,82
cat -concatenate files, 33
CIAff interpreter - pt i, 323
ca tman - create cat files for manual pages, 564

cb - format filter for C source files, 34
cc - C compiler, 35
cca t - compress files, 63
cd - change directory, 39
change directory - csb, 82
change directory - sh, 382
cd mail command, 252
cdc - change delta commentary, 40
cdpath - C-Shell variable, 87
CDPATH shell variable sh, 379
cf low - generate C flow graph, 42
cframedemo - graphics demo, 529
change
default shell, 48
delta commentary, 40
directory, 39
group ownership of file - chgrp, 45
login password - passwd, 292
login password in yellow pages - yppasswd, 518
login shell, 48
mode of file, 46
owner of file - chown, 565
permissions of file, 46
priority of command - nice, 279
process priority - renice, 663
working directory, 39
change name of file or directory - mv, 278
character translation - tr, 458
characters for equations - eqnchar, 537
characters in file, count - wc, 500
chdir - change directory - csh, 82
chdir mail command, 252
check directory - dcheck, 577
check file system - f sck, 594
check quota consistency - quota check, 657
check spelling - spell,396
checkeq - check eqn constructs, 146
checknr - check nroffltroff files, 44
chess - chess game, 524
chesstool- SunView chess game, 525
chgrp - change group, 45
chmod - change mode, 46
chown - change owner of file, 565
chroot - change root directory for a command, 566
chsh - change shell, 48
clean print queue- Ipc,617
clean UUCP spool area - uuclean, 714
clear - clear screen, 49
clear i-node - clri, 567
clear colormap - clear hardware color map, 50
clear=:functions -resetSunView selection service, 51
click - control keyboard click, 52
clock - display time in window, 53
clr i-clear i-node, 567
cmd mail environment variable, 257
cmdtool - shell or program with SunView text facility, 54
cmp - compare files, 57
code coverage tool- tcov,434
code flow graph - cflow,42

-732-

Index - Continued

code formatter
cb - C source format filter, 34
vgrind- troff preprocessor for listings, 486
indent - format C source, 205
co 1 - filter reverse paper motions, 58
colcrt - document previwer, 59
co 1 rm - remove columns from file, 60
columns
print in multiple - pr,309
remove from file, 60, 99
comb - combine deltas, 61
combine sees deltas, 61
conun - find commonality, 62
command
change priority of - nice, 279
describe- whatis,502
execution, in C-Shell, 81
grouping in the C-Shell), 76
inquiry, in C-She11, 81
locate - wherei s, 503
process options in scripts - get opt, 186
run immune to hangup - nohup, 283
command interpreter
csh - C-She11, 74
sh - Bourne Shell, 377 thru 384
command substitution, 79
commands to Bourne Shell, 378, 382 thru 384, see also Bourne
Shell commands
commands, introduction, 1
communications
cu - connect to remote system, 451
enroll- enroll for secret mail, 512
mai 1 - send and receive mail, 249 thru 258
mesg - permit or deny messages, 271
talk - talk to another user, 428
telnet - TELNET interface, 438
tftp-trivial file transfer program, 447
tip -connect to remote system, 451
uuclean - clean UUCP spool area, 714
uucp - UNIX to UNIX copy, 477
uudecode - decode binary file, 479
uuencode - encode binary file, 479
uulog - UUCP log, 477
uuname - UUCP list of names, 477
uusend - send file to remote host, 480
uux - UNIX to UNIX command execution, 481
wri te - write to another user, 508
xget - receive secret mail, 512
xsend- send secret mail, 512
compare
files, 57
files differentially, 122
files side-by-side, 370
three-way differential- diff3,124
versions of SCCS file - sccsdiff,364
compile Pascal programs - pc, 294
compiler generator, 155
compiler generators
lex -lexical analyzer generator, 222
yacc - parser generator, 514
compiler preprocessors
epp - C preprocessor, 69

compiler preprocessors, continued
rat for - rational FORTRAN, 334
compilers
cc - C compiler, 35
f 7 7 - FORTRAN compiler, 156
pc - Pascal compiler, 294
rpcgen - generate RPC protocols, C header files, 347
compress -compress files, 64
compress files, 63
comsat - biff server, 568
concatenate files - eat, 33
config - build system configuration files, 569
configuration files, build - config,569
configure network interface parameters - ifconfig, 606
connect to remote system
cu,451
tip, 451
continue shell command - sh,382
continue - cycle loop - csh, 82
control flow - in C-Shell, 81
control line printer - lpc, 617 thru 618
control magnetic tape - mt, 277
conv mail environment variable, 257
convert
spaces to tabs unexpand, 152
tabs to spaces expand, 152
convert 8-bit rasterfile to I-bit rasterfile- rasfilter8tol,
332
convert and copy files, 112
convert foreign font files - vswap,494
convert units - units, 474
copy
archives, 67
files, 66
files from remote machine - rcp, 335
standard output to many files - tee, 435
copy mail command, 252
Copy mail command, 252
core image, get of process - gcore, 179
count blocks in file - sum, 409
count lines, words, characters in file - we, 500
cp - copy files, 66
cpio - copy archives, 67
cpp - C preprocessor, 69
CPU PROM monitor program, 630
crash analyzer- analyze, 560
crash - crash information, 574
create
bibliography - addbib, 6
cat files for manual pages - catman, 564
delta - delta, 116
directory - mkdir, 272
error log - drnesg, 582
fifo - mknod, 628
file system - rnkf s, 627
font width table - vwidth,496
mail aliases database - newaliases,644
named pipe - rnknod, 628
new file system - newf s, 645
permuted index - ptx, 324

-733-

Index - Continued

create, continued
prototype file system - mkproto, 629
random library - ranlib, 331
sees data bases, 9
sees delta- delta, 116
script of terminal session - script, 369
special file - mknod, 628
system configuration files - conf ig, 569
system log entry - syslog, 426
tags file, 93
yellow pages database - ypinit,718
yellow pages dbm file - makedbm, 622
cron - clock daemon, 576
cross reference e program - exref, 100
cross reference Pascal program - pxref,329
crt mail environment variable, 257
crypt - encrypt, 73
csh - C-Shell, 74
• eshre file, 74
csplit - split file into sections, 91
ctags - create tags file, 93
etraee - display program trace, 95
cu - connect to remote system, 451
current domain, set or display name - domainname, 128
cursor demo - cursor attributes demo 533
curve fitti;g, spline,397
'
cu t - remove columns from file, 99
ewd - C-Shell variable, 87
cxref - cross reference C program, 100

debug tools, continued
kadb - kernel debugger, 612
decimal dump file - od, 286
decode binary file - uudecode, 479
decode files
crypt", 73
des - Data Encryption Standard, 119
crypt - decrypt, 73
default - catchall in switch - esh, 82
defaults, update kernel from- input from defaults 210
defaults_from_input - update d;faults from kernel,
defaultsedit -changing SunView default settings 114
defining Bourne Shell functions, 378
'
delayed execution
add job to queue - at, 17
display queue - atq, 19
remove jobs from queue- atrm, 20
delete
columns from file, 60, 99
directory - rmdir, 344
file - rm, 344
filename affixes - basename, 25
nroff, troff, tbl and eqn constructs - deroff,
118
print jobs - lprm, 239
repeated lines - uniq, 473
delete delayed execution jobs - atrm, 20
delete mail command, 253
delta
changecommenbuy,40
combine, 61
make sces delta - delta, 116
remove - rmdel, 345
demos
bouncedemo - bouncing square graphics demo, 529
canvas_demo-canvas subwindow demo, 533
cframedemo - graphics demo, 529
cursor_demo - cursor attributes demo, 533
flight - graphics processor demo, 528
framedemo - graphics demo, 529
goban - go board graphics demo, 529
graphics processor, 528
graphics demos, 529
introduction, 521
jumpdemo - graphics demo, 529
maze - graphics demo, 529
rotob j - graphics processor demo, 528
shaded - graphics demo, 529
show - graphics demo, 529
showmap - graphics demo, 529
spheresdemo - graphics demo, 529
stringart - graphics demo, 529
sun cube - graphics demo, 529
SunView demos, 533
demount file system - umount, 634
deny messages - mesg, 271
deroff - remove troff constructs, 118
des - data encryption, 119
describe command - whatis, 502
desk calculator, 110
devices
paging, specify - swapon, 701

210

D
daemons
biod daemon, 646
nf sd daemon, 646
rquotad - remote quota server, 679
sprayd - spray server, 698
DARPA
Internet directory service - who is, 507
Internet file transfer protocol server - ft pd, 597
TELNET protocol server- telnetd, 707
DARPA Time server - timed, 709
to RPC mapper- portmap, 650
DARPA Trivial name server- tnamed, 710
Data Encryption Standard - des, 119
database operator - join, 215
date -date and time, 101
dbx - source debugger, 103
dbxtool - debugger, 109
de - desk calculator, 110
dcheek - directory consistency check, 577
dd - convert and copy, 112
DEAD mail environment variable, 257
debug mail environment variable, 257
debug network.- ping, 649
debug tools
adb -debugger, 2
adbgen - generate adb script, 556
ctraee - display program trace, 95
dbx - source debugger, 103
dbxtool-debugger,l09

-734-

Index - Continued

devices, continued
swapping, specify - swapon, 701
df - display free space, 121
diag - initialize/diagnose disk, 578
diagnose/initialize disk - diag, 578
diagnostics
gxtest - graphics board diagnostics, 602
110 error mapping page, 400
imemtest - memory diagnostic, 607
diagnostics - sysdiag, 703
diff - differential compare, 122
diff3 - three-way differential compare, 124
diffmk - add change marks to documents, 126
di rcmp - compare directories, 127
directory
changenameof- mV,278
change working, 39
check consistency - dcheck, 577
delete - rmdir, 344
differential compare, 122
display name of working - pwd, 325
list contents of - Is, 241
make- mkdir,272,273
make link to - In, 228
move --:. mv, 278
remove- rmdir, 344
rename - mv, 278
dirs - print directory stack - csh, 83
disable print queue - lpc, 617
discard mail command, 253
disk
diagnose/initialize - diag, 578
diagnostics - sysdiag, 703
dkinfo - geometry information, 581
disk quotas
edquota - edit user quotas, 586
quota check - check quota consistency, 657
quotaof f - turn file system quotas off, 658
quotaon - tum file system quotas on, 658
repquota - summarize quotas, 664
rquotad - remote quota server, 679
display
architecture of current Sun host, 14
call-graph profile data - gprof, 188
current domain name - domainname, 128
current host identifier, 200
current host name, 201
date, 101
date and time, 101
delayed execution queue - atq, 19
disk usage, 129
disk usage and limits - quota, 330
effective user name - whoami, 506
file by screenfuls - more, 274
file names - Is, 241
file system quotas - repquota, 664
first lines of file, 198
free space in file system, 121
group membership, 197
identifier of current host, 200
last commands - lastcomm, 218
last part of file - tail, 427

display, continued
login name - logname, 231
name list of object file or library - nm, 282
name of current host, 201
page size - pagesize, 291
printer queue - lpq, 235
process status - ps, 320
processor of current Sun host, 247
program profile - prof, 314
program trace - ctrace, 95
sees file editing status - sact, 359
selected lines from file - sed, 371
status of network hosts - rup, 354
system up time - uptime, 475
time and date, 101
time in window, 53
user and group IDs - id, 204
users on system- users, 476
waiting mail- prmail,313
working directory name - pwd, 325
display editor - vi, 488
display status of local hosts - ruptime, 355
dkinfo - disk geometry information, 581
dme sg - create error log, 582
do shell command - sh, 378
document production
addbib -create bibliography, 6
checknr - check nroffltroff files, 44
col - filter reverse paper motions, 58
col crt command, 59
deroff - delete troff, tbl and eqn constructs, 118
dif fmk - add change marks, 126
eqn - set mathematical equations, 146
eqnchar - special characters for equations, 537
fmt - simple formatter, 166
indxbib - make inverted index, 209
lookbib - find bibliographic references, 233
-man - macros to format manual pages, 542
-me - macro package, 544
-ms - macro package, 546
nroff - document formatter, 284
pti - (old) troff interpreter, 323
ptx - generate permuted index, 324
ref er - insert literature references, 340
rof fbib - print bibliographic database, 346
soelim-eliminate .so's fromnroffinput, 391
sortbib - sort bibliographic database, 395
spell - check spelling, 396
tbl - table formatter, 433
troff - typeset documents, 460
-vfontinfo - examine font files, 485
vtroff - format document for raster printer, 495
vwidth - make font width table, 496
domainname - set/display domain name, 128
done shell command - sh, 378
dot mail environment variable, 257
dp mail command, 253
draw graph, 191
dt mail command, 253
du -display disk usage, 129
dump - dump file system, 583
dump frame buffer image - screendump, 366

-735-

Index - Continued

erase, continued
file - rm, 344
erase magnetic tape - mt, 277
error - analyze error messages, 148
esac shell command - sh,378
escape character, quotes and comments - C-Shell, 76
escape mail environment variable, 257
etherd - Ethernet statistics server daemon, 588
etherfind - find packets on the Ethernet, 589
Ethernet
find packets - etherf indo 589
statistics server daemon - etherd, 588
eval
shell command - csb, 83
shell command - sh, 382
evaluate expressions, 153
ex -line editor, 150
exec
shell command - csb, 83
shell command - sh,382
execute commands at specified times - cron, 576
executing commands - in C-Shell, 81
exi t shell command - sh,382
exi t mail command, 253
exi t - exit shell- csb, 83
expand - expand tabs, 152
export shell command - sh, 382
expr - evaluate expressions, 153
expression evaluation, 153
expressions - in C-Shell, 80
extend bibliography - addbib, 6
extract strings from C code - xstr, 513
eyacc - compiler generator, 155

dumpf s - dump file system information, 585

E
echo - C-Shell variable. 87
echo - echo arguments, 130, 382
echo mail command, 253
echo - echo arguments - csh. 83
ed -line editor, 131. 138
edit
fonts- fontedit, 168
icons - i conedi t. 202
password file - vipw, 715
SunView defaults - defaultsedit,114
user quotas - edquota, 586
edit -line editor, 150
edi t mail command, 253
editing text
ed -line editor, 131
ed -line editor, System V, 138
edi t -line editor, 150
ex -line editor, 150
sed - stream editor, 371
EDITOR mail environment variable, 257
edquota - edit user quotas, 586
EEPROM display and load program - eeprom, 587
egrep - pattern scanner, 193
el if shell command - sh, 378
eliminate tifdef's fromC input- unifdef,472
eliminate .so's from moff input - soelim, 391
el se shell command - sh,378
else mail command, 254
else - alternative commands - csh, 84
emulate Tektronix 4014 - tektool, 436
enable print queue - Ipc, 617
encode binary file - uuencode, 479
encode files
crypt", 73
des - Data Encryption Standard, 119
encrypted mail
enroll for - enroll, 512
receive - enroll, 512
send - xsend, 512
encryption key, generate - makekey,624
end - end loop - csb, 83
endif mail command, 254
endi f - end conditional- csh, 84
endsw - end switch - csh, 86
enro 11 - enroll for secret mail, 512
env - obtain or alter environment variables, 145
environment
display variables - printenv, 312
t set - set terminal characteristics for, 463
environment variables - in C-Shell, 87
environment variables in mail, see also mail environment variables
eqn - remove constructs - deroff, 118
eqn - mathematical typesetting, 146
eqnchar - special characters for equations, 537

F
f77 -FORTRAN compiler, 156
fastboot - reboot system, 591
fasthalt - halt system, 591
fg - job to foreground - csh, 83
fgrep - pattern scanner, 193
f i shell command - sh, 378
fifo, make - mknod, 628
fignore -C-SheU variable, 87
file
browse through text- more, 274
browse through text- page, 274
browse through text- pg, 301
change name of - mv, 278
change ownership - ehown, 565
copy from remote machine - rep, 335
count lines, words, characters in - we, 500
delete - rm, 344
display last part of - tail,427
dump - od, 286
find lines in sorted - look, 232
identify version - what, 501
make link to - In, 228
move - mv, 278
print - Ipr, 237
remove - rm, 344

erase

directory -

rmdir,344
-736-

Index - Continued

file, continu.ed
rename - mv, 278
reverse lines in - rev, 341
send to remote host- uusend,480
split into pieces - split, 398
sum - sum and count blocks in file, 409
update last modified date of - touch, 456
file - get file type, 160
file inquries - in C-Shell, 80
f i Ie mail command, 253
file system
cd - change directory, 39
check and repair - fsck, 594
check consistency - icheck, 605
check directory - dcheck, 577
create new - newf s, 645
demount - umount, 634
display disk usage and limits - quota, 330
display free space, 121
dump information - dumpf s, 585
edquota - edit user quotas, 586
free space display, 121
hierarchy - hier, 538
make- mkfs, 627
make prototype- mkproto, 629
mount - mount, 634
quotacheck - check quota consistency, 657
quotaoff - tum file system quotas off, 658
quotaon - tum file system quotas on, 658
repquota - summarize quotas, 664
rquotad - remote quota server, 679
summarize ownership - quot, 656
tune - tunefs, 712
unmount- umount,634
where am 1- pwd, 325
file system dump - dump, 583
file system restore - restore, 665
file transfer protocol
ftp command, 174
server - ft pd, 597
filec-C-Shell variable, 87
filename completion - C-Shell, 75
filename SUbstitution, 79
files
c spli t - split file into sections, 91
basename - strip affixes, 25
cat -concatenate, 33
cca t - compress files, 63
chmod - change mode, 46
cmp - compare files, 57
col rm - remove columns from, 60
corom - find commonality, 62
compare, 57
compare, three-way differential- diff3, 124
compress -compress files, 63, 64
convert and copy, 112
copy, 66
copy standard output to many - tee, 435
cp - copy files, 66
cpio - copy archives, 67
crypt - encrypUdecrypt, 73
. cshrc and the C-Shell, 74
cut - remove columns from, 99

files, continu.ed
des - encrypUdecrypt, data encryption standard, 119
determine type of, 160
differential compare, 122
display first lines of, 198
display names - Is, 241
find, 161
find differences, 122
• login and the C-Shell, 74
. logout and the C-Shell, 74
pack - pack files, 289
paste - horizontal merge, 293
pca t - pack files, 289
prepare files for printing - pr, 309
search for patterns in - grep, 193
side-by-side compare, 370
sort - sort or merge files, 392
split FORTRAN file- fsplit, 173
transfer, 174
uncompres s - uncompress files, 63, 64
unpack - unpack files, 289
z ca t - compress files, 64
files used by programs
• nf snnn - pointer to open-but-unlinked NFS file, 646
/bin/mail -local mail delivery, 692
/boot - standalone boot program, 563
/etc/dumpdates- dump record, 584
/etc/ethers - hostethernet map, 641
/ et c / f stab - table of filesystems to mount at boot, 635
/etc/gateways -list of distant routing gateways, 677
/etc/group-group, 559
/ et c /ho st s . equi v -list of trusted clients, 620
/etc/hosts -hostlD map, 641
/ etc/mtab - table of mounted file systems, 635
/etc/named.nnn-name server process ID, 639
/ et c / named. boot - name server configuration file, 639
/ et c / named. run - name server debug output, 639
/etc/nd.local- nd command file, 641
/etc/nologin -disallow 10gins, 695
/ etc/passwd - password file, 559
/ et c / rc • boot - boot script, 660
/etc/rc .local- boot script, 660
/ et c / rc - boot script, 660
/ et c / rmtab -list of hosts with local filesystems mounted,
695
/ et c / rpc - names for RPC programs, 678
/ etc/ servers -list of Internet server processes, 608
/ etc/ statmon - network status monitor files, 699
/ et c / sy slog. nnn - system log process ID, 705
/etc/syslog. conf - system log configuration file, 705
/ etc/utmp - record of current logins, 568
/ etc/yp/tiomain/ypservers -list of Yellow Pages
servers for a yP domain, 722
/ et c/ yp /Makef il e - makefile for Yellow Pages, 720
/ etc/yp/ypxfr .log - Yellow Pages transfer log, 727
/kadb - kadb standalone program, 613
/ setup. info - setup information, 693
/ sys/ conf - configuration files directory, 573
/tmp/ rstdir* - file containing directories on dump tape,
667
/tmp/rstmod* -owner, mode, and timestamps on dump
tape, 667
/tptpboot - directory of alternate boot programs, 563
/usr / adm/?_sum - printer accounting summaries, 648
-737-

Index - Continued

files used by programs, continued
/usr/adm/?acct -printer accounting files, 648
/usr/adm/acct -process accounting file, 688
/usr/adm/cronlog- cron log, 576
/usr/adm/diaglog- fparel diagnostics, 592
/usr/ adm/messages - system diagnostics log, 582
/usr/adm/msgbuf - system diagnostic scratch file, 582
/usr/ adm/ savacct - process accounting summary file
by command, 688
/usr / adm/ shutdownlog - shutdown log, 689
/usr/ adm/usracct - process accounting summary file
by user ID, 688
/usr/adm/wtmp-login accounting, 555
/usr/bin/uux-deliver uucp mail, 692
/usr/etc/yp/ypserv .log- Yellow Pages log file,
724
/usr/lib/adb-adb scripts directory, 557
/usr/lib/aliases* - mail aliases, 692
/usr / lib/ crontab - table of timed events, 576
/usr/lib/mailhosts -mail hosts, 692
/usr/lib/makewhatis - script to make whatis
database, 564
/usr/ lib/ sendmail. cf - sendmail configuration,
692
/usr/lib/sendmail.fc-fioun sendmail
configuration, 692
/usr/ lib/ sendmail. hf - help file for SMPT commands,626
/usr/ lib/ sendmail. st - sendmail statistics file,
621
/usr/ lib/uucp - uucp utilities directory, 714
/usr/man/ cat? - nroff'ed manual pages, 564
/usr/man/fmt? - troff'ed manual pages, 564
/usr/man/man? - manual page sources, 564
/usr/man/whatis - whatis database, 564
/ us r / man - manual pages directory, 564
/usr/mdec/installboot - script to install boot
blocks,563
/usr/ spool/mqueue - temporary files and mail queue,
692
/usr/ spool- spool directory, 618
/vrnunix - UNIX kernel, 560
quotas - quotas file at filesystemroot, 657
restoresymtable - restore incremental state file,
667
filter reverse paper motions - col, 58
find
find lines in sorted file - look, 232
find literature references - refer, 340
find object file size - size, 389
find ordering for object library - lorder, 234
patterns in file - grep, 193
find printable strings in binary file- strings, 399
program - whereis, 503
find - find files, 161
finger - info on users, 164
flight - graphics processor demo, 528
floating-point
reliability tests - fparel, 592
version and tests - fpaversion, 593
flush disk activity - sync, 425
fmt - simple formatter, 166
fold - fold long lines, 167

folder mail command, 253
folder mail environment variable, 257
folders mail command, 253
followup mail command, 253
Followup mail command, 253
font
files, convert foreign - vswap, 494
vwidth - make font width table, 496
fontedi t - font editor, 168
for shell command- sh,378
foreach -loop on list of names - csh, 83
format e programs - indent, 205
format document for raster printer - vtroff,495
format tables - tbl,433
FORTRAN
f77 - FORTRAN compiler, 156
print file - fpr, 171
rat for - rational FORTRAN, 334
splitfile- fsplit,173
tags file - ctags, 93
• forward file, 256
forwarding mail, 256
fpa rel - floating-point reliability tests, 592
fpaversion - floating-point version and tests, 593
fpr - print FORTRAN file, 171
framedemo - graphics demo, 529
from - who is mail from, 172
f rom mail command, 253
f sck - check and repair file system, 594
f sirand - install random inode generation numbers, 596
f spli t - split FORTRAN file, 173
ftp-file transfer, 174
ft pd - file transfer protocol server, 597
functions in Bourne Shell, 378

G
games
boggletool-SunView game of boggle, 522
canfield - solitaire card game, 523
che s s - chess game, 524
chesstool- SunView chess game, 525
gammontool- SunView backgammon game, 526
introduction, 521
life - SunView game of life, 532
gammontool- SunView backgammon game, 526
gco re - core image of process, 179
generate
adb script - adbgen, 556
encryption key - makekey, 624
lexical analyzer - 1 ex, 222
Pascal execution profile - pxp, 327
permuted index - ptx, 324
get
magnetic tape unit status - mt, 277
terminal name - tty, 468
get - get sees file, 180
get terminal options - stty, 401
get_selection - copy a SunView selection to standard output, 185
get opt - process options in scripts, 186

-738-

Index - Continued

gettable - get NIC host tables, 599
get t y - set terminal mode, 600
gfxtool- SunWindows graphics tool, 187
glob - filename expand wordlist- csh, 83
goban - go board graphics demo, 529
goto - command transfer - csh, 83
GP, initialize graphics processor - gpconf ig, 601
gpconfig - bind cgtwo frame buffers to GP, 601
gprof - call-graph profile, 188
graph - draw graph, 191
graphics
spline - interpolate smooth curve, 397
vplot - plot on Versatec, 491
graphics board diagnostics - gxtest, 602
graphics filters - plot, 307
graphics tool- gfxtool, 187
grep - pattern scanner, 193
group mail command, 252
group, display user and group IDs - id, 204
grouping commands in the C-Shell, 76
groups - display group membership, 197
grpck - check groups, 655
gxte st - graphics board diagnostics, 602

iconedi t - edit icons, 202
id - display user and group IDs, 204
identify file version - what, 501
if shell command - sh, 378
if mail command, 254
if -conditional statement- csh,83
ifconfig - configure network interface parameters, 606
IFS shell variable- sh,379
ignore mail command, 253
ignore mail environment variable, 257
ignoreeof - C-Shell variable, 87
ignoreeof mail environment variable, 257
imemtest -memory diagnostic, 607
in shell command - sh, 378
incremental file system dump - dump, 583
incremental file system restore - restore, 665
indent -formatC source, 205
indexing, generate permuted index - ptx, 324
indxbib - make inverted index, 209
inetd - internet services daemon, 608
information
miscellaneous, 535
non-, miscellaneous, 535
inhibit messages - mesg, 271
ini t - process control initialization, 609
initialize/diagnose disk - diag, 578
input_from_defaults - update kernel from defaults database, 210
insert literature references - refer, 340
install- install files, 211
install yellow pages database - ypini t, 718
Internet
directory service - whoi s, 507
file transfer protocol server - ft pd, 597
interpolate smooth curve - spline, 397
interpret(old) troff output- pti,323
interpret Pascal- px, 326
interprocess communication
ipcrm, 212
ipcs,213
introduction
commands, I
games and demos, 521
miscellaneous information, 535
miscellaneous noninformation, 535
system maintenance and operation, 551
i 0 sta t - report 110 statistics, 611
ipcrm - remove interprocess communication identifiers, 212
iipcs - display interprocess communication status, 213

H
halt - stop processor, 603
halt system - fasthalt, 591
hard link, make - In, 228
hardpaths - C-Shell variable, 87
hash shell command- sh,382
hashstat -display hashing statistics - csh,83
head - display head of file, 198
header mail environment variable, 257
header s mail command, 253
help - getSCCS help, 199
help mail command, 253
hexadecimal dump file - od, 286
hier - file system hierarchy, 538
histchars - C-Shell variable, 87
history - C-Shell variable, 87
hi story - display history list - c sh, 83
history substitution - in C-Shell, 76
history substitution modifiers, 77
hold mail command, 253
hold mail environment variable, 257
home - C-Shell variable, 87
HOME mail environment variable, 256
HOME shell variable - sh, 379
ho st id - display host 10, 200
ho stname - display host name, 201
htable -convert NIC standard format host tables, 604

J
job control \m csh, 81
jobs - display job list - c sh, 84
join - relational database operator, 215
j umpdemo - graphics demo, 529

I
i-node, clear- clri,567
110 redirection in the C-Shell, 77
110 statistics report- iostat, 611
iAPX286 - machine type indication, 248
icheck - file system consistency check, 605

-739-

Index - Continued

K

locate program - wherei s, 503
lockd - network lock daemon, 616
lockscreen - save window context, 229
login
change password - pa sswd, 292
display effective user name - whoami, 506
display login name - logname,231
display user and group IDs - id, 204
info on users - finger, 164
list last - last, 217
make script of session - script, 369
ruser s - who is on local network, 356
rwho - who is on local network, 358
save window context- lockscreen, 229
to local machine - login, 230
to remote machine - rlogin, 342
what are users doing - w, 497
who - who is logged in, 505
login accounting, display login record - ac, 555
login shell command - sh, 382
login environment
display variables - printenv, 312
t set - set terminal characteristics, 463
tty - get terminal name, 468
• login file, 74
login password
change password - passwd, 292
change in yellow pages - yppasswd, 518
login -login new user - csh, 84
logname -display login name, 231
. logout file, 74
logout - end session - csh, 84
look - find lines in a sorted file, 232
look for pattern in file - grep, 193
lookbib -find bibliographic references, 233
loop - C-SheU control flow, 81
lorder - find ordering for object library, 234
lpc -line printer control, 617
I pd -line printer daemon, 619
I pq - display printer queue, 235
lpr - print files, 237
lprm - remove print jobs, 239
I s -list files, 241

kadb - kernel debugger, 612
keep mail environment variable, 257
keepsavemail environment variable, 257
keyboard click, control with - eli ck, 52
kgmon - dump profile buffers, 614
kill- terminate process, 216
kill-killjobs and processes - csh,84

L
languages
cb - format filter for C sources, 34
cc - C compiler, 35
tcflow - code flow graph, 42
cpp - C preprocessor, 69
cxref - cross reference C program, 100
f77 -FORTRAN compiler, 156
indent - format C source, 205
lex - generate lexical analyzer, 222
lint - C program verifier, 225
mkstr - create C error messages, 273
pc - Pascal compiler, 294, 304
pix - Pascal translator and interpreter, 306
pmerge - merge Pascal files, 308
px - interpret Pascal, 326
pxp - generate Pascal execution profile, 327
pxref - cross reference Pascal program, 329
rat for - rational FORTRAN, 334
t COy - code coverage tool, 434
xstr - extract strings from C code, 513
la st -list last logins, 217
lastcomrn - display last commands, 218
ld - link editor, 219
leave - remind you of leaving time, 221
lex - generate lexical analyzer, 222
LEX language tags file - ctags, 93
lexical analysis - C-Shell, 76
library
find ordering for object- lorder, 234
make random- ranlib,33l
library management
ar -library maintenance, 12
Ii fe - SunView game of life, 532
limi t - alter resource limitations - csh,84
limits
disk space - quota, 330
line -read one line, 224
line numbering - nl, 280
line printer control- lpc, 617 thru 618
line printer daemon - lpd, 619
lines
count- wc,500
find, in sorted file - look, 232
link -make a link, 615
link editor - ld, 219
lint - C program verifier, 225
list mail command, 254
LI STER mail environment variable, 257
literature references, find and insert- refer, 340
load frame buffer image - screen load, 367

M
m4 - macro processor, 244
m6 8k - machine type truth value, 248
mach - display Sun processor, 247
macro processor - m4, 244
magnetic tape
backspace files - mt, 277
backspace records - mt, 277
erase - mt,277
forward space files - mt, 277
forward space records - mt, 277
get unit status - mt, 277
manipulate - mt, 277
place unit off-line - mt, 277
retension - mt, 277
rewind - mt,277
skip backward files - mt, 277
-740-

Index - Continued

magnetic tape, continued
skip backward records - mt, 277
skip forward files - mt, 277
skip forward reconis - mt, 277
write BOF mark on - mt,277
magnify raster image - rastrepl, 333
mail - C-Shell variable, 87
emoll for secret - enroll, 512
print waiting - prmail,313
receive secret mail- enroll, 512
send secret mail- xsend, 512
mail - send and receive mail, 249 thrw 258
mail commands, 252 thrw 256
!,252
",252
=,252
1,252
1,254
alias, 252
alternates, 252
cd, 252
chdir,252
copy, 252
Copy, 252
delete, 253
discard, 253
dp,253
dt,253
echo, 253
edit, 253
else, 254
endif,254
exit, 253
file, 253
folder, 253
folders, 253
followup, 253
Followup, 253
from, 253
group, 252
headers, 253
help, 253
hold, 253
if, 254
ignore, 253
list, 254
mail, 254
mbox,254
new, 254
next, 254
pipe, 254
preserve, 253
print, 254
Print, 254
quit, 254
reply, 254
Reply, 255
Replyall,255
reply sender, 254
respond, 254
Respond, 255
save, 255
Save, 255

mail commands, continued
set, 255
shell, 255
size, 255
source, 255
top, 255
touch, 255
type, 254
Type, 254
undelete, 255
unread, 254
unset, 256
version, 256
visual, 256
write, 256
xit,253
z,256
mail delivery server - sendmail, 690
mail, forwarding messages, 256
mail mail command, 254
mail services
biff - mail notifier, 28
binmail-version 7 mail, 29
who is mail from - from, 172
mail tilde escapes, 250 thrll251
-! ,250
,250
-- ,250
-< ,251
-1 ,250
,250
-I ,251
-A ,250
-b ,251
-c ,251
-d ,251
-e ,251
-f ,251
-h ,251
-i ,251
-m ,251
-p ,251
-q ,251
-r ,251
-s ,251
- t ,251
-v ,251
-w ,251
-x ,251
mail utilities
comsat - biff server, 568
create aliases database - newaliases,644
statistics - mailstats,621
MAIL shell variable sh,379
mail variables, 256 thrw 258
allnet,256
alwaysignore.256
append, 256
askcc,256
asksub,256
autoprint, 256
bang, 256
cmd,257

-741-

Index -

Continued

mail variables, continued
conv,257
crt, 257
DEAD, 257
debug, 257
dot, 257
EDITOR, 257
escape, 257
folder, 257
header, 257
hold, 257
HOME, 256
ignore, 257
ignoreeof, 257
keep, 257
keeps ave, 257
LISTER, 257
MAILRC,256
MBox,257
metoo,257
no, 257
onehop, 257
outfolder,257
page, 257
PAGER, 258
prompt,258
quiet,258
record, 258
replyall, 258
save, 258
sendmail,258
sendwai t, 258
SHELL, 258
showto, 258
sign, 258
toplines,258
verbose, 258
VISUAL, 258
MAILCHECK shell variable - sh, 379
MAILPATH shell variable - sh,379
MAILRC mail environment variable, 256
mail stat s - mail delivery statistics, 621
mail tool - SunView mail interface, 259
maintain programs - make, 2621NU 268
maintenance and operation, 551
make
delta, secs - delta, 116
directory - mkdir, 272
fifo - mknod, 628
file system- mkfs, 627
hard link to file - In, 228
named pipe - mknod, 628
new file system - newf s, 645
sces delta - delta, 116
special file - mknod, 628
symbolic link: to file - In, 228
system log entry - syslog,426
system special files - makedev,623
make - build programs, 262 Ihru 268
makedbm - make yellow pages dbm file, 622
makedev - make system special files, 623
makekey - generate encryption key, 624
man - online display of reference pages, 269

-man - macros to format manual pages, 542
manipulate magnetic tape - mt, 277
manual pages
create cat files for- catman,564
describe command - whatis, 502
maze - graphics demo, 529
mbox mail command, 254
MBOX mail environment variable, 257
mc68881 version - display MC68881 version, 625
mconnect - open connection to remote mail server, 626
-me - macro package, 544
memory diagnostic - imemtest, 607
memory diagnostics - sysdiag, 703
merge or sort files - sort, 392
merge files- paste, 293
merge Pascal files - pmerge, 308
mesg - permit or deny messages, 271
messages
permit or deny - mesg,271
metacharacters - C-Shell, 76
metoo mail environment variable, 257
miscellaneous information, 535
miscellaneous noninformation, 535
mkdir - make directory, 272
mkf s - make file system, 627
mknod - make special file, 628
mkproto - make prototype file system, 629
mkstr - create e error messages, 273
modes, change permission - chmod, 46
monitor program, 630
more - browse text file, 274
mount - mount file system, 634
mount file system - mount, 634
mountd - NFS mount server, 637
move directory - mv, 278
move file - mv, 278
move print jobs - lpc, 617
-ms - macro package, 546
mt - manipulate magnetic tape, 277
multiple columns, print in - pr, 309
mv - move or rename files or directory, 278

N
named - internet domain name server daemon, 638
named pipe, make - mknod, 628
ncheck - convert i-numbers to filenames, 640
nd - network disk control, 641
neqn - mathematical typesetting, 146
net stat - display networlc status, 642
network
copy files across - rcp, 335
rusers - who is logged in on local network, 356
rwall - write to all users, 357
rwho - who is logged in on local network, 358
network debugging - ping, 649
network disk control- nd, 641
network file system
biod daemon, 646
nf sd daemon, 646
-742-

Index - Continued

p

network interface parameters, configure - ifconfig,606
network routing daemon - routed, 676
network rwall server - rwalld, 684
network status, display - netstat, 642
new mail command, 254
newaliases - make mail aliases database, 644
newfs - make new file system, 645
next mail command, 254
NFS mount server - mountd, 637
NFS statistics, display- nfsstat, 647
nfsd daemon, 646
nfsstat - display network statistics, 647
NIC host tables, get from host- gettable, 599
nice - change priority of command, 279
nice - run low priority process - csh, 84
nl - number lines, 280
nm - display name list, 282
no mail environment variable, 257
nobeep - C-Shell variable, 88
noclobber - C-Shell variable, 88
noglob - C-Shell variable, 88
nohup - run command immune to hangup, 283
nohup - run command immune to hangups - csh, 84
noninformation miscellaneous, 535
information miscellaneous, 535
nonomatch - C-Shell variable, 88
notify - C-Shell variable, 88
not i fy - request immediate notification - c sh, 85
nroff - document formatter, 284
nroff utilities
checknr - check nroff/troff files, 44
col - filter reverse paper motions, 58
col crt - filter nroff output for CRT, 59
nroff utilities, 118
soelim- eliminate . so's, incorporate sourced-in files,
391

pac - printer/plotter accounting, 648
pack - pack files, 289
page - browse text file, 274
page mail environment variable, 257
page size, display - pagesize, 291
PAGER mail environment variable, 258
pagesize - display page size, 291
paging devices, specify - swapon, 701
parentheses - C-Shell command grouping, 76
parser generator - yacc, 514
Pascal compiler - pc, 294
Pascal interpreter code translator - pc, 304
Pascal language
pmerge - merge Pascal files, 308
px - interpret Pascal, 326
pxp - generate Pascal execution profile, 327
pxref - cross reference Pascal program, 329
tags file - ctags, 93
pas swd - change login password, 292
password
change in yellow pages - yppasswd, 518
change login - passwd, 292
password file
edit- vipw, 715
paste - horizontal merge, 293
path - C-Shell variable, 88
PATH shell variable sh,379
patterns, search in file for- grep, 193
pc - Pascal compiler, 294
pea t - pack files, 289
pdpll- machine type truth value, 248
perfmeter - display performance statistics, 298
perfmon - display performance statistics, 300
performance monitoring - perfmeter, 298, 300
display call-graph profile data - gprof, 188
prof - display program profile, 314
pxp - generate Pascal execution profile, 327
time - time command, 450
peripheral diagnostics - sysdiag, 703
permissions, change mode - chmod, 46
permit messages - mesg, 271
permuted index, generate - ptx, 324
pg - browse text file, 301
pi - Pascal interpreter code translator, 304
ping - debug network, 649
pipe mail command, 254
pipeline - C-Shell, 76
pix - Pascal translator and interpreter, 306
place magnetic tape unit off-line - mt, 277
plot - graphics filters, 307
plot on Versatec - vplot, 491
pmerge - merge Pascal files, 308
popd - pop shell directory stack - csh, 85
portmap - DARPA to RPC mapper, 650
postmortem crash analyzer - analyze, 560
pr - prepare files for printing, 309
predefined variables, in C-Shell, 87
prepare files for printing - pr,309

o
object code management
ar -library maintenance, 12
ranlib - make random library, 331
object file
find printable strings in - strings, 399
size - find object file size, 389
strip - strip symbols and relocation bits, 400
object library
find ordering for- lorder, 234
octal dump file - od, 286
od - dump file, 286
on - remote command execution, 288
onehop mail environment variable, 257
onintr - handle interrupts in scripts - csh,85
online reference - man, 269
operators - in C-Shell, 80
outfolder mail environment variable, 257
overview - take over screen w/ graphics, 289
owner of file, change - chown, 565

-743-

Index - Continued

preserve mail command, 253
pretty printer
indent - format e source, 205
vgrind- make formatted listings, 486
colcrt command, 59
print
FORTRAN file- fpr, 171
print waiting mail- prmail,313
values from yP database - ypcat, 516
working directory name - pwd, 325
print bibliographic database - roffbib.346
print files
lpr -print files, 237
pr int mail command, 254
Print mail command, 254
printenv -display environnment, 312
printer
abort- lpc, 617
clean queue- lpc, 617
control- lpc, 617
daemon - lpd, 619
disable queue - lpc, 617
lpq - display queue, 235
enable queue - lpc, 617
move jobs - lpc, 618
remove jobs from queue - lprm, 239
restart - 1 pc, 617
start- lpc, 617
status of - lpc, 617
stop- lpc,617
printer/plotter accounting, 648
prmail - print waiting mail, 313
process
change priority - renice, 663
display status - ps, 320
get core image of, 179
terminate - kill,216
wai t - wait process completion. 498
prof - display program profile, 314
profile
display call-graph - gprof, 188
profiling
prof - display program profile, 314
pxp - generate Pascal execution profile, 327
programming languages
analyze and disperse compiler error messages, 148
assembler, 15
cc - e compiler, 35
cpp - e preprocessor, 69
cxref - cross reference e program. 100
f77 -FORTRAN compiler, 156
lex - generate lexical analyzer, 222
lint - C program verifier, 225
pc - Pascal compiler, 294, 304
pix - Pascal translator and interpreter, 306
pme rge - merge Pascal files, 308
print FORTRAN file- fpr, 171
px - interpret Pascal. 326
pxp - generate Pascal execution profile, 327
pxref - cross reference Pascal program, 329
split FORTRAN file- fsplit, 173
vgrind - make formatted listings, 486

programming languages, continued
xstr - extract strings from e code, 513
programming tools
adb - debug tool, 2
be - calculator language, 26
cflow - code flow graph, 42
compiler generator, 155
ctags - create tags file, 93
ctrace - display program trace, 95
dbx - source debugger, 103
dbxtool-debugger,l09
display call-graph profile data - gprof, 188
indent - format C source, 205
install-install files, 211
ld -link editor, 219
lex - generate lexical analyzer, 222
lint - e program verifier, 225
lorder - find ordering for object library, 234
m4 - macro processor, 244
maintain object libraries, 12
make - build programs, 262 thru 268
mkstr - create e error messages, 273
nm-display name list, 282
prof - display program profile, 314
ran lib - make random library, 331
rat for - rational FORTRAN, 334
sec s - source code control system, 360
size - find object file size, 389
strings - find printable strings in binary file, 399
strip - strip symbols and relocation bits, 400
t cov - code coverage tool, 434
time - time command, 450
touch - update last modified date of file, 456
unifdef - eliminate t ifdef's from e input, 472
yacc - parser generator, 514
programs, introduction, 1
PROM monitor program. 630
PROM monitor program. display and load program - eeprorn,
587
prompt - e-Shell variable, 88
prompt mail environment variable, 258
provide truth values - true, 462
prs - display sees history, 315
prt - display sees history, 318
ps - display process status, 320
PSI shell variable - sh, 379
PS2 shell variable - sh,379
pstat - display system statistics, 651
pt i - (old) t ro f f interpreter, 323
ptx - generate permuted index, 324
pu shd - push shell directory stack - c sh, 85
pwck - check passwords, 655
pwd - print working directory name, 325, 382
px - interpret Pascal, 326
pxp - generate Pascal execution profile, 327
pxref - cross reference Pascal program. 329

Q
queue
atq - display delayed execution, 19
lpq - display printer, 235

-744-

Index - Continued

queue, continued
remove jobs from delayed execution - atrrn, 20
remove jobs from printer- lprrn, 239
quick substitution - in C-Shell, 77
quiet mail environment variable, 258
qui t mail command, 254
quot - summarize file system ownership, 656
quota - display disk usage and limits, 330
quotacheck - check quota consistency, 657
quotaoff - tum file system quotas off, 658
quotaon - tum file system quotas on, 658
quotas
edquota - edit user quotas, 586
quota check - check quota consistency, 657
quotaoff - tum file system quotas off, 658
quotaon - tum file system quotas on, 658
repquota - summarize quotas, 664
rquotad - remote quota server, 679

R
ranI ib - make random library, 331
rarpd - reverse Address Resolution Protocol daemon, 659
rasfil ter8tol- convert 8-bitrasterfile to I-bit rasterfile,
332
ra st repl - magnify raster image, 333
ratfor -rational FORTRAN, 334
rc - startup commands, 660
rep - remote file copy, 335
rdate - remote date, 661
rdi s t - remote file distribution, 336
read shell command - sh, 383
read mail- mail, 249 thru 258
readonly shell command - sh, 383
reboot - system startup procedures, 662
reboot system- fastboot, 591
rebuild yellow pages database - ypmake, 719
receive secret mail- enroll,512
record mail environment variable, 258
refer - insert literature references, 340
regenerate programs - make, 262 thru 268
rehash - recompute command hash table - csh, 85
join, 215
relational database operator reminder services
bif f - mail notifier, 28
calendar -reminder service, 32
leave - remind you of leaving time, 221
remote command execution - on, 288
remote execution server - rexecd, 670
remote file copy - rep, 335
remote host
send file to - uusend, 480
remote login
rlogin, 342
server - rlogind, 672
remote magtape protocol server - rmt, 674
remote procedure call services
rquotad - remote quota server, 679
sprayd- spray server, 698
remote shell- rsh, 352
remote shell server - rshd, 680

remote system
connect to - cu,451
connect to - tip, 451
remove
columns from file, 60, 99
delayed execution jobs - atrrn, 20
remove delta from secs file - rmdel, 345
directory- rmdir,344
file - rrn, 344
filename affixes - basename,25
nroff, troff, tbl and eqn constructs - deroff,
118
print jobs - lprrn, 239
repeated lines - un iq, 473
rename directory - mv, 278
rename file - rnv,278
renice - change process priority, 663
repeat - execute command repeatedly - csh, 85
reply mail command, 254
Reply mail command, 255
replyall mail environment variable, 258
Replyall mail command, 255
reply sender mail command, 254
report file system quotas - repquota, 664
repquota - summarize quotas, 664
reset - reset terminal bits, 463
reset terminal bits - reset, 463
respond mail command, 254
Respond mail command, 255
restart printer - lpc, 617
restore -restore file system, 665
restore file system- restore, 665
restore frame buffer image - screenload, 367
retension magnetic tape - mt,277
ret urn shell command - sh, 383
rev - reverse lines in file, 341
reverse lines in file - rev, 341
rewind magnetic tape - mt, 277
rexd - remote execution daemon, 669
rexecd - remote execution server, 670
rlogin -remote login, 342
rlogind-remote login server, 672
rm - remove file or directory, 344
rma i 1 - process remote mail, 673
rmdel - remove delta from SCCS file, 345
rmdi r - remove directory, 344
rmt - remote magtape protocol server, 674
roffbib -print bibliographic database, 346
root directory, change for a command - chroot, 566
rotobj - graphics processor demo, 528
route - manipulate routing tables, 675
routed - network routing daemon, 676
RPC
generate protocols - rpcgen, 347
report RPC information - rpcinf 0, 678
rpcgen - generate RPC protocol, C header files, and server
skeleton, 347
rpc in f 0 - report RPC information, 678
rquotad-remote quota server, 679

-745-

Index - Continued

rsh -remote shell, 352
rshd - remote shell server, 680
rstatd - kernel statistics server, 682,683
rup - display status of network hosts, 354
rupt ime - display status of local hosts, 355
rusers - who is logged in on local network, 356
rwalld - network rwall server, 684
rwho - who is logged in on local network, 358
rwhod - system. status server, 685

S
sa - process accounting summary, 687
save mail command, 255
sa vemail environment variable, 258
savecore - save OS core dump, 689
savehist -C-Shel1 variable, 88
sccs - source code control system, 360
sees commands
admin - administer SCCS, 9
cdc - change delta commentary, 40
comb - combine deltas, 61
get -getseCS file, 180
help - get SCCS help, 199
cdc -display sees history, .315
prt -display sces history, 318
rmdel - remove delta, 345
sact - display secs file editing status, 359
sccsdiff -compare versions of SCCS file, 364
unget - unget SCCS file, 471
val-validate secs file, 484
sces delta
change commentary, 40
combine, 61
create - delta, 116
remove- rmdel, 345
sccsdi ff - compare versions of sces file, 364
screen fonts, edit- font edit, 168
screen-oriented editor - vi, 488
screenblank - turn of idle screen, 365
screendump - dump frame buffer image, 366
screenload-restore frame buffer image, 367
script - make script of terminal session, 369
sdiff - side-by-side compare, 370
search for files, 161
search forpattem in file - grep, 193
secret mail
enroll for - enroll, 512
receive - enroll,512
send- xsend, 512
sed - stream editor, 371
selection, copy to standard output - get_selection, 185
send
file to remote host- uusend, 480
secret mail- xsend, 512
signal to process - kill, 216
send and receive mail- mai 1, 249 thru 258
sendmail - mail delivery system, 690
sendmail mail environment variable, 258
sendwait mail environment variable, 258
servers

servers, continued
comsat - biff server, 568
ft pd - Internet File Transfer Protocol, 597
inetd - internet services daemon, 608
lockd - network lock daemon, 616
mountd - mount request server, 637
named - internet domain name server daemon, 638
rexecd - remote execution server, 670
r logind - remote login server, 672
rshd-remote shell server, 680
rstatd-kemel statistics server, 682,683
rwalld-networkrwall server, 684
rwhod - system status server, 685
statd - network status monitor, 699
talkd - talk program server, 706
telnetd - TELNET protocol server, 707
t ft pd - Trivial File Transfer Protocol server, 708
timed - DARPA Time server, 709
tnamed - DARPA Trivial name server, 710
yppas swdd - yellow pages password server, 720
set
current domain name - domainname, 128
current host name, 201
name of current host, 201
terminal characteristics - tset, 463
set shell command - sh, 383
set mail command, 255
set - change value of shell variable - c sh, 85
set terminal options - stty, 401
setenv - set or display variables in environment - csh, 85
setkeys - change keyboard layout, 374
setup - Sun UNIX installation program, 693
sh - Bourne Shell, 377 thru 384
shaded - graphics demo, 529
shell - C-Shell variable, 88
Bourne - sh, 377 thru 384
change login, 48
chsh - change shell, 48
comparison of csh and sh,74
csh-C-Shell, 74
remote - rsh, 352
Shell commands (Bourne Shell), 378, 382 thru 384, see also
BoUTTU! Shell commands
Shell functions (Bourne Shell), 378
shell mail command, 255
SHELL mail environment variable, 258
SHELL shell variable - sh, 379
Shell variables (Bourne Shell), 379
shell window
cmdtool,54
shell tool, 385
shell tool- shell terminal window, 385
shift shell command - sh, 383
shift - shift argument list- csh,85
show - graphics demo, 529
showmap - graphics demo, 529
showmount - display remote mounts, 694
showto mail environment variable, 258
shutdown - shut down multiuser operation, 695
sign mail environment variable, 258
log in - sign on, 230
-746-

Index - COn1inued

stop-halt job orprocess- csh, 86
stream editor - sed, 371
stringart - graphics demo, 529
strings - find printable strings in binary file, 399
strip - strip symbols and relocation bits, 400
strip filename affixes - basenarne, 25
s tty - get terminal options, 401
stty - set terminal options, 401
stty_frorn_defaults - set terminal from SunView defaults,
407
su - substitute user id, 408
substitute user id - su, 408
sum - sum and count blocks in file, 409
summarize file system quotas - repquota, 664
sun - machine type truth value, 248
sun3cvt - convert large Sun-2 executables to Sun-3, 410
suncube - graphics demo, 529
suntool s - Suntools window environment, 412
SunView
iconedit, 202
start up environment, 411
SunView environment, changing default settings defaultsedit,114
SunWindows, graphics too1- gfxtool,187
super-user command - su, 408
suspend execution - sleep, 390
suspend - suspend shell- csh, 86
swapon - specify paging device, 701
swapping devices, specify - swapon, 701
swin - set window input behavior, 420
switch - multi-way branch - csh, 86
switcher, 422
symbolic link, make - In, 228
syrnorder - update symbol table ordering, 424
sync - update super block, 425, 702
sysdiag - system diagnostics, 703
syslog - make system log entry, 426, 704
system administration
adduser - add new user account, 558
analyze - crash analyzer, 560
catman - create cat files for manual pages, 564
install - install files, 211
system configuration files, build - conf ig, 569
system EEPROM display and load program, 587
system maintenance and operation, 551
system PROM monitor program, 630
system special files - rnakedev, 623
system status server - rwhod, 685
System V commands
banner, 24
cat,33
cc,35
chrnod, 46
col,58
date, 101
diff3,124
dircmp, 127
du,129
echo, 130

login - sign on, continued
to remote machine - rlogin,342
sign-on last- last, 217
signal handling, in C-Shell, 81
size - find object file size, 389
size mail command, 255
skip backward magnetic tape files - rnt, 277
skip backward magnetic tape records - rnt, 277
skip forward magnetic tape files - mt, 277
skip forward magnetic tape records - rnt, 277
skyversion - display SKY version, 696
sleep - suspend execution, 390
smoothing, interpolate curve - spline, 397
soelim - eliminate .so's from nroff input, 391
sort bibliographic database - sortbib, 395
sort - sortor merge files, 392
sort or merge files - sort, 392
sort topologically - tsort, 467
sortbib - sort bibliographic database, 395
sorted file
find lines in - look,232
remove repeated lines - uniq, 473
source code control system - sees, 360
source mail command, 255
source - read commands from file - csh, 85
spaces, to tabs - un expand, 152
special characters for equations - eqnchar, 537
special file
make - mknod, 628
special files - rnakedev, 623
spell- check spelling, 396
spellin - check spelling, 396
spellout - check spelling, 396
spheresderno - graphics demo, 529
spline - interpolate smooth curve, 397
spli t - split file into pieces, 398
spray - spray packets, 697
sprayd - spray server, 698
stand-alone utilities
kadb - kernel debugger, 612
diag - initialize/diagnose disk, 578
gxtest - graphics board diagnostics, 602
irnerntest - memory diagnostic, 607
standard output
copy to many files - tee, 435
start printer - 1 pc, 617
startup procedures - boot, 562, 662
statd - network status monitor, 699
statistics
110 - iostat,611
rstatd-kemel statistics server, 682, 683
statistics ofNFS, display- nfsstat, 647
status - C-Shell variable, 88
status of network
display - netstat,642
status of printer - Ipc, 617
sticky - set sticky bit, 700
stop printer - lpc, 617
stop processor- halt, 603

-747-

Index - Continued

System V commands, continued
ed., 138
expr, 153
grep, 193
lint, 225
Is, 241
m4,244
nohup, 283
od., 286
pg,301
pr,309
sed, 371
sort, 392
stty,404
sum, 409
test, 439
tic,449
time,450
touch,456
tput, 457
tr,458
uname, 470

test shell command - sh, 383,439
text editing
ed-line editor, 131
ed -line editor, System V, 138
edit -line editor, 150
ex -line editor, 150
sed - stream editor, 371
vi - visual editor, 488
text file
browse through - pg, 301
text file, browse through
more, 274
page, 274
text processing utilities
awk - scan and process patterns, 21
cat - concatenate files, 33
reverse lines in file - rev, 341
search for patterns - grep, 193
sort - sort or merge files, 392
spell - check spelling, 396
split - split file into pieces, 398
t a i l - display last part of file, 427
t r - translate characters, 458
tsort - topological sort, 467
ul - underline text, 469
uniq - remove repeated lines, 473
textedit -SunView text editor, 441
tftp- trivial file transfer program, 447
tftpd - Trivial File Transfer Protocol server, 708
then shell command - sh,378
tic - System V terminal information compiler, 449
tilde escapes in mail, 250 thru 251, see also mail tilde escapes
time - C-Shell variable, 88
display date and, 101
display in window, 53
time - time command, 450
time-monitoracommand- csh, 86
timed - time server, 709
timed event services
at - do job at specified time, 17
calendar - reminder service, 32
leave -remind you of leaving time, 221
timed events - cron, 576
times shell command - sh,383
tip - connect to remote system, 451
tnamed-name server, 710
toolplaces - show current window info, 455
tools
mailtool,259
textedit,441
top mail command, 255
toplines mail environment variable, 258
topological sort- tsort, 467
touch - update last modified date of file, 456
touch mail command, 255
tput - System V terminal info database query, 457
t r - translate characters, 458
t ra f f ic - show Ethernet traffic, 459
translate and interpret Pascal programs - pc, 306
translate characters - tr,458
transliterate protocol trace - trpt, 711

T
tabs, expand to spaces - expand., 152
tail - display last part of file, 427
talk - talk to another user, 428
talkd - talk server, 706
tape
backspace files - mt, 277
backspace records - mt, 277
erase- mt,277
forward space files - mt, 277
forward space records - mt, 277
get unit status - mt, 277
manipulate magnetic - mt,277
place unit off-line - mt, 277
retension - mt, 277
rewind - mt, 277
skip backward files - mt,277
skip backward records - mt, 277
skip forward files - mt, 277
skip forward records - mt, 277
write EOF mark on - mt, 277
tape archiver - tar, 429
tape block size - 1024 bytes, 583
tar - tape archiver, 429
tbl-remove constructs - deroff,118
table formatter, 433
tcov - code coverage tool, 434
tee - copy standard output to many files, 435
tektool- emulate Tektronix 4014,436
Tektronix 4014, emulate - tektool,436
telnet - TELNET interface, 438
telnetd - TELNET protocol server, 707
terminal
get name of- tty, 468
get options - stty, 401
make script of session- script, 369
reset bits - re set, 463
set characteristics - t set, 463
set options - stty, 401

-748-

Index - Continued

trap shell command - sh, 383
trivial file transfer program - tft p, 447
troff - typeset documents, 460
troff utilities
checknr - check nroff/troff files, 44
col - filter reverse paper motions, 58
troff utilities, 118
soelim- eliminate . so's, incorporate sourced-in files,
391
trpt - transliterate protocol trace, 711
true -provide truth values, 462
tset - set terminal characteristics, 463
tsort - topological sort, 467
tty
st t y - set terminal options, 401
tty - get terminal name, 468
tty, set characteristics - tset, 463
tunefs - tune file system, 712
type shell command - sh,383
t ypemail command, 254
Type mail command, 254
typeset documents - t ro f f, 460

user
display effective name - logname, 231, 506
display user and group IDs - id, 204
talk to another- talk, 428
write to another- write, 508
user ID, substitute - su, 408
user quotas
edquota - edit user quotas, 586
quota check - check quota consistency, 657
quotaoff - tum file system quotas off, 658
quota on - tum file system quotas on, 658
repquota - summarize quotas, 664
rquotad - remote quota server, 679
users
info on users - finger, 164
list last logins - last, 217
what are they doing - w,497
who - who is logged in, 505
write to all- wall,499
users - display users on system, 476
utilities, introduction, 1
uuclean - clean UUCP spool area, 714
uucp - UNIX to UNIX copy, 477
uuep log - uulog, 477
uudecode - decode binary file, 479
uuencode - encode binary file, 479
uulog - UUCP log, 477
uuname - UUCP list of names, 477
uusend - send file to remote host, 480
uux - UNIX to UNIX command execution, 481

U
u3b - machine type truth value, 248
u3b2 - machine type truth value, 248
u3b5 - machine type truth value, 248
ul - underline text, 469
umask shell command - sh,383
umask - change/display file creation mask - csh, 86
umount - unmount file system, 634
unalias - remove aliases - csh, 86
uname - print UNIX hostname, 470
uncompress - uncompress files, 63,64
uncompress files, 63
undelete mail command, 255
underline text- ul,469
un expand - spaces to tabs, 152
unget - unget sees file, 471
unhash - discard hash table - csh, 86
unifdef - eliminate :ltifdef's from e input, 472
uniq - remove repeated lines, 473
uni t s - convert units, 474
UNIX to UNIX command execution - uux, 481
UNIX to UNIX copy - uucp, 477
unlimi t - remove resource limitiations - csh,86
unlink - remove a link, 615
unpack - unpack files, 289
unread mail command, 254
unset shell command - sh,383
unset mail command, 256
unset - discard shell variables - csh, 86
unsetenv -remove environment variables - csh, 86
until shell command - sh,378
update - update super block, 713
update last modified date of file - touch, 456
update programs - make, 262 thru 268
update super block - sync, 425
uptime - display system up time, 475

V
vacation - automatic mail replies, 483
val - validate secs file, 484
validate secs file - val,484
variable substitution, in C-Shell, 78
variables in Bourne Shell, 379
variables in C-Shell, 87
environment variables in mail
vax - machine type truth value, 248
verbose - C-Shell variable, 89
verbose mail environment variable, 258
verifier, C programs - lint, 225
plot graphics on - vplot, 491
version mail command, 256
version of file - what, 501
vfontinfo - examine font files, 485
vgrind- make formatted listings, 486
vi - visual editor, 488
view - view file, 490
vipw - edit password file, 715
visual editor - vi, 488
visual mail command, 256
VISUAL mail environment variable, 258
vmstat - display virtual memory statistics, 716
vplot -ploton Versatec, 491
vpq - display raster print queue, 492
vpr - print on raster printer/plotter, 492
vprint - print on raster printer/plotter, 492

-749-

Index - Continued

yppoll- yellow pages version inquiry, 721
yppush - force propagation of changed yellow pages map, 722
ypserv - yellow pages server process, 723
ypset - direct ypbind to a server, 725
ypwhi ch - who is yellow pages server, 519, 726
ypxfr - move remote yellow pages map to local host, 727
yppas swdd - yellow pages password server, 720

vprm - remove jobs from raster print queue, 492
vswap - convert foreign font files, 494
vt ro ff - format document for raster printer, 495
vwidth - make font width table, 496

w
w - what are users doing, 497
wait shell command - sh, 384, 498
wai t - wait for background process - csh, 86
wall - write to all users, 499
we - count lines, words, characters in file, 500
what are users doing - w,497
what - identify file version, 501
whatis - describe command, 502
wherei s - find program, 503
which - find program file, 504
while shell command- sh,378
while-repeat commands- csh,86
who - who is logged in, 505
who is logged in on local network - rusers, 356, 358
whoami - display effective user name, 506
whoi s - Internet directory service, 507
window environment- suntools, 412
window management
adjacentscreens command, 8
swi tcher utility, 422
window, save context- lockscreen, 229
words in file, count - we, 500
working directory
cd - change directory, 39
display name of - pwd, 325
write - write to another user, 508
write EOF mark on magnetic tape - mt, 277
write mail command, 256
write to all users - wall,499
write to all users on network: - rwall, 357

z
z mail command, 256
zcat - compress files, 64

X
xargs - construct and use initial arguments lists, 510
xget - receive secret mail, 512
xi t mail command, 253
xsend - send secret mail, 512
xstr - extract strings from C code, 513

y
yacc - parser generator, 514
YACC language tags file - ctags, 93
yellow pages
change login password in - yppasswd,518
make database - ypini t, 718
make dbm file - makedbm, 622
print values from database - ypcat, 516
rebuild database - ypmake, 719
yes - be repetitively affirmative, 515
ypcat - print values from yP database, 516
ypini t - make yellow pages database, 718
ypmake - rebuild yellow pages database, 719
ypmatch-match YPkeys, 517
yppa s s wd - change login password in yellow pages, 518
-750-

Revision History

Version

Date

Comments

A

23 February 1983

First edition of this manual.

B

15 April 1983

Second edition of this manual with
corrections to numerous manual pages.

C

1 August 1983

Third edition of this manual with
corrections to numerous manual pages.

D

1 November 1983

Fourth edition of this manual with
numerous corrections. Added OPTIONS
section headings for clarity, and
corrected numerous incorrect crossreferences.

E

7 January 1984

Fifth edition of this manual with
numerous corrections. The title was
changed from User' s Manual to
Commands Reference Manual.

F

15 May 1985

Corrected numerous errors. Brought
Maintenance Commands and
Procedures, formerly section 8, back
into this volume and removed it from
the System Manager' s Manual. Made
page numbering contiguous thto\lghout,
and replaced the P ermute4bideJ9Ii.th a
conventional one.

G

1 January 1986

Seventh edition, withfuiuiYCotfect:i9h~
to manual pages.<» . . . . . >.< . . »».... . >< . >.<
Eighth edition, fOF$pn3.2
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                     : 2015:09:18 16:44:57-08:00
Modify Date                     : 2015:09:18 16:32:17-07:00
Metadata Date                   : 2015:09:18 16:32:17-07:00
Producer                        : Adobe Acrobat 9.0 Paper Capture Plug-in
Format                          : application/pdf
Document ID                     : uuid:19f0592c-5a08-de40-9209-ea76146d941b
Instance ID                     : uuid:f0914888-2298-6d41-8fbd-c26497e4bdd6
Page Layout                     : SinglePage
Page Mode                       : UseNone
Page Count                      : 776

EXIF Metadata provided by EXIF.tools