man pages section 1: User

Commands

Sun Microsystems, Inc.

4150 Network Circle
Santa Clara, CA 95054
U.S.A.

Part No: 817–0707–10

April 2004
Copyright 2004 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. All rights reserved.

This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No
part of this product or document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any.
Third-party software, including font technology, is copyrighted and licensed from Sun suppliers.
Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S.
and other countries, exclusively licensed through X/Open Company, Ltd.
Sun, Sun Microsystems, the Sun logo, docs.sun.com, AnswerBook, AnswerBook2, and Solaris are trademarks, registered trademarks, or service marks
of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks
of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun
Microsystems, Inc.
The OPEN LOOK and Sun™ Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the
pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a
non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees who implement OPEN LOOK GUIs
and otherwise comply with Sun’s written license agreements.
U.S. Government Rights – Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and
applicable provisions of the FAR and its supplements.
DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Copyright 2004 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. Tous droits réservés.
Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l’utilisation, la copie, la distribution, et la
décompilation. Aucune partie de ce produit ou document ne peut être reproduite sous aucune forme, par quelque moyen que ce soit, sans
l’autorisation préalable et écrite de Sun et de ses bailleurs de licence, s’il y en a. Le logiciel détenu par des tiers, et qui comprend la technologie relative
aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun.
Des parties de ce produit pourront être dérivées du système Berkeley BSD licenciés par l’Université de Californie. UNIX est une marque déposée aux
Etats-Unis et dans d’autres pays et licenciée exclusivement par X/Open Company, Ltd.
Sun, Sun Microsystems, le logo Sun, docs.sun.com, AnswerBook, AnswerBook2, et Solaris sont des marques de fabrique ou des marques déposées, ou
marques de service, de Sun Microsystems, Inc. aux Etats-Unis et dans d’autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des
marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d’autres pays. Les produits portant les marques
SPARC sont basés sur une architecture développée par Sun Microsystems, Inc.
L’interface d’utilisation graphique OPEN LOOK et Sun™ a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît
les efforts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d’utilisation visuelle ou graphique pour l’industrie
de l’informatique. Sun détient une licence non exclusive de Xerox sur l’interface d’utilisation graphique Xerox, cette licence couvrant également les
licenciés de Sun qui mettent en place l’interface d’utilisation graphique OPEN LOOK et qui en outre se conforment aux licences écrites de Sun.
CETTE PUBLICATION EST FOURNIE “EN L’ETAT” ET AUCUNE GARANTIE, EXPRESSE OU IMPLICITE, N’EST ACCORDEE, Y COMPRIS DES
GARANTIES CONCERNANT LA VALEUR MARCHANDE, L’APTITUDE DE LA PUBLICATION A REPONDRE A UNE UTILISATION
PARTICULIERE, OU LE FAIT QU’ELLE NE SOIT PAS CONTREFAISANTE DE PRODUIT DE TIERS. CE DENI DE GARANTIE NE
S’APPLIQUERAIT PAS, DANS LA MESURE OU IL SERAIT TENU JURIDIQUEMENT NUL ET NON AVENU.

040116@7518
Contents

Preface 19

Introduction 25
Intro(1) 26

User Commands 29
acctcom(1) 30
adb(1) 33
addbib(1) 34
alias(1) 36
allocate(1) 39
amt(1) 41
answerbook2(1) 42
appcert(1) 43
apptrace(1) 50
apropos(1) 55
ar(1) 57
arch(1) 61
as(1) 62
asa(1) 66
at(1) 68
atq(1) 75
atrm(1) 76
audioconvert(1) 77
audioplay(1) 81

3
 audiorecord(1) 83
auths(1) 86
awk(1) 88
banner(1) 93
basename(1) 94
basename(1B) 96
bc(1) 97
bdiff(1) 101
bfs(1) 102
biff(1B) 106
break(1) 107
cal(1) 109
calendar(1) 110
cancel(1) 112
cat(1) 114
cc(1B) 117
cd(1) 119
cdrw(1) 122
checknr(1) 128
chgrp(1) 129
chkey(1) 131
chmod(1) 133
chown(1) 139
chown(1B) 141
ckdate(1) 142
ckgid(1) 145
ckint(1) 147
ckitem(1) 149
ckkeywd(1) 152
ckpath(1) 154
ckrange(1) 157
ckstr(1) 160
cksum(1) 163
cktime(1) 165
ckuid(1) 167
ckyorn(1) 169
clear(1) 171
cmp(1) 172

4 man pages section 1: User Commands • April 2004

col(1) 174
comm(1) 176
command(1) 178
compress(1) 181
coproc(1F) 184
cp(1) 188
cpio(1) 192
cpp(1) 200
cputrack(1) 206
crle(1) 210
crontab(1) 220
crypt(1) 224
csh(1) 225
csplit(1) 251
ct(1C) 254
ctags(1) 256
cu(1C) 259
cut(1) 266
date(1) 269
dc(1) 273
deallocate(1) 277
deroff(1) 279
df(1B) 280
dhcpinfo(1) 281
diff(1) 283
diff3(1) 287
diffmk(1) 289
dircmp(1) 290
dis(1) 291
dispgid(1) 293
dispuid(1) 294
dos2unix(1) 295
download(1) 297
dpost(1) 299
du(1) 302
du(1B) 305
dump(1) 307
dumpcs(1) 310

Contents 5
 echo(1) 311
echo(1B) 315
echo(1F) 316
ed(1) 317
edit(1) 329
egrep(1) 333
eject(1) 336
elfdump(1) 340
enable(1) 342
env(1) 344
eqn(1) 346
error(1) 351
ex(1) 355
exec(1) 365
exit(1) 367
expand(1) 369
exportfs(1B) 371
expr(1) 372
expr(1B) 375
exstr(1) 378
face(1) 382
factor(1) 383
fastboot(1B) 384
fdformat(1) 385
fgrep(1) 390
file(1) 392
file(1B) 394
filesync(1) 396
find(1) 403
finger(1) 410
fmlcut(1F) 413
fmlexpr(1F) 415
fmlgrep(1F) 418
fmli(1) 420
fmt(1) 423
fmtmsg(1) 424
fnattr(1) 429
fnbind(1) 432

6 man pages section 1: User Commands • April 2004

fnlist(1) 434
fnlookup(1) 436
fnrename(1) 437
fnsearch(1) 438
fnunbind(1) 445
fold(1) 446
from(1B) 448
ftp(1) 449
ftpcount(1) 460
ftpwho(1) 461
gcore(1) 462
gencat(1) 463
geniconvtbl(1) 466
genlayouttbl(1) 469
genmsg(1) 484
getconf(1) 490
getfacl(1) 495
getfrm(1F) 499
getitems(1F) 500
getopt(1) 501
getoptcvt(1) 503
getopts(1) 506
gettext(1) 512
gettxt(1) 514
glob(1) 516
gprof(1) 517
graph(1) 522
grep(1) 524
groups(1) 529
groups(1B) 530
grpck(1B) 531
hash(1) 532
head(1) 534
history(1) 536
hostid(1) 545
hostname(1) 546
iconv(1) 547
indicator(1F) 549

Contents 7
 indxbib(1) 550
install(1B) 551
ipcrm(1) 553
ipcs(1) 554
isainfo(1) 558
isalist(1) 560
jobs(1) 561
join(1) 568
kbd(1) 571
kdestroy(1) 574
keylogin(1) 575
keylogout(1) 577
kill(1) 578
kinit(1) 582
klist(1) 587
kpasswd(1) 589
ksh(1) 590
ktutil(1) 641
last(1) 643
lastcomm(1) 645
ld(1) 647
ld(1B) 659
ldap(1) 660
ldapdelete(1) 664
ldaplist(1) 667
ldapmodify(1) 671
ldapmodrdn(1) 675
ldapsearch(1) 678
ldd(1) 683
ld.so.1(1) 688
let(1) 695
lex(1) 696
limit(1) 708
line(1) 713
lint(1B) 714
list_devices(1) 716
listusers(1) 718
llc2_autoconfig(1) 719

8 man pages section 1: User Commands • April 2004

llc2_config(1) 720
llc2_stats(1) 722
ln(1) 730
ln(1B) 733
loadkeys(1) 736
locale(1) 737
localedef(1) 740
logger(1) 744
logger(1B) 746
login(1) 748
logname(1) 755
logout(1) 756
look(1) 757
lookbib(1) 758
lorder(1) 759
lp(1) 760
lpc(1B) 767
lpq(1B) 771
lpr(1B) 773
lprm(1B) 777
lpstat(1) 779
lptest(1B) 783
ls(1) 784
ls(1B) 790
m4(1) 793
mach(1) 798
machid(1) 799
madv.so.1(1) 801
mail(1B) 805
mailcompat(1) 806
mailp(1) 807
mailq(1) 809
mailstats(1) 811
mailx(1) 813
make(1S) 835
man(1) 870
mconnect(1) 876
mcs(1) 877

Contents 9
 mdb(1) 879
mesg(1) 920
message(1F) 921
mixerctl(1) 923
mkdir(1) 925
mkmsgs(1) 927
mkstr(1B) 929
more(1) 931
mp(1) 938
mpss.so.1(1) 946
msgfmt(1) 949
mt(1) 955
mv(1) 958
nawk(1) 961
nca(1) 982
ncab2clf(1) 984
ncakmod(1) 986
netscape(1) 987
newform(1) 992
newgrp(1) 995
news(1) 997
newtask(1) 998
nice(1) 1001
nis+(1) 1003
niscat(1) 1018
nischgrp(1) 1021
nischmod(1) 1023
nischown(1) 1026
nischttl(1) 1028
nisdefaults(1) 1030
niserror(1) 1033
nisgrpadm(1) 1034
nisln(1) 1038
nisls(1) 1040
nismatch(1) 1042
nismkdir(1) 1045
nisopaccess(1) 1048
nispasswd(1) 1051

10 man pages section 1: User Commands • April 2004

nisrm(1) 1055
nisrmdir(1) 1057
nistbladm(1) 1059
nistest(1) 1065
nl(1) 1067
nm(1) 1071
nohup(1) 1076
nroff(1) 1080
od(1) 1083
on(1) 1089
optisa(1) 1091
pack(1) 1092
pagesize(1) 1095
pargs(1) 1096
passwd(1) 1098
paste(1) 1105
patch(1) 1108
pathchk(1) 1113
pathconv(1F) 1116
pax(1) 1118
perl(1) 1127
pfexec(1) 1134
pg(1) 1135
pgrep(1) 1140
pkginfo(1) 1144
pkgmk(1) 1146
pkgparam(1) 1149
pkgproto(1) 1151
pkgtrans(1) 1153
plimit(1) 1156
plot(1B) 1158
pmap(1) 1160
postdaisy(1) 1167
postdmd(1) 1169
postio(1) 1171
postmd(1) 1174
postplot(1) 1177
postprint(1) 1179

Contents 11
 postreverse(1) 1181
posttek(1) 1183
ppgsz(1) 1185
pr(1) 1188
praliases(1) 1193
prctl(1) 1194
preap(1) 1197
prex(1) 1199
print(1) 1211
printenv(1B) 1212
printf(1) 1213
priocntl(1) 1218
proc(1) 1229
prof(1) 1232
profiles(1) 1236
projects(1) 1238
ps(1) 1239
ps(1B) 1248
pvs(1) 1251
pwd(1) 1254
ranlib(1) 1255
rcapstat(1) 1256
rcp(1) 1260
rdist(1) 1262
read(1) 1267
readfile(1F) 1270
readonly(1) 1271
refer(1) 1272
regcmp(1) 1274
regex(1F) 1276
reinit(1F) 1278
renice(1) 1279
reset(1F) 1282
rlogin(1) 1283
rm(1) 1286
rmformat(1) 1290
roffbib(1) 1297
roles(1) 1299

12 man pages section 1: User Commands • April 2004

rpcgen(1) 1301
rpm2cpio(1) 1306
rsh(1) 1307
run(1F) 1311
runat(1) 1313
rup(1) 1316
rup(1C) 1317
ruptime(1) 1318
rusage(1B) 1319
rusers(1) 1321
rwho(1) 1322
sag(1) 1323
sar(1) 1325
sccs(1) 1330
sccs-admin(1) 1340
sccs-cdc(1) 1344
sccs-comb(1) 1346
sccs-delta(1) 1348
sccs-get(1) 1351
sccs-help(1) 1357
sccs-prs(1) 1358
sccs-prt(1) 1362
sccs-rmdel(1) 1365
sccs-sact(1) 1366
sccs-sccsdiff(1) 1367
sccs-unget(1) 1368
sccs-val(1) 1369
scp(1) 1371
script(1) 1373
sdiff(1) 1374
sed(1) 1376
sed(1B) 1384
set(1) 1390
set(1F) 1395
setcolor(1F) 1397
setfacl(1) 1398
setpgrp(1) 1402
sftp(1) 1403

Contents 13
 sh(1) 1406
shell(1F) 1424
shell_builtins(1) 1425
shift(1) 1429
shutdown(1B) 1430
size(1) 1431
sleep(1) 1433
smart2cfg(1) 1435
soelim(1) 1437
solregis(1) 1438
sort(1) 1441
sortbib(1) 1448
sotruss(1) 1450
spell(1) 1452
spline(1) 1455
split(1) 1456
srchtxt(1) 1458
ssh(1) 1461
ssh-add(1) 1471
ssh-agent(1) 1473
ssh-http-proxy-connect(1) 1475
ssh-keygen(1) 1477
ssh-socks5-proxy-connect(1) 1480
strchg(1) 1482
strings(1) 1485
strip(1) 1487
stty(1) 1489
stty(1B) 1497
sum(1) 1504
sum(1B) 1505
suspend(1) 1506
symorder(1) 1507
sysV-make(1) 1508
tabs(1) 1515
tail(1) 1519
talk(1) 1522
tar(1) 1525
tbl(1) 1536

14 man pages section 1: User Commands • April 2004

tcopy(1) 1538
tee(1) 1539
telnet(1) 1540
test(1) 1550
test(1B) 1558
test(1F) 1560
tftp(1) 1562
time(1) 1565
times(1) 1568
timex(1) 1569
tip(1) 1571
tnfdump(1) 1580
tnfxtract(1) 1585
touch(1) 1587
touch(1B) 1591
tplot(1) 1592
tput(1) 1593
tr(1) 1598
tr(1B) 1603
trap(1) 1604
troff(1) 1606
true(1) 1609
truss(1) 1610
tset(1B) 1617
tsort(1) 1622
tty(1) 1624
type(1) 1625
typeset(1) 1626
ucblinks(1B) 1628
ul(1) 1629
umask(1) 1630
uname(1) 1634
unifdef(1) 1637
uniq(1) 1639
units(1) 1642
unix2dos(1) 1644
uptime(1) 1646
users(1B) 1647

Contents 15
 uucp(1C) 1648
uuencode(1C) 1652
uuglist(1C) 1655
uustat(1C) 1656
uuto(1C) 1660
uux(1C) 1663
vacation(1) 1667
vc(1) 1670
vgrind(1) 1674
vi(1) 1678
vipw(1B) 1688
volcancel(1) 1689
volcheck(1) 1690
volmissing(1) 1692
volrmmount(1) 1693
vsig(1F) 1695
w(1) 1696
wait(1) 1698
wc(1) 1701
what(1) 1703
whatis(1) 1705
whereis(1B) 1706
which(1) 1708
who(1) 1709
whoami(1B) 1712
whocalls(1) 1713
whois(1) 1714
write(1) 1715
xargs(1) 1718
xgettext(1) 1723
xstr(1) 1725
yacc(1) 1727
yes(1) 1731
ypcat(1) 1732
ypmatch(1) 1733
yppasswd(1) 1734
ypwhich(1) 1735

16 man pages section 1: User Commands • April 2004

Index 1737

Contents 17
18 man pages section 1: User Commands • April 2004
Preface

Both novice users and those familar with the SunOS operating system can use online
man pages to obtain information about the system and its features. A man page is
intended to answer concisely the question “What does it do?” The man pages in
general comprise a reference manual. They are not intended to be a tutorial.

Overview
The following contains a brief description of each man page section and the
information it references:
■ Section 1 describes, in alphabetical order, commands available with the operating
system.
■ Section 1M describes, in alphabetical order, commands that are used chiefly for
system maintenance and administration purposes.
■ Section 2 describes all of the system calls. Most of these calls have one or more
error returns. An error condition is indicated by an otherwise impossible returned
value.
■ Section 3 describes functions found in various libraries, other than those functions
that directly invoke UNIX system primitives, which are described in Section 2.
■ Section 4 outlines the formats of various files. The C structure declarations for the
file formats are given where applicable.
■ Section 5 contains miscellaneous documentation such as character-set tables.
■ Section 6 contains available games and demos.
■ Section 7 describes various special files that refer to specific hardware peripherals
and device drivers. STREAMS software drivers, modules and the
STREAMS-generic set of system calls are also described.

19
 ■ Section 9 provides reference information needed to write device drivers in the
kernel environment. It describes two device driver interface specifications: the
Device Driver Interface (DDI) and the Driver⁄Kernel Interface (DKI).
■ Section 9E describes the DDI/DKI, DDI-only, and DKI-only entry-point routines a
developer can include in a device driver.
■ Section 9F describes the kernel functions available for use by device drivers.
■ Section 9S describes the data structures used by drivers to share information
between the driver and the kernel.

Below is a generic format for man pages. The man pages of each manual section
generally follow this order, but include only needed headings. For example, if there
are no bugs to report, there is no BUGS section. See the intro pages for more
information and detail about each section, and man(1) for more information about man
pages in general.
NAME This section gives the names of the commands or
functions documented, followed by a brief
description of what they do.
SYNOPSIS This section shows the syntax of commands or
functions. When a command or file does not exist
in the standard path, its full path name is shown.
Options and arguments are alphabetized, with
single letter arguments first, and options with
arguments next, unless a different argument order
is required.

The following special characters are used in this

section:
[ ] Brackets. The option or argument
enclosed in these brackets is optional. If
the brackets are omitted, the argument
must be specified.
. . . Ellipses. Several values can be provided
for the previous argument, or the
previous argument can be specified
multiple times, for example, "filename
. . ." .
| Separator. Only one of the arguments
separated by this character can be
specified at a time.
{ } Braces. The options and/or arguments
enclosed within braces are
interdependent, such that everything
enclosed must be treated as a unit.

20 man pages section 1: User Commands • April 2004

PROTOCOL This section occurs only in subsection 3R to
indicate the protocol description file.
DESCRIPTION This section defines the functionality and behavior
of the service. Thus it describes concisely what the
command does. It does not discuss OPTIONS or
cite EXAMPLES. Interactive commands,
subcommands, requests, macros, and functions are
described under USAGE.
IOCTL This section appears on pages in Section 7 only.
Only the device class that supplies appropriate
parameters to the ioctl(2) system call is called
ioctl and generates its own heading. ioctl calls
for a specific device are listed alphabetically (on the
man page for that specific device). ioctl calls are
used for a particular class of devices all of which
have an io ending, such as mtio(7I).
OPTIONS This secton lists the command options with a
concise summary of what each option does. The
options are listed literally and in the order they
appear in the SYNOPSIS section. Possible
arguments to options are discussed under the
option, and where appropriate, default values are
supplied.
OPERANDS This section lists the command operands and
describes how they affect the actions of the
command.
OUTPUT This section describes the output – standard output,
standard error, or output files – generated by the
command.
RETURN VALUES If the man page documents functions that return
values, this section lists these values and describes
the conditions under which they are returned. If a
function can return only constant values, such as 0
or –1, these values are listed in tagged paragraphs.
Otherwise, a single paragraph describes the return
values of each function. Functions declared void do
not return values, so they are not discussed in
RETURN VALUES.
ERRORS On failure, most functions place an error code in
the global variable errno indicating why they
failed. This section lists alphabetically all error
codes a function can generate and describes the
conditions that cause each error. When more than

Preface 21
 one condition can cause the same error, each
condition is described in a separate paragraph
under the error code.
USAGE This section lists special rules, features, and
commands that require in-depth explanations. The
subsections listed here are used to explain built-in
functionality:

Commands
Modifiers
Variables
Expressions
Input Grammar
EXAMPLES This section provides examples of usage or of how
to use a command or function. Wherever possible a
complete example including command-line entry
and machine response is shown. Whenever an
example is given, the prompt is shown as
example%, or if the user must be superuser,
example#. Examples are followed by explanations,
variable substitution rules, or returned values. Most
examples illustrate concepts from the SYNOPSIS,
DESCRIPTION, OPTIONS, and USAGE sections.
ENVIRONMENT VARIABLES This section lists any environment variables that
the command or function affects, followed by a
brief description of the effect.
EXIT STATUS This section lists the values the command returns to
the calling program or shell and the conditions that
cause these values to be returned. Usually, zero is
returned for successful completion, and values
other than zero for various error conditions.
FILES This section lists all file names referred to by the
man page, files of interest, and files created or
required by commands. Each is followed by a
descriptive summary or explanation.
ATTRIBUTES This section lists characteristics of commands,
utilities, and device drivers by defining the
attribute type and its corresponding value. See
attributes(5) for more information.
SEE ALSO This section lists references to other man pages,
in-house documentation, and outside publications.

22 man pages section 1: User Commands • April 2004

DIAGNOSTICS This section lists diagnostic messages with a brief
explanation of the condition causing the error.
WARNINGS This section lists warnings about special conditions
which could seriously affect your working
conditions. This is not a list of diagnostics.
NOTES This section lists additional information that does
not belong anywhere else on the page. It takes the
form of an aside to the user, covering points of
special interest. Critical information is never
covered here.
BUGS This section describes known bugs and, wherever
possible, suggests workarounds.

Preface 23
24 man pages section 1: User Commands • April 2004
Introduction

25
Intro(1)
NAME Intro – introduction to commands and application programs

DESCRIPTION This section describes, in alphabetical order, commands available with this operating
system.

Pages of special interest are categorized as follows:

1B Commands found only in the SunOS/BSD Compatibility Package.
1C Commands for communicating with other systems.
1F Commands associated with Form and Menu Language Interpreter
(FMLI).
1S Commands specific to the SunOS system.

OTHER See these sections of the man pages section 1M: System Administration Commands for
SECTIONS more information.
■ Section 1M in this manual for system maintenance commands.
■ Section 4 of this manual for information on file formats.
■ Section 5 of this manual for descriptions of publicly available files and
miscellaneous information pages.
■ Section 6 in this manual for computer demonstrations.

For tutorial information about these commands and procedures, see:

■ Solaris Advanced User’s Guide

Manual Page Unless otherwise noted, commands described in the SYNOPSIS section of a manual
Command Syntax page accept options and other arguments according to the following syntax and
should be interpreted as explained below.

name [-option...] [cmdarg...] where:

[ ] Surround an option or cmdarg that is not required.
... Indicates multiple occurrences of the option or cmdarg.
name The name of an executable file.
{ } The options and/or arguments enclosed within braces are
interdependent, such that everything enclosed must be treated as a
unit.
option (Always preceded by a “−”.) noargletter... or, argletter optarg[,...]
noargletter A single letter representing an option without an option-argument.
Note that more than one noargletter option can be grouped after
one “−” (Rule 5, below).
argletter A single letter representing an option requiring an
option-argument.

26 man pages section 1: User Commands • Last Revised 1 Nov 1999

 Intro(1)
optarg An option-argument (character string) satisfying a preceding
argletter. Note that groups of optargs following an argletter must be
separated by commas, or separated by a tab or space character and
quoted (Rule 8, below).
cmdarg Path name (or other command argument) not beginning with “−”,
or “−” by itself indicating the standard input.

Command Syntax These command syntax rules are not followed by all current commands, but all new
Standard: Rules commands will obey them. getopts(1) should be used by all shell procedures to
parse positional parameters and to check for legal options. It supports Rules 3-10
below. The enforcement of the other rules must be done by the command itself.
1. Command names (name above) must be between two and nine characters long.
2. Command names must include only lower-case letters and digits.
3. Option names (option above) must be one character long.
4. All options must be preceded by “−”.
5. Options with no arguments may be grouped after a single “−”.
6. The first option-argument (optarg above) following an option must be preceded by
a tab or space character.
7. Option-arguments cannot be optional.
8. Groups of option-arguments following an option must either be separated by
commas or separated by tab or space character and quoted (−o xxx,z,yy or − o
"xxx z yy").
9. All options must precede operands (cmdarg above) on the command line.
10. “− −” may be used to indicate the end of the options.
11. The order of the options relative to one another should not matter.
12. The relative order of the operands (cmdarg above) may affect their significance in
ways determined by the command with which they appear.
13. “−” preceded and followed by a space character should only be used to mean
standard input.

ATTRIBUTES See attributes(5) for a discussion of the attributes listed in this section.

SEE ALSO getopts(1), wait(1), exit(2), getopt(3C), wait(3UCB), attributes(5)

DIAGNOSTICS Upon termination, each command returns two bytes of status, one supplied by the
system and giving the cause for termination, and (in the case of “normal” termination)
one supplied by the program [see wait(3UCB) and exit(2)]. The former byte is 0 for
normal termination; the latter is customarily 0 for successful execution and non-zero
to indicate troubles such as erroneous parameters, or bad or inaccessible data. It is
called variously “exit code”, “exit status”, or “return code”, and is described only
where special conventions are involved.

Introduction 27
Intro(1)
WARNINGS Some commands produce unexpected results when processing files containing null
characters. These commands often treat text input lines as strings and therefore
become confused upon encountering a null character (the string terminator) within a
line.

28 man pages section 1: User Commands • Last Revised 1 Nov 1999

User Commands

29
acctcom(1)
NAME acctcom – search and print process accounting files
SYNOPSIS acctcom [-abfhikmqrtv] [-C sec] [-e time] [-E time] [-g group]
[-H factor] [-I chars] [-l line] [-n pattern] [-o output-file] [-O sec]
[-s time] [-S time] [-u user] [filename…]

DESCRIPTION The acctcom utility reads filenames, the standard input, or /var/adm/pacct, in the
form described by acct(3HEAD) and writes selected records to standard output. Each
record represents the execution of one process. The output shows the COMMAND NAME,
USER, TTYNAME, START TIME, END TIME, REAL (SEC), CPU (SEC), MEAN SIZE
(K), and optionally, F (the fork()/exec() flag: 1 for fork() without exec()),
STAT (the system exit status), HOG FACTOR, KCORE MIN, CPU FACTOR, CHARS
TRNSFD, and BLOCKS READ (total blocks read and written).

A ‘#’ is prepended to the command name if the command was executed with
super-user privileges. If a process is not associated with a known terminal, a ‘?’ is
printed in the TTYNAME field.

If no filename is specified, and if the standard input is associated with a terminal or

/dev/null (as is the case when using ‘&’ in the shell), /var/adm/pacct is read;
otherwise, the standard input is read.

If any filename arguments are given, they are read in their respective order. Each file is
normally read forward, that is, in chronological order by process completion time. The
file /var/adm/pacct is usually the current file to be examined; a busy system may
need several such files of which all but the current file are found in
/var/adm/pacctincr.

OPTIONS The following options are supported:

-a Show some average statistics about the processes selected. The
statistics will be printed after the output records.
-b Read backwards, showing latest commands first. This option has
no effect when standard input is read.
-f Print the fork()/exec() flag and system exit status columns in
the output. The numeric output for this option will be in octal.
-h Instead of mean memory size, show the fraction of total available
CPU time consumed by the process during its execution. This “hog
factor” is computed as (total CPU time)/(elapsed time).
-i Print columns containing the I/O counts in the output.
-k Instead of memory size, show total kcore-minutes.
-m Show mean core size (the default).
-q Do not print any output records, just print the average statistics as
with the -a option.
-r Show CPU factor (user-time/(system-time + user-time)).

30 man pages section 1: User Commands • Last Revised 11 Jan 1996

 acctcom(1)
-t Show separate system and user CPU times.
-v Exclude column headings from the output.
-C sec Show only processes with total CPU time (system-time +
user-time) exceeding sec seconds.
-e time Select processes existing at or before time.
-E time Select processes ending at or before time. Using the same time for
both -S and -E shows the processes that existed at time.
-g group Show only processes belonging to group. The group may be
designated by either the group ID or group name.
-H factor Show only processes that exceed factor, where factor is the “hog
factor” as explained in option -h above.
-I chars Show only processes transferring more characters than the cutoff
number given by chars.
-l line Show only processes belonging to terminal /dev/term/line.
-n pattern Show only commands matching pattern that may be a regular
expression as in regcmp(3C), except + means one or more
occurrences.
-o output-file Copy selected process records in the input data format to
output-file; suppress printing to standard output.
-O sec Show only processes with CPU system time exceeding sec seconds.
-s time Select processes existing at or after time, given in the format
hr [ :min [ :sec ] ].
-S time Select processes starting at or after time.
-u user Show only processes belonging to user. The user may be specified
by a user ID, a login name that is then converted to a user ID, ‘#’
(which designates only those processes executed with superuser
privileges), or ‘?’ (which designates only those processes
associated with unknown user IDs).
FILES /etc/group system group file
/etc/passwd system password file
/var/adm/pacctincr active processes accounting file

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWaccu

User Commands 31
acctcom(1)

ATTRIBUTE TYPE ATTRIBUTE VALUE

CSI enabled

SEE ALSO ps(1), acct(1M), acctcms(1M), acctcon(1M), acctmerg(1M), acctprc(1M),

acctsh(1M), fwtmp(1M), runacct(1M), su(1M), acct(2), regcmp(3C),
acct(3HEAD), utmp(4), attributes(5)

System Administration Guide: Basic Administration

NOTES acctcom reports only on processes that have terminated; use ps(1) for active
processes.

32 man pages section 1: User Commands • Last Revised 11 Jan 1996

 adb(1)
NAME adb – general-purpose debugger
SYNOPSIS adb [-kw] [-I dir] [-P prompt] [-V mode] [object [core]]

DESCRIPTION The adb utility is an interactive, general-purpose debugger. It can be used to examine
files and provides a controlled environment for the execution of programs.

The adb utility is now implemented as a link to the mdb(1) utility in Solaris 9. mdb(1)
is a low-level debugging utility that can be used to examine user processes as well as
the live operating system or operating system crash dumps. The new mdb(1) utility
provides complete backwards compatibility with the existing syntax and features of
adb, including support for processing adb macro files. The Solaris Modular Debugger
Guide and mdb(1) man page describes the features of mdb, including its adb
compatibility mode. This mode will be activated by default when the adb link is
executed.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWmdb (32-bit)

SUNWmdbx (64-bit)

SEE ALSO mdb(1), attributes(5)

Solaris Modular Debugger Guide

User Commands 33
addbib(1)
NAME addbib – create or extend a bibliographic database
SYNOPSIS addbib [-a] [-p promptfile] database

DESCRIPTION When addbib starts up, answering y to the initial Instructions? prompt yields
directions. Typing n (or RETURN) skips the directions. addbib then prompts for
various bibliographic fields, reads responses from the terminal, and sends output
records to database. A null response (just RETURN) means to leave out that field. A ‘−’
(minus sign) means to go back to the previous field. A trailing backslash allows a field
to be continued on the next line. The repeating Continue? prompt allows the user
either to resume by typing y (or RETURN), to quit the current session by typing n or
q, or to edit database with any system editor (see vi(1), ex(1), ed(1)).

OPTIONS The following options are supported:

-a Suppresses prompting for an abstract. Asking for an abstract is the
default. Abstracts are ended with a Control−D.
-p promptfile Uses a new prompting skeleton, defined in promptfile. This file
should contain prompt strings, a TAB, and the key-letters to be
written to the database.

USAGE

Bibliography Key The most common key-letters and their meanings are given below. addbib insulates
Letters you from these key-letters, since it gives you prompts in English, but if you edit the
bibliography file later on, you will need to know this information.
%A Author’s name
%B Book containing article referenced
%C City (place of publication)
%D Date of publication
%E Editor of book containing article referenced
%F Footnote number or label (supplied by refer)
%G Government order number
%H Header commentary, printed before reference
%I Issuer (publisher)
%J Journal containing article
%K Keywords to use in locating reference
%L Label field used by -k option of refer
%M Bell Labs Memorandum (undefined)
%N Number within volume
%O Other commentary, printed at end of reference

34 man pages section 1: User Commands • Last Revised 14 Sep 1992

 addbib(1)
%P Page number(s)
%Q Corporate or Foreign Author (unreversed)
%R Report, paper, or thesis (unpublished)
%S Series title
%T Title of article or book
%V Volume number
%X Abstract — used by roffbib, not by refer
%Y,Z Ignored by refer

EXAMPLES EXAMPLE 1 Editing the bibliography file

Except for A, each field should be given just once. Only relevant fields should be
supplied.
%A Mark Twain
%T Life on the Mississippi
%I Penguin Books
%C New York
%D 1978

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWdoc

SEE ALSO ed(1), ex(1), indxbib(1), lookbib(1), refer(1), roffbib(1), sortbib(1), vi(1),
attributes(5)

User Commands 35
alias(1)
NAME alias, unalias – create or remove a pseudonym or shorthand for a command or series
of commands
SYNOPSIS /usr/bin/alias [alias-name [= string…]]
/usr/bin/unalias alias-name…
/usr/bin/unalias -a
csh alias [name [def]]
unalias pattern
ksh alias [-tx] [name [= value]…]
unalias name…

DESCRIPTION The alias and unalias utilities create or remove a pseudonym or shorthand term
for a command or series of commands, with different functionality in the C-shell and
Korn shell environments.

/usr/bin/alias The alias utility creates or redefines alias definitions or writes the values of existing
alias definitions to standard output. An alias definition provides a string value that
replaces a command name when it is encountered.

An alias definition affects the current shell execution environment and the execution
environments of the subshells of the current shell. When used as specified by this
document, the alias definition will not affect the parent process of the current shell nor
any utility environment invoked by the shell.

/usr/bin/unalias The unalias utility removes the definition for each alias name specified. The aliases
are removed from the current shell execution environment.

csh alias assigns def to the alias name. def is a list of words that may contain escaped
history-substitution metasyntax. name is not allowed to be alias or unalias. If def is
omitted, the alias name is displayed along with its current definition. If both name and
def are omitted, all aliases are displayed.

Because of implementation restrictions, an alias definition must have been entered on

a previous command line before it can be used.

unalias discards aliases that match (filename substitution) pattern. All aliases may be
removed by ‘unalias *’.

ksh alias with no arguments prints the list of aliases in the form name=value on standard
output. An alias is defined for each name whose value is given. A trailing space in
value causes the next word to be checked for alias substitution. The -t flag is used to
set and list tracked aliases. The value of a tracked alias is the full pathname
corresponding to the given name. The value becomes undefined when the value of
PATH is reset but the aliases remained tracked. Without the -t flag, for each name in

36 man pages section 1: User Commands • Last Revised 28 Sep 2001

 alias(1)
the argument list for which no value is given, the name and value of the alias is
printed. The -x flag is used to set or print exported aliases. An exported alias is defined
for scripts invoked by name. The exit status is non-zero if a name is given, but no value,
and no alias has been defined for the name.

The aliases given by the list of names may be removed from the alias list with
unalias.

OPTIONS The following option is supported by unalias:

-a Removes all alias definitions from the current shell execution environment.

ksh The following option is supported by alias:

-t Sets and lists tracked aliases.

OPERANDS The following operands are supported:

alias alias-name Write the alias definition to standard output.
unalias alias-name The name of an alias to be removed.
alias-name=string Assign the value of string to the alias alias-name.

If no operands are given, all alias definitions will be written to standard output.

OUTPUT The format for displaying aliases (when no operands or only name operands are
specified) is:

"%s=%s\n" name, value

The value string will be written with appropriate quoting so that it is suitable for
reinput to the shell.

EXAMPLES EXAMPLE 1 Modifying a command’s output

This example specifies that the output of the ls utility is columnated and more
annotated:
example% alias ls="ls −CF"

EXAMPLE 2 Repeating previous entries in the command history file

This example creates a simple “redo” command to repeat previous entries in the
command history file:
example% alias r=’fc −s’

EXAMPLE 3 Specifying a command’s output options

This example provides that the du utility summarize disk output in units of 1024
bytes:

User Commands 37
alias(1)
EXAMPLE 3 Specifying a command’s output options (Continued)

example% alias du=du −k

EXAMPLE 4 Dealing with an argument that is itself an alias name

This example sets up the nohup utility so that it can deal with an argument that is
itself an alias name:
example% alias nohup="nohup "

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of alias and unalias: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and
NLSPATH.

EXIT STATUS The following exit values are returned:

0 Successful completion.
alias >0 One of the alias-name operands specified did not have an alias definition, or
an error occurred.
unalias >0 One of the alias-name operands specified did not represent a valid alias
definition, or an error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

Interface Stability Standard

SEE ALSO csh(1), ksh(1), shell_builtins(1), attributes(5), environ(5), standards(5)

38 man pages section 1: User Commands • Last Revised 28 Sep 2001

 allocate(1)
NAME allocate – device allocation
SYNOPSIS allocate [-s] [-U uname] device
allocate [-s] [-U uname] -g dev-type
allocate [-s] [-U uname] -F device

DESCRIPTION The allocate utility manages the ownership of devices through its allocation
mechanism. It ensures that each device is used by only one qualified user at a time.

The device argument specifies the device to be manipulated. To preserve the integrity
of the device’s owner, the allocate operation is executed on all the device special files
associated with that device.

The argument dev−type is the device type to be operated on and can only be used with
the -g option.

The default allocate operation allocates the device special files associated with device to
the uid of the current process.

If the -F option is specified, the device cleaning program is executed when allocation
is performed. This cleaning program is found in /etc/security/lib. The name of
this program is found in the device_allocate(4) entry for the device in the dev−exec
field.

Only authorized users may allocate a device. The required authorizations are specified
in device_allocate(4).

OPTIONS The following options are supported:

-g dev−type Allocates a non−allocated device with a device−type matching
dev−type.
-s Silent. Suppresses any diagnostic output.
-F device Reallocates the device allocated to another user. This option is
often used with -U to reallocate a specific device to a specific user.
Only a user with the solaris.devices.revoke authorization
is permitted to use this option.
-U uname Uses the user ID uname instead of the user ID of the current
process when performing the allocate operation. Only a user with
the solaris.devices.revoke authorization is permitted to use
this option.

EXIT STATUS The following exit values are returned:

non—zero An error occurred.

FILES /etc/security/device_allocate

/etc/security/device_maps

User Commands 39
allocate(1)
/etc/security/dev/*

/etc/security/lib/*

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO deallocate(1), list_devices(1), bsmconv(1M), dminfo(1M),

device_allocate(4), device_maps(4), attributes(5)

NOTES The functionality described in this man page is available only if the Basic Security
Module (BSM) has been enabled. See bsmconv(1M) for more information.

/etc/security/dev, mkdevalloc(1M), and mkdevmaps(1M) may not be

supported in a future release of the Solaris operating environment.

40 man pages section 1: User Commands • Last Revised 17 Jan 2001

 amt(1)
NAME amt – run abstract machine test
SYNOPSIS amt [-s]

DESCRIPTION The amt command is for use in a Common Criteria security certified system. The
command is used to verify that the low level functions necessary to enforce the object
reuse requirements of the Controlled Access Protection Profile are working correctly.
/usr/bin/amt is a shell script that executes tests specific to your system. For a 32–bit
system, the tests run as a 32–bit application. For a 64–bit system, the tests run twice;
once as a 32–bit application and once as a 64–bit application.

amt lists test results with a "pass" or "fail" for each test it performs, unless output is
suppressed with the -s option.

OPTIONS The following option is supported:

s Suppresses output.

EXIT STATUS The following error values are returned:

0 All tests passed.
>0 Count of the number of tests that failed.
<0 Incorrect command line argument.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu (32-bit), SUNWcsxu (64-bit)

Interface Stability Evolving

SEE ALSO attributes(5)

User Commands 41
answerbook2(1)
NAME answerbook2 – online documentation system
SYNOPSIS /usr/dt/bin/answerbook2 [-h]

DESCRIPTION The AnswerBook2 server product is no longer included with Solaris or the Solaris
Documentation CD products. Solaris docmentation is now provided in HTML and
PDF format on the Documentation CD and does not require the AnswerBook2 server
to be viewed.

The answerbook2 utility opens the default web browser and displays an HTML page
that shows a link to locally installed documentation, and, if the AnswerBook2 server
has been defined, a link to AnswerBook2 collections.

To define a default AnswerBook2 server, use the environment variable,

AB2_DEFAULTSERVER.

This functionality is also accessible through the AnswerBook2 option on the CDE front
panel Help menu.

If you need an AnswerBook2 server, you can download the AnswerBook2 server
software from http://www.sun.com.

OPTIONS The following option is supported:

-h Displays a usage statement.
ENVIRONMENT AB2_DEFAULTSERVER Fully-qualified URL that identifies the default
VARIABLES AnswerBook2 server to use. For example:
http://imaserver.eng.sun.com:8888/

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability http://www.sun.com

SEE ALSO attributes(5)

NOTES Use the online Help system to find out more about the AnswerBook2 product, once
the web browser is opened and the AnswerBook2 library can be viewed.

42 man pages section 1: User Commands • Last Revised 29 Nov 2001

 appcert(1)
NAME appcert – examine application-level products for unstable use of Solaris interfaces
SYNOPSIS appcert [-h] [-n] [-f infile] [-w working_dir] [-B] [-L] [-S] {obj
| dir…}

DESCRIPTION The appcert utility examines an application’s conformance to the Solaris Application
Binary Interface (ABI). The Solaris ABI defines the runtime library interfaces in Solaris
that are safe and stable for application use. More specifically, appcert identifies any
dependencies on unstable runtime interfaces, as well as certain other risks that could
cause the product to fail to work on a subsequent release of Solaris.

appcert checks for:

■ Private symbol usage in Solaris libraries. These are private symbols, that is, functions
or data, that are not intended for developer consumption. They are interfaces that
Solaris libraries use to call one another. These symbols might change their semantic
behavior or even disappear altogether (so-called "demoted" symbols), so it is a
good practice to make sure your application does not depend upon any of them.
■ Static linking. In particular, this refers to static linking of archives libc.a,
libsocket.a, and libnsl.a, that is, instead of dynamically linking the
corresponding shared object .so’s. Because the semantics of private symbol calls
from one Solaris library to another can change from one release to another, it is not
a good practice to "hardwire" library code into your binary objects.
■ Unbound symbols. These are library symbols (that is, functions or data) that the
dynamic linker could not resolve when appcert was run. This might be an
environment problem (for example, LD_LIBRARY_PATH) or a build problem (for
example, not specifying -llib and/or -z defs with compiling). They are flagged
to point these problems out and in case a more serious problem is indicated.

An entire product can be readily examined by appcert (that is, if the product is a
collection of many programs and supporting shared objects) by referring appcert to
the directories where the product is installed.

To perform its task, appcert constructs a profile of interface dependencies for each
object file within the product (whether an executable object or shared object), to
determine all the Solaris system interfaces that are depended upon. (Notice that
appcert uses the Solaris runtime linker to make this determination.) These
dependency profiles are then compared to a definition of the Solaris ABI to identify
any interfaces that are Private (unsafe and unstable for application-level use).

appcert generates a simple roll-up report that indicates which of the product’s
components, if any, had liabilities and what those liabilities were. The report aids
developers who are examining their product’s release-to-release stability.

Notice that appcert produces complete interface dependency information, both the
Public (safe and stable) Solaris interfaces and the Private (non-ABI) interfaces. This
information can also be examined for each product component, if you want.

IMPORTANT: appcert must run in the same environment in which the application
being checked runs. See NOTES.

User Commands 43
appcert(1)
OPTIONS The following options are supported:
-B If appcert is run in "batch" mode, the output report will contain
one line per binary, beginning with PASS if no problems were
detected for the binary, FAIL if any problems were found, or INC
if the binary could not be completely checked. Do not interpret
these labels too literally. For example, PASS just means that none
of the appcert warnings were triggered. These strings are flush
left and so can be selected via grep ^FAIL ..., and so forth.
-f infile Specifies the file infile that contains a list of files (one per line) to
check. This list is appended to the list determined from the
command line operands (see OPERANDS below).
-h Prints out the usage information.
-L appcert examines your product for the presence of shared
objects. If it finds some, it appends the directories they reside in to
LD_LIBRARY_PATH. Use this flag to prevent appcert from doing
this.
-n When searching directories for binaries to check, this option does
not follow symbolic links. See find(1).
-S Appends Solaris library directories (that is,
/usr/openwin/lib:/usr/dt/lib) to LD_LIBRARY_PATH.
-w working_dir Identifies the directory in which to run the library components and
create temporary files (default is /tmp).

OPERANDS The following operands are supported:

{ obj | dir} ... A complete list of objects and/or directories that contain the
objects constituting the product to be checked. appcert
recursively searches directories looking for object files; non-object
files are ignored.

EXIT STATUS The following exit values are returned:

0 appcert ran successfully and found no potential binary stability
problems.
1 appcert failed to run successfully.
2 Some of the objects checked have potential binary stability problems.
3 No binary objects were located that could be checked.

LIMITATIONS If the object file to be examined depends on libraries, those dependencies must be
recorded in it (by using the compiler’s -l switch).

If the object file to be examined depends on other shared libraries, those libraries must
be accessible via LD_LIBRARY_PATH or RPATH when appcert is run.

44 man pages section 1: User Commands • Last Revised 15 Dec 2000

 appcert(1)
To check 64-bit applications, the machine must be running the 64-bit Solaris kernel.
See isalist(1). Also, the checks for static linking are currently not done on 64-bit
applications.

appcert cannot examine:

■ Object files that are completely or partially statically linked.

Completely statically linked objects are reported as unstable.

■ Executable files that do not have execute permission set.

These are skipped. Shared objects without execute permission are not skipped.
■ Object files that are setuid root.

Due to limitations in ldd(1), these are skipped. Copy and/or change the
permissions to check them.
■ Non-ELF file executables such as shell scripts.
■ Non-C language interfaces to Solaris; for example, C++ and Java.

The code itself need not be in C as long as the calls to Solaris libaries are in C.

OUTPUT FILES appcert records its findings in the following files in the working directory
(/tmp/appcert.????? by default):
Index A mapping between checked binaries and the subdirectory in the
working directory in which the output specific to that binary can
be found.
Report A copy of the rollup report that was displayed on stdout when
appcert was run.
Skipped A list of binaries that appcert was asked to check but had to skip,
along with a brief reason why each was skipped.

In addition, there is per-object information in the subdirectories under

appcert.?????/objects/, in the following files:
check.demoted_symbols A list of symbols suspected to be demoted Solaris
symbols.
check.dynamic.private A list of private Solaris symbols to which the object
makes direct bindings.
check.dynamic.public A list of public Solaris symbols to which the object
makes direct bindings.

User Commands 45
appcert(1)
check.dynamic.unbound A list of symbols not bound by the dynamic linker
when ldd -r was run. For convenience, ldd output
lines containing "file not found" are also included.
summary.dynamic A pretty-printed summary of dynamic bindings for the
objects examined, including tables of Public and
Private symbols used from each Solaris library.

Other files are temporary files used internally by appcert.

OUTPUT
MESSAGES
Private Symbol Private symbols are functions or data variables in a Solaris library that are not
Use intended for developer or external use. These symbols are interfaces that the Solaris
libraries use to call and communicate with one another. They are marked in pvs(1)
output with the symbol version name "SUNWprivate".

Private symbols can change their semantic behavior or even disappear altogether
("demoted" or "deprecated" symbols), so your application should not depend upon
any of them.

Demoted Symbols Demoted symbols are functions or data variables in a Solaris library that were once
private to that library and have been removed (or possibly scoped local to the library)
in a later Solaris release. If your application directly calls one of these demoted
symbols, it will fail to run (relocation error) on the release in which the symbol was
removed and releases thereafter.

In some rare cases, a demoted symbol will return in a later release, but nevertheless
there are still some releases on which the application will not run.

Sun Microsystems Inc. performed most of the library scoping in the transition from
Solaris 2.5.1 to 2.6. This action was done to increase binary stability. By making these
completely internal interfaces invisible (that is, they cannot be dynamically linked
against), a developer cannot accidentally or intentionally call these interfaces. For
more information, see the Linker and Libraries Guide, in particular the chapter on
versioning. This document may be found online at http://docs.sun.com.

Unbound Symbols Unbound symbols are library symbols (that is, functions or data) referenced by the
application that the dynamic linker could not resolve when appcert was run. Note:
appcert does not actually run your application, so some aspect of the environment
that affects dynamic linking might not be set properly.

Unbound symbols do not necessarily indicate a potential binary stability problem.

They only mean that when appcert was run, the runtime dynamic linker could not
resolve these symbols.

Unbound symbols might be due to LD_LIBRARY_PATH not being correctly set. Make
sure it is set, so that all of your binary objects can find all of the libraries they depend
on (either your product’s own libraries, Solaris libraries, or those of a third party).
Then re-run appcert.

46 man pages section 1: User Commands • Last Revised 15 Dec 2000

 appcert(1)
You might find it useful to write a shell script that sets up the environment correctly
and then runs appcert on the binaries you want to check.

Another common cause for unbound symbols is when a shared object under test has
not recorded its dynamic dependencies, that is, at build time the -l switch was not
supplied to the compiler and ld(1). So the shared object requires that the executables
that link against it have the correct dependencies recorded.

Notice that such a shared object can either be linked in the standard way (that is,
specified at an executable’s build time) or dynamically opened (for example, an
executable calls dlopen(3DL) on the shared object sometimes when running). Either
case can give rise to unbound symbols when appcert is run. The former can usually
be resolved by setting LD_LIBRARY_PATH appropriately before running appcert.
The latter (dlopen) is usually difficult to resolve. Under some circumstances, you
might be able to set LD_PRELOAD appropriately to preload the needed libraries, but
this procedure does not always work.

How do you know if the environment has been set up correctly so that there will be no
unbound symbols? It must be set up so that running ldd -r on the binary yields no
“file not found” or “symbol not found” errors. See ld.so.1(1) and ldd(1) for
more information on dynamic linking.

In any event, appcert flags unbound symbols as a warning in case they might
indicate a more serious problem. Unbound symbols can be an indicator of
dependencies on demoted symbols (symbols that have been removed from a library or
scoped local to it). Dependencies on demoted symbols will lead to serious binary
stability problems.

However, setting up the environment properly should remove most unbound

symbols. In general, it is good practice to record library dependencies at build time
whenever possible because it helps make the binary object better defined and
self-contained. Also recommended is using the -z defs flag when building shared
objects, to force the resolution of all symbols during compilation. See ld(1) for more
information.

No Bindings appcert runs /bin/ldd -r on each binary object to be tested. It sets the
Found environment variable LD_DEBUG=“files,bindings”. (See ldd(1) and ld.so.1(1)
for more information). If that command fails for some reason, appcert will have no
dynamic symbol binding information and will find “no bindings”.

appcert can fail if any of the following is true:

■ The binary object does not have read permission.
■ The binary object is SUID or SGID and the user does not have sufficient privileges.
■ The binary object is an executable without the execute permission bit set.
■ The binary object is a 64-bit application, but the kernel running on the current
machine supports only 32-bit applications.
■ The binary object is completely statically linked.

User Commands 47
appcert(1)
■ The binary object has no library dependency information recorded.

Other cases exist as well (for example, out of memory). In general, this flag means that
appcert could not completely examine the object due to permissions or environment.
Try to modify the permissions or environment so that the dynamic bindings can be
recorded.

Obsolete Library An obsolete library is one whose use is deprecated and that might, in some future
release, be removed from Solaris altogether. appcert flags these because applications
depending on them might not run in future releases of Solaris. All interfaces,
including Private ones, in an obsolete library are frozen and will not change.

Use of Direct use of the symbols sys_errlist or sys_nerr presents a risk in which
sys_errlist/sys_nerr reference might be made past the end of the sys_errlist array. These symbols are
deprecated in 32-bit versions of Solaris and are absent altogether in 64-bit versions.
Use strerror(3C) instead.

Use of Strong vs. The “strong” symbols (for example, _socket) associated with “weak” symbols (for
Weak Symbols example, socket ) are reserved as private (their behavior could change in the future).
Your application should only directly reference the weak symbol (usually the strong
symbols begin with “_”).

Note: Under certain build environments, the strong/private symbol dependency gets
recorded into your binary instead of the weak/public one, even though the source
code doesn’t appear to reference the private symbol. Nevertheless, steps should be
taken to trace down why this is occurring and fix the dependency.

NOTES appcert needs to run in the same environment in which the application being
checked runs. Otherwise it might not be able to resolve references correctly to
interfaces in the Solaris libraries. Take the following steps:
1. Make sure that LD_LIBRARY_PATH and any other aspects of the environment are
set to whatever settings are used when the application is run. Also make sure that
it contains the directories containing any non-Solaris shared objects that are part of
the product, so that they can be found when referenced.
2. Make sure that all the binaries to be checked:
■ Are dynamically linked ELF objects
■ Have execute permission set on executables (this is not necessary for shared
objects)
■ Are not SUID root (otherwise you will have to be root to check them; make
non-SUID copies and check those if necessary).

You might find it useful to write a shell script that sets up the environment correctly
and then runs appcert.

Some potential problems that can be encountered are:

■ appcert reports unbound symbols that appear to be part of Solaris libraries.

48 man pages section 1: User Commands • Last Revised 15 Dec 2000

 appcert(1)
This is probably caused when the application uses dlopen(3DL) to access a shared
object that does not have its Solaris dependencies recorded. appcert cannot
resolve symbol use in such cases, since the dynamic linker is never invoked on the
shared object, and there is no other dependency information that could be used to
resolve the Solaris symbol bindings. This can also occur with non-Solaris symbols.
To avoid this problem, make sure that when a shared object is built, its
dependencies on Solaris libraries are explicitly recorded by using the -llib option
on the compile line (see cc(1) and ld(1)).
■ appcert reports that the application uses a Solaris private symbol that is not
referenced in the application’s source code.
This problem is most likely due to static linking of a Solaris library that references
that symbol. Since appcert uses the dynamic linker to resolve symbols, statically
linked libraries appear to appcert to be part of the application code (which, in a
sense, they are). This can also sometimes happen as a result of macro substitution
in a Solaris header file.
To avoid this problem, whenever possible do not statically link Solaris library
archives into your application.
■ appcert does not recognize a library as part of Solaris.
Some obsolete Solaris libraries are so old that they were obsoleted before their
symbols could be versioned. Consequently, appcert cannot recognize them as
being part of Solaris.

BUGS The use of the terms “public” and “private” as equivalent to “stable” and
“unstable” is unfortunately somewhat confusing. In particular, experimental or
evolving interfaces are public in the sense that they are documented and their use is
encouraged. But they are unstable, because an application built with them might not
run on subsequent releases. Thus, they are classified as private for appcert’s
purposes until they are no longer evolving. Conversely, obsolete interfaces will
eventually disappear, and so are unstable, even though they have been public and
stable in the past and are still treated as public by appcert. Fortunately, these two
situations are rare.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWapct

Interface stability Stable

SEE ALSO cc(1), find(1), isalist(1), ld(1), ldd(1), ld.so.1(1), pvs(1), dlopen(3DL),
strerror(3C), intro(4), attributes(5)

Linker and Libraries Guide

User Commands 49
apptrace(1)
NAME apptrace – trace application function calls to Solaris shared libraries
SYNOPSIS apptrace [-f] [-F [!] tracefromlist] [-T [!] tracetolist] [-o outputfile]
[ [-tv] [!] call ,…] command [command arguments]

DESCRIPTION The apptrace utility runs the executable program specified by command and traces
all calls that the program command makes to the Solaris shared libraries. Tracing means
that for each call the program makes, apptrace reports the name of the library
interface called, the values of the arguments passed, and the return value.

By default, apptrace traces calls directly from the executable object to any of the
shared objects it depends on. Indirect calls (that is, calls made between shared objects
that the executable depends upon) are not reported by default.

Calls from or to additional shared objects may be traced using the -F or -T options
(see below).

The default reporting format is a single line per call, with no formatted printing of
arguments passed by reference or of data structures.

Formatted printing providing additional argument details is obtained using the -v

option (see below).

By default, every interface provided by a shared object is traced if called. However, the
set of interfaces to be traced can be restricted, using the -t and/or -v options.

Since it is generally possible to trace calls between any of the dynamic objects linked at
runtime (the executable object and any of the shared objects depended upon), the
report of each traced call gives the name of the object from which the call was made.

apptrace traces all of the procedure calls that occur between dynamic objects via the
procedure linkage table, so only those procedure calls which are bound via the table
will be traced. See the Linker and Libraries Guide.

OPTIONS The following options are supported:

-f Follows all children created by fork(2). This option
will also cause the process id to be printed at the
beginning of each line.
-F [!]tracefromlist Traces calls from a comma-separated list of shared
objects. Only calls from these shared objects will be
traced. The default is to trace calls from the main
executable only. Only the basename of the shared object
is required. For example, libc will match /usr/lib/libc.so.1.
Additionally, shell style wildcard characters are
supported as described in fnmatch(5). A list preceded
by a ‘‘!’’ defines a list of objects from which calls should
not be traced. If the tracing of calls from command is
required, then command must be a member of
tracefromlist.

50 man pages section 1: User Commands • Last Revised 12 Jul 2001

 apptrace(1)
-o outputfile apptrace output will be directed to the outputfile. By
default, apptrace output is placed on the stderr
stream of the process being traced.
-t [!]call, . . . Traces or excludes function calls. Those calls specified
in the comma-separated list call are traced. If the list
begins with a !, the specified function calls are excluded
from the trace output. The default is -t *. The use of
shell style wildcards is allowed.
-T [!]tracetolist Traces calls to a comma-separated list of shared objects.
The default is to trace calls to all shared objects. As
above, the basename is all that is required and
wildcarding is allowed. A list preceded by a ‘‘!’’
denotes a list of objects to which calls should not be
traced.
-v [!]call, . . . Provides verbose, formatted output of the arguments
and return values of the function calls specified (as
above in the -t option). Unlike truss(1), calls named
by the -v option do not have to be named by the -t
option. For example, apptrace -v open is equivalent
to truss -t open -v open.

EXAMPLES EXAMPLE 1 Tracing the date command

% apptrace date
date → libc.so.1:atexit(func = 0xff3ba1c8) = 0x0
date → libc.so.1:atexit(func = 0x117e4) = 0x0
date → libc.so.1:setlocale(category = 0x6, locale = "") = "C"
date → libc.so.1:textdomain(domainname =
"SUNW_OST_OSCMD") = "SUNW_OST_OSCMD"
date → libc.so.1:getopt(argc = 0x1, argv = 0xffbeed5c,
optstring = "a:u") = 0xffffffff errno = No error
date → libc.so.1:time(tloc = 0x21ecc) = 0x371397c3
date → libc.so.1:nl_langinfo(item = 0x3a) = "%a %b %e %T %Z %Y"
date → libc.so.1:localtime(clock = 0x21ecc) = 0xff03c928
date → libc_psr.so.1:memcpy(0xffbeeccc, 0xff03c928, 0x24)
date → libc.so.1:strftime(s = "Tue Apr 13 15:15:15 ",
maxsize = 0x400, format = "%a %b %e %T %Z %Y",
timeptr = 0xffbeeccc) = 0x1c
date → libc.so.1:puts(Tue Apr 13 15:15:15 EDT 1999
s = "Tue Apr 13 15:15:15 ") = 0x1d
date → libc.so.1:exit(status = 0)

EXAMPLE 2 Tracing a specific set of interfaces with verbosity set

% apptrace -v ’*gid*’ id -a
id → libc.so.1:getgid() = 0xa
return = (gid_t) 10 (0xa)
id → libc.so.1:getegid() = 0xa
return = (gid_t) 10 (0xa)
id → libc.so.1:getgrgid(gid = 0xa) = 0x2238c

User Commands 51
apptrace(1)
EXAMPLE 2 Tracing a specific set of interfaces with verbosity set (Continued)

gid = (gid_t) 10 (0xa)

return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223a0 "staff"
gr_passwd: (char *) 0x223a6 ""
gr_gid: (gid_t) 10 (0xa)
gr_mem: (char **) 0x2239c
}

id → libc.so.1:getgrgid(gid = 0xa) = 0x2238c

gid = (gid_t) 10 (0xa)
return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223a0 "staff"
gr_passwd: (char *) 0x223a6 ""
gr_gid: (gid_t) 10 (0xa)
gr_mem: (char **) 0x2239c
}

id → libc.so.1:getgrgid(gid = 0x3) = 0x2238c

gid = (gid_t) 3 (0x3)
return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223b4 "sys"
gr_passwd: (char *) 0x223b8 ""
gr_gid: (gid_t) 3 (0x3)
gr_mem: (char **) 0x2239c
}

id → libc.so.1:getgrgid(gid = 0x29) = 0x2238c

gid = (gid_t) 41 (0x29)
return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223a4 "opcom"
gr_passwd: (char *) 0x223aa ""
gr_gid: (gid_t) 41 (0x29)
gr_mem: (char **) 0x2239c
}

id → libc.so.1:getgrgid(gid = 0xe) = 0x2238c

gid = (gid_t) 14 (0xe)
return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223a0 "sysadmin"
gr_passwd: (char *) 0x223a9 ""
gr_gid: (gid_t) 14 (0xe)
gr_mem: (char **) 0x2239c
}

id → libc.so.1:getgrgid(gid = 0xd3) = 0x2238c

gid = (gid_t) 211 (0xd3)
return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223a8 "test"
gr_passwd: (char *) 0x223ad ""
gr_gid: (gid_t) 211 (0xd3)
gr_mem: (char **) 0x2239c
}

uid=44013(georgn) gid=10(staff) groups=10(staff),3(sys),

52 man pages section 1: User Commands • Last Revised 12 Jul 2001

 apptrace(1)
EXAMPLE 2 Tracing a specific set of interfaces with verbosity set (Continued)

41(opcom),14(sysadmin),211(test)

FILES Basic runtime support for apptrace is provided by the link auditing feature of the
Solaris runtime linker (ld.so.1(1)) and the apptrace command’s use of this facility
relies on an auditing object (apptrace.so.1) kept in /usr/lib/abi.

In order to perform formatted printing of arguments when tracing calls (as selected by
the -v option), apptrace needs to know the number and data types of the arguments
supplied to the called interface. Special runtime support shared objects are provided
which apptrace relies upon to perform formatted printing. A runtime support object
is provided for each Solaris shared library, which contains an "interceptor" function for
each interface within the shared library. These supporting shared objects are kept in
/usr/lib/abi. apptrace has a simple algorithm to map from the name of a library
interface to the name of an interceptor function in the library’s supporting
verbose-tracing shared object. If an interceptor is not found in the library’s supporting
tracing shared object, apptrace cannot determine either the number or data types of
the arguments for that interface. In this case, apptrace uses a default output format
for the call-tracing report (hex-formatted printing of the first three arguments).

LIMITATIONS In general, apptrace cannot trace calls to functions accepting variable argument lists.
There has been some clever coding in several specific cases to work around this
limitation, most notably in the printf and scanf families.

Functions that attempt to probe the stack or otherwise extract information about the
caller cannot be traced. Some examples are [gs]etcontext(), [sig]longjmp(),
[sig]setjmp(), and vfork().

Functions such as exit(2) that do not return may also produce strange output. Also,
functions that call other traced functions before returning will produce slightly
garbled output.

For security reasons, only root can apptrace setuid/setgid programs.

Tracing functions whose usage requires the inclusion of varargs.h, such as

vwprintw(3XCURSES) and vwscanw(3XCURSES), will not provide formatted
printing of arguments.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcstl (32–bit)

SUNWcstlx (64–bit)

User Commands 53
apptrace(1)
SEE ALSO ld.so.1(1), truss(1), vwprintw(3XCURSES), vwscanw(3XCURSES),
attributes(5), fnmatch(5)

Linker and Libraries Guide

54 man pages section 1: User Commands • Last Revised 12 Jul 2001

 apropos(1)
NAME apropos – locate commands by keyword lookup
SYNOPSIS apropos keyword…

DESCRIPTION The apropos utility displays the man page name, section number, and a short
description for each man page whose NAME line contains keyword. This information is
contained in the /usr/share/man/windex database created by catman(1M). If
catman(1M) was not run, or was run with the -n option, apropos fails. Each word is
considered separately and the case of letters is ignored. Words which are part of other
words are considered; for example, when looking for ‘compile’, apropos finds all
instances of ‘compiler’ also.

apropos is actually just the -k option to the man(1) command.

EXAMPLES EXAMPLE 1 To find a man page whose NAME line contains a keyword

Try
example% apropos password

and
example% apropos editor

If the line starts ‘filename(section) . . .’ you can run

man -s section filename
to display the man page for filename.

EXAMPLE 2 To find the man page for the subroutine printf()

Try
example% apropos format

and then
example% man -s 3s printf

to get the manual page on the subroutine printf().

FILES /usr/share/man/windex table of contents and keyword database

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWdoc

CSI Enabled

SEE ALSO man(1), whatis(1), catman(1M), attributes(5)

User Commands 55
apropos(1)
DIAGNOSTICS /usr/share/man/windex: No such file or directory
This database does not exist. catman(1M) must be run to create it.

56 man pages section 1: User Commands • Last Revised 20 Dec 1996

 ar(1)
NAME ar – maintain portable archive or library
SYNOPSIS /usr/ccs/bin/ar -d [-Vv] archive file…
/usr/ccs/bin/ar -m [-abiVv] [posname] archive file…
/usr/ccs/bin/ar -p [-sVv] archive [file…]
/usr/ccs/bin/ar -q [-cVv] archive file…
/usr/ccs/bin/ar -r [-abciuVv] [posname] archive file…
/usr/ccs/bin/ar -t [-sVv] archive [file…]
/usr/ccs/bin/ar -x [-CsTVv] archive [file…]
/usr/xpg4/bin/ar -d [-Vv] archive file…
/usr/xpg4/bin/ar -m [-abiVv] [posname] archive file…
/usr/xpg4/bin/ar -p [-sVv] archive [file…]
/usr/xpg4/bin/ar -q [-cVv] archive file…
/usr/xpg4/bin/ar -r [-abciuVv] [posname] archive file…
/usr/xpg4/bin/ar -t [-sVv] archive [file…]
/usr/xpg4/bin/ar -x [-CsTVv] archive [file…]

DESCRIPTION The ar utility maintains groups of files combined into a single archive file. Its main
use is to create and update library files. However, it can be used for any similar
purpose. The magic string and the file headers used by ar consist of printable ASCII
characters. If an archive is composed of printable files, the entire archive is printable.

When ar creates an archive, it creates headers in a format that is portable across all
machines. The portable archive format and structure are described in detail in
ar(3HEAD). The archive symbol table (described in ar(3HEAD)) is used by the link
editor ld(1) to effect multiple passes over libraries of object files in an efficient manner.
An archive symbol table is only created and maintained by ar when there is at least
one object file in the archive. The archive symbol table is in a specially named file that
is always the first file in the archive. This file is never mentioned or accessible to the
user. Whenever the ar command is used to create or update the contents of such an
archive, the symbol table is rebuilt. The -s option described below will force the
symbol table to be rebuilt.

OPTIONS The following options are supported:

-a Positions new files in archive after the file named by the posname operand.
-b Positions new files in archive before the file named by the posname operand.
-c Suppresses the diagnostic message that is written to standard error by
default when archive is created.

User Commands 57
ar(1)
-C Prevents extracted files from replacing like-named files in the file system.
This option is useful when -T is also used to prevent truncated file names
from replacing files with the same prefix.
-d Deletes one or more files from archive.
-i Positions new files in archive before the file named by the posname operand
(equivalent to -b).
-m Moves files. If -a, -b, or -i with the posname operand are specified, moves
files to the new position; otherwise, moves files to the end of archive.
-p Prints the contents of files in archive to standard output. If no files are
specified, the contents of all files in archive will be written in the order of
the archive.
-q Quickly appends files to the end of archive. Positioning options -a, -b, and
-i are invalid. The command does not check whether the added files are
already in archive. This option is useful to avoid quadratic behavior when
creating a large archive piece-by-piece.
-r Replaces or adds files in archive. If archive does not exist, a new archive file
will be created and a diagnostic message will be written to standard error
(unless the -c option is specified). If no files are specified and the archive
exists, the results are undefined. Files that replace existing files will not
change the order of the archive. If the -u option is used with the -r option,
then only those files with dates of modification later than the archive files
are replaced. If the -a, -b, or -i option is used, then the posname argument
must be present and specifies that new files are to be placed after (-a) or
before (-b or -i) posname; otherwise the new files are placed at the end.
-s Forces the regeneration of the archive symbol table even if ar is not
invoked with an option that will modify the archive contents. This
command is useful to restore the archive symbol table after the strip(1)
command has been used on the archive.
-t Prints a table of contents of archive. The files specified by the file operands
will be included in the written list. If no file operands are specified, all files
in archive will be included in the order of the archive.
-T Allows file name truncation of extracted files whose archive names are
longer than the file system can support. By default, extracting a file with a
name that is too long is an error; a diagnostic message will be written and
the file will not be extracted.
-u Updates older files. When used with the -r option, files within archive will
be replaced only if the corresponding file has a modification time that is at
least as new as the modification time of the file within archive.
-V Prints its version number on standard error.
/usr/ccs/bin/ar -v Gives verbose output. When used with the option characters -d, -r, or -x,
writes a detailed file-by-file description of the archive creation and the

58 man pages section 1: User Commands • Last Revised 15 Feb 2002

 ar(1)
constituent files, and maintenance activity. When used with -p, writes the
name of the file to the standard output before writing the file itself to the
standard output. When used with -t, includes a long listing of information
about the files within the archive. When used with -x, prints the filename
preceding each extraction. When writing to an archive, a message is written
to the standard error.
/usr/xpg4/bin/ar -v Same as /usr/ccs/bin/ar version, except when writing to an archive,
no message is written to the standard error.
-x Extracts the files named by the file operands from archive. The contents of
archive will not be changed. If no file operands are given, all files in archive
will be extracted. If the file name of a file extracted from archive is longer
than that supported in the directory to which it is being extracted, the
results are undefined. The modification time of each file extracted will be
set to the time file is extracted from archive.

OPERANDS The following operands are supported:

archive A path name of the archive file.
file A path name. Only the last component will be used when
comparing against the names of files in the archive. If two or more
file operands have the same last path name component (
basename(1)), the results are unspecified. The implementation’s
archive format will not truncate valid file names of files added to
or replaced in the archive.
posname The name of a file in the archive file, used for relative positioning;
see options -m and -r.

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of ar: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, LC_TIME, and NLSPATH.
TMPDIR Determine the pathname that overrides the default directory for
temporary files, if any.
TZ Determine the timezone used to calculate date and time strings
written by ar -tv. If TZ is unset or null, an unspecified default
timezone shall be used.

EXIT STATUS The following exit values are returned:

0 Successful completion.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

User Commands 59
ar(1)
/usr/ccs/bin/ar ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWbtool

/usr/xpg4/bin/ar ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWxcu4

Interface Stability Standard

SEE ALSO basename(1), cc(1B), cpio(1), ld(1), lorder(1), strip(1), tar(1), ar(3HEAD),
a.out(4), attributes(5), environ(5), standards(5)

NOTES If the same file is mentioned twice in an argument list, it may be put in the archive
twice.

By convention, archives are suffixed with the characters .a.

60 man pages section 1: User Commands • Last Revised 15 Feb 2002

 arch(1)
NAME arch – display the architecture of the current host
SYNOPSIS arch [-k | archname]

DESCRIPTION arch displays the application architecture of the current host system. Due to extensive
historical use of this command without any options, all SunOS 5.x SPARC based
systems will return "sun4" as their application architecture. Use of this command is
discouraged; see NOTES section below.

Systems can be broadly classified by their architectures, which define what executables
will run on which machines. A distinction can be made between kernel architecture
and application architecture (or, commonly, just “architecture”). Machines that run
different kernels due to underlying hardware differences may be able to run the same
application programs.
OPTIONS -k Display the kernel architecture, such as sun4m, sun4c, and so forth. This
defines which specific SunOS kernel will run on the machine, and has
implications only for programs that depend on the kernel explicitly (for
example, ps(1)).

OPERANDS The following operand is supported:

archname Use archname to determine whether the application binaries for
this application architecture can run on the current host system.
The archname must be a valid application architecture, such as
sun4, i86pc, and so forth.

If application binaries for archname can run on the current host

system, TRUE (0) is returned; otherwise, FALSE (1) is returned.

EXIT STATUS The following exit values are returned:

0 Successful completion.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO mach(1), ps(1), uname(1), attributes(5)

NOTES This command is provided for compatibility with previous releases and its use is
discouraged. Instead, the uname command is recommended. See uname(1) for usage
information.

User Commands 61
as(1)
NAME as – assembler

SYNOPSIS
Sparc as [-b] [-K PIC] [-L] [-m] [-n] [-o outfile] [-P] [-Dname] [-Dname=def]
[-Ipath] [-Uname…] [-q] [-Qy | n] [-s] [-S [a | b | c | l | A | B
| C | L]] [-T] [-V]
[-xarch=v7 | -xarch=v8 | -xarch=v8a | -xarch=v8plus | -xarch=v8plusa | -xarc
[-xF] filename…
x86 as [-b] [-K PIC] [-L] [-m] [-n] [-o outfile] [-P] [-Dname] [-Dname=def]
[-Ipath] [-Uname…] [-Qy | n] [-s] [-S [a | b | c | l | A | B | C
| L]] [-T] [-V] filename…

DESCRIPTION The as command creates object files from assembly language source files.

OPTIONS

Common Options The following flags are common to both SPARC and x86. They may be specified in any
order:
-b Generates extra symbol table information for the Sun
SourceBrowser.
-K PIC Generates position-independent code.
-L Saves all symbols, including temporary labels that are
normally discarded to save space, in the ELF symbol
table.
-m Runs the m4(1) macro processor on the input to the
assembler.
-n Suppresses all the warnings while assembling.
-o outfile Puts the output of the assembly in outfile. By default,
the output file name is formed by removing the .s
suffix, if there is one, from the input file name and
appending a .o suffix.
-P Runs cpp(1), the C preprocessor, on the files being
assembled. The preprocessor is run separately on each
input file, not on their concatenation. The preprocessor
output is passed to the assembler.
-Dname
-Dname=def When the -P option is in effect, these options are
passed to the cpp(1) preprocessor without
interpretation by the as command; otherwise, they are
ignored.

62 man pages section 1: User Commands • Last Revised 15 Apr 2002

 as(1)
-Ipath When the -P option is in effect, this option is passed to
the cpp(1) preprocessor without interpretation by the
as command; otherwise, it is ignored.
-Uname When the -P option is in effect, this option is passed to
the cpp(1) preprocessor without interpretation by the
as command; otherwise, it is ignored.
-Qy | n If y is specified, this option produces the "assembler
version" information in the comment section of the
output object file. If n is specified, the information is
suppressed.
-s Places all stabs in the .stabs section. By default, stabs
are placed in stabs.excl sections, which are stripped
out by the static linker, ld(1), during final execution.
When the -s option is used, stabs remain in the final
executable because .stab sections are not stripped by
the static linker.
-S[a|b|c|l|A|B|C|L] Produces a disassembly of the emitted code to the
standard output. Adding each of the following
characters to the -S option produces:
a disassembling with address
b disassembling with “.bof”
c disassembling with comments
l disassembling with line numbers

Capital letters turn the switch off for the corresponding

option.
-T This is a migration option for 4.x assembly files to be
assembled on 5.x systems. With this option, the symbol
names in 4.x assembly files will be interpreted as 5.x
symbol names.
-V Writes the version number of the assembler being run
on the standard error output.
-xF Allows function reordering by the Performance
Analyzer. If you compile with the -xF option, and then
run the Performance Analyzer, you can generate a map
file that shows an optimized order for the functions.
The subsequent link to build the executable file can be
directed to use that map file by using the linker -M
mapfile option. It places each function from the
executable file into a separate section.

User Commands 63
as(1)
Options for -q Performs a quick assembly. When the -q option is
SPARC only used, many error checks are not performed. Note: This
option disables many error checks. Use of this option to
assemble handwritten assembly language is not
recommended.
-xarch=v7 This option instructs the assembler to accept
instructions defined in the SPARC version 7 (V7)
architecture. The resulting object code is in ELF format.
-xarch=v8 This option instructs the assembler to accept
instructions defined in the SPARC-V8 architecture, less
the quad-precision floating-point instructions. The
resulting object code is in ELF format.
-xarch=v8a This option instructs the assembler to accept
instructions defined in the SPARC-V8 architecture, less
the quad-precision floating-point instructions and less
the fsmuld instruction. The resulting object code is in
ELF format. This is the default choice of the
-xarch=options.
-xarch=v8plus This option instructs the assembler to accept
instructions defined in the SPARC-V9 architecture, less
the quad-precision floating-point instructions. The
resulting object code is in ELF format. It will not
execute on a Solaris V8 system (a machine with a V8
processor). It will execute on a Solaris V8+ system. This
combination is a SPARC 64–bit processor and a 32–bit
OS.
-xarch=v8plusa This option instructs the assembler to accept
instructions defined in the SPARC-V9 architecture, less
the quad-precision floating-point instructions, plus the
instructions in the Visual Instruction Set (VIS). The
resulting object code is in V8+ ELF format. It will not
execute on a Solaris V8 system (a machine with a V8
processor). It will execute on a Solaris V8+ system
-xarch=v9 This option limits the instruction set to the SPARC-V9
architecture. The resulting .o object files are in 64-bit
ELF format and can only be linked with other object
files in the same format. The resulting executable can
only be run on a 64-bit SPARC processor running 64-bit
Solaris with the 64–bit kernel.
-xarch=v9a This option limits the instruction set to the SPARC-V9
architecture, adding the Visual Instruction Set (VIS)
and extensions specific to UltraSPARC processors. The
resulting .o object files are in 64-bit ELF format and can

64 man pages section 1: User Commands • Last Revised 15 Apr 2002

 as(1)
only be linked with other object files in the same
format. The resulting executable can only be run on a
64-bit SPARC processor running 64-bit Solaris with the
64–bit kernel.

OPERANDS The following operand is supported:

filename Assembly language source file
ENVIRONMENT TMPDIR The as command normally creates temporary files in the directory
VARIABLES /tmp. Another directory may be specified by setting the
environment variable TMPDIR to the chosen directory. (If TMPDIR
is not a valid directory, then as will use /tmp).

FILES By default, as creates its temporary files in /tmp.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWsprot

SEE ALSO cc(1B), cpp(1),ld(1), m4(1), nm(1), strip(1), tmpnam(3C), a.out(4), attributes(5)

dbx and analyzer manual pages available with Forte Developer

NOTES If the -m option, which invokes the m4(1) macro processor, is used, keywords for m4
cannot be used as symbols (variables, functions, labels) in the input file, since m4
cannot determine which keywords are assembler symbols and which keywords are
real m4 macros.

Whenever possible, access the assembler through a compilation system interface

program such as cc(1B).

All undefined symbols are treated as global.

User Commands 65
asa(1)
NAME asa – convert FORTRAN carriage-control output to printable form
SYNOPSIS asa [-f] [file…]

DESCRIPTION The asa utility will write its input files to standard output, mapping carriage-control
characters from the text files to line-printer control sequences.

The first character of every line will be removed from the input, and the following
actions will be performed.

If the character removed is:

SPACE The rest of the line will be output without change.
0 It is replaced by a newline control sequence followed by the rest of the
input line.
1 It is replaced by a newpage control sequence followed by the rest of the
input line.
+ It is replaced by a control sequence that causes printing to return to the first
column of the previous line, where the rest of the input line is printed.

For any other character in the first column of an input line, asa skips the character
and prints the rest of the line unchanged.

If asa is called without providing a filename, the standard input is used.

OPTIONS The following option is supported:

-f Start each file on a new page.

OPERANDS The following operand is supported:

file A pathname of a text file used for input. If no file operands are specified,
or ‘ − ’ is specified, then the standard input will be used.

EXAMPLES The command

a.out | asa | lp

converts output from a.out to conform with conventional printers and directs it
through a pipe to the printer.

The command
asa output

shows the contents of file output on a terminal as it would appear on a printer.

The following program is used in the next two examples:

write(*,’(" Blank")’)
write(*,’("0Zero ")’)
write(*,’("+ Plus ")’)

66 man pages section 1: User Commands • Last Revised 18 Apr 1995

 asa(1)
write(*,’("1One ")’)
end

Both of the following examples produce two pages of output:

Page 1:
Blank

ZeroPlus

Page 2:
One

EXAMPLE 1 Using actual files

a.out > MyOutputFile
asa < MyOutputFile | lp

EXAMPLE 2 Using only pipes

a.out | asa | lp

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of asa: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

EXIT STATUS The following exit values are returned:

0 All input files were output successfully.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

Interface Stability Standard

SEE ALSO lp(1), attributes(5), environ(5), standards(5)

User Commands 67
at(1)
NAME at, batch – execute commands at a later time
SYNOPSIS at [-c | -k | -s] [-m] [-f file] [-p project] [-q queuename] -t time
at [-c | -k | -s] [-m] [-f file] [-p project] [-q queuename] timespec…
at -l [-p project] [-q queuename] [at_job_id. ..]
at -r at_job_id. ..
batch [-p project]

DESCRIPTION

at The at utility reads commands from standard input and groups them together as an
at-job, to be executed at a later time.

The at-job will be executed in a separate invocation of the shell, running in a separate
process group with no controlling terminal, except that the environment variables,
current working directory, file creation mask (see umask(1)), and system resource
limits (for sh and ksh only, see ulimit(1)) in effect when the at utility is executed
will be retained and used when the at-job is executed.

When the at-job is submitted, the at_job_id and scheduled time are written to standard
error. The at_job_id is an identifier that will be a string consisting solely of
alphanumeric characters and the period character. The at_job_id is assigned by the
system when the job is scheduled such that it uniquely identifies a particular job.

User notification and the processing of the job’s standard output and standard error
are described under the -m option.

Users are permitted to use at and batch (see below) if their name appears in the file
/usr/lib/cron/at.allow. If that file does not exist, the file
/usr/lib/cron/at.deny is checked to determine if the user should be denied
access to at. If neither file exists, only a user with the solaris.jobs.user
authorization is allowed to submit a job. If only at.deny exists and is empty, global
usage is permitted. The at.allow and at.deny files consist of one user name per
line.

cron and at jobs will be not be executed if the user’s account is locked. Only accounts
which are not locked as defined in shadow(4) will have their job or process executed.

batch The batch utility reads commands to be executed at a later time. It is the equivalent
of the command:
at −q b −m now
where queue b is a special at queue, specifically for batch jobs. Batch jobs will be
submitted to the batch queue for immediate execution.

OPTIONS The following options are supported. If the -c, -k, or -s options are not specified, the
SHELL environment variable by default determines which shell to use.
-c C shell. csh(1) is used to execute the at-job.

68 man pages section 1: User Commands • Last Revised 11 Jan 2002

 at(1)
-k Korn shell. ksh(1) is used to execute the at-job.
-s Bourne shell. sh(1) is used to execute the at-job.
-f file Specifies the path of a file to be used as the source of the at-job,
instead of standard input.
-l (The letter ell.) Reports all jobs scheduled for the invoking user if
no at_job_id operands are specified. If at_job_ids are specified,
reports only information for these jobs.
-m Sends mail to the invoking user after the at-job has run,
announcing its completion. Standard output and standard error
produced by the at-job will be mailed to the user as well, unless
redirected elsewhere. Mail will be sent even if the job produces no
output.

If -m is not used, the job’s standard output and standard error will
be provided to the user by means of mail, unless they are
redirected elsewhere; if there is no such output to provide, the user
is not notified of the job’s completion.
-p project Specifies under which project the at or batch job will be run.
When used with the -l option, limits the search to that particular
project. Values for project will be interpreted first as a project name,
and then as a possible project ID, if entirely numeric. By default,
the user’s current project is used.
-q queuename Specifies in which queue to schedule a job for submission. When
used with the -l option, limits the search to that particular queue.
Values for queuename are limited to the lower case letters a through
z. By default, at-jobs will be scheduled in queue a. In contrast,
queue b is reserved for batch jobs. Since queue c is reserved for
cron jobs, it can not be used with the -q option.
-r at_job_id Removes the jobs with the specified at_job_id operands that were
previously scheduled by the at utility.
-t time Submits the job to be run at the time specified by the time
option-argument, which must have the format as specified by the
touch(1) utility.

OPERANDS The following operands are supported:

at_job_id The name reported by a previous invocation of the at utility at the
time the job was scheduled.
timespec Submit the job to be run at the date and time specified. All of the
timespec operands are interpreted as if they were separated by
space characters and concatenated. The date and time are

User Commands 69
at(1)
interpreted as being in the timezone of the user (as determined by
the TZ variable), unless a timezone name appears as part of time
below.

In the "C" locale, the following describes the three parts of the time
specification string. All of the values from the LC_TIME categories
in the "C" locale are recognized in a case-insensitive manner.
time The time can be specified as one, two or four
digits. One- and two-digit numbers are taken
to be hours, four-digit numbers to be hours
and minutes. The time can alternatively be
specified as two numbers separated by a colon,
meaning hour:minute. An AM/PM indication
(one of the values from the am_pm keywords in
the LC_TIME locale category) can follow the
time; otherwise, a 24-hour clock time is
understood. A timezone name of GMT, UCT, or
ZULU (case insensitive) can follow to specify
that the time is in Coordinated Universal Time.
Other timezones can be specified using the TZ
environment variable. The time field can also
be one of the following tokens in the "C" locale:
midnight Indicates the time 12:00 am (00:00).
noon Indicates the time 12:00 pm.
now Indicate the current day and time.
Invoking at now will submit an
at-job for potentially immediate
execution (that is, subject only to
unspecified scheduling delays).
date An optional date can be specified as either a
month name (one of the values from the mon
or abmon keywords in the LC_TIME locale
category) followed by a day number (and
possibly year number preceded by a comma)
or a day of the week (one of the values from
the day or abday keywords in the LC_TIME
locale category). Two special days are
recognized in the "C" locale:
today Indicates the current day.
tomorrow Indicates the day following the
current day.

70 man pages section 1: User Commands • Last Revised 11 Jan 2002

 at(1)
If no date is given, today is assumed if the
given time is greater than the current time, and
tomorrow is assumed if it is less. If the given
month is less than the current month (and no
year is given), next year is assumed.
increment The optional increment is a number preceded
by a plus sign (+) and suffixed by one of the
following: minutes, hours, days, weeks,
months, or years. (The singular forms will be
also accepted.) The keyword next is
equivalent to an increment number of + 1. For
example, the following are equivalent
commands:
at 2pm + 1 week
at 2pm next week

USAGE The format of the at command line shown here is guaranteed only for the "C" locale.
Other locales are not supported for midnight, noon, now, mon, abmon, day, abday,
today, tomorrow, minutes, hours, days, weeks, months, years, and next.

Since the commands run in a separate shell invocation, running in a separate process
group with no controlling terminal, open file descriptors, traps and priority inherited
from the invoking environment are lost.

EXAMPLES

at EXAMPLE 1 Typical sequence at a terminal

This sequence can be used at a terminal:

$ at −m 0730 tomorrow
sort < file >outfile
<EOT>

EXAMPLE 2 Redirecting output

This sequence, which demonstrates redirecting standard error to a pipe, is useful in a

command procedure (the sequence of output redirection specifications is significant):
$ at now + 1 hour <<!
diff file1 file2 2>&1 >outfile | mailx mygroup

EXAMPLE 3 Self-rescheduling a job

To have a job reschedule itself, at can be invoked from within the at-job. For example,
this "daily-processing" script named my.daily will run every day (although
crontab is a more appropriate vehicle for such work):

User Commands 71
at(1)
EXAMPLE 3 Self-rescheduling a job (Continued)

# my.daily runs every day

at now tomorrow < my.daily
daily-processing

EXAMPLE 4 Various time and operand presentations

The spacing of the three portions of the "C" locale timespec is quite flexible as long as
there are no ambiguities. Examples of various times and operand presentations
include:
at 0815am Jan 24
at 8 :15amjan24
at now "+ 1day"
at 5 pm FRIday
at ’17
utc+
30minutes’

batch EXAMPLE 5 Typical sequence at a terminal

This sequence can be used at a terminal:

$ batch
sort <file >outfile
<EOT>

EXAMPLE 6 Redirecting output

This sequence, which demonstrates redirecting standard error to a pipe, is useful in a

command procedure (the sequence of output redirection specifications is significant):
$ batch <<!
diff file1 file2 2>&1 >outfile | mailx mygroup
!

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of at and batch: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, NLSPATH, and
LC_TIME.
DATEMSK If the environment variable DATEMSK is set, at will use its value as
the full path name of a template file containing format strings. The
strings consist of format specifiers and text characters that are used
to provide a richer set of allowable date formats in different
languages by appropriate settings of the environment variable
LANG or LC_TIME. The list of allowable format specifiers is located
in the getdate(3C) manual page. The formats described in the
OPERANDS section for the time and date arguments, the special
names noon, midnight, now, next, today, tomorrow, and the
increment argument are not recognized when DATEMSK is set.

72 man pages section 1: User Commands • Last Revised 11 Jan 2002

 at(1)
SHELL Determine a name of a command interpreter to be used to invoke
the at-job. If the variable is unset or NULL, sh will be used. If it is
set to a value other than sh, the implementation will use that shell;
a warning diagnostic will be printed telling which shell will be
used.
TZ Determine the timezone. The job will be submitted for execution at
the time specified by timespec or -t time relative to the timezone
specified by the TZ variable. If timespec specifies a timezone, it will
override TZ. If timespec does not specify a timezone and TZ is unset
or NULL, an unspecified default timezone will be used.

EXIT STATUS The following exit values are returned:

0 The at utility successfully submitted, removed or listed a job or jobs.
>0 An error occurred, and the job will not be scheduled.
FILES /usr/lib/cron/at.allow names of users, one per line, who are
authorized access to the at and batch
utilities
/usr/lib/cron/at.deny names of users, one per line, who are
denied access to the at and batch utilities

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

at ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

CSI Not enabled

Interface Stability Standard

batch ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

CSI Enabled

Interface Stability Standard

SEE ALSO auths(1), crontab(1), csh(1), date(1), ksh(1), sh(1), touch(1), ulimit(1),
umask(1), cron(1M), getdate(3C), auth_attr(4), shadow(4), attributes(5),
environ(5), standards(5)

NOTES Regardless of queue used, cron(1M) has a limit of 100 jobs in execution at any time.

User Commands 73
at(1)
There can be delays in cron at job execution. In some cases, these delays can
compound to the point that cron job processing appears to be hung. All jobs will be
executed eventually. When the delays are excessive, the only workaround is to kill and
restart cron.

74 man pages section 1: User Commands • Last Revised 11 Jan 2002

 atq(1)
NAME atq – display the jobs queued to run at specified times
SYNOPSIS atq [-c] [-n] [username…]

DESCRIPTION The atq utility displays the at jobs queued up for the current user. at(1) is a utility
that allows users to execute commands at a later date. If invoked by a user with the
solaris.jobs.admin authorization, atq will display all jobs in the queue.

If no options are given, the jobs are displayed in chronological order of execution.

When an authorized user invokes atq without specifying username, the entire queue is
displayed; when a username is specified, only those jobs belonging to the named user
are displayed.

OPTIONS The following options are supported:

-c Displays the queued jobs in the order they were created (that is, the time
that the at command was given).
-n Displays only the total number of jobs currently in the queue.
FILES /var/spool/cron/atjobs spool area for at jobs.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO at(1), atrm(1), auths(1), cron(1M), auth_attr(4), attributes(5)

User Commands 75
atrm(1)
NAME atrm – remove jobs spooled by at or batch
SYNOPSIS atrm [-afi] [ [job #] [user…]]

DESCRIPTION The atrm utility removes delayed-execution jobs that were created with the at(1)
command, but have not yet executed. The list of these jobs and associated job numbers
can be displayed by using atq(1).

atrm removes each job-number you specify, and/or all jobs belonging to the user you
specify, provided that you own the indicated jobs.

You can only remove jobs belonging to other users if you have
solaris.jobs.admin privileges.

OPTIONS The following options are supported:

-a All. Removes all unexecuted jobs that were created by the current user. If
invoked by the privileged user, the entire queue will be flushed.
-f Force. All information regarding the removal of the specified jobs is
suppressed.
-i Interactive. atrm asks if a job should be removed. If you respond with a y,
the job will be removed.
FILES /var/spool/cron/atjobs spool area for at jobs

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO at(1), atq(1), auths(1), cron(1M), auth_attr(4), attributes(5)

76 man pages section 1: User Commands • Last Revised 13 Aug 1999

 audioconvert(1)
NAME audioconvert – convert audio file formats
SYNOPSIS audioconvert [-pF] [-f outfmt] [-o outfile] [ [-i infmt] [file…]] …

DESCRIPTION audioconvert converts audio data between a set of supported audio encodings and
file formats. It can be used to compress and decompress audio data, to add audio file
headers to raw audio data files, and to convert between standard data encodings, such
as -law and linear PCM.

If no filenames are present, audioconvert reads the data from the standard input
stream and writes an audio file to the standard output. Otherwise, input files are
processed in order, concatenated, and written to the output file.

Input files are expected to contain audio file headers that identify the audio data
format. If the audio data does not contain a recognizable header, the format must be
specified with the -i option, using the rate, encoding, and channels keywords to
identify the input data format.

The output file format is derived by updating the format of the first input file with the
format options in the -f specification. If -p is not specified, all subsequent input files
are converted to this resulting format and concatenated together. The output file will
contain an audio file header, unless format=raw is specified in the output format
options.

Input files may be converted in place by using the -p option. When -p is in effect, the
format of each input file is modified according to the -f option to determine the
output format. The existing files are then overwritten with the converted data.

The file(1) command decodes and prints the audio data format of Sun audio files.

OPTIONS The following options are supported:

-p In Place: The input files are individually converted to the format
specified by the -f option and rewritten. If a target file is a
symbolic link, the underlying file will be rewritten. The -o option
may not be specified with -p.
-F Force: This option forces audioconvert to ignore any file header
for input files whose format is specified by the -i option. If -F is
not specified, audioconvert ignores the -i option for input files
that contain valid audio file headers.
-f outfmt Output Format: This option is used to specify the file format and
data encoding of the output file. Defaults for unspecified fields are
derived from the input file format. Valid keywords and values are
listed in the next section.
-o outfile Output File: All input files are concatenated, converted to the
output format, and written to the named output file. If -o and -p
are not specified, the concatenated output is written to the
standard output. The -p option may not be specified with -o.

User Commands 77
audioconvert(1)
-i infmt Input Format: This option is used to specify the data encoding of
raw input files. Ordinarily, the input data format is derived from
the audio file header. This option is required when converting
audio data that is not preceded by a valid audio file header. If -i
is specified for an input file that contains an audio file header, the
input format string will be ignored, unless -F is present. The
format specification syntax is the same as the -f output file
format.

Multiple input formats may be specified. An input format

describes all input files following that specification, until a new
input format is specified.
file File Specification: The named audio files are concatenated,
converted to the output format, and written out. If no file name is
present, or if the special file name ‘−’ is specified, audio data is
read from the standard input.
-? Help: Prints a command line usage message.

Format The syntax for the input and output format specification is:
Specification
keyword=value[,keyword=value . . . ]

with no intervening whitespace. Unambiguous values may be used without the

preceding keyword=.
rate The audio sampling rate is specified in samples per second. If a
number is followed by the letter k, it is multiplied by 1000 (for
example, 44.1k = 44100). Standard of the commonly used sample
rates are: 8k, 16k, 32k, 44.1k, and 48k.
channels The number of interleaved channels is specified as an integer. The
words mono and stereo may also be used to specify one and two
channel data, respectively.
encoding This option specifies the digital audio data representation.
Encodings determine precision implicitly (ulaw implies 8-bit
precision) or explicitly as part of the name (for example,
linear16). Valid encoding values are:
ulaw CCITT G.711 -law encoding. This is an 8-bit
format primarily used for telephone quality
speech.
alaw CCITT G.711 A-law encoding. This is an 8-bit
format primarily used for telephone quality
speech in Europe.
linear8,
linear16,

78 man pages section 1: User Commands • Last Revised 16 Feb 2001

 audioconvert(1)
linear32 Linear Pulse Code Modulation (PCM)
encoding. The name identifies the number of
bits of precision. linear16 is typically used
for high quality audio data.
pcm Same as linear16.
g721 CCITT G.721 compression format. This
encoding uses Adaptive Delta Pulse Code
Modulation (ADPCM) with 4-bit precision. It is
primarily used for compressing -law voice data
(achieving a 2:1 compression ratio).
g723 CCITT G.723 compression format. This
encoding uses Adaptive Delta Pulse Code
Modulation (ADPCM) with 3-bit precision. It is
primarily used for compressing -law voice data
(achieving an 8:3 compression ratio). The audio
quality is similar to G.721, but may result in
lower quality when used for non-speech data.

The following encoding values are also accepted as shorthand to

set the sample rate, channels, and encoding:
voice Equivalent to
encoding=ulaw,rate=8k,channels=mono.
cd Equivalent to
encoding=linear16,rate=44.1k,channels=stereo.
dat Equivalent to
encoding=linear16,rate=48k,channels=stereo.
format This option specifies the audio file format. Valid formats are:
sun Sun compatible file format (the default).
raw Use this format when reading or writing raw audio
data (with no audio header), or in conjunction with an
offset to import a foreign audio file format.
offset (-i only) Specifies a byte offset to locate the start of the audio data.
This option may be used to import audio data that contains an
unrecognized file header.

USAGE See largefile(5) for the description of the behavior of audioconvert when
encountering files greater than or equal to 2 Gbyte ( 231 bytes).

EXAMPLES EXAMPLE 1 Recording and compressing voice data before storing it

Record voice data and compress it before storing it to a file:

example% audiorecord | audioconvert -f g721 > mydata.au

User Commands 79
audioconvert(1)
EXAMPLE 2 Concatenating two audio files

Concatenate two Sun format audio files, regardless of their data format, and output an
8-bit ulaw, 16 kHz, mono file:
example% audioconvert -f ulaw,rate=16k,mono -o outfile.au infile1 infile2

EXAMPLE 3 Converting a directory to Sun format

Convert a directory containing raw voice data files, in place, to Sun format (adds a file
header to each file):
example% audioconvert -p -i voice -f sun *.au

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Architecture SPARC, x86

Availability SUNWauda

Interface Stability Evolving

SEE ALSO audioplay(1), audiorecord(1), file(1), attributes(5), largefile(5)

NOTES The algorithm used for converting multi-channel data to mono is implemented by
simply summing the channels together. If the input data is perfectly in phase (as
would be the case if a mono file is converted to stereo and back to mono), the resulting
data may contain some distortion.

80 man pages section 1: User Commands • Last Revised 16 Feb 2001

 audioplay(1)
NAME audioplay – play audio files
SYNOPSIS audioplay [-iV] [-v vol] [-b bal] [-p speaker | headphone | line]
[-d dev] [file…]

DESCRIPTION The audioplay utility copies the named audio files (or the standard input if no
filenames are present) to the audio device. If no input file is specified and standard
input is a tty, the port, volume, and balance settings specified on the command line
will be applied and the program will exit.

The input files must contain a valid audio file header. The encoding information in
this header is matched against the capabilities of the audio device and, if the data
formats are incompatible, an error message is printed and the file is skipped.
Compressed ADPCM (G.721) monaural audio data is automatically uncompressed
before playing.

Minor deviations in sampling frequency (that is, less than 1%) are ordinarily ignored.
This allows, for instance, data sampled at 8012 Hz to be played on an audio device
that only supports 8000 Hz. If the -V option is present, such deviations are flagged
with warning messages.

OPTIONS The following options are supported:

-i
Immediate: If the audio device is unavailable (that is, another process currently has
write access), audioplay ordinarily waits until it can obtain access to the device.
When the -i option is present, audioplay prints an error message and exits
immediately if the device is busy.
-V
Verbose: Prints messages on the standard error when waiting for access to the audio
device or when sample rate deviations are detected.
-v vol
Volume: The output volume is set to the specified value before playing begins, and
is reset to its previous level when audioplay exits. The vol argument is an integer
value between 0 and 100, inclusive. If this argument is not specified, the output
volume remains at the level most recently set by any process.
-b bal
Balance: The output balance is set to the specified value before playing begins, and
is reset to its previous level when audioplay exits. The bal argument is an integer
value between -100 and 100, inclusive. A value of -100 indicates left balance, 0
middle, and 100 right. If this argument is not specified, the output balance remains
at the level most recently set by any process.
-p speaker | headphone | line
Output Port: Selects the built-in speaker (the default), headphone jack, or line
out as the destination of the audio output signal. If this argument is not specified,
the output port will remain unchanged. Please note: Not all audio adapters support
all of the output ports. If the named port does not exist, an appropriate substitute
will be used.

User Commands 81
audioplay(1)
-d dev
Device: The dev argument specifies an alternate audio device to which output
should be directed. If the -d option is not specified, the AUDIODEV environment
variable is consulted (see below). Otherwise, /dev/audio is used as the default
audio device.
−\?
Help: Prints a command line usage message.
OPERANDS file File Specification: Audio files named on the command line are played
sequentially. If no filenames are present, the standard input stream (if it is
not a tty) is played (it, too, must contain an audio file header). The special
filename ‘−’ may be used to read the standard input stream instead of a file.
If a relative path name is supplied, the AUDIOPATH environment variable is
consulted (see below).

USAGE See largefile(5) for the description of the behavior of audioplay when
encountering files greater than or equal to 2 Gbyte ( 231 bytes).
ENVIRONMENT AUDIODEV The full path name of the audio device to write to, if no -d
VARIABLES argument is supplied. If the AUDIODEV variable is not set,
/dev/audio is used.
AUDIOPATH A colon-separated list of directories in which to search for audio
files whose names are given by relative pathnames. The current
directory (".") may be specified explicitly in the search path. If the
AUDIOPATH variable is not set, only the current directory will be
searched.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Architecture SPARC, x86

Availability SUNWauda

Interface Stability Evolving

SEE ALSO audioconvert(1), audiorecord(1), mixerctl(1), attributes(5), largefile(5),

usb_ac(7D), audio(7I), mixer(7I)

BUGS audioplay currently supports a limited set of audio format conversions. If the audio
file is not in a format supported by the audio device, it must first be converted. For
example, to convert to voice format on the fly, use the command:
example% audioconvert -f voice myfile | audioplay

The format conversion will not always be able to keep up with the audio output. If
this is the case, you should convert to a temporary file before playing the data.

82 man pages section 1: User Commands • Last Revised 16 Feb 2001

 audiorecord(1)
NAME audiorecord – record an audio file
SYNOPSIS audiorecord [-af] [-v vol] [-b bal] [-m monvol] [-p mic | line
| internal-cd] [-c channels] [-s rate] [-e encoding] [-t time]
[-i info] [-d dev] [file]

DESCRIPTION The audiorecord utility copies audio data from the audio device to a named audio
file (or the standard output if no filename is present). If no output file is specified and
standard output is a tty, the volume, balance, monitor volume, port, and audio format
settings specified on the command line will be applied and the program will exit.

By default, monaural audio data is recorded at 8 kHz and encoded in -law format. If
the audio device supports additional configurations, the -c, -s, and -e options may
be used to specify the data format. The output file is prefixed by an audio file header
that identifies the format of the data encoded in the file.

Recording begins immediately and continues until a SIGINT signal (for example,
Ctrl-C) is received. If the -t option is specified, audiorecord stops when the
specified quantity of data has been recorded.

If the audio device is unavailable (that is, another process currently has read access),
audiorecord prints an error message and exits immediately.

OPTIONS The following options are supported:

-a
Append: Appends the data on the end of the named audio file. The audio device
must support the audio data format of the existing file.
-f
Force: When the -a flag is specified, the sample rate of the audio device must match
the sample rate at which the original file was recorded. If the -f flag is also
specified, sample rate differences are ignored, with a warning message printed on
the standard error.
-v vol
Volume: The recording gain is set to the specified value before recording begins, and
is reset to its previous level when audiorecord exits. The vol argument is an
integer value between 0 and 100, inclusive. If this argument is not specified, the
input volume will remain at the level most recently set by any process.
-b bal
Balance: The recording balance is set to the specified value before recording begins,
and is reset to its previous level when audiorecord exits. The bal argument is an
integer value between -100 and 100, inclusive. A value of -100 indicates left balance,
0 middle, and 100 right. If this argument is not specified, the input balance will
remain at the level most recently set by any process.
-m monvol
Monitor Volume: The input monitor volume is set to the specified value before
recording begins, and is reset to its previous level when audiorecord exits. The
monval argument is an integer value between 0 and 100, inclusive. A non-zero value

User Commands 83
audiorecord(1)
allows a directly connected input source to be heard on the output speaker while
recording is in-progress. If this argument is not specified, the monitor volume will
remain at the level most recently set by any process.
-p mic | line | internal-cd
Input Port: Selects the mic, line, or internal-cd input as the source of the audio
output signal. If this argument is not specified, the input port will remain
unchanged. Please note: Some systems will not support all possible input ports. If
the named port does not exist, this option is ignored.
-c channels
Channels: Specifies the number of audio channels (1 or 2). The value may be
specified as an integer or as the string mono or stereo. The default value is mono.
-s rate
Sample Rate: Specifies the sample rate, in samples per second. If a number is
followed by the letter k, it is multiplied by 1000 (for example, 44.1k = 44100). The
default sample rate is 8 kHz.
-e encoding
Encoding: Specifies the audio data encoding. This value may be one of ulaw, alaw,
or linear. The default encoding is ulaw.
-t time
Time: The time argument specifies the maximum length of time to record. Time can
be specified as a floating-point value, indicating the number of seconds, or in the
form: hh:mm:ss.dd, where the hour and minute specifications are optional.
-i info
Information: The ‘information’ field of the output file header is set to the string
specified by the info argument. This option cannot be specified in conjunction with
the -a argument.
-d dev
Device: The dev argument specifies an alternate audio device from which input
should be taken. If the -d option is not specified, the AUDIODEV environment
variable is consulted (see below). Otherwise, /dev/audio is used as the default
audio device.
-\?
Help: Prints a command line usage message.
OPERANDS file File Specification: The named audio file is rewritten (or appended). If no
filename is present (and standard output is not a tty), or if the special
filename ‘−’ is specified, output is directed to the the standard output.

USAGE See largefile(5) for the description of the behavior of audiorecord when
encountering files greater than or equal to 2 Gbyte ( 231 bytes).
ENVIRONMENT AUDIODEV The full path name of the audio device to record from, if no -d
VARIABLES argument is supplied. If the AUDIODEV variable is not set,
/dev/audio is used.

84 man pages section 1: User Commands • Last Revised 16 Feb 2001

 audiorecord(1)
ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Architecture SPARC, x86

Availability SUNWauda

Interface Stability Evolving

SEE ALSO audioconvert(1), audioplay(1), mixerctl(1), attributes(5), largefile(5),

usb_ac(7D), audio(7I), mixer(7I)

User Commands 85
auths(1)
NAME auths – print authorizations granted to a user
SYNOPSIS auths [ user …]

DESCRIPTION The auths command prints on standard output the authorizations that you or the
optionally-specified user or role have been granted. Authorizations are rights that are
checked by certain privileged programs to determine whether a user may execute
restricted functionality.

Each user may have zero or more authorizations. Authorizations are represented by
fully-qualified names, which identify the organization that created the authorization
and the functionality that it controls. Following the Java convention, the hierarchical
components of an authorization are separated by dots (.), starting with the reverse
order Internet domain name of the creating organization, and ending with the specific
function within a class of authorizations.

An asterisk (*) indicates all authorizations in a class.

A user’s authorizations are looked up in user_attr(4) and in the

/etc/security/policy.conf file (see policy.conf(4)). Authorizations may be
specified directly in user_attr(4) or indirectly through prof_attr(4).
Authorizations may also be assigned to every user in the system directly as default
authorizations or indirectly as default profiles in the /etc/security/policy.conf
file.

EXAMPLES EXAMPLE 1 Sample output

The auths output has the following form:

example% auths tester01 tester02
tester01 : com.sun.system.date,com.sun.jobs.admin
tester02 : com.sun.system.*
example%

Notice that there is no space after the comma separating the authorization names in
tester01.

EXIT STATUS The following exit values are returned:

0 Successful completion.
1 An error occurred.

FILES /etc/user_attr

/etc/security/auth_attr

/etc/security/policy.conf

/etc/security/prof_attr

86 man pages section 1: User Commands • Last Revised 23 Aug 2002

 auths(1)
ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO profiles(1), roles(1), getauthattr(3SECDB), auth_attr(4), policy.conf(4),

prof_attr(4), user_attr(4), attributes(5)

User Commands 87
awk(1)
NAME awk – pattern scanning and processing language
SYNOPSIS /usr/bin/awk [-f progfile] [-F c] [’ prog ’] [parameters] [filename…]
/usr/xpg4/bin/awk [-F ERE] [-v assignment…] ’program’ -f progfile…
[argument…]

DESCRIPTION The /usr/xpg4/bin/awk utility is described on the nawk(1) manual page.

The /usr/bin/awk utility scans each input filename for lines that match any of a set
of patterns specified in prog. The prog string must be enclosed in single quotes ( ´) to
protect it from the shell. For each pattern in prog there may be an associated action
performed when a line of a filename matches the pattern. The set of pattern-action
statements may appear literally as prog or in a file specified with the -f progfile option.
Input files are read in order; if there are no files, the standard input is read. The file
name ’−’ means the standard input.

OPTIONS The following options are supported:

-f progfile awk uses the set of patterns it reads from progfile.
-Fc Uses the character c as the field separator (FS) character. See the
discussion of FS below.

USAGE

Input Lines Each input line is matched against the pattern portion of every pattern-action
statement; the associated action is performed for each matched pattern. Any filename of
the form var=value is treated as an assignment, not a filename, and is executed at the
time it would have been opened if it were a filename. Variables assigned in this manner
are not available inside a BEGIN rule, and are assigned after previously specified files
have been read.

An input line is normally made up of fields separated by white spaces. (This default
can be changed by using the FS built-in variable or the -Fc option.) The default is to
ignore leading blanks and to separate fields by blanks and/or tab characters.
However, if FS is assigned a value that does not include any of the white spaces, then
leading blanks are not ignored. The fields are denoted $1, $2, . . . ; $0 refers to the
entire line.

Pattern-action A pattern-action statement has the form:

Statements
pattern { action }

Either pattern or action may be omitted. If there is no action, the matching line is
printed. If there is no pattern, the action is performed on every input line.
Pattern-action statements are separated by newlines or semicolons.

Patterns are arbitrary Boolean combinations ( !, ||, &&, and parentheses) of relational
expressions and regular expressions. A relational expression is one of the following:

88 man pages section 1: User Commands • Last Revised 7 Jul 2000

 awk(1)
expression relop expression
expression matchop regular_expression

where a relop is any of the six relational operators in C, and a matchop is either ~
(contains) or !~ (does not contain). An expression is an arithmetic expression, a
relational expression, the special expression
var in array

or a Boolean combination of these.

Regular expressions are as in egrep(1). In patterns they must be surrounded by

slashes. 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 the occurrence of the first pattern to the occurrence of the second pattern.

The special patterns BEGIN and END may be used to capture control before the first
input line has been read and after the last input line has been read respectively. These
keywords do not combine with any other patterns.

Built-in Variables Built-in variables include:

FILENAME name of the current input file
FS input field separator regular expression (default blank and tab)
NF number of fields in the current record
NR ordinal number of the current record
OFMT output format for numbers (default %.6g)
OFS output field separator (default blank)
ORS output record separator (default new-line)
RS input record separator (default new-line)

An action is a sequence of statements. A statement may be one of the following:

if ( expression ) statement [ else statement ]
while ( expression ) statement
do statement while ( expression )
for ( expression ; expression ; expression ) statement
for ( var in array ) statement
break
continue
{ [ statement ] . . . }
expression # commonly variable = expression
print [ expression-list ] [ >expression ]
printf format [ ,expression-list ] [ >expression ]
next # skip remaining patterns on this input line
exit [expr] # skip the rest of the input; exit status is expr

User Commands 89
awk(1)
Statements are terminated by semicolons, newlines, or right braces. An empty
expression-list stands for the whole input line. Expressions take on string or numeric
values as appropriate, and are built using the operators +, −, *, /, %, ^ and
concatenation (indicated by a blank). The operators ++, −−, +=, −=, *=, /=, %=, ^=, >,
>=, <, <=, ==, !=, and ?: are also available in expressions. Variables may be scalars,
array elements (denoted x[i]), or fields. Variables are initialized to the null string or
zero. Array subscripts may be any string, not necessarily numeric; this allows for a
form of associative memory. String constants are quoted (""), with the usual C escapes
recognized within.

The print statement prints its arguments on the standard output, or on a file if
>expression is present, or on a pipe if ’|cmd’ is present. The output resulted from the
print statement is terminated by the output record separator with each argument
separated by the current output field separator. The printf statement formats its
expression list according to the format (see printf(3C)).

Built-in Functions The arithmetic functions are as follows:

cos(x) Return cosine of x, where x is in radians. (In
/usr/xpg4/bin/awk only. See nawk(1).)
sin(x) Return sine of x, where x is in radians. (In /usr/xpg4/bin/awk
only. See nawk(1).)
exp(x) Return the exponential function of x.
log(x) Return the natural logarithm of x.
sqrt(x) Return the square root of x.
int(x) Truncate its argument to an integer. It will be truncated toward 0
when x > 0.

The string functions are as follows:

index(s, t)
Return the position in string s where string t first occurs, or 0 if it does not occur at
all.
int(s)
truncates s to an integer value. If s is not specified, $0 is used.
length(s)
Return the length of its argument taken as a string, or of the whole line if there is no
argument.
split(s, a, fs)
Split the string s into array elements a[1], a[2], . . . a[n], and returns n. The
separation is done with the regular expression fs or with the field separator FS if fs
is not given.

90 man pages section 1: User Commands • Last Revised 7 Jul 2000

 awk(1)
sprintf(fmt, expr, expr, . . . )
Format the expressions according to the printf(3C) format given by fmt and
returns the resulting string.
substr(s, m, n)
returns the n-character substring of s that begins at position m.

The input/output function is as follows:

getline Set $0 to the next input record from the current input file.
getline returns 1 for successful input, 0 for end of file, and −1
for an error.

Large File See largefile(5) for the description of the behavior of awk when encountering files
Behavior greater than or equal to 2 Gbyte ( 231 bytes).

EXAMPLES EXAMPLE 1 Printing lines longer than 72 characters

example% length > 72

EXAMPLE 2 Printing first two fields in opposite order

example% { print $2, $1 }

EXAMPLE 3 Same, with input fields separated by comma and/or blanks and tabs
example% BEGIN { FS = ",[ \t]*|[ \t]+" }
{ print $2, $1 }

EXAMPLE 4 Adding up first column, print sum and average

example% { s += $1 }
END { print "sum is", s, " average is", s/NR }

EXAMPLE 5 Printing fields in reverse order

example% { for (i = NF; i > 0; −−i) print $i }

EXAMPLE 6 Printing all lines between start/stop pairs

example% /start/, /stop/

EXAMPLE 7 Printing all lines whose first field is different from the previous one
example% $1 != prev { print; prev = $1 }

EXAMPLE 8 Printing a file, filling in page numbers starting at 5

example% /Page/ { $2 = n++; }
{ print }

User Commands 91
awk(1)
EXAMPLE 9 Printing a file and numbering its pages, starting at 5

Assuming this program is in a file named prog, the following command line prints
the file input numbering its pages starting at 5:
example% awk -f prog n=5 input

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of awk: LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, NLSPATH,
and PATH.
LC_NUMERIC Determine the radix character used when interpreting numeric
input, performing conversions between numeric and string values
and formatting numeric output. Regardless of locale, the period
character (the decimal-point character of the POSIX locale) is the
decimal-point character recognized in processing awk programs
(including assignments in command-line arguments).

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

/usr/bin/awk ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

CSI Enabled

/usr/xpg4/bin/awk ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWxcu4

CSI Enabled

Interface Stability Standard

SEE ALSO egrep(1), grep(1), nawk(1), sed(1), printf(3C), attributes(5), environ(5),

largefile(5), standards(5)

NOTES 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 an expression to be treated as a string,
concatenate the null string ("") to it.

92 man pages section 1: User Commands • Last Revised 7 Jul 2000

 banner(1)
NAME banner – make posters
SYNOPSIS banner strings

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

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

SEE ALSO echo(1), attributes(5)

User Commands 93
basename(1)
NAME basename, dirname – deliver portions of path names
SYNOPSIS /usr/bin/basename string [suffix]
/usr/xpg4/bin/basename string [suffix]
dirname string

DESCRIPTION The basename utility deletes any prefix ending in / and the suffix (if present in string)
from string, and prints the result on the standard output. It is normally used inside
substitution marks (‘ ‘) within shell procedures.

/usr/bin The suffix is a pattern defined on the expr(1) manual page.

/usr/xpg4/bin The suffix is a string with no special significance attached to any of the characters it
contains.

The dirname utility delivers all but the last level of the path name in string.

EXAMPLES EXAMPLE 1 Setting environment variables

The following example, invoked with the argument /home/sms/personal/mail

sets the environment variable NAME to the file named mail and the environment
variable MYMAILPATH to the string /home/sms/personal:
example% NAME=‘basename $HOME/personal/mail‘
example% MYMAILPATH=‘dirname $HOME/personal/mail‘

EXAMPLE 2 Compiling a file and moving the output

This shell procedure, invoked with the argument /usr/src/bin/cat.c, compiles

the named file and moves the output to cat in the current directory:
example% cc $1
example% mv a.out ‘basename $1 .c‘

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of basename and dirname: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES,
and NLSPATH.

EXIT STATUS The following exit values are returned:

0 Successful completion.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

/usr/bin ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

94 man pages section 1: User Commands • Last Revised 18 Mar 1997

 basename(1)
/usr/xpg4/bin ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWxcu4

Interface Stability Standard

SEE ALSO expr(1), attributes(5), environ(5), standards(5)

User Commands 95
basename(1B)
NAME basename – display portions of pathnames
SYNOPSIS /usr/ucb/basename string [suffix]

DESCRIPTION The basename utility deletes any prefix ending in ‘/’ and the suffix, if present in string.
It directs the result to the standard output, and is normally used inside substitution
marks (‘ ‘) within shell procedures. The suffix is a string with no special significance
attached to any of the characters it contains.

EXAMPLES EXAMPLE 1 Using the basename command.

This shell procedure invoked with the argument /usr/src/bin/cat.c compiles the
named file and moves the output to cat in the current directory:
example% cc $1
example% mv a.out ‘basename $1 .c‘

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWscpu

SEE ALSO sh(1), attributes(5)

96 man pages section 1: User Commands • Last Revised 28 Mar 1995

 bc(1)
NAME bc – arbitrary precision arithmetic language
SYNOPSIS bc [-c] [-l] [file…]

DESCRIPTION The bc utility implements an arbitrary precision calculator. It takes input from any
files given, then reads from the standard input. If the standard input and standard
output to bc are attached to a terminal, the invocation of bc is interactive, causing
behavioral constraints described in the following sections. bc processes a language
that resembles C and is a preprocessor for the desk calculator program dc, which it
invokes automatically unless the -c option is specified. In this case the dc input is
sent to the standard output instead.

USAGE The syntax for bc programs is as follows:

L means a letter a−z,
E means an expression: a (mathematical or logical) value, an operand that
takes a value, or a combination of operands and operators that evaluates to
a value,
S means a statement.

Comments Enclosed in /* and */.

Names (Operands) Simple variables: L.

Array elements: L [ E ] (up to BC_DIM_MAX dimensions).
The words ibase, obase (limited to BC_BASE_MAX), and scale (limited to
BC_SCALE_MAX).

Other Operands Arbitrarily long numbers with optional sign and decimal point. Strings of fewer than
BC_STRING_MAX characters, between double quotes ("). ( E )
sqrt ( E ) Square root
length ( E ) Number of significant decimal digits.
scale ( E ) Number of digits right of decimal point.
L ( E , ... , E )
Operators + − * / % ^
(% is remainder; ^ is power)
++ −−
(prefix and postfix; apply to names)
== <= >= != < >
= =+ =− =* =/ =% =^

Statements E
{ S ;. . . ; S }
if ( E ) S

User Commands 97
bc(1)
while ( E ) S
for ( E ; E ; E ) S
null statement
break
quit

.string

Function define L ( L ,. . . , L ) {
Definitions auto L ,. . . , L
S ;. . . S
return ( E )
}
Functions in -l s(x) sine
Math Library
c(x) cosine
e(x) exponential
l(x) log
a(x) arctangent
j(n,x) Bessel function

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 new-lines may separate statements. Assignment to
scale influences the number of digits to be retained on arithmetic operations in the
manner of dc. 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 stacked
during function calls. When using arrays as function arguments or defining them as
automatic variables, empty square brackets must follow the array name.

OPTIONS The following operands are supported:

-c Compile only. The output is dc commands that are sent to the
standard output.
-l Define the math functions and initialize scale to 20, instead of
the default zero.

OPERANDS The following operands are supported:

file A pathname of a text file containing bc program statements. After
all cases of file have been read, bc will read the standard input.

98 man pages section 1: User Commands • Last Revised 28 Mar 1995

 bc(1)
EXAMPLES EXAMPLE 1 Setting the precision of a variable

In the shell, the following assigns an approximation of the first ten digits of n to the
variable x:
x=$(printf "%s\n" ’scale = 10; 104348/33215’ | bc)

EXAMPLE 2 Defining a computing function

Defines 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=1; 1==1; i++){
a = a*x
b = b*i
c = a/b
if(c == 0) return(s)
s = s+c
}
}

EXAMPLE 3 Printing the approximate values of the function

Prints approximate values of the exponential function of the first ten integers:
for(i=1; i<=10; i++) e(i)

or
for (i = 1; i <= 10; ++i) { e(i) }

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of bc: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

EXIT STATUS The following exit values are returned:

0 All input files were processed successfully.
unspecified An error occurred.
FILES /usr/lib/lib.b mathematical library
/usr/include/limits.h to define BC_ parameters

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

User Commands 99
bc(1)

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

Interface Stability Standard

SEE ALSO dc(1), awk(1), attributes(5), environ(5), standards(5)

NOTES The bc command does not recognize the logical operators && and | |.

The for statement must have all three expressions (E’s).

100 man pages section 1: User Commands • Last Revised 28 Mar 1995
 bdiff(1)
NAME bdiff – big diff
SYNOPSIS bdiff filename1 filename2 [n] [-s]

DESCRIPTION bdiff is used in a manner analogous to diff to find which lines in filename1 and
filename2 must be changed to bring the files into agreement. Its purpose is to allow
processing of files too large for diff. If filename1 (filename2) is −, the standard input is
read.

bdiff ignores lines common to the beginning of both files, splits the remainder of
each file into n-line segments, and invokes diff on corresponding segments. If both
optional arguments are specified, they must appear in the order indicated above.

The output of bdiff is exactly that of diff, with line numbers adjusted to account
for the segmenting of the files (that is, to make it look as if the files had been processed
whole). Note: Because of the segmenting of the files, bdiff does not necessarily find a
smallest sufficient set of file differences.
OPTIONS n The number of line segments. The value of n is 3500 by default. If the
optional third argument is given and it is numeric, it is used as the value
for n. This is useful in those cases in which 3500-line segments are too large
for diff, causing it to fail.
-s Specifies that no diagnostics are to be printed by bdiff (silent option).
Note: However, this does not suppress possible diagnostic messages from
diff, which bdiff calls.

USAGE See largefile(5) for the description of the behavior of bdiff when encountering
files greater than or equal to 2 Gbyte ( 231 bytes).

FILES /tmp/bd?????

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

CSI enabled

SEE ALSO diff(1), attributes(5), largefile(5)

DIAGNOSTICS Use help for explanations.

User Commands 101

bfs(1)
NAME bfs – big file scanner
SYNOPSIS /usr/bin/bfs [-] filename

DESCRIPTION The bfs command is (almost) like ed(1) except that it is read-only and processes
much larger files. Files can be up to 1024K bytes and 32K lines, with up to 512
characters, including new-line, per line (255 for 16-bit machines). bfs is usually more
efficient than ed(1) for scanning a file, since the file is not copied to a buffer. It is most
useful for identifying sections of a large file where csplit(1) can be used to divide it
into more manageable pieces for editing.

Normally, the size of the file being scanned is printed, as is the size of any file written
with the w (write) command. The optional − suppresses printing of sizes. Input is
prompted with * if P and a carriage return are typed, as in ed(1). Prompting can be
turned off again by inputting another P and carriage return. Note that messages are
given in response to errors if prompting is turned on.

All address expressions described under ed(1) are supported. In addition, regular
expressions may be surrounded with two symbols besides / and ?:
> indicates downward search without wrap-around, and
< indicates upward search without wrap-around.

There is a slight difference in mark names; that is, only the letters a through z may be
used, and all 26 marks are remembered.

bfs Commands The e, g, v, k, p, q, w, =, !, and null commands operate as described under ed(1).
Commands such as −−−, +++−, +++=, −12, and +4p are accepted. Note that 1,10p
and 1,10 will both print the first ten lines. The f command only prints the name of
the file being scanned; there is no remembered file name. The w command is
independent of output diversion, truncation, or crunching (see the xo, xt, and xc
commands, below). The following additional commands are available:
xf file
Further commands are taken from the named file. When an end-of-file is reached,
an interrupt signal is received or an error occurs, reading resumes with the file
containing the xf. The xf commands may be nested to a depth of 10.
xn
List the marks currently in use (marks are set by the k command).
xo [ file ]
Further output from the p and null commands is diverted to the named file,
which, if necessary, is created mode 666 (readable and writable by everyone), unless
your umask setting (see umask(1)) dictates otherwise. If file is missing, output is
diverted to the standard output. Note that each diversion causes truncation or
creation of the file.

102 man pages section 1: User Commands • Last Revised 20 May 1996
 bfs(1)
: label
This positions a label in a command file. The label is terminated by new-line, and
blanks between the : (colon) and the start of the label are ignored. This command
may also be used to insert comments into a command file, since labels need not be
referenced.
( . , . )xb/regular expression/label
A jump (either upward or downward) is made to label if the command succeeds. It
fails under any of the following conditions:
1. Either address is not between 1 and $.
2. The second address is less than the first.
3. The regular expression does not match at least one line in the specified range,
including the first and last lines.

On success, . (dot) is set to the line matched and a jump is made to label. This
command is the only one that does not issue an error message on bad addresses, so
it may be used to test whether addresses are bad before other commands are
executed. Note that the command, xb/^/ label, is an unconditional jump.

The xb command is allowed only if it is read from someplace other than a terminal.
If it is read from a pipe, only a downward jump is possible.
xt number
Output from the p and null commands is truncated to, at most, number characters.
The initial number is 255.
xv[digit] [spaces] [value]
The variable name is the specified digit following the xv. The commands xv5100 or
xv5 100 both assign the value 100 to the variable 5. The command xv61,100p
assigns the value 1,100p to the variable 6. To reference a variable, put a % in front
of the variable name. For example, using the above assignments for variables 5 and
6:
1,%5p
1,%5
%6

will all print the first 100 lines.

g/%5/p

would globally search for the characters 100 and print each line containing a
match. To escape the special meaning of %, a \ must precede it.

g/".*\%[cds]/p

User Commands 103

bfs(1)
could be used to match and list %c, %d, or %s formats (for example, "printf"-like
statements) of characters, decimal integers, or strings. Another feature of the xv
command is that the first line of output from a UNIX system command can be
stored into a variable. The only requirement is that the first character of value be an
!. For example:
.w junk
xv5!cat junk
!rm junk
!echo "%5"
xv6!expr %6 + 1

would put the current line into variable 35, print it, and increment the variable 36
by one. To escape the special meaning of ! as the first character of value, precede it
with a \.

xv7\!date

stores the value !date into variable 7.

xbz label
xbn label
These two commands will test the last saved return code from the execution of a
UNIX system command (!command) or nonzero value, respectively, to the specified
label. The two examples below both search for the next five lines containing the
string size:
Example 1:
xv55
: l
/size/
xv5!expr %5 − 1
!if 0%5 != 0 exit 2
xbn l

Example 2:
xv45
: l
/size/
xv4!expr %4 − 1
!if 0%4 = 0 exit 2
xbz l

xc [switch]
If switch is 1, output from the p and null commands is crunched; if switch is 0,
it is not. Without an argument, xc reverses switch. Initially, switch is set for no
crunching. Crunched output has strings of tabs and blanks reduced to one blank
and blank lines suppressed.

OPERANDS The following operand is supported:

104 man pages section 1: User Commands • Last Revised 20 May 1996
 bfs(1)
filename Any file up to 1024K bytes and 32K lines, with up to 512
characters, including new-line, per line (255 for 16-bit machines).
filename can be a section of a larger file which has been divided
into more manageable sections for editing by the use of
csplit(1).

EXIT STATUS The following exit values are returned:

0 Successful completion without any file or command errors.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

SEE ALSO csplit(1), ed(1), umask(1), attributes(5)

DIAGNOSTICS Message is ? for errors in commands, if prompting is turned off. Self-explanatory error
messages are displayed when prompting is on.

User Commands 105

biff(1B)
NAME biff – give notice of incoming mail messages
SYNOPSIS /usr/ucb/biff [y | n]

DESCRIPTION biff turns mail notification on or off for the terminal session. With no arguments,
biff displays the current notification status for the terminal.

If notification is allowed, the terminal rings the bell and displays the header and the
first few lines of each arriving mail message. biff operates asynchronously. For
synchronized notices, use the MAIL variable of sh(1) or the mail variable of csh(1).

A ‘biff y’ command can be included in your ~/.login or ~/.profile file for

execution when you log in.
OPTIONS y Allow mail notification for the terminal.
n Disable notification for the terminal.
FILES ~/.login User’s login file
~/.profile User’s profile file

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWscpu

SEE ALSO csh(1), mail(1), sh(1), attributes(5)

106 man pages section 1: User Commands • Last Revised 14 Sep 1992
 break(1)
NAME break, continue – shell built-in functions to escape from or advance within a
controlling while, for, foreach, or until loop
sh break [n]
continue [n]
csh break
continue
ksh *break [n]
*continue [n]

DESCRIPTION

sh break exits from the enclosing for or while loop, if any. If n is specified, break n
levels.

continue resumes the next iteration of the enclosing for or while loop. If n is
specified, resume at the n-th enclosing loop.

csh break resumes execution after the end of the nearest enclosing foreach 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.

continue continues execution of the next iteration of the nearest enclosing while or
foreach loop.

ksh break exits from the enclosed for, while, until, or select loop, if any. If n is
specified then break n levels.

continue resumes the next iteration of the enclosed for, while, until, or select
loop. If n is specified then resume at the n-th enclosed loop.

On this man page, ksh(1) commands that are preceded by one or two * (asterisks) are
treated specially in the following ways:
1. Variable assignment lists preceding the command remain in effect when the
command completes.
2. I/O redirections are processed after variable assignments.
3. Errors cause a script that contains them to abort.
4. Words, following a command preceded by ** that are in the format of a variable
assignment, are expanded with the same rules as a variable assignment. This
means that tilde substitution is performed after the = sign and word splitting and
file name generation are not performed.

User Commands 107

break(1)
ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO csh(1), exit(1), ksh(1), sh( 1), attributes(5)

108 man pages section 1: User Commands • Last Revised 15 Apr 1994
 cal(1)
NAME cal – display a calendar
SYNOPSIS cal [ [month] year]

DESCRIPTION The cal utility writes a Gregorian calendar to standard output. If the year operand is
specified, a calendar for that year is written. If no operands are specified, a calendar
for the current month is written.

OPERANDS The following operands are supported:

month Specify the month to be displayed, represented as a decimal integer from 1
(January) to 12 (December). The default is the current month.
year Specify the year for which the calendar is displayed, represented as a
decimal integer from 1 to 9999. The default is the current year.

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of cal: LANG, LC_ALL, LC_CTYPE, LC_TIME, LC_MESSAGES, and
NLSPATH.
TZ Determine the timezone used to calculate the value of the current month.

EXIT STATUS The following exit values are returned:

0 Successful completion.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

Interface Stability Standard

SEE ALSO calendar(1), attributes(5), environ(5), standards(5)

NOTES An unusual calendar is printed for September 1752. That is the month 11 days were
skipped to make up for lack of leap year adjustments. To see this calendar, type:
cal 9 1752

The command cal 83 refers to the year 83, not 1983.

The year is always considered to start in January.

User Commands 109

calendar(1)
NAME calendar – reminder service
SYNOPSIS calendar [-]

DESCRIPTION The calendar utility consults the file calendar in the current directory and writes
lines that contain today’s or tomorrow’s date anywhere in the line to standard output.
Most reasonable month-day dates such as Aug. 24, august 24, 8/24, and so forth,
are recognized, but not 24 August or 24/8. On Fridays and weekends “tomorrow”
extends through Monday. calendar can be invoked regularly by using the
crontab(1) or at(1) commands.

When the optional argument - is present, calendar does its job for every user who
has a file calendar in his or her login directory and sends them any positive results
by mail(1). Normally this is done daily by facilities in the UNIX operating system
(seecron(1M)).

If the environment variable DATEMSK is set, calendar will use its value as the full
path name of a template file containing format strings. The strings consist of
conversion specifications and text characters and are used to provide a richer set of
allowable date formats in different languages by appropriate settings of the
environment variable LANG or LC_TIME; see environ(5). Seestrftime(3C) for the
list of allowable conversion specifications.

EXAMPLES EXAMPLE 1 Possible contents of a template

The following example shows the possible contents of a template:

%B %eth of the year %Y

%B represents the full month name, %e the day of month and %Y the year (4 digits).

If DATEMSK is set to this template, the following calendar file would be valid:
March 7th of the year 1989 <Reminder>

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of calendar: LC_CTYPE, LC_TIME, LC_MESSAGES, NLSPATH, and TZ.
EXIT STATUS 0 Successful completion.
>0 An error occurred.
FILES /etc/passwd system password file
/tmp/cal* temporary files used by calendar
/usr/lib/calprog program used to determine dates for today and
tomorrow

110 man pages section 1: User Commands • Last Revised 1 Feb 1995
 calendar(1)
ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

SEE ALSO at(1), crontab(1), mail(1), cron(1M), ypbind(1M), strftime(3C),

attributes(5), environ(5)

NOTES Appropriate lines beginning with white space will not be printed.

Your calendar must be public information for you to get reminder service.

calendar’s extended idea of ‘‘tomorrow’’ does not account for holidays.

The - argument works only on calendar files that are local to the machine; calendar
is intended not to work on calendar files that are mounted remotely with NFS. Thus,
‘calendar -’ should be run only on diskful machines where home directories exist;
running it on a diskless client has no effect.

calendar is no longer in the default root crontab. Because of the network burden
‘calendar -’ can induce, it is inadvisable in an environment running ypbind(1M)
with a large passwd.byname map. If, however, the usefulness of calendar outweighs
the network impact, the super-user may run ‘crontab -e’ to edit the root crontab.
Otherwise, individual users may wish to use ‘crontab -e’ to edit their own crontabs
to have cron invoke calendar without the - argument, piping output to mail
addressed to themselves.

User Commands 111

cancel(1)
NAME cancel – cancel print request
SYNOPSIS cancel [request-ID…] [destination…]
cancel -u user… [destination…]

DESCRIPTION The cancel utility cancels print requests. There are two forms of the cancel
command.

The first form of cancel has two optional arguments: print requests (request-ID) and
destinations (destination). Specifying request-ID with destination cancels request-ID on
destination. Specifying only the destination cancels the current print request on
destination. If destination is not specified, cancel cancels the requested print request on
all destinations.

The second form of cancel cancels a user’s print requests on specific destinations.

Users can only cancel print requests associated with their username. By default, users
can only cancel print requests on the host from which the print request was submitted.
If a super-user has set user-equivalence=true in /etc/printers.conf on the
print server, users can cancel print requests associated with their username on any
host. Super-users can cancel print requests on the host from which the print request
was submitted. Super-users can also cancel print requests from the print server.

The print client commands locate destination information using the “printers”
database in the name service switch. See nsswitch.conf(4), printers(4), and
printers.conf(4) for details.

OPTIONS The following options are supported:

-u user The name of the user for which print requests are to be cancelled.
Specify user as a username.

OPERANDS The following operands are supported:

destination The destination on which the print requests are to be canceled.
destination is the name of a printer or class of printers (see
lpadmin(1M)). If destination is not specified, cancel cancels the
requested print request on all destinations. Specify destination
using atomic, POSIX-style (server:destination), or Federated
Naming Service (FNS) (. . ./service/printer/. . .)
names. See NOTES for information regarding using POSIX-style
destination names with cancel. See printers.conf(4) for
information regarding the naming conventions for atomic and FNS
names, and standards(5) for information regarding POSIX.
request-ID The print request to be canceled. Specify request-ID using LP-style
request IDs (destination-number).
user The name of the user for which the print requests are to be
cancelled. Specify user as a username.

112 man pages section 1: User Commands • Last Revised 12 Apr 1999
 cancel(1)
EXIT STATUS The following exit values are returned:
0 Successful completion.
non-zero An error occurred.
FILES /var/spool/print/* LP print queue.
$HOME/.printers User-configurable printer database.
/etc/printers.conf System printer configuration database.
printers.conf.byname NIS version of /etc/printers.conf.
printers.org_dir NIS+ version of /etc/printers.conf.
fns.ctx_dir.domain FNS version of /etc/printers.conf.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWpcu

SEE ALSO lp(1), lpq(1B), lpr(1B), lprm(1B), lpstat(1), lpadmin( 1M), nsswitch.conf(4),
printers(4), printers.conf(4), attributes(5), standards(5)

NOTES POSIX-style destination names (server:destination) are treated as print requests if

destination has the same format as an LP-style request-ID. See standards(5).

User Commands 113

cat(1)
NAME cat – concatenate and display files
SYNOPSIS cat [-nbsuvet] [file…]

DESCRIPTION The cat utility reads each file in sequence and writes it on the standard output. Thus:
example% cat file
prints file on your terminal, and:
example% cat file1 file2 >file3
concatenates file1 and file2, and writes the results in file3. If no input file is given, cat
reads from the standard input file.

OPTIONS The following options are supported:

-n Precede each line output with its line number.
-b Number the lines, as -n, but omit the line numbers from blank lines.
-u The output is not buffered. (The default is buffered output.)
-s cat is silent about non-existent files.
-v Non-printing characters (with the exception of tabs, new-lines and
form-feeds) are printed visibly. ASCII control characters (octal 000 − 037)
are printed as ^n, where n is the corresponding ASCII character in the
range octal 100 − 137 (@, A, B, C, . . ., X, Y, Z, [, \, ], ^, and _); the DEL
character (octal 0177) is printed ^?. Other non-printable characters are
printed as M-x, where x is the ASCII character specified by the low-order
seven bits.

When used with the -v option, the following options may be used:
-e A $ character will be printed at the end of each line (prior to the new-line).
-t Tabs will be printed as ^I’s and formfeeds to be printed as ^L’s.

The -e and -t options are ignored if the -v option is not specified.

OPERANDS The following operand is supported:

file A path name of an input file. If no file is specified, the standard
input is used. If file is ‘ − ’, cat will read from the standard input
at that point in the sequence. cat will not close and reopen
standard input when it is referenced in this way, but will accept
multiple occurrences of ‘ − ’ as file.

USAGE See largefile(5) for the description of the behavior of cat when encountering files
greater than or equal to 2 Gbyte ( 231 bytes).

EXAMPLES EXAMPLE 1 Concatenating a file

The following command:

example% cat myfile

114 man pages section 1: User Commands • Last Revised 1 Feb 1995
 cat(1)
EXAMPLE 1 Concatenating a file (Continued)

writes the contents of the file myfile to standard output.

EXAMPLE 2 Concatenating two files into one

The following command:

example% cat doc1 doc2 > doc.all
concatenates the files doc1 and doc2 and writes the result to doc.all.

EXAMPLE 3 Concatenating two arbitrary pieces of input with a single invocation

The command:
example% cat start - middle - end > file
when standard input is a terminal, gets two arbitrary pieces of input from the terminal
with a single invocation of cat. Note, however, that if standard input is a regular file,
this would be equivalent to the command:
cat start - middle /dev/null end > file
because the entire contents of the file would be consumed by cat the first time ‘ − ’
was used as a file operand and an end-of-file condition would be detected immediately
when ‘ − ’ was referenced the second time.

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of cat: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

EXIT STATUS The following exit values are returned:

0 All input files were output successfully.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

CSI enabled

Interface Stability Standard

SEE ALSO touch(1), attributes(5), environ(5), largefile(5), standards(5)

NOTES Redirecting the output of cat onto one of the files being read will cause the loss of the
data originally in the file being read. For example,

User Commands 115

cat(1)
example% cat filename1 filename2 >filename1
causes the original data in filename1 to be lost.

116 man pages section 1: User Commands • Last Revised 1 Feb 1995
 cc(1B)
NAME cc – C compiler
SYNOPSIS /usr/ucb/cc [options]

DESCRIPTION /usr/ucb/cc is the interface to the BSD Compatibility Package C compiler. It is a

script that looks for the link /usr/ccs/bin/ucbcc to the C compiler. The
/usr/ccs/bin/ucbcc link is available only with the SPROcc package, whose
default location is /opt/SUNWspro. The /usr/ucb/cc interface is identical to
/usr/ccs/bin/ucbcc, except that BSD headers are used and BSD libraries are
linked before base libraries. The /opt/SUNWspro/man/man1/acc.1 man page is
available only with the SPROcc package.

OPTIONS The /usr/ucb/cc interface accepts the same options as /usr/ccs/bin/ucbcc,

with the following exceptions:
-Idir Search dir for included files whose names do not begin with a
slash ( / ) prior to searching the usual directories. The directories
for multiple -I options are searched in the order specified. The
preprocessor first searches for #include files in the directory
containing sourcefile, and then in directories named with -I
options (if any), then /usr/ucbinclude, and finally, in
/usr/include.
-Ldir Add dir to the list of directories searched for libraries by
/usr/ccs/bin/ucbcc. This option is passed to
/usr/ccs/bin/ld and /usr/lib. Directories specified with this
option are searched before /usr/ucblib and /usr/lib.
-Y P, dir Change the default directory used for finding libraries.

EXIT STATUS The following exit values are returned:

0 Successful compilation or link edit.
>0 An error occurred.
FILES /usr/ccs/bin/ld link editor
/usr/lib/libc C library
/usr/ucbinclude BSD Compatibility directory for header files
/usr/ucblib BSD Compatibility directory for libraries
/usr/ucblib/libucb BSD Compatibility C library
/usr/lib/libsocket library containing socket routines
/usr/lib/libnsl library containing network functions
/usr/lib/libelf library containing routines to process ELF object files
/usr/lib/libaio library containing asynchronous I/O routines

User Commands 117

cc(1B)
ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWscpu

SEE ALSO ld(1), a.out(4), attributes(5)

NOTES The -Y P, dir option may have unexpected results and should not be used.

118 man pages section 1: User Commands • Last Revised 24 Feb 1998
 cd(1)
NAME cd, chdir, pushd, popd, dirs – change working directory
SYNOPSIS /usr/bin/cd [directory]
sh cd [argument]
chdir [argument]
csh cd [dir]
chdir [dir]
pushd [+n | dir]
popd [+n]
dirs [-l]
ksh cd [arg]
cd old new

DESCRIPTION

/usr/bin/cd The /usr/bin/cd utility changes the current directory in the context of the cd utility
only. This is in contrast to the version built into the shell, as described below.
/usr/bin/cd has no effect on the invoking process but can be used to determine
whether or not a given directory can be set as the current directory.

sh The Bourne shell built-in cd changes the current directory to argument. The shell
parameter HOME is the default argument. The shell parameter CDPATH defines the
search path for the directory containing argument. Alternative directory names are
separated by a colon (:). The default path is <null> (specifying the current
directory). Note: 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 argument begins with ‘/’, ‘.’, or ‘. . ’, the search path is not
used. Otherwise, each directory in the path is searched for argument. cd must have
execute (search) permission in argument. Because a new process is created to execute
each command, cd would be ineffective if it were written as a normal command;
therefore, it is recognized by and is internal to the shell. (See pwd(1), sh(1), and
chdir(2)).

chdir is just another way to call cd.

csh If dir is not specified, the C shell built-in cd uses the value of shell parameter HOME as
the new working directory. If dir specifies a complete path starting with ‘ / ’, ‘ . ’, or
‘ . . ’, dir becomes the new working directory. If neither case applies, cd tries to find
the designated directory relative to one of the paths specified by the CDPATH shell
variable. CDPATH has the same syntax as, and similar semantics to, the PATH shell
variable. cd must have execute (search) permission in dir. Because a new process is
created to execute each command, cd would be ineffective if it were written as a
normal command; therefore, it is recognized by and is internal to the C-shell. (See
pwd(1), sh(1), and chdir(2)).

User Commands 119

cd(1)
chdir changes the shell’s working directory to directory dir. 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.

pushd will push a directory onto the directory stack. With no arguments, exchange
the top two elements.
+n Rotate the n’th entry to the top of the stack and cd to it.
dir Push the current working directory onto the stack and change to dir.

popd pops the directory stack and cd 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.

dirs will print the directory stack, most recent to the left; the first directory shown is
the current directory. With the -l argument, produce an unabbreviated printout; use
of the ~ notation is suppressed.

ksh The Korn shell built-in cd command can be in either of two forms. In the first form it
changes the current directory to arg. If arg is − the directory is changed to the previous
directory. The shell variable HOME is the default arg. The variable PWD is set to the
current directory. The shell variable CDPATH defines the search path for the directory
containing arg. Alternative directory names are separated by a colon (:). The default
path is <null> (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 ‘ / ’, ‘
. ’, or ‘ . . ’, then the search path is not used. Otherwise, each directory in the path
is searched for arg.

The second form of cd substitutes the string new for the string old in the current
directory name, PWD and tries to change to this new directory.

The cd command may not be executed by rksh. Because a new process is created to
execute each command, cd would be ineffective if it were written as a normal
command; therefore, it is recognized by and is internal to the Korn shell. (See pwd(1),
sh(1), and chdir(2)).

OPERANDS The following operands are supported:

directory An absolute or relative pathname of the directory that becomes the
new working directory. The interpretation of a relative pathname
by cd depends on the CDPATH environment variable.

OUTPUT If a non-empty directory name from CDPATH is used, an absolute pathname of the new
working directory will be written to the standard output as follows:

"%s\n", <new directory>

120 man pages section 1: User Commands • Last Revised 26 Mar 2001
 cd(1)
Otherwise, there will be no output.

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of cd: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.
CDPATH A colon-separated list of pathnames that refer to directories. If the
directory operand does not begin with a slash ( / ) character, and
the first component is not dot or dot-dot, cd will search for
directory relative to each directory named in the CDPATH variable,
in the order listed. The new working directory will be set to the
first matching directory found. An empty string in place of a
directory pathname represents the current directory. If CDPATH is
not set, it will be treated as if it were an empty string.
HOME The name of the home directory, used when no directory operand is
specified.
OLDPWD A pathname of the previous working directory, used by cd-.
PWD A pathname of the current working directory, set by cd after it has
changed to that directory.

EXIT STATUS The following exit values are returned by cd:

0 The directory was successfully changed.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

Interface Stability Standard

SEE ALSO csh(1), ksh(1), pwd(1), sh(1), chdir(2), attributes(5), environ(5), standards(5)

User Commands 121

cdrw(1)
NAME cdrw – CD read and write
SYNOPSIS cdrw -i [-vSCO] [-d device] [-p speed] [image-file]
cdrw -a [-vSCO] [-d device] [-p speed] [-T audio-type] audio-file1
[audio-file2…]
cdrw -x [-v] [-d device] [-T audio-type] track-number out-file
cdrw -c [-vSC] [-d device] [-p speed] [-m tmp-dir] [-s src-device]
cdrw -b [-v] [-d device]all | session
cdrw -M [-v] [-d device]
cdrw -l [-v]
cdrw -h

DESCRIPTION The cdrw command provides the ability to create data and audio CDs. It also provides
the ability to extract audio tracks from an audio CD. Any MMC-compliant CD-R or
CD-RW drive can be used with cdrw.

cdrw will search for a CD writer device connected to the system, unless the user
specifies a device with the -d option. If it finds a single such writer device, it will use
that as the default CD writer device for the command.

When more than one CD writer is connected to the system, use the -d option to
indicate which device is desired. The device name can be specified in one of the
following ways: /dev/rdsk/cNtNdNsN, cNtNdNsN, cNtNdN, or a symbolic name
used by volume manager, such as cdrom or cdrom1. The -l option will provide a list
of CD writers.

For instructions on adding a USB-mass-storage-class-compliant CD-RW to your

system, see scsa2usb(7D).

Creating Data CDs When creating data CDs, cdrw uses the track-at-once mode of writing. With the -i
option, the user will specify a file that contains the data to write on CD media. In the
absence of such a file, cdrw will read data from standard input.

In either case, the data will typically first have been prepared by using the
mkisofs(1M) command to convert the file and file information into the High Sierra
format used on CDs. See the examples that include use of this command.

Creating Audio For creating an audio CD, using the -a option, single or multiple audio files can be
CDs specified. All of the audio files should be in the supported audio formats. Currently
approved formats are:
sun Sun .au files with data in Red Book CDDA form
wav RIFF (.wav) files with data in Red Book CDDA form
cda .cda files having raw CD audio data (that is, 16 bit PCM stereo at 44.1 KHz
sample rate in little-endian byteorder)

122 man pages section 1: User Commands • Last Revised 21 Aug 2001
 cdrw(1)
aur .aur files having raw CD data in big-endian byteorder

If no audio format is specified, cdrw tries to understand the audio file format based on
the file extension. The case of the characters in the extension is ignored. If a format is
specified using the -T option, it will be assumed as the audio file type for all the files
specified. Also, -cdrw will close the session after writing the audio tracks. Therefore,
the tracks to be written should be specified in a single command line.

Extracting Audio cdrw can also be used for extracting audio data from an audio CD with the -x option.
The CD should have tracks in Red Book CDDA form. By default, the output format is
based on the file extension. A user can specify a sun, wav, cda, or aur output format
using the -T option.

Copying CDs cdrw can be used to copy single session data CD-ROMs and Red Book audio CDs. For
copying a CD, cdrw looks for a specified source device. If no source device is specified
when using the -c option, the current CD writing device is assumed to be the source.
cdrw will extract the track or tracks into a temporary file and will look for a blank
writable CD-R/RW media in the current CD writing device. If no such media is found,
the user will be asked to insert a blank writable CD media in the current CD writing
device. If enough space is not available in the default temporary directory, an
alternative directory can be specified using the -m option.

Erasing CD-RW Users have to erase the CD-RW media before it can be re-written. With the -b option,
Media the following flavors of erasing are currently supported:
session Erase the last session.
all Erase the entire media.

If the session erasing type is used, cdrw will erase the last session. If there is only
one session recorded on the CD-RW (for example, a data/audio CD-RW created by
this tool), then session erasing is useful as it will only erase the portion that is
recorded, leaving behind a blank disk. This is faster than erasing the entire media.

The all erasing type should be used if it is a multisession disk, or the last session is
not closed, or disk status is unknown, and the user wishes to erase the disk. With this
type of erase, cdrw will erase the entire disk.

Checking The user can get a list of CD writing devices currently present in the system with the
device-list or -l option. Also, for a particular media, the user can get the blanking status and table
media-status of contents through the -M option. The -M option also prints information about the last
session start address and the next writable address. This information, along with the
-O option, can be used to create multisession CDs. Please refer to mkisofs(1M) for
more information.

OPTIONS The following options are supported:

-a Creates an audio disk. At least one audio-file name must be specified. A CD
can not have more than 99 audio tracks, so no more than 99 audio files can

User Commands 123

cdrw(1)
be specified. Also, the maximum audio data that can be written to the
media by default is 74 minutes, unless -C is specified.
-b Blanks a CD-RW media. The type of erasing must be specified by the all
or session argument.
-c Copies a CD. If no other argument is specified, the default CD writing
device is assumed to be the source device as well. In this case, the copying
operation will read the source media into a temporary directory and will
prompt the user to place a blank media into the drive for copying to
proceed.
-C Uses media stated capacity. Without this option, cdrw will use a default
value for writable CD media, which is 74 minutes for an audio CD or
681984000 bytes for a data CD.
-d Specifies CD writing device.
-h Help. Prints usage message.
-i Specifies image file for creating data CDs. The file size should be less than
what can be written on a CD-R or CD-RW media, which is 681984000 bytes
by default or the media stated capacity if the -C option is used. Also, it is
better to have the file locally available instead of having it on an
NFS-mounted filesystem, because the CD writing process expects data to
be available continuously without interruptions.
-l Lists all the CD writers found in the system.
-m Uses an alternate temporary directory instead of system default temporary
directory for storing track data while copying a CD. An alternate
temporary directory might be required because the amount of data on a CD
can be huge (as much as 800 Mbytes for an 80 minute audio CD) and the
system default temporary directory might not have that much space.
-M Reports media status. cdrw will report if the media is blank or not, its table
of contents, the last session’s start address, and the next writable address if
the disk is open.
-O Keeps the disk open. cdrw will close the session, but it will keep the disk
open so that another session can be added later on to create a multisession
disk.
-p Sets the CD writing speed. For example, -p 4 will set the speed to 4X. If
this option is not specified, cdrw will use the default speed of the CD
writer. If this option is specified, cdrw will try to set the drive write speed
to this value, but there is no guarantee of the speed actually used by the
drive.
-s Specifies source device for copying CD.

124 man pages section 1: User Commands • Last Revised 21 Aug 2001
 cdrw(1)
-S Simulation mode. In this mode, cdrw will do everything with the drive
laser turned off, so nothing will be written to the media. This can be used
to verify if the system can provide data at a rate good enough for CD
writing.
-T Audio format to use extracting audio files or reading audio files for audio
CD creation. The audio-type can be sun, wav, cda, or aur.
-v Verbose mode.
-x Extracts audio data from an audio track.

EXAMPLES EXAMPLE 1 Creating a data CD

example% cdrw -i /local/iso_image

EXAMPLE 2 Creating a CD from a directory

This example creates a CD from the directory tree /home/foo:

example% mkisofs –r /home/foo 2>/dev/null | cdrw –i –p 1

EXAMPLE 3 Extracting an audio track number

This example extracts audio track number 1 to /home/foo/song1.wav:

example% cdrw –x –T wav 1 /home/foo/song1.wav

EXAMPLE 4 Using wav files

This example creates an audio CD from wav files on disk:

example% cdrw –a song1.wav song2.wav song3.wav song4.wav

EXAMPLE 5 Erasing a CD-RW media

This example erases a CD-RW media in a CD-RW drive:

example% cdrw –b all

EXAMPLE 6 Creating a data CD with multiple drives

This example creates a data CD on a system with multiple CD-R/RW drives:

example% cdrw –d c1t6d0s2 –i /home/foo/iso-image

EXAMPLE 7 Checking data delivery rate

This example checks if the system can provide data to a CD-RW drive at a rate
sufficient for the write operation:

User Commands 125

cdrw(1)
EXAMPLE 7 Checking data delivery rate (Continued)

example% cdrw –S –i /home/foo/iso-image

EXAMPLE 8 Running at a higher priority

This example runs cdrw at a higher priority (for root user only):
example# priocntl –e –p 60 cdrw –i /home/foo/iso-image

EXAMPLE 9 Creating a multi-session disk

Create the first session image using mkisofs(1M) and record it onto the disk without
closing the disk:
example% cdrw -O -i /home/foo/iso-image

Additional sessions can be added to an open disk by creating an image with

mkisofs(1M) using the session start and next writable address reported by cdrw.
example% cdrw -M

Track No. |Type |Start address

----------+--------+-------------
1 |Data | 0
Leadout |Data | 166564

Last session start address: 162140

Next writable address: 173464

example% mkisofs -o /tmp/image2 -r -C 0,173464 -M \

/dev/rdsk/c0t2d0s2 /home/foo

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcdrw

SEE ALSO audioconvert(1), mkisofs(1M), priocntl(1), attributes(5), rbac(5),

scsa2usb(7D), sd(7D)

NOTES The CD writing process requires data to be supplied at a constant rate to the drive. It
is advised to keep I/O activity to a minimum and shut down the related applications
while writing CDs.

When making copies or extracting audio tracks, it is better to use an MMC compliant
source CD-ROM drive. The CD writing device can be used for this purpose.

126 man pages section 1: User Commands • Last Revised 21 Aug 2001
 cdrw(1)
Before writing a CD, ensure that the media is blank by using the -M option and use the
-S simulation mode to test the system to make sure it can provide data at the required
rate. In case the system is not able to provide data at the required rate, try simulation
with a slower write speed set through the -p option. Users can also try to run cdrw at
a higher priority using the priocntl(1) command.

The -p option is provided for users who are aware of the CD-R/RW drive and its
capabilities to operate at different write speeds. Some commercially available drives
handle the drive speed setting command differently, so use this option judiciously.

Most commercially available drives allow writing beyond 74 minutes as long as the
media has the capacity (such as 80–minute media). However, such capability of
writing beyond 74 minutes might not be supported by the drive in use. If the drive
being used supports such capability, then use the -C option to indicate that the tool
should rely on the capacity indicated by the media.

The cdrw command uses rbac(5) to control user access to the devices. By default,
cdrw is accessible to all users but can be restricted to individual users. Please refer to
"Administering CD-R/CD-RW devices" in the System Administration Guide: Basic
Administration for more information.

User Commands 127

checknr(1)
NAME checknr – check nroff and troff input files; report possible errors
SYNOPSIS checknr [-fs] [-a . x1 . y1 . x2 . y2 ... .xn .yn] [-c . x1 . x2 . x3
... .xn] [filename…]

DESCRIPTION checknr checks a list of nroff(1) or troff(1) 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:
■ Font changes using \fx . . . \fP.
■ Size changes using \sx . . . \s0.
■ 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(5) and me(5) 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 \fP and each \sx must be terminated with \s0.
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 \fP and \s0
forms anyway, you should think of this as a contribution to your document
preparation style.
OPTIONS -f Ignore \f font changes.
-s Ignore \s size changes.
-a .x1 .y1. . . 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 -a 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
‘-a.BS.ES’
-c .x1 . . . Define commands which checknr would otherwise complain
about as undefined.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWdoc

SEE ALSO eqn(1), nroff(1), troff(1), attributes(5), me(5), ms(5)

BUGS There is no way to define a one-character macro name using the -a option.

128 man pages section 1: User Commands • Last Revised 14 Sep 1992
 chgrp(1)
NAME chgrp – change file group ownership
SYNOPSIS chgrp [-fhR] group file…

DESCRIPTION The chgrp utility will set the group ID of the file named by each file operand to the
group ID specified by the group operand.

For each file operand, it will perform actions equivalent to the chown(2) function,
called with the following arguments:
■ The file operand will be used as the path argument.
■ The user ID of the file will be used as the owner argument.
■ The specified group ID will be used as the group argument.

Unless chgrp is invoked by a process with appropriate privileges, the set-user-ID and
set-group-ID bits of a regular file will be cleared upon successful completion; the
set-user-ID and set-group-ID bits of other file types may be cleared.

The operating system has a configuration option _POSIX_CHOWN_RESTRICTED, to

restrict ownership changes. When this option is in effect, the owner of the file may
change the group of the file only to a group to which the owner belongs. Only the
super-user can arbitrarily change owner IDs, whether or not this option is in effect. To
set this configuration option, include the following line in /etc/system:
set rstchown = 1

To disable this option, include the following line in /etc/system:

set rstchown = 0

_POSIX_CHOWN_RESTRICTED is enabled by default. See system(4) and

fpathconf(2).

OPTIONS The following options are supported:

-f Force. Do not report errors.
-h If the file is a symbolic link, change the group of the symbolic link. Without
this option, the group of the file referenced by the symbolic link is changed.
-R Recursive. chgrp descends through the directory, and any subdirectories,
setting the specified group ID as it proceeds. When a symbolic link is
encountered, the group of the target file is changed (unless the -h option is
specified), but no recursion takes place.

OPERANDS The following operands are supported:

group A group name from the group database or a numeric group ID. Either
specifies a group ID to be given to each file named by one of the file
operands. If a numeric group operand exists in the group database as a
group name, the group ID number associated with that group name is used
as the group ID.

User Commands 129

chgrp(1)
file A path name of a file whose group ID is to be modified.

USAGE See largefile(5) for the description of the behavior of chgrp when encountering
files greater than or equal to 2 Gbyte (231 bytes).

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of chgrp: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

EXIT STATUS The following exit values are returned:

0 The utility executed successfully and all requested changes were made.
>0 An error occurred.
FILES /etc/group group file

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

CSI Enabled (see NOTES)

Interface Stability Standard

SEE ALSO chmod(1), chown(1), id(1M), chown(2), fpathconf(2), group(4), passwd(4),

system(4), attributes(5), environ(5), largefile(5), standards(5)

NOTES chgrp is CSI-enabled except for the group name.

130 man pages section 1: User Commands • Last Revised 20 Dec 1996
 chkey(1)
NAME chkey – change user’s secure RPC key pair
SYNOPSIS chkey [-p] [-s nisplus | nis | files | ldap] [-m <mechanism>]

DESCRIPTION chkey is used to change a user’s secure RPC public key and secret key pair. chkey
prompts for the old secure-rpc password and verifies that it is correct by decrypting
the secret key. If the user has not already used keylogin(1) to decrypt and store the
secret key with keyserv(1M), chkey registers the secret key with the local
keyserv( 1M) daemon. If the secure-rpc password does not match the login
password, chkey prompts for the login password. chkey uses the login password to
encrypt the user’s secret Diffie-Hellman (192 bit) cryptographic key. chkey can also
encrypt other Diffie-Hellman keys for authentication mechanisms configured using
nisauthconf(1M).

chkey ensures that the login password and the secure-rpc password(s) are kept the
same, thus enabling password shadowing. See shadow(4).

The key pair can be stored in the /etc/publickey file (see publickey(4)), the NIS
publickey map, or the NIS+ cred.org_dir table. If a new secret key is generated,
it will be registered with the local keyserv(1M) daemon. However, only NIS+ can
store Diffie-Hellman keys other than 192-bits.

Keys for specific mechanisms can be changed or reencrypted using the -m option
followed by the authentication mechanism name. Multiple -m options can be used to
change one or more keys. However, only mechanisms configured using
nisauthconf(1M) can be changed with chkey.

If the source of the publickey is not specified with the -s option, chkey consults the
publickey entry in the name service switch configuration file. See
nsswitch.conf(4). If the publickey entry specifies one and only one source, then
chkey will change the key in the specified name service. However, if multiple name
services are listed, chkey can not decide which source to update and will display an
error message. The user should specify the source explicitly with the -s option.

Non root users are not allowed to change their key pair in the files database.

OPTIONS The following options are supported:

-p Re-encrypt the existing secret key with the user’s login
password.
-s nisplus Update the NIS+ database.
-s nis Update the NIS database.
-s files Update the files database.
-s ldap Update the LDAP database.
-m <mechanism> Changes or re-encrypt the secret key for the specified
mechanism.

User Commands 131

chkey(1)
FILES /etc/nsswitch.conf
/etc/publickey

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO keylogin(1), keylogout(1), keyserv(1M), newkey(1M), nisaddcred(1M),

nisauthconf(1M), nsswitch.conf(4), publickey(4), shadow(4), attributes(5)

NOTES NIS+ might not be supported in future releases of the Solaris™ Operating
Environment. Tools to aid the migration from NIS+ to LDAP are available in the
Solaris 9 operating environment. For more information, visit
http://www.sun.com/directory/nisplus/transition.html.

132 man pages section 1: User Commands • Last Revised 24 Jan 2002
 chmod(1)
NAME chmod – change the permissions mode of a file
SYNOPSIS chmod [-fR] absolute-mode file…
chmod [-fR] symbolic-mode-list file…

DESCRIPTION The chmod utility changes or assigns the mode of a file. The mode of a file specifies its
permissions and other attributes. The mode may be absolute or symbolic.

Absolute mode An absolute mode specification has the following format:

chmod [options] absolute-mode file . . .where absolute-mode is specified using octal

numbers nnnn defined as follows:

n a number from 0 to 7. An absolute mode is constructed from the OR of any

of the following modes:
4000 Set user ID on execution.
20 # 0 Set group ID on execution if # is 7, 5, 3, or 1.

Enable mandatory locking if # is 6, 4, 2, or 0.

For directories, files are created with BSD semantics for

propagation of the group ID. With this option, files and
subdirectories created in the directory inherit the group ID of
the directory, rather than of the current process. For directories,
the set-gid bit may only be set or cleared by using symbolic
mode.
1000 Turn on sticky bit. See chmod(2).
0400 Allow read by owner.
0200 Allow write by owner.
0100 Allow execute (search in directory) by owner.
0700 Allow read, write, and execute (search) by owner.
0040 Allow read by group.
0020 Allow write by group.
0010 Allow execute (search in directory) by group.
0070 Allow read, write, and execute (search) by group.
0004 Allow read by others.
0002 Allow write by others.
0001 Allow execute (search in directory) by others.
0007 Allow read, write, and execute (search) by others.

User Commands 133

chmod(1)
For directories, the setgid bit cannot be set (or cleared) in absolute mode; it must be
set (or cleared) in symbolic mode using g+s (or g-s).

Symbolic mode A symbolic mode specification has the following format:

chmod [options] symbolic-mode-list file . . .where symbolic-mode-list is a comma-separated

list (with no intervening whitespace) of symbolic mode expressions of the form:

[who] operator [permissions]

Operations are performed in the order given. Multiple permissions letters following a
single operator cause the corresponding operations to be performed simultaneously.
who zero or more of the characters u, g, o, and a specifying whose
permissions are to be changed or assigned:
u user’s permissions
g group’s permissions
o others’ permissions
a all permissions (user, group, and other)

If who is omitted, it defaults to a, but the setting of the file mode

creation mask (see umask in sh(1) or csh(1) for more information)
is taken into account. When who is omitted, chmod will not
override the restrictions of your user mask.
operator either +, −, or =, signifying how permissions are to be changed:
+ Add permissions.

If permissions is omitted, nothing is added.

If who is omitted, add the file mode bits represented by

permissions, except for the those with corresponding bits
in the file mode creation mask.

If who is present, add the file mode bits represented by

the permissions.
− Take away permissions.

If permissions is omitted, do nothing.

If who is omitted, clear the file mode bits represented

by permissions, except for those with corresponding bits
in the file mode creation mask.

If who is present, clear the file mode bits represented by

permissions.

134 man pages section 1: User Commands • Last Revised 4 Dec 2000
 chmod(1)
= Assign permissions absolutely.

If who is omitted, clear all file mode bits; if who is

present, clear the file mode bits represented by who.

If permissions is omitted, do nothing else.

If who is omitted, add the file mode bits represented by

permissions, except for the those with corresponding bits
in the file mode creation mask.

If who is present, add the file mode bits represented by

permissions.

Unlike other symbolic operations, = has an absolute effect in that it

resets all other bits represented by who. Omitting permissions is
useful only with = to take away all permissions.
permission any compatible combination of the following letters:
l mandatory locking
r read permission
s user or group set-ID
t sticky bit
w write permission
x execute permission
X execute permission if the file is a directory or if there is
execute permission for one of the other user classes
u,g,o indicate that permission is to be taken from the current
user, group or other mode respectively.

Permissions to a file may vary depending on your user

identification number (UID) or group identification number (GID).
Permissions are described in three sequences each having three
characters:

User Group Other

rwx rwx rwx

This example (user, group, and others all have permission to read,
write, and execute a given file) demonstrates two categories for
granting permissions: the access class and the permissions
themselves.

User Commands 135

chmod(1)
The letter s is only meaningful with u or g, and t only works with
u.

Mandatory file and record locking (l) refers to a file’s ability to

have its reading or writing permissions locked while a program is
accessing that file.

In a directory which has the set-group-ID bit set (reflected as either

-----s--- or -----l--- in the output of ’ls -ld’), files and
subdirectories are created with the group-ID of the parent
directory—not that of current process.

It is not possible to permit group execution and enable a file to be

locked on execution at the same time. In addition, it is not possible
to turn on the set-group-ID bit and enable a file to be locked on
execution at the same time. The following examples, therefore, are
invalid and elicit error messages:
chmod g+x,+l file
chmod g+s,+l file

Only the owner of a file or directory (or the super-user) may

change that file’s or directory’s mode. Only the super-user may set
the sticky bit on a non-directory file. If you are not super-user,
chmod will mask the sticky-bit but will not return an error. In
order to turn on a file’s set-group-ID bit, your own group ID must
correspond to the file’s and group execution must be set.

OPTIONS The following options are supported:

-f Force. chmod will not complain if it fails to change the mode of a file.
-R Recursively descends through directory arguments, setting the mode for
each file as described above. When symbolic links are encountered, the
mode of the target file is changed, but no recursion takes place.

OPERANDS The following operands are supported:

absolute-mode
symbolic-mode-list Represents the change to be made to the file mode bits of each file
named by one of the file operands. See Absolute Mode and
Symbolic Mode above in the DESCRIPTION section for more
information.
file A path name of a file whose file mode bits are to be modified.

USAGE See largefile(5) for the description of the behavior of chmod when encountering
files greater than or equal to 2 Gbyte ( 231 bytes).

EXAMPLES EXAMPLE 1 Denying execute permission to everyone

example% chmod a-x file

136 man pages section 1: User Commands • Last Revised 4 Dec 2000
 chmod(1)
EXAMPLE 2 Allowing only read permission to everyone
example% chmod 444 file

EXAMPLE 3 Making a file readable and writable by the group and others
example% chmod go+rw file
example% chmod 066 file

EXAMPLE 4 Causing a file to be locked during access

example% chmod +l file

EXAMPLE 5 Allowing everyone to read, write, and execute the file and turn on the set
group-ID
example% chmod a=rwx,g+s file
example% chmod 2777 file

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of chmod: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

EXIT STATUS The following exit values are returned:

0 Successful completion.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

CSI enabled

Interface Stability Standard

SEE ALSO getfacl(1), ls(1), setfacl(1), chmod(2), attributes(5), environ(5),

largefile(5), standards(5)

NOTES Absolute changes do not work for the set-group-ID bit of a directory. You must use
g+s or g-s.

chmod permits you to produce useless modes so long as they are not illegal (for
instance, making a text file executable). chmod does not check the file type to see if
mandatory locking is meaningful.

If the filesystem is mounted with the nosuid option, setuid execution is not allowed.

User Commands 137

chmod(1)
If you use chmod to change the file group owner permissions on a file with ACL
entries, both the file group owner permissions and the ACL mask are changed to the
new permissions. Be aware that the new ACL mask permissions may change the
effective permissions for additional users and groups who have ACL entries on the
file. Use the getfacl(1) command to make sure the appropriate permissions are set
for all ACL entries.

138 man pages section 1: User Commands • Last Revised 4 Dec 2000
 chown(1)
NAME chown – change file ownership
SYNOPSIS chown [-fhR] owner [: group] file…

DESCRIPTION The chown utility will set the user ID of the file named by each file to the user ID
specified by owner, and, optionally, will set the group ID to that specified by group.

If chown is invoked by other than the super-user, the set-user-ID bit is cleared.

Only the owner of a file (or the super-user) may change the owner of that file.

The operating system has a configuration option {_POSIX_CHOWN_RESTRICTED}, to

restrict ownership changes. When this option is in effect the owner of the file is
prevented from changing the owner ID of the file. Only the super-user can arbitrarily
change owner IDs whether or not this option is in effect. To set this configuration
option, include the following line in /etc/system:
set rstchown = 1

To disable this option, include the following line in /etc/system:

set rstchown = 0

{_POSIX_CHOWN_RESTRICTED} is enabled by default. See system(4) and

fpathconf(2).

OPTIONS The following options are supported:

-f Do not report errors.
-h If the file is a symbolic link, change the owner of the symbolic link. Without
this option, the owner of the file referenced by the symbolic link is
changed.
-R Recursive. chown descends through the directory, and any subdirectories,
setting the ownership ID as it proceeds. When a symbolic link is
encountered, the owner of the target file is changed (unless the -h option is
specified), but no recursion takes place.

OPERANDS The following operands are supported:

owner[: group] A user ID and optional group ID to be assigned to
file. The owner portion of this operand must be a user
name from the user database or a numeric user ID.
Either specifies a user ID to be given to each file named
by file. If a numeric owner exists in the user database as
a user name, the user ID number associated with that
user name will be used as the user ID. Similarly, if the
group portion of this operand is present, it must be a
group name from the group database or a numeric
group ID. Either specifies a group ID to be given to
each file. If a numeric group operand exists in the

User Commands 139

chown(1)
group database as a group name, the group ID number
associated with that group name will be used as the
group ID.
file A path name of a file whose user ID is to be modified.

USAGE See largefile(5) for the description of the behavior of chown when encountering
files greater than or equal to 2 Gbyte ( 231 bytes).

EXAMPLES EXAMPLE 1 Changing ownership of all files in the hierarchy

To change ownership of all files in the hierarchy, including symbolic links, but not the
targets of the links:
example% chown −R −h owner[:group] file...

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of chown: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

EXIT STATUS The following exit values are returned:

0 The utility executed successfully and all requested changes were made.
>0 An error occurred.
FILES /etc/passwd system password file

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

CSI Enabled (see NOTES)

Interface Stability Standard

SEE ALSO chgrp(1), chmod(1), chown(2), fpathconf(2), passwd(4), system(4),

attributes(5), environ(5), largefile(5), standards(5)

NOTES chown is CSI-enabled except for the owner and group names.

140 man pages section 1: User Commands • Last Revised 1 Jun1998

 chown(1B)
NAME chown – change owner
SYNOPSIS /usr/ucb/chown [-fR] owner [.group] filename…

DESCRIPTION chown changes the owner of the filenames to owner. The owner may be either a decimal
user ID (UID) or a login name found in the password file. An optional group may also
be specified. The group may be either a decimal group ID (GID) or a group name
found in the GID file.

Only the super-user can change owner, in order to simplify accounting procedures.
OPTIONS -f Do not report errors.
-R 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.

USAGE See largefile(5) for the description of the behavior of chown when encountering
files greater than or equal to 2 Gbyte ( 231 bytes).
FILES /etc/passwd password file

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWscpu

SEE ALSO chgrp(1), chown(2), group(4), passwd(4), attributes(5), largefile(5)

User Commands 141

ckdate(1)
NAME ckdate, errdate, helpdate, valdate – prompts for and validates a date
SYNOPSIS ckdate [-Q] [-W width] [-f format] [-d default] [-h help] [-e error]
[-p prompt] [-k pid [-s signal]]
/usr/sadm/bin/errdate [-W width] [-e error] [-f format]
/usr/sadm/bin/helpdate [-W width] [-h help] [-f format]
/usr/sadm/bin/valdate [-f format] input

DESCRIPTION The ckdate utility prompts a user and validates the response. It defines, among other
things, a prompt message whose response should be a date, text for help and error
messages, and a default value (which will be returned if the user responds with a
RETURN). The user response must match the defined format for a date.

All messages are limited in length to 70 characters and are formatted automatically.
Any white space used in the definition (including newline) is stripped. The -W option
cancels the automatic formatting. When a tilde is placed at the beginning or end of a
message definition, the default text will be inserted at that point, allowing both
custom text and the default text to be displayed.

If the prompt, help or error message is not defined, the default message (as defined
under NOTES) will be displayed.

Three visual tool modules are linked to the ckdate command. They are errdate
(which formats and displays an error message), helpdate (which formats and
displays a help message), and valdate (which validates a response). These modules
should be used in conjunction with FML objects. In this instance, the FML object
defines the prompt. When format is defined in the errdate and helpdate
modules, the messages will describe the expected format.

OPTIONS The following options are supported:

-d default Defines the default value as default. The default does not have to
meet the format criteria.
-e error Defines the error message as error.
-f format Specifies the format against which the input will be verified.
Possible formats and their definitions are:
%b = abbreviated month name (jan, feb, mar)
%B = full month name %d = day of month (01 - 31)
%D = date as %m/%d/%y (the default format)
%e = day of month (1 - 31; single digits are preceded by a
blank)
%h = abbreviated month name, identical to %b%
%m = month number (01 - 12)

142 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckdate(1)
%y = year within century (for instance, 89)
%Y = year as CCYY (for instance, 1989)
-h help Defines the help messages as help.
-k pid Specifies that process ID pid is to be sent a signal if the user
chooses to abort.
-p prompt Defines the prompt message as prompt.
-Q Specifies that quit will not be allowed as a valid response.
-s signal Specifies that the process ID pid defined with the -k option is to be
sent signal signal when quit is chosen. If no signal is specified,
SIGTERM is used.
-W width Specifies that prompt, help and error messages will be formatted
to a line length of width.

OPERANDS The following operand is supported:

input Input to be verified against format criteria.

EXIT STATUS The following exit values are returned:

0 Successful execution.
1 EOF on input, or negative width on -W option, or usage error.
3 User termination (quit).
4 Garbled format argument.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO attributes(5)

NOTES The default prompt for ckdate is:

Enter the date [?,q]:

The default error message is:

ERROR - Please enter a date. Format is <format>.

The default help message is:

Please enter a date. Format is <format>.

User Commands 143

ckdate(1)
When the quit option is chosen (and allowed), q is returned along with the return code
3. The valdate module will not produce any output. It returns zero for success and
non-zero for failure.

144 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckgid(1)
NAME ckgid, errgid, helpgid, valgid – prompts for and validates a group id
SYNOPSIS ckgid [-Q] [-W width] [-m] [-d default] [-h help] [-e error] [-p prompt]
[-k pid [-s signal]]
/usr/sadm/bin/errgid [-W width] [-e error]
/usr/sadm/bin/helpgid [-W width] [-m] [-h help]
/usr/sadm/bin/valgid input

DESCRIPTION ckgid prompts a user and validates the response. It defines, among other things, a
prompt message whose response should be an existing group ID, text for help and
error messages, and a default value (which will be returned if the user responds with a
carriage return).

All messages are limited in length to 70 characters and are formatted automatically.
Any white space used in the definition (including newline) is stripped. The -W option
cancels the automatic formatting. When a tilde is placed at the beginning or end of a
message definition, the default text will be inserted at that point, allowing both
custom text and the default text to be displayed.

If the prompt, help or error message is not defined, the default message (as defined
under NOTES) will be displayed.

Three visual tool modules are linked to the ckgid command. They are errgid
(which formats and displays an error message), helpgid (which formats and displays
a help message), and valgid (which validates a response). These modules should be
used in conjunction with FML objects. In this instance, the FML object defines the
prompt.

OPTIONS The following options are supported:

-d default Defines the default value as default. The default is not validated
and so does not have to meet any criteria.
-e error Defines the error message as error.
-h help Defines the help messages as help.
-k pid Specifies that process ID pid is to be sent a signal if the user
chooses to abort.
-m Displays a list of all groups when help is requested or when the
user makes an error.
-p prompt Defines the prompt message as prompt.
-Q Specifies that quit will not be allowed as a valid response.
-s signal Specifies that the process ID pid defined with the -k option is to be
sent signal signal when quit is chosen. If no signal is specified,
SIGTERM is used.

User Commands 145

ckgid(1)
-W width Specifies that prompt, help and error messages will be formatted
to a line length of width.

OPERANDS The following operand is supported:

input Input to be verified against /etc/group.

EXIT STATUS The following exit values are returned:

0 Successful execution.
1 EOF on input, or negative width on -W option, or usage error.
3 User termination (quit).

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO attributes(5)

NOTES The default prompt for ckgid is:

Enter the name of an existing group [?,q]:

The default error message is:

ERROR: Please enter one of the following group names: [List]

If the -m option of ckgid is used, a list of valid groups is displayed here.

The default help message is:

ERROR: Please enter one of the following group names: [List]

If the -m option of ckgid is used, a list of valid groups is displayed here.

When the quit option is chosen (and allowed), q is returned along with the return code
3. The valgid module will not produce any output. It returns 0 for success and
non-zero for failure.

146 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckint(1)
NAME ckint, errint, helpint, valint – display a prompt; verify and return an integer value
SYNOPSIS ckint [-Q] [-W width] [-b base] [-d default] [-h help] [-e error]
[-p prompt] [-k pid [-s signal]]
/usr/sadm/bin/errint [-W width] [-b base] [-e error]
/usr/sadm/bin/helpint [-W width] [-b base] [-h help]
/usr/sadm/bin/valint [-b base] input

DESCRIPTION The ckint utility prompts a user, then validates the response. It defines, among other
things, a prompt message whose response should be an integer, text for help and error
messages, and a default value (which will be returned if the user responds with a
carriage return).

All messages are limited in length to 70 characters and are formatted automatically.
Any white space used in the definition (including newline) is stripped. The -W option
cancels the automatic formatting. When a tilde is placed at the beginning or end of a
message definition, the default text will be inserted at that point, allowing both
custom text and the default text to be displayed.

If the prompt, help or error message is not defined, the default message (as defined
under NOTES) will be displayed.

Three visual tool modules are linked to the ckint command. They are errint
(which formats and displays an error message), helpint (which formats and displays
a help message), and valint (which validates a response). These modules should be
used in conjunction with FML objects. In this instance, the FML object defines the
prompt. When base is defined in the errint and helpint modules, the messages
will include the expected base of the input.

OPTIONS The following options are supported:

-b base Defines the base for input. Must be 2 to 36, default is 10.
-d default Defines the default value as default. The default is not validated
and so does not have to meet any criteria.
-e error Defines the error message as error.
-h help Defines the help messages as help.
-k pid Specifies that process ID pid is to be sent a signal if the user
chooses to abort.
-p prompt Defines the prompt message as prompt.
-Q Specifies that quit will not be allowed as a valid response.
-s signal Specifies that the process ID pid defined with the -k option is to be
sent signal signal when quit is chosen. If no signal is specified,
SIGTERM is used.

User Commands 147

ckint(1)
-W width Specifies that prompt, help and error messages will be formatted
to a line length of width.

OPERANDS The following operand is supported:

input Input to be verified against base criterion.

EXIT STATUS The following exit values are returned:

0 Successful execution.
1 EOF on input, or negative width on -W option, or usage error.
3 User termination (quit).

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO attributes(5)

NOTES The default base 10 prompt for ckint is:

Enter an integer [?,q]:

The default base 10 error message is:

ERROR - Please enter an integer.

The default base 10 help message is:

Please enter an integer.

The messages are changed from "integer" to "base base integer" if the base is set to a
number other than 10.

When the quit option is chosen (and allowed), q is returned along with the return code
3. The valint module will not produce any output. It returns 0 for success and
non-zero for failure.

148 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckitem(1)
NAME ckitem, erritem, helpitem – build a menu; prompt for and return a menu item
SYNOPSIS ckitem [-Q] [-W width] [-uno] [-f filename] [-l label] [ [-i invis] [,…]]
[-m max] [-d default] [-h help] [-e error] [-p prompt] [-k pid
[-s signal]] [choice [...]]
/usr/sadm/bin/erritem [-W width] [-e error] [choice [..]]
/usr/sadm/bin/helpitem [-W width] [-h help] [choice [..]]

DESCRIPTION The ckitem utility builds a menu and prompts the user to choose one item from a
menu of items. It then verifies the response. Options for this command define, among
other things, a prompt message whose response will be a menu item, text for help and
error messages, and a default value (which will be returned if the user responds with a
carriage return).

By default, the menu is formatted so that each item is prepended by a number and is
printed in columns across the terminal. Column length is determined by the longest
choice. Items are alphabetized.

All messages are limited in length to 70 characters and are formatted automatically.
Any white space used in the definition (including newline) is stripped. The -W option
cancels the automatic formatting. When a tilde is placed at the beginning or end of a
message definition, the default text will be inserted at that point, allowing both
custom text and the default text to be displayed.

If the prompt, help or error message is not defined, the default message (as defined
under NOTES) will be displayed.

Two visual tool modules are linked to the ckitem command. They are erritem
(which formats and displays an error message) and helpitem (which formats and
displays a help message). These modules should be used in conjunction with FML
objects. In this instance, the FML object defines the prompt. When choice is defined in
these modules, the messages will describe the available menu choice (or choices).

OPTIONS The following options are supported:

-d default Define the default value as default. The default is not validated and
so does not have to meet any criteria.
-e error Define the error message as error.
-f filename Define a file, filename, which contains a list of menu items to be
displayed. (The format of this file is: token<tab>description.
Lines beginning with a pound sign (#) are designated as comments
and ignored.)
-h help Define the help messages as help.
-i invis Define invisible menu choices (those which will not be printed in
the menu). (For example, ‘‘all’’ used as an invisible choice would
mean it is a legal option but does not appear in the menu. Any

User Commands 149

ckitem(1)
number of invisible choices may be defined.) Invisible choices
should be made known to a user either in the prompt or in a help
message.
-k pid Specify that the process ID pid is to be sent a signal if the user
chooses to abort.
-l label Define a label, label, to print above the menu.
-m max Define the maximum number of menu choices that the user can
choose. The default is 1.
-n Specify that menu items should not be displayed in alphabetical
order.
-o Specify that only one menu token will be returned.
-p prompt Define the prompt message as prompt.
-Q Specify that quit will not be allowed as a valid response.
-s signal Specify that process ID pid defined with the -k option is to be sent
signal signal when quit is chosen. If no signal is specified,
SIGTERM is used.
-u Specify that menu items should be displayed as an unnumbered
list.
-W width Specify that prompt, help and error messages will be formatted to
a line length of width.

OPERANDS The following operand is supported:

choice Define menu items. Items should be separated by white space or
newline.

EXIT STATUS The following exit values are returned:

0 Successful execution.
1 EOF on input, or negative width on -W option, or inability to open file on
-f option, or usage error.
3 User termination (quit).
4 No choices from which to choose.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO attributes(5)

150 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckitem(1)
NOTES The user may input the number of the menu item if choices are numbered or as much
of the string required for a unique identification of the item. Long menus are paged
with 10 items per page.

When menu entries are defined both in a file (by using the -f option) and also on the
command line, they are usually combined alphabetically. However, if the -n option is
used to suppress alphabetical ordering, then the entries defined in the file are shown
first, followed by the options defined on the command line.

The default prompt for ckitem is:

Enter selection [?,??,q]:

One question mark will give a help message and then redisplay the prompt. Two
question marks will give a help message and then redisplay the menu label, the menu
and the prompt.

The default error message if you typed a number is:

ERROR: Bad numeric choice specification

The default error message if you typed a string is:

ERROR: Entry does not match available menu selection. Enter the number
of the menu item you wish to select, the token which is associated
with the menu item, or a partial string which uniquely identifies the
token for the menu item. Enter ?? to reprint the menu.

The default help message is:

Enter the number of the menu item you wish to select, the token
which is associated with the menu item, or a partial string which
uniquely identifies the token for the menu item. Enter ? to
reprint the menu.

When the quit option is chosen (and allowed), q is returned along with the return code
3.

User Commands 151

ckkeywd(1)
NAME ckkeywd – prompts for and validates a keyword
SYNOPSIS ckkeywd [-Q] [-W width] [-d default] [-h help] [-e error] [-p prompt]
[-k pid [-s signal]] keyword [...]

DESCRIPTION ckkeywd prompts a user and validates the response. It defines, among other things, a
prompt message whose response should be one of a list of keywords, text for help and
error messages, and a default value (which will be returned if the user responds with a
carriage return). The answer returned from this command must match one of the
defined list of keywords.

All messages are limited in length to 70 characters and are formatted automatically.
Any white space used in the definition (including newline) is stripped. The -W option
cancels the automatic formatting. When a tilde is placed at the beginning or end of a
message definition, the default text will be inserted at that point, allowing both
custom text and the default text to be displayed.

If the prompt, help or error message is not defined, the default message (as defined
under NOTES) will be displayed.

OPTIONS The following options are supported:

-d default Defines the default value as default. The default is not validated
and so does not have to meet any criteria.
-e error Defines the error message as error.
-h help Defines the help messages as help.
-k pid Specifies that process ID pid is to be sent a signal if the user
chooses to abort.
-p prompt Defines the prompt message as prompt.
-Q Specifies that quit will not be allowed as a valid response.
-s signal Specifies that the process ID pid defined with the -k option is to be
sent signal signal when quit is chosen. If no signal is specified,
SIGTERM is used.
-W width Specifies that prompt, help and error messages will be formatted
to a line length of width.

OPERANDS The following operand is supported:

keyword Defines the keyword, or list of keywords, against which the
answer will be verified.

EXIT STATUS The following exit values are returned:

0 Successful execution.
1 EOF on input, or negative width on -W option, or no keywords from which
to choose, or usage error.

152 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckkeywd(1)
3 User termination (quit).

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO attributes(5)

NOTES The default prompt for ckkeywd is:

Enter appropriate value [keyword,[ . . . ],?,q]:

The default error message is:

ERROR: Please enter one of the following keywords: keyword,[ . . . ],q

The default help message is:

keyword,[ . . . ],q

When the quit option is chosen (and allowed), q is returned along with the return code
3.

User Commands 153

ckpath(1)
NAME ckpath, errpath, helppath, valpath – display a prompt; verify and return a pathname
SYNOPSIS ckpath [-Q] [-W width] [-a | l] [-b | c | f | y] [-n [o | z]]
[-rtwx] [-d default] [-h help] [-e error] [-p prompt] [-k pid
[-s signal]]
/usr/sadm/bin/errpath [-W width] [-a | l] [-b | c | f | y] [-n [o
| z]] [-rtwx] [-e error]
/usr/sadm/bin/helppath [-W width] [-a | l] [-b | c | f | y] [-n [o
| z]] [-rtwx] [-h help]
/usr/sadm/bin/valpath [-a | l] [-b | c | f | y] [-n [o | z]]
[-rtwx] input

DESCRIPTION The ckpath utility prompts a user and validates the response. It defines, among other
things, a prompt message whose response should be a pathname, text for help and
error messages, and a default value (which is returned if the user responds with a
RETURN).

The pathname must obey the criteria specified by the first group of options. If no
criteria is defined, the pathname must be for a normal file that does not yet exist. If
neither -a (absolute) or -l (relative) is given, then either is assumed to be valid.

All messages are limited in length to 79 characters and are formatted automatically.
Tabs and newlines are removed after a single white space character in a message
definition, but spaces are not removed. When a tilde is placed at the beginning or end
of a message definition, the default text is inserted at that point, allowing both custom
text and the default text to be displayed.

If the prompt, help or error message is not defined, the default message (as defined
under EXAMPLES) is displayed.

Three visual tool modules are linked to the ckpath command. They are errpath
(which formats and displays an error message on the standard output), helppath
(which formats and displays a help message on the standard output), and valpath
(which validates a response). These modules should be used in conjunction with
Framed Access Command Environment (FACE) objects. In this instance, the FACE
object defines the prompt.

OPTIONS The following options are supported:

-a Pathname must be an absolute path.
-b Pathname must be a block special file.
-c Pathname must be a character special file.
-d default Defines the default value as default. The default is not validated
and so does not have to meet any criteria.
-e error Defines the error message as error.
-f Pathname must be a regular file.

154 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckpath(1)
-h help Defines the help message as help.
-k pid Specifies that process ID pid is to be sent a signal if the user
chooses to quit.
-l Pathname must be a relative path.
-n Pathname must not exist (must be new).
-o Pathname must exist (must be old).
-p prompt Defines the prompt message as prompt.
-Q Specifies that quit is not allowed as a valid response.
-r Pathname must be readable.
-s signal Specifies that the process ID pid defined with the -k option is to be
sent signal signal when quit is chosen. If no signal is specified,
SIGTERM is used.
-t Pathname must be creatable (touchable). Pathname will be created
if it does not already exist.
-w Pathname must be writable.
-W width Specify that prompt, help and error messages be formatted to a
line length of width.
-x Pathname must be executable.
-y Pathname must be a directory.
-z Pathname must have a file having a size greater than zero bytes.

OPERANDS The following operand is supported:

input Input to be verified against validation options.

EXAMPLES The text of the default messages for ckpath depends upon the criteria options that
have been used.

EXAMPLE 1 Default prompt

An example default prompt for ckpath (using the -a option) is:

example% ckpath -a
Enter an absolute pathname [?,q]

EXAMPLE 2 Default error message

An example default error message (using the -a option) is:

example% /usr/sadm/bin/errpath -a
ERROR: A pathname is a filename, optionally preceded by parent directories.
The pathname you enter: - must begin with a slash (/)

User Commands 155

ckpath(1)
EXAMPLE 3 Default help message

An example default help message (using the -a option) is:

example% /usr/sadm/bin/helppath -a
A pathname is a filename, optionally preceded by parent directories.
The pathname you enter: - must begin with a slash (/)

EXAMPLE 4 The quit option

When the quit option is chosen (and allowed), q is returned along with the return code
3. Quit input gets a trailing newline.

EXAMPLE 5 Using the valpath module

The valpath module will produce a usage message on stderr. It returns 0 for success
and non-zero for failure.
example% /usr/sadm/bin/valpath
usage: valpath [-[a|l][b|c|f|y][n|[o|z]]rtwx] input
.
.
.

EXIT STATUS The following exit values are returned:

0 Successful execution.
1 EOF on input, or negative width on -W option, or usage error.
2 Mutually exclusive options.
3 User termination (quit).
4 Mutually exclusive options.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO face(1), signal(3HEAD), attributes(5)

156 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckrange(1)
NAME ckrange, errange, helprange, valrange – prompts for and validates an integer
SYNOPSIS ckrange [-Q] [-W width] [-l lower] [-u upper] [-b base] [-d default]
[-h help] [-e error] [-p prompt] [-k pid [-s signal]]
/usr/sadm/bin/errange [-W width] [-e error] [-l lower] [-u upper]
[-b base]
/usr/sadm/bin/helprange [-W width] [-h help] [-l lower] [-u upper]
[-b base]
/usr/sadm/bin/valrange [-l lower] [-u upper] [-b base] input

DESCRIPTION The ckrange utility prompts a user for an integer between a specified range and
determines whether this response is valid. It defines, among other things, a prompt
message whose response should be an integer in the range specified, text for help and
error messages, and a default value (which is returned if the user responds with a
RETURN).

This command also defines a range for valid input. If either the lower or upper limit is
left undefined, then the range is bounded on only one end.

All messages are limited in length to 79 characters and are formatted automatically.
Tabs and newlines are removed after a single whitespace character in a message
definition, but spaces are not removed. When a tilde is placed at the beginning or end
of a message definition, the default text will be inserted at that point, allowing both
custom text and the default text to be displayed.

If the prompt, help or error message is not defined, the default message (as defined
under EXAMPLES) is displayed.

Three visual tool modules are linked to the ckrange command. They are errange
(which formats and displays an error message on the standard output), helprange
(which formats and displays a help message on the standard output), and valrange
(which validates a response). These modules should be used in conjunction with
Framed Access Command Environment (FACE) objects. In this instance, the FACE
object defines the prompt.

Note: Negative "input" arguments confuse getopt in valrange. By inserting a "−"

before the argument, getopt processing will stop. See getopt(1) and intro(1) about
getopt parameter handling. getopt is used to parse positional parameters and to
check for legal options.

OPTIONS The following options are supported:

-b base Defines the base for input. Must be 2 to 36, default is 10. Base
conversion uses strtol(3C). Output is always base 10.
-d default Defines the default value as default. default is converted using
strtol(3C) in the desired base. Any characters invalid in the
specified base will terminate the strtol conversion without error.

User Commands 157

ckrange(1)
-e error Defines the error message as error.
-h help Defines the help message as help.
-k pid Specifies that process ID pid is to be sent a signal if the user
chooses to quit.
-l lower Defines the lower limit of the range as lower. Default is the
machine’s largest negative long.
-p prompt Defines the prompt message as prompt.
-Q Specifies that quit will not be allowed as a valid response.
-s signal Specifies that the process ID pid defined with the -k option is to be
sent signal signal when quit is chosen. If no signal is specified,
SIGTERM is used.
-u upper Defines the upper limit of the range as upper. Default is the
machine’s largest positive long.
-W width Specifies that prompt, help and error messages will be formatted
to a line length of width.

OPERANDS The following operand is supported:

input Input to be verified against upper and lower limits and base.

EXAMPLES EXAMPLE 1 Default base 10 prompt

The default base 10 prompt for ckrange is:

example% ckrange
Enter an integer between lower_bound and
upper_bound [lower_bound−upper_bound,?,q]:

EXAMPLE 2 Default base 10 error message

The default base 10 error message is:

example% /usr/sadm/bin/errange
ERROR: Please enter an integer between lower_bound \
and upper_bound.

EXAMPLE 3 Default base 10 help message

The default base 10 help message is:

example% /usr/sadm/bin/helprange
Please enter an integer between lower_bound and upper_bound.

158 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckrange(1)
EXAMPLE 4 Changing messages for a base other than 10

The messages are changed from ‘‘integer’’ to ‘‘base base integer’’ if the base is set to a
number other than 10. For example,
example% /usr/sadm/bin/helprange -b 36

EXAMPLE 5 Using the quit option

When the quit option is chosen (and allowed), q is returned along with the return code
3. Quit input gets a trailing newline.

EXAMPLE 6 Using the valrange module

The valrange module will produce a usage message on stderr. It returns 0 for
success and non-zero for failure.
example% /usr/sadm/bin/valrange
usage: valrange [-l lower] [-u upper] [-b base] input

EXIT STATUS The following exit values are returned:

0 Successful execution.
1 EOF on input, or negative width on -W option, or usage error.
2 Usage error.
3 User termination (quit).

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO intro(1), face(1), getopt(1), strtol(3C), attributes(5), signal(3HEAD)

User Commands 159

ckstr(1)
NAME ckstr, errstr, helpstr, valstr – display a prompt; verify and return a string answer
SYNOPSIS ckstr [-Q] [-W width] [ [-r regexp] [...]] [-l length] [-d default]
[-h help] [-e error] [-p prompt] [-k pid [- s signal]]
/usr/sadm/bin/errstr [-W width] [-e error] [-l length] [ [-r regexp]
[...]]
/usr/sadm/bin/helpstr [-W width] [-h help] [-l length] [ [-r regexp]
[...]]
/usr/sadm/bin/valstr [-l length] [ [-r regexp] [...]] input

DESCRIPTION The ckstr utility prompts a user and validates the response. It defines, among other
things, a prompt message whose response should be a string, text for help and error
messages, and a default value (which are returned if the user responds with a
RETURN).

The answer returned from this command must match the defined regular expression
and be no longer than the length specified. If no regular expression is given, valid
input must be a string with a length less than or equal to the length defined with no
internal, leading or trailing white space. If no length is defined, the length is not
checked.

All messages are limited in length to 79 characters and are formatted automatically.
Tabs and newlines are removed after a single white space character in a message
definition, but spaces are not removed. When a tilde is placed at the beginning or end
of a message definition, the default text will be inserted at that point, allowing both
custom text and the default text to be displayed.

If the prompt, help or error message is not defined, the default message (as defined
under EXAMPLES) is displayed.

Three visual tool modules are linked to the ckstr command. They are errstr
(which formats and displays an error message on the standard output), helpstr
(which formats and displays a help message on the standard output), and valstr
(which validates a response). These modules should be used in conjunction with
Framed Access Command Environment (FACE) objects. In this instance, the FACE
object defines the prompt.

OPTIONS The following options are supported:

-d default Defines the default value as default. The default is not validated
and so does not have to meet any criteria.
-e error Defines the error message as error.
-h help Defines the help message as help.
-k pid Specifies that process ID pid is to be sent a signal if the user
chooses to quit.
-l length Specifies the maximum length of the input.

160 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckstr(1)
-p prompt Defines the prompt message as prompt.
-Q Specifies that quit will not be allowed as a valid response.
-r regexp Specifies a regular expression, regexp, against which the input
should be validated. May include white space. If multiple
expressions are defined, the answer need match only one of them.
-s signal Specifies that the process ID pid defined with the -k option is to be
sent signal signal when quit is chosen. If no signal is specified,
SIGTERM is used.
-W width Specifies that prompt, help and error messages will be formatted
to a line length of width.

OPERANDS The following operand is supported:

input Input to be verified against format length and/or regular
expression criteria.

EXAMPLES EXAMPLE 1 Default prompt

The default prompt for ckstr is:

example% ckstr
Enter an appropriate value [?,q]:

EXAMPLE 2 Default error message

The default error message is dependent upon the type of validation involved. The user
will be told either that the length or the pattern matching failed. The default error
message is:
example% /usr/sadm/bin/errstr
ERROR: Please enter a string which contains no embedded,
leading or trailing spaces or tabs.

EXAMPLE 3 Default help message

The default help message is also dependent upon the type of validation involved. If a
regular expression has been defined, the message is:
example% /usr/sadm/bin/helpstr -r regexp
Please enter a string which matches the following pattern:
regexp

Other messages define the length requirement and the definition of a string.

EXAMPLE 4 Using the quit option

When the quit option is chosen (and allowed), q is returned along with the return code
3. Quit input gets a trailing newline.

User Commands 161

ckstr(1)
EXAMPLE 5 Using the valstr module

The valstr module will produce a usage message on stderr. It returns 0 for success
and non-zero for failure.
example% /usr/sadm/bin/valstr
usage: valstr [-l length] [[-r regexp] [ . . . ]] input

EXIT STATUS The following exit values are returned:

0 Successful execution.
1 EOF on input, or negative width on -W option, or usage error.
2 Invalid regular expression.
3 User termination (quit).

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO face(1), signal(3HEAD), attributes(5)

162 man pages section 1: User Commands • Last Revised 14 Sep 1992
 cksum(1)
NAME cksum – write file checksums and sizes
SYNOPSIS cksum [file…]

DESCRIPTION The cksum command calculates and writes to standard output a cyclic redundancy
check (CRC) for each input file, and also writes to standard output the number of
octets in each file.

For each file processed successfully, cksum will write in the following format:

"%u %d %s\n" <checksum>, <# of octets>, <path name>

If no file operand was specified, the path name and its leading space will be omitted.

The CRC used is based on the polynomial used for CRC error checking in the
referenced Ethernet standard.

The encoding for the CRC checksum is defined by the generating polynomial:

G (x) = x32 + x26 + x23 + x22 + x16 + x12 + x11 + x10 + x8 + x7 + x5 + x4 + x2 + x + 1

Mathematically, the CRC value corresponding to a given file is defined by the

following procedure:
1. The n bits to be evaluated are considered to be the coefficients of a mod 2
polynomial M(x) of degree n−1. These n bits are the bits from the file, with the most
significant bit being the most significant bit of the first octet of the file and the last
bit being the least significant bit of the last octet, padded with zero bits (if
necessary) to achieve an integral number of octets, followed by one or more octets
representing the length of the file as a binary value, least significant octet first. The
smallest number of octets capable of representing this integer is used.
2. M(x) is multiplied by x 32 (that is, shifted left 32 bits) and divided by G(x) using
mod 2 division, producing a remainder R(x) of degree ≤ 31.
3. The coefficients of R(x) are considered to be a 32-bit sequence.
4. The bit sequence is complemented and the result is the CRC.

OPERANDS The following operand is supported:

file A path name of a file to be checked. If no file operands are specified, the
standard input is used.

USAGE The cksum command is typically used to quickly compare a suspect file against a
trusted version of the same, such as to ensure that files transmitted over noisy media
arrive intact. However, this comparison cannot be considered cryptographically
secure. The chances of a damaged file producing the same CRC as the original are
astronomically small; deliberate deception is difficult, but probably not impossible.

User Commands 163

cksum(1)
Although input files to cksum can be any type, the results need not be what would be
expected on character special device files. Since this document does not specify the
block size used when doing input, checksums of character special files need not
process all of the data in those files.

The algorithm is expressed in terms of a bitstream divided into octets. If a file is

transmitted between two systems and undergoes any data transformation (such as
moving 8-bit characters into 9-bit bytes or changing “Little Endian” byte ordering to
“Big Endian”), identical CRC values cannot be expected. Implementations performing
such transformations may extend cksum to handle such situations.

See largefile(5) for the description of the behavior of cksum when encountering
files greater than or equal to 2 Gbyte ( 231 bytes).

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of cksum: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

EXIT STATUS The following exit values are returned:

0 All files were processed successfully.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

Interface Stability Standard

SEE ALSO sum(1), attributes(5), environ(5), largefile(5), standards(5)

164 man pages section 1: User Commands • Last Revised 1 Feb 1995
 cktime(1)
NAME cktime, errtime, helptime, valtime – display a prompt; verify and return a time of day
SYNOPSIS cktime [-Q] [-W width] [-f format] [-d default] [-h help] [-e error]
[-p prompt] [-k pid [-s signal]]
/usr/sadm/bin/errtime [-W width] [-e error] [-f format]
/usr/sadm/bin/helptime [-W width] [-h help] [-f format]
/usr/sadm/bin/valtime [-f format] input

DESCRIPTION The cktime utility prompts a user and validates the response. It defines, among other
things, a prompt message whose response should be a time, text for help and error
messages, and a default value (which is returned if the user responds with a
RETURN). The user response must match the defined format for the time of day.

All messages are limited in length to 70 characters and are formatted automatically.
Any white space used in the definition (including NEWLINE) is stripped. The -W
option cancels the automatic formatting. When a tilde is placed at the beginning or
end of a message definition, the default text is inserted at that point, allowing both
custom text and the default text to be displayed.

If the prompt, help or error message is not defined, the default message (as defined
under NOTES) is displayed.

Three visual tool modules are linked to the cktime command. They are errtime
(which formats and displays an error message), helptime (which formats and
displays a help message), and valtime (which validates a response). These modules
should be used in conjunction with FML objects. In this instance, the FML object
defines the prompt. When format is defined in the errtime and helptime
modules, the messages will describe the expected format.

OPTIONS The following options are supported:

-d default Defines the default value as default. The default is not validated
and so does not have to meet any criteria.
-e error Defines the error message as error.
-f format Specifies the format against which the input will be verified.
Possible formats and their definitions are:
%H = hour (00 - 23)
%I = hour (00 - 12)
%M = minute (00 - 59)
%p = ante meridian or post meridian
%r = time as %I:%M:%S %p
%R = time as %H:%M (the default format)
%S = seconds (00 - 59)
%T = time as %H:%M:%S

-h help Defines the help messages as help.

User Commands 165

cktime(1)
-k pid Specifies that process ID pid is to be sent a signal if the user
chooses to abort.
-p prompt Defines the prompt message as prompt.
-Q Specifies that quit will not be allowed as a valid response.
-s signal Specifies that the process ID pid defined with the -k option is to be
sent signal signal when quit is chosen. If no signal is specified,
SIGTERM is used.
-W width Specifies that prompt, help and error messages will be formatted
to a line length of width.

OPERANDS The following operand is supported:

input Input to be verified against format criteria.

EXIT STATUS The following exit values are returned:

0 Successful execution.
1 EOF on input, or negative width on -W option, or usage error .
3 User termination (quit) .
4 Garbled format argument.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO attributes(5)

NOTES The default prompt for cktime is:

Enter a time of day [?,q]:

The default error message is:

ERROR: Please enter the time of day. Format is <format>.

The default help message is:

Please enter the time of day. Format is <format>.

When the quit option is chosen (and allowed), q is returned along with the return code
3. The valtime module will not produce any output. It returns 0 for success and
non-zero for failure.

166 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckuid(1)
NAME ckuid, erruid, helpuid, valuid – prompts for and validates a user ID
SYNOPSIS ckuid [-Q] [-W width] [-m] [-d default] [-h help] [-e error] [-p prompt]
[-k pid [-s signal]]
/usr/sadm/bin/erruid [-W width] [-e error]
/usr/sadm/bin/helpuid [-W width] [-m] [-h help]
/usr/sadm/bin/valuid input

DESCRIPTION The ckuid utility prompts a user and validates the response. It defines, among other
things, a prompt message whose response should be an existing user ID, text for help
and error messages, and a default value (which are returned if the user responds with
a RETURN).

All messages are limited in length to 70 characters and are formatted automatically.
Any white space used in the definition (including NEWLINE) is stripped. The -W
option cancels the automatic formatting. When a tilde is placed at the beginning or
end of a message definition, the default text is inserted at that point, allowing both
custom text and the default text to be displayed.

If the prompt, help or error message is not defined, the default message (as defined
under NOTES) is displayed.

Three visual tool modules are linked to the ckuid command. They are erruid
(which formats and displays an error message), helpuid (which formats and displays
a help message), and valuid (which validates a response). These modules should be
used in conjunction with FML objects. In this instance, the FML object defines the
prompt.

OPTIONS The following options are supported:

-d default Defines the default value as default. The default is not validated
and so does not have to meet any criteria.
-e error Defines the error message as error.
-h help Defines the help messages as help.
-k pid Specifies that process ID pid is to be sent a signal if the user
chooses to abort.
-m Displays a list of all logins when help is requested or when the
user makes an error.
-p prompt Defines the prompt message as prompt.
-Q Specifies that quit will not be allowed as a valid response.
-s signal Specifies that the process ID pid defined with the -k option is to be
sent signal signal when quit is chosen. If no signal is specified,
SIGTERM is used.

User Commands 167

ckuid(1)
-W width Specifies that prompt, help and error messages will be formatted
to a line length of width.

OPERANDS The following operand is supported:

input Input to be verified against /etc/passwd.

EXIT STATUS The following exit values are returned:

0 Successful execution.
1 EOF on input, or negative width on -W option, or usage error.
2 Usage error.
3 User termination (quit).

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO attributes(5)

NOTES The default prompt for ckuid is:

Enter the login name of an existing user [?,q]:

The default error message is:

ERROR - Please enter the login name of an existing user.

If the -m option is used, the default error message is:

ERROR: Please enter one of the following login names: <List>

The default help message is:

Please enter the login name of an existing user.

If the -m option is used, the default help message is:

Please enter one of the following login names: <List>

When the quit option is chosen (and allowed), q is returned along with the return code
3. The valuid module will not produce any output. It returns 0 for success and
non-zero for failure.

168 man pages section 1: User Commands • Last Revised 14 Sep 1992
 ckyorn(1)
NAME ckyorn, erryorn, helpyorn, valyorn – prompts for and validates yes/no
SYNOPSIS ckyorn [-Q] [-W width] [-d default] [-h help] [-e error] [-p prompt]
[-k pid [-s signal]]
/usr/sadm/bin/erryorn [-W width] [-e error]
/usr/sadm/bin/helpyorn [-W width] [-h help]
/usr/sadm/bin/valyorn input

DESCRIPTION ckyorn prompts a user and validates the response. It defines, among other things, a
prompt message for a yes or no answer, text for help and error messages, and a
default value (which is returned if the user responds with a RETURN).

All messages are limited in length to 70 characters and are formatted automatically.
Any white space used in the definition (including newline) is stripped. The -W option
cancels the automatic formatting. When a tilde is placed at the beginning or end of a
message definition, the default text is inserted at that point, allowing both custom text
and the default text to be displayed.

If the prompt, help or error message is not defined, the default message (as defined
under NOTES) is displayed.

Three visual tool modules are linked to the ckyorn command. They are erryorn
(which formats and displays an error message), helpyorn (which formats and
displays a help message), and valyorn (which validates a response). These modules
should be used in conjunction with FACE objects. In this instance, the FACE object
defines the prompt.

OPTIONS The following options are supported:

-d default Defines the default value as default. The default is not validated
and so does not have to meet any criteria.
-e error Defines the error message as error.
-h help Defines the help messages as help.
-k pid Specifies that process ID pid is to be sent a signal if the user
chooses to abort.
-p prompt Defines the prompt message as prompt.
-Q Specifies that quit will not be allowed as a valid response.
-s signal Specifies that the process ID pid defined with the -k option is to be
sent signal signal when quit is chosen. If no signal is specified,
SIGTERM is used.
-W width Specifies that prompt, help and error messages will be formatted
to a line length of width.

OPERANDS The following operand is supported:

User Commands 169

ckyorn(1)
input Input to be verified as y, yes, or n, no (in any combination of
upper- and lower-case letters).

EXIT STATUS The following exit values are returned:

0 Successful execution.
1 EOF on input, or negative width on -W option, or usage error.
2 Usage error.
3 User termination (quit).

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO attributes(5)

NOTES The default prompt for ckyorn is:

Yes or No [y,n,?,q]:

The default error message is:

ERROR - Please enter yes or no.

The default help message is:

To respond in the affirmative, enter y, yes, Y, or YES.
To respond in the negative, enter n, no, N, or NO.

When the quit option is chosen (and allowed), q is returned along with the return code
3. The valyorn module will not produce any output. It returns 0 for success and
non-zero for failure.

170 man pages section 1: User Commands • Last Revised 14 Sep 1992
 clear(1)
NAME clear – clear the terminal screen
SYNOPSIS clear [term]

DESCRIPTION The clear utility clears the terminal screen if this is possible. It looks in the
environment for the terminal type, if this is not already specified by the term operand,
and then looks up the terminfo database to figure out how to clear the screen.
OPERANDS term Indicates the type of terminal. Normally, this operand is unnecessary
because the default is taken from the environment variable TERM.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO tput(1), attributes(5)

User Commands 171

cmp(1)
NAME cmp – compare two files
SYNOPSIS cmp [-l] [-s] file1 file2 [skip1] [skip2]

DESCRIPTION The cmp utility compares two files. cmp will write no output if the files are the same.
Under default options, if they differ, it writes to standard output the byte and line
numbers at which the first difference occurred. Bytes and lines are numbered
beginning with 1. If one file is an initial subsequence of the other, that fact is noted.
skip1 and skip2 are initial byte offsets into file1 and file2 respectively, and may be either
octal or decimal; a leading 0 denotes octal.

OPTIONS The following options are supported:

-l Write the byte number (decimal) and the differing bytes (octal) for each
difference.
-s Write nothing for differing files; return exit statuses only.

OPERANDS The following operands are supported:

file1 A path name of the first file to be compared. If file1 is −, the standard input
will be used.
file2 A path name of the second file to be compared. If file2 is −, the standard
input will be used.

If both file1 and file2 refer to standard input or refer to the same FIFO special, block
special or character special file, an error results.

USAGE See largefile(5) for the description of the behavior of cmp when encountering files
greater than or equal to 2 Gbyte (231 bytes).

EXAMPLES EXAMPLE 1 Comparing files byte for byte

The following example:

example% cmp file1 file2 0 1024

does a byte for byte comparison of file1 and file2. It skips the first 1024 bytes in file2
before starting the comparison.

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of cmp: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

EXIT STATUS The following error values are returned:

0 The files are identical.
1 The files are different; this includes the case where one file is identical to
the first part of the other.
>1 An error occurred.

172 man pages section 1: User Commands • Last Revised 1 Feb 1995
 cmp(1)
ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

CSI enabled

Interface Stability Standard

SEE ALSO comm(1), diff(1), attributes(5), environ(5), largefile(5), standards(5)

User Commands 173

col(1)
NAME col – reverse line-feeds filter
SYNOPSIS col [-bfpx]

DESCRIPTION The col utility reads from the standard input and writes to the standard output. It
performs the line overlays implied by reverse line-feeds, and by forward and reverse
half-line-feeds. Unless -x is used, all blank characters in the input will be converted to
tab characters wherever possible. col is particularly useful for filtering multi-column
output made with the .rt command of nroff(1) and output resulting from use of the
tbl(1) preprocessor.

The ASCII control characters SO and SI are assumed by col to start and end text in an
alternative character set. The character set to which each input character belongs is
remembered, and on output SI and SO characters are generated as appropriate to
ensure that each character is written in the correct character set.

On input, the only control characters accepted are space, backspace, tab,
carriage-return and newline characters, SI, SO, VT, reverse line-feed, forward
half-line-feed and reverse half-line-feed. The VT character is an alternative form of full
reverse line-feed, included for compatibility with some earlier programs of this type.
The only other characters to be copied to the output are those that are printable.

The ASCII codes for the control functions and line-motion sequences mentioned above
are as given in the table below. ESC stands for the ASCII escape character, with the
octal code 033; ESC− means a sequence of two characters, ESC followed by the
character x.

reverse line-feed ESC−7

reverse half-line-feed ESC−8

forward half-line-feed ESC−9

vertical-tab (VT) 013

start-of-text (SO) 016

end-of-text (SI) 017

OPTIONS -b Assume that the output device in use is not capable of backspacing. In this
case, if two or more characters are to appear in the same place, only the last
one read will be output.
-f Although col accepts half-line motions in its input, it normally does not
emit them on output. Instead, text that would appear between lines is
moved to the next lower full-line boundary. This treatment can be
suppressed by the -f (fine) option; 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.

174 man pages section 1: User Commands • Last Revised 1 Feb 1995
 col(1)
-p Normally, col will ignore any escape sequences unknown to it that are
found in its input; the -p option may be used to cause col to output these
sequences as regular characters, subject to overprinting from reverse line
motions. The use of this option is highly discouraged unless the user is
fully aware of the textual position of the escape sequences.
-x Prevent col from converting blank characters to tab characters on output
wherever possible. Tab stops are considered to be at each column position n
such that n modulo 8 equals 1.

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of col: LC_CTYPE, LC_MESSAGES, and NLSPATH.

EXIT STATUS The following error values are returned:

0 Successful completion.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

CSI enabled

SEE ALSO nroff(1), tbl(1), ascii(5), attributes(5), environ(5)

NOTES The input format accepted by col matches the output produced by nroff with either
the -T37 or -Tlp options. Use -T37 (and the -f option of col) if the ultimate
disposition of the output of col will be a device that can interpret half-line motions,
and -Tlp otherwise.

col cannot back up more than 128 lines or handle more than 800 characters per 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.

User Commands 175

comm(1)
NAME comm – select or reject lines common to two files
SYNOPSIS comm [-123] file1 file2

DESCRIPTION The comm utility will read file1 and file2, which should be ordered in the current
collating sequence, and produce three text columns as output: lines only in file1; lines
only in file2; and lines in both files.

If the input files were ordered according to the collating sequence of the current locale,
the lines written will be in the collating sequence of the original lines. If not, the
results are unspecified.

OPTIONS The following options are supported:

-1 Suppress the output column of lines unique to file1.
-2 Suppress the output column of lines unique to file2.
-3 Suppress the output column of lines duplicated in file1 and file2.

OPERANDS The following operands are supported:

file1 A path name of the first file to be compared. If file1 is −, the standard input
is used.
file2 A path name of the second file to be compared. If file2 is −, the standard
input is used.

USAGE See largefile(5) for the description of the behavior of comm when encountering files
greater than or equal to 2 Gbyte ( 231 bytes).

EXAMPLES EXAMPLE 1 Printing a list of utilities specified by files

If file1, file2, and file3 each contained a sorted list of utilities:

example% comm -23 file1 file2 | comm -23 - file3

would print a list of utilities in file1 not specified by either of the other files. The entry:
example% comm -12 file1 file2 | comm -12 - file3

would print a list of utilities specified by all three files. And the entry:
example% comm -12 file2 file3 | comm -23 -file1

would print a list of utilities specified by both file2 and file3, but not specified in file1.

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of comm: LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, and
NLSPATH.

EXIT STATUS The following exit values are returned:

0 All input files were successfully output as specified.

176 man pages section 1: User Commands • Last Revised 21 Feb 1996
 comm(1)
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

CSI enabled

Interface Stability Standard

SEE ALSO cmp(1), diff(1), sort(1), uniq(1), attributes(5), environ(5), largefile(5),

standards(5)

User Commands 177

command(1)
NAME command – execute a simple command
SYNOPSIS command [-p] command_name [argument…]
command [-v | -V]command_name

DESCRIPTION The command utility causes the shell to treat the arguments as a simple command,
suppressing the shell function lookup.

If the command_name is the same as the name of one of the special built-in utilities, the
special properties will not occur. In every other respect, if command_name is not the
name of a function, the effect of command will be the same as omitting command.

The command utility also provides information concerning how a command name will
be interpreted by the shell; see -v and -V.

OPTIONS The following options are supported:

-p Perform the command search using a default value for PATH that is
guaranteed to find all of the standard utilities.
-v Write a string to standard output that indicates the path or command that
will be used by the shell, in the current shell execution environment to
invoke command_name.
■ Utilities, regular built-in utilities, command_names including a slash
character, and any implementation-provided functions that are found
using the PATH variable will be written as absolute path names.
■ Shell functions, special built-in utilities, regular built-in utilities not
associated with a PATH search, and shell reserved words will be written
as just their names.
■ An alias will be written as a command line that represents its alias
definition.
■ Otherwise, no output will be written and the exit status will reflect that
the name was not found.
-V Write a string to standard output that indicates how the name given in the
command_name operand will be interpreted by the shell, in the current shell
execution environment. Although the format of this string is unspecified, it
will indicate in which of the following categories command_name falls and
include the information stated:
■ Utilities, regular built-in utilities, and any implementation-provided
functions that are found using the PATH variable will be identified as
such and include the absolute path name in the string.
■ Other shell functions will be identified as functions.
■ Aliases will be identified as aliases and their definitions will be
included in the string.
■ Special built-in utilities will be identified as special built-in utilities.
■ Regular built-in utilities not associated with a PATH search will be
identified as regular built-in utilities.

178 man pages section 1: User Commands • Last Revised 1 Feb 1995
 command(1)
■ Shell reserved words will be identified as reserved words.

OPERANDS The following operands are supported:

argument One of the strings treated as an argument to command_name.
command_name The name of a utility or a special built-in utility.

EXAMPLES EXAMPLE 1 Make a version of cd that always prints out the new working directory exactly
once:
cd() {
command cd "$@" >/dev/null
pwd
}

EXAMPLE 2 Start off a ‘‘secure shell script’’ in which the script avoids being spoofed by its
parent:
IFS=’
’
# The preceding value should be <space><tab><newline>.
# Set IFS to its default value.
\unalias -a
# Unset all possible aliases.
# Note that unalias is escaped to prevent an alias
# being used for unalias.
unset -f command
# Ensure command is not a user function.
PATH="$(command -p getconf _CS_PATH):$PATH"
# Put on a reliable PATH prefix.
# . . .

At this point, given correct permissions on the directories called by PATH, the script
has the ability to ensure that any utility it calls is the intended one. It is being very
cautious because it assumes that implementation extensions may be present that
would allow user functions to exist when it is invoked. This capability is not specified
by this document, but it is not prohibited as an extension. For example, the ENV
variable precedes the invocation of the script with a user startup script. Such a script
could define functions to spoof the application.

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of command: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.
PATH Determine the search path used during the command search, except as
described under the -p option.

EXIT STATUS When the -v or -V options are specified, the following exit values are returned:
0 Successful completion.
>0 The command_name could not be found or an error occurred.

Otherwise, the following exit values are returned:

User Commands 179

command(1)
126 The utility specified by command_name was found but could not be
invoked.
127 An error occurred in the command utility or the utility specified by
command_name could not be found.

Otherwise, the exit status of command will be that of the simple command specified by
the arguments to command.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

Interface Stability Standard

SEE ALSO sh(1), type(1), attributes(5), environ(5), standards(5)

180 man pages section 1: User Commands • Last Revised 1 Feb 1995
 compress(1)
NAME compress, uncompress, zcat – compress, uncompress files or display expanded files
SYNOPSIS compress [-fv] [-b bits] [file…]
compress [-cfv] [-b bits] [file]
uncompress [-cfv] [file…]
zcat [file…]

DESCRIPTION

compress The compress utility will attempt to reduce the size of the named files by using
adaptive Lempel-Ziv coding. Except when the output is to the standard output, each
file will be replaced by one with the extension .Z, while keeping the same ownership
modes, change times and modification times. If appending the .Z to the file pathname
would make the pathname exceed 1023 bytes, the command will fail. If no files are
specified, the standard input will be 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(1)) and it 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.

uncompress The uncompress utility will restore files to their original state after they have been
compressed using the compress utility. If no files are specified, the standard input
will be uncompressed to the standard output.

This utility supports the uncompressing of any files produced by compress. For files
produced by compress on other systems, uncompress supports 9- to 16-bit
compression (see -b).

zcat The zcat utility will write to standard output the uncompressed form of files that
have been compressed using compress. It is the equivalent of uncompress -c.
Input files are not affected.

OPTIONS The following options are supported:

-c Writes to the standard output; no files are changed and no .Z files are
created. The behavior of zcat is identical to that of ‘uncompress -c’.
-f When compressing, forces compression of file, even if it does not actually
reduce the size of the file, or if the corresponding file.Z file already exists. If
the -f option is not given, and the process is not running in the
background, prompts to verify whether an existing file.Z file should be
overwritten. When uncompressing, does not prompt for overwriting files.
If the -f option is not given, and the process is not running in the
background, prompts to verify whether an existing file should be

User Commands 181

compress(1)
overwritten. If the standard input is not a terminal and -f is not given,
writes a diagnostic message to standard error and exits with a status
greater than 0.
-v Verbose. Writes to standard error messages concerning the percentage
reduction or expansion of each file.
-b bits Sets the upper limit (in bits) for common substring codes. bits must be
between 9 and 16 (16 is the default). Lowering the number of bits will
result in larger, less compressed files.

OPERANDS The following operand is supported:

file A path name of a file to be compressed by compress, uncompressed by
uncompress, or whose uncompressed form is written to standard out by
zcat. If file is −, or if no file is specified, the standard input will be used.

USAGE See largefile(5) for the description of the behavior of compress, uncompress,
and zcat when encountering files greater than or equal to 2 Gbyte ( 231 bytes).

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of compress, uncompress, and zcat: LANG, LC_ALL, LC_CTYPE,
LC_MESSAGES, and NLSPATH.

EXIT STATUS The following error values are returned:

0 Successful completion.
1 An error occurred.
2 One or more files were not compressed because they would have increased
in size (and the -f option was not specified).
>2 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

CSI Enabled

Interface Stability Standard

SEE ALSO ln(1), pack(1), attributes(5), environ(5), largefile(5), standards(5)

DIAGNOSTICS Usage: compress [-fvc] [-b maxbits] [file . . . ]
Invalid options were specified on the command line.
Missing maxbits
Maxbits must follow -b, or invalid maxbits, not a numeric value.

182 man pages section 1: User Commands • Last Revised 9 Sep 1999
 compress(1)
file: not in compressed format
The file specified to uncompress has not been compressed.
file: compressed with xxbits, can only handle yybits
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.
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, (such as a directory), it is left unaltered.
– – has xx other links: unchanged
The input file has links; it is left unchanged. See ln(1) for more information.
– – file unchanged
No savings are achieved by compression. The input remains uncompressed.
filename too long to tack on .Z
The path name is too long to append the .Z suffix.

NOTES Although compressed files are compatible between machines with large memory, -b
12 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.

User Commands 183

coproc(1F)
NAME coproc, cocreate, cosend, cocheck, coreceive, codestroy – communicate with a process
SYNOPSIS cocreate [-r rpath] [-w wpath] [-i id] [-R refname] [-s send_string]
[-e expect_string] command
cosend [-n] proc_id string
cocheck proc_id
coreceive proc_id
codestroy [-R refname] proc_id [string]

DESCRIPTION These co-processing functions provide a flexible means of interaction between FMLI
and an independent process; especially, they enable FMLI to be responsive to
asynchronous activity.

The cocreate function starts command as a co-process and initializes communications

by setting up pipes between FMLI and the standard input and standard output of
command. The argument command must be an executable and its arguments (if any).
This means that command expects strings on its input (supplied by cosend) and sends
information on its output that can be handled in various ways by FMLI.

The cosend function sends string to the co-process identified by proc_id via the pipe
set up by cocreate (optionally wpath), where proc_id can be either the command or id
specified in cocreate. By default, cosend blocks, waiting for a response from the
co-process. Also by default, FMLI does not send a send_string and does not expect an
expect_string (except a newline). That is, it reads only one line of output from the
co-process. If -e expect_string was not defined when the pipe was created, then the
output of the co-process is any single string followed by a newline: any other lines of
output remain on the pipe. If the -e option was specified when the pipe was created,
cosend reads lines from the pipe until it reads a line starting with expect_string. All
lines except the line starting with expect_string become the output of cosend.

The cocheck function determines if input is available from the process identified by
proc_id, where proc_id can be either the command or id specified in cocreate. It
returns a Boolean value, which makes cocheck useful in if statements and in other
backquoted expressions in Boolean descriptors. cocheck receives no input from the
co-process; it simply indicates if input is available from the co-process. You must use
coreceive to actually accept the input. The cocheck function can be called from a
reread descriptor to force a frame to update when new data is available. This is
useful when the default value of a field in a form includes coreceive.

The coreceive function is used to read input from the co-process identified by
proc_id, where proc_id can be either the command or id specified in cocreate. It should
only be used when it has been determined, using cocheck, that input is actually
available. If the -e option was used when the co-process was created, coreceive will
continue to return lines of input until expect_string is read. At this point, coreceive
will terminate. The output of coreceive is all the lines that were read excluding the

184 man pages section 1: User Commands • Last Revised 5 Jul 1990
 coproc(1F)
line starting with expect_string . If the -e option was not used in the cocreate, each
invocation of coreceive will return exactly one line from the co-process. If no input
is available when coreceive is invoked, it will simply terminate without producing
output.

The codestroy function terminates the read/write pipes to proc-id, where proc_id can
be either the command or id specified in cocreate. It generates a SIGPIPE signal to
the (child) co-process. This kills the co-process, unless the co-process ignores the
SIGPIPE signal. If the co-process ignores the SIGPIPE, it will not die, even after the
FMLI process terminates (the parent process id of the co-process will be 1).

The optional argument string is sent to the co-process before the co-process dies. If
string is not supplied, a NULL string is passed, followed by the normal send_string
(newline by default). That is, codestroy will call cosend proc_id string: this implies
that codestroy will write any output generated by the co-process to stdout. For
example, if an interactive co-process is written to expect a "quit" string when the
communication is over, the close descriptor could be defined; close=‘codestroy
ID ’quit’ | message‘ and any output generated by the co-process when the
string quit is sent to it via codestroy (using cosend) would be redirected to the
message line.

The codestroy function should usually be given the -R option, since you may have
more than one process with the same name, and you do not want to kill the wrong
one. codestroy keeps track of the number of refnames you have assigned to a process
with cocreate, and when the last instance is killed, it kills the process (id) for you.
codestroy is typically called as part of a close descriptor because close is
evaluated when a frame is closed. This is important because the co-process will
continue to run if codestroy is not issued.

When writing programs to use as co-processes, the following tips may be useful. If the
co-process program is written in C language, be sure to flush output after writing to
the pipe. (Currently, awk(1) and sed(1) cannot be used in a co-process program
because they do not flush after lines of output.) Shell scripts are well-mannered, but
slow. C language is recommended. If possible, use the default send_string, rpath and
wpath. In most cases, expect_string will have to be specified. This, of course, depends
on the co-process.

In the case where asynchronous communication from a co-process is desired, a

co-process program should use vsig to force strings into the pipe and then signal
FMLI that output from the co-process is available. This causes the reread descriptor
of all frames to be evaluated immediately.

OPTIONS cocreate options are:

-r rpath If -r is specified, rpath is the pathname from which
FMLI reads information. This option is usually used to
set up communication with processes that naturally
write to a certain path. If -r is not specified, cocreate
will choose a unique path in /var/tmp.

User Commands 185

coproc(1F)
-w wpath If -w is specified, wpath is the pathname to which
cosend writes information. This option is usually used
so that one process can talk to many different FMLI
processes through the same pipe. If -w is not specified,
cocreate will choose a unique path in /var/tmp.
-i id If -i is specified, id is an alternative name for the
co-processinitialized by this cocreate. If -i is not
specified, id defaults to command. The argument id can
later be used with the other co-processing functions
rather than command. This option is typically used,
since it facilitates the creation of two or more
co-processes generated from the same command. (For
example, cocreate -i ID1 program args and
cocreate -i ID2 program different_args).
-R refname If -R is specified, refname is a local name for the
co-process. Since the cocreate function can be issued
more than once, a refname is useful when the same
co-process is referenced a second or subsequent time.
With the -R option, if the co-process already exists a
new one will not be created: the same pipes will be
shared. Then, refname can be used as an argument to
the -R option to codestroy when you want to end a
particular connection to a co-process and leave other
connections undisturbed. (The co-process is only killed
after codestroy -R has been called as many times as
cocreate -R was called.)
-s send_string The -s option specifies send_string as a string that will
be appended to all output sent to the co-process using
cosend. This option allows a co-process to know when
input from FMLI has completed. The default
send_string is a newline if -s is not specified.
-e expect_string The -e option specifies expect_string as a string that
identifies the end of all output returned by the
co-process. (Note: expect_string need only be the initial
part of a line, and there must be a newline at the end of
the co-process output.) This option allows FMLI to
know when output from the co-process has completed.
The default expect_string is a newline if -e is not
specified.

cosend options are:

-n If the -n option is specified, cosend will not wait for a response from the
co-process. It simply returns, providing no output. If the -n option is not
used, a co-process that does not answer will cause FMLI to permanently
hang, waiting for input from the co-process.

186 man pages section 1: User Commands • Last Revised 5 Jul 1990
 coproc(1F)
EXAMPLES EXAMPLE 1 Sample commands
.
.
.
init=‘cocreate -i BIGPROCESS initialize‘
close=‘codestroy BIGPROCESS‘
.
.
.
reread=‘cocheck BIGPROCESS‘

name=‘cosend -n BIGPROCESS field1‘

.
.
.
name="Receive field"
inactive=TRUE
value=‘coreceive BIGPROCESS‘

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO awk(1), cat(1), sed(1), vsig(1F), attributes(5)

NOTES If cosend is used without the -n option, a co-process that does not answer will cause
FMLI to permanently hang.

The use of non-alphabetic characters in input and output strings to a co-process

should be avoided because they may not get transferred correctly.

User Commands 187

cp(1)
NAME cp – copy files
SYNOPSIS /usr/bin/cp [-fip@] source_file target_file
/usr/bin/cp [-fip@] source_file… target
/usr/bin/cp -r | -R [-fip@] source_dir… target
/usr/xpg4/bin/cp [-fip@] source_file target_file
/usr/xpg4/bin/cp [-fip@] source_file… target
/usr/xpg4/bin/cp -r | -R [-fip@] source_dir… target

DESCRIPTION In the first synopsis form, neither source_file nor target_file are directory files, nor can
they have the same name. The cp utility will copy the contents of source_file to the
destination path named by target_file. If target_file exists, cp will overwrite its contents,
but the mode (and ACL if applicable), owner, and group associated with it are not
changed. The last modification time of target_file and the last access time of source_file
are set to the time the copy was made. If target_file does not exist, cp creates a new file
named target_file that has the same mode as source_file except that the sticky bit is not
set unless the user is super-user. In this case, the owner and group of target_file are
those of the user, unless the setgid bit is set on the directory containing the newly
created file. If the directory’s setgid bit is set, the newly created file will have the
group of the containing directory rather than of the creating user. If target_file is a link
to another file, cp will overwrite the link destination with the contents of source_file;
the link(s) from target_file will remain.

In the second synopsis form, one or more source_files are copied to the directory
specified by target. For each source_file specified, a new file with the same mode (and
ACL if applicable), is created in target; the owner and group are those of the user
making the copy. It is an error if any source_file is a file of type directory, if target either
does not exist or is not a directory.

In the third synopsis form, one or more directories specified by source_dir are copied to
the directory specified by target. Either -r or -R must be specified. For each source_dir,
cp will copy all files and subdirectories.

OPTIONS The following options are supported for both /usr/bin/cp and
/usr/xpg4/bin/cp:
-f Unlink. If a file descriptor for a destination file cannot be obtained, attempt
to unlink the destination file and proceed.
-i Interactive. cp will prompt for confirmation whenever the copy would
overwrite an existing target. A y answer means that the copy should
proceed. Any other answer prevents cp from overwriting target.
-r Recursive. cp will copy the directory and all its files, including any
subdirectories and their files to target.
-R Same as -r, except pipes are replicated, not read from.

188 man pages section 1: User Commands • Last Revised 6 Jun 2001
 cp(1)
-@ Preserves extended attributes. cp will attempt to copy all of the source
file’s extended attributes along with the file data to the destination file.

/usr/bin/cp The following option is supported for /usr/bin/cp only:

-p Preserve. cp duplicates not only the contents of source_file, but also
preserves the owner and group id, permission modes, modification and
access time, ACLs, and extended attributes, if applicable. Notice that the
command may fail if ACLs are copied to a file system without appropriate
support. The command will not fail if unable to preserve extended
attributes, modification and access time, or permission modes. If unable to
preserve owner and group id, cp will not fail, and it will clear S_ISUID
and S_ISGID bits in the target. cp will print a diagnostic message to
stderr and return a non-zero exit status if unable to clear these bits.

In order to preserve the owner and group id, permission modes, and
modification and access times, users must have the appropriate file access
permissions. This includes being superuser or the same owner id as the
destination file.

/usr/xpg4/bin/cp The following option is supported for /usr/xpg4/bin/cp only:

-p Preserve. cp duplicates not only the contents of source_file, but also
preserves the owner and group id, permission modes, modification and
access time, ACLs, and extended attributes, if applicable. Notice that the
command may fail if ACLs or extended attributes are copied to a file
system without appropriate support. If unable to duplicate the
modification and access time or the permission modes, cp will print a
diagnostic message to stderr and return a non-zero exit status. If unable
to preserve owner and group id, cp will not fail, and it will clear S_ISUID
and S_ISGID bits in the target. cp will print a diagnostic message to
stderr and return a non-zero exit status if unable to clear these bits.

In order to preserve the owner and group id, permission modes, and
modification and access times, users must have the appropriate file access
permissions. This includes being superuser or the same owner id as the
destination file.

OPERANDS The following operands are supported:

source_file A pathname of a regular file to be copied.
source_dir A pathname of a directory to be copied.
target_file A pathname of an existing or non-existing file, used for the output
when a single file is copied.
target A pathname of a directory to contain the copied files.

USAGE See largefile(5) for the description of the behavior of cp when encountering files
greater than or equal to 2 Gbyte ( 231 bytes).

User Commands 189

cp(1)
EXAMPLES EXAMPLE 1 Copying a file
example% cp goodies goodies.old

example% ls goodies*
goodies goodies.old

EXAMPLE 2 Copying a list of files to a destination directory

example% cp ~/src/* /tmp

EXAMPLE 3 Copying a directory, first to a new, and then to an existing destination directory
example% ls ~/bkup
/usr/example/fred/bkup not found

example% cp -r ~/src ~/bkup

example% ls -R ~/bkup
x.c y.c z.sh

example% cp -r ~/src ~/bkup

example% ls -R ~/bkup
src x.c y.c z.sh
src:
x.c y.c z.s

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of cp: LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, and
NLSPATH.

EXIT STATUS The following exit values are returned:

0 All files were copied successfully.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

/usr/bin/cp ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

CSI Enabled

Interface Stability Stable

/usr/xpg4/bin/cp ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWxcu4

190 man pages section 1: User Commands • Last Revised 6 Jun 2001
 cp(1)

ATTRIBUTE TYPE ATTRIBUTE VALUE

CSI Enabled

Interface Stability Standard

SEE ALSO chmod(1), chown(1), setfacl(1), utime(2), attributes(5), environ(5), fsattr(5),

largefile(5), standards(5)

NOTES The permission modes of the source file are preserved in the copy.

A -- permits the user to mark the end of any command line options explicitly, thus
allowing cp to recognize filename arguments that begin with a -.

User Commands 191

cpio(1)
NAME cpio – copy file archives in and out
SYNOPSIS cpio -i [-bBcdfkmPrsStuvV6@] [-C bufsize] [-E file] [-H header]
[-I file [-M message]] [-R id] [pattern…]
cpio -o [-aABcLPvV@] [-C bufsize] [-H header] [-O file [-M message]]
cpio -p [-adlLmPuvV@] [-R id] directory

DESCRIPTION The cpio command copies files into and out of a cpio archive. The cpio archive may
span multiple volumes. The -i, -o, and -p options select the action to be performed.
The following list describes each of the actions. These actions are mutually exclusive.

Copy In Mode cpio -i (copy in) extracts files from the standard input, which is assumed to be the
product of a previous cpio -o command. Only files with names that match one of the
patterns are selected. See sh(1) and OPERANDS for more information about pattern.
Extracted files are conditionally copied into the current directory tree, based on the
options described below. The permissions of the files will be those of the previous
cpio -o command. The owner and group will be the same as the current user, unless
the current user is the super-user. If this is the case, owner and group will be the same
as those resulting from the previous cpio -o command. Notice that if cpio -i tries
to create a file that already exists and the existing file is the same age or younger
(newer), cpio will output a warning message and not replace the file. The -u option
can be used to unconditionally overwrite the existing file.

Copy Out Mode cpio -o (copy out) reads a list of file path names from the standard input and copies
those files to the standard output, together with path name and status information in
the form of a cpio archive. Output is padded to an 8192-byte boundary by default or
to the user-specified block size (with the -B or -C options) or to some
device-dependent block size where necessary (as with the CTC tape).

Pass Mode cpio -p (pass) reads a list of file path names from the standard input and
conditionally copies those files into the destination directory tree, based on the options
described below.

Note: cpio assumes four-byte words.

If, when writing to a character device (-o) or reading from a character device (-i),
cpio reaches the end of a medium (such as the end of a diskette), and the -O and -I
options are not used, cpio prints the following message:
To continue, type device/file name when ready.

To continue, you must replace the medium and type the character special device name
(/dev/rdiskette for example) and press RETURN. You may want to continue by
directing cpio to use a different device. For example, if you have two floppy drives
you may want to switch between them so cpio can proceed while you are changing
the floppies. Press RETURN to cause the cpio process to exit.

OPTIONS The following options are supported:

192 man pages section 1: User Commands • Last Revised 22 Oct 2001
 cpio(1)
-i (copy in) Reads an archive from the standard input and
conditionally extracts the files contained in it and places them into
the current directory tree.
-o (copy out) Reads a list of file path names from the standard input
and copies those files to the standard output in the form of a cpio
archive.
-p (pass) Reads a list of file path names from the standard input and
conditionally copies those files into the destination directory tree.

The following options can be appended in any sequence to the -i, -o, or -p options:
-a Resets access times of input files after they have been copied,
making cpio’s access invisible. Access times are not reset for
linked files when cpio -pla is specified.
-A Appends files to an archive. The -A option requires the -O option.
Valid only with archives that are files, or that are on floppy
diskettes or hard disk partitions. The effect on files that are linked
in the existing portion of the archive is unpredictable.
-b Reverses the order of the bytes within each word. Use only with
the -i option.
-B Blocks input/output 5120 bytes to the record. The default buffer
size is 8192 bytes when this and the -C options are not used. -B
does not apply to the -p (pass) option.
-c Reads or writes header information in ASCII character form for
portability. There are no UID or GID restrictions associated with
this header format. Use this option between SVR4-based machines,
or the -H odc option between unknown machines. The -c option
implies the use of expanded device numbers, which are only
supported on SVR4-based systems. When transferring files
between SunOS 4 or Interactive UNIX and the Solaris 2.6
Operating environment or compatible versions, use -H odc.
-C bufsize Blocks input/output bufsize bytes to the record, where bufsize is
replaced by a positive integer. The default buffer size is 8192 bytes
when this and -B options are not used. -C does not apply to the
-p (pass) option.
-d Creates directories as needed.
-E file Specifies an input file (file) that contains a list of filenames to be
extracted from the archive (one filename per line).
-f Copies in all files except those in patterns. See OPERANDS for a
description of pattern.

User Commands 193

cpio(1)
-H header Reads or writes header information in header format. Always use
this option or the -c option when the origin and the destination
machines are different types. This option is mutually exclusive
with options -c and -6.

Valid values for header are:

bar bar head and format. Used only with the -i
option ( read only).
crc | CRC ASCII header with expanded device numbers
and an additional per-file checksum. There are
no UID or GID restrictions associated with this
header format.
odc ASCII header with small device numbers. This
is the IEEE/P1003 Data Interchange Standard
cpio header and format. It has the widest range
of portability of any of the header formats. It is
the official format for transferring files between
POSIX-conforming systems (see
standards(5)). Use this format to
communicate with SunOS 4 and Interactive
UNIX. This header format allows UIDs and
GIDs up to 262143 to be stored in the header.
tar | TAR tar header and format. This is an older tar
header format that allows UIDs and GIDs up
to 2097151 to be stored in the header. It is
provided for the reading of legacy archives
only, that is, in conjunction with option -i.

Specifying this archive format with option -o

has the same effect as specifying the "ustar"
format: the output archive is in ustar format,
and must be read using -H ustar.
ustar | USTAR IEEE/P1003 Data Interchange Standard tar
header and format. This header format allows
UIDs and GIDs up to 2097151 to be stored in
the header.

Files with UIDs and GIDs greater than the limit stated above will
be archived with the UID and GID of 60001. To transfer a large
file (8 Gb — 1 byte), the header format can be tar|TAR,
ustar|USTAR, or odc only.
-I file Reads the contents of file as an input archive, instead of the
standard input. If file is a character special device, and the current

194 man pages section 1: User Commands • Last Revised 22 Oct 2001
 cpio(1)
medium has been completely read, replace the medium and press
RETURN to continue to the next medium. This option is used only
with the -i option.
-k Attempts to skip corrupted file headers and I/O errors that may be
encountered. If you want to copy files from a medium that is
corrupted or out of sequence, this option lets you read only those
files with good headers. For cpio archives that contain other cpio
archives, if an error is encountered, cpio may terminate
prematurely. cpio will find the next good header, which may be
one for a smaller archive, and terminate when the smaller
archive’s trailer is encountered. Use only with the -i option.
-l In pass mode, makes hard links between the source and
destination whenever possible. If the -L option is also specified,
the hard link will be to the file referred to by the symbolic link.
Otherwise, the hard link will be to the symbolic link itself. Use
only with the -p option.
-L Follows symbolic links. If a symbolic link to a directory is
encountered, archives the directory referred to by the link, using
the name of the link. Otherwise, archives the file referred to by the
link, using the name of the link.
-m Retains previous file modification time. This option is ineffective
on directories that are being copied.
-M message Defines a message to use when switching media. When you use the
-O or -I options and specify a character special device, you can
use this option to define the message that is printed when you
reach the end of the medium. One %d can be placed in message to
print the sequence number of the next medium needed to
continue.
-O file Directs the output of cpio to file, instead of the standard output. If
file is a character special device and the current medium is full,
replace the medium and type a carriage return to continue to the
next medium. Use only with the -o option.
-P Preserves ACLs. If the option is used for output, existing ACLs are
written along with other attributes, except for extended attributes,
to the standard output. ACLs are created as special files with a
special file type. If the option is used for input, existing ACLs are
extracted along with other attributes from standard input. The
option recognizes the special file type. Notice that errors will occur
if a cpio archive with ACLs is extracted by previous versions of
cpio. This option should not be used with the -c option, as ACL
support may not be present on all systems, and hence is not
portable. Use ASCII headers for portability.

User Commands 195

cpio(1)
-r Interactively renames files. If the user types a carriage return
alone, the file is skipped. If the user types a ‘‘.’’, the original
pathname will be retained. Not available with cpio -p.
-R id Reassigns ownership and group information for each file to user
ID. (ID must be a valid login ID from /etc/passwd.) This option
is valid only for the super-user.
-s Swaps bytes within each half word.
-S Swaps halfwords within each word.
-t Prints a table of contents of the input. If any file in the table of
contents has extended attributes, these are also listed. No files are
created. -t and -V are mutually exclusive.
-u Copies unconditionally. Normally, an older file will not replace a
newer file with the same name.
-v Verbose. Prints a list of file and extended attribute names. When
used with the -t option, the table of contents looks like the output
of an ls -l command (see ls(1)).
-V Special verbose. Prints a dot for each file read or written. Useful to
assure the user that cpio is working without printing out all file
names.
-6 Processes a UNIX System Sixth Edition archive format file. Use
only with the -i option. This option is mutually exclusive with -c
and -H.
-@ Includes extended attributes in archive. By default, cpio does not
place extended attributes in the archive. With this flag, cpio will
look for extended attributes on the files to be placed in the archive
and add them, as regular files, to the archive. The extended
attribute files go in the archive as special files with special file
types. When the -@ flag is used with -i or -p, it instructs cpio to
restore extended attribute data along with the normal file data.
Extended attribute files can only be extracted from an archive as
part of a normal file extract. Attempts to explicitly extract attribute
records are ignored.

OPERANDS The following operands are supported:

directory A path name of an existing directory to be used as the target of
cpio -p.
pattern Expressions making use of a pattern-matching notation similar to
that used by the shell (see sh(1)) for filename pattern matching,
and similar to regular expressions. The following metacharacters
are defined:
* Matches any string, including the empty string.

196 man pages section 1: User Commands • Last Revised 22 Oct 2001
 cpio(1)
? Matches any single character.
[ . . . ]Matches any one of the enclosed characters. A pair of
characters separated by ‘−’ matches any symbol
between the pair (inclusive), as defined by the system
default collating sequence. If the first character
following the opening ‘[’ is a ‘!’, the results are
unspecified.
! The ! (exclamation point) means not. For example, the
!abc* pattern would exclude all files that begin with
abc.

In pattern, metacharacters ?, *, and [ . . .] match the slash (/)

character, and backslash (\) is an escape character. Multiple cases
of pattern can be specified and if no pattern is specified, the default
for pattern is * (that is, select all files).

Each pattern must be enclosed in double quotes. Otherwise, the

name of a file in the current directory might be used.

USAGE See largefile(5) for the description of the behavior of cpio when encountering files
greater than or equal to 2 Gbyte ( 231 bytes).

EXAMPLES The following examples show three uses of cpio.

EXAMPLE 1 Using standard input

example% ls | cpio -oc > ../newfile

When standard input is directed through a pipe to cpio -o, as in the example above,
it groups the files so they can be directed (>) to a single file (../newfile). The -c
option insures that the file will be portable to other machines (as would the -H
option). Instead of ls(1), you could use find(1), echo(1), cat(1), and so on, to pipe a
list of names to cpio. You could direct the output to a device instead of a file.

EXAMPLE 2 Extracting files into directories

example% cat newfile | cpio -icd "memo/a1" "memo/b*"

In this example, cpio -i uses the output file of cpio -o (directed through a pipe
with cat), extracts those files that match the patterns (memo/a1, memo/b*), creates
directories below the current directory as needed (-d option), and places the files in
the appropriate directories. The -c option is used if the input file was created with a
portable header. If no patterns were given, all files from newfile would be placed in
the directory.

EXAMPLE 3 Copying or linking files to another directory

example% find . -depth -print | cpio -pdlmv newdir

User Commands 197

cpio(1)
EXAMPLE 3 Copying or linking files to another directory (Continued)

In this example, cpio -p takes the file names piped to it and copies or links (-l
option) those files to another directory, newdir. The -d option says to create
directories as needed. The -m option says to retain the modification time. (It is
important to use the -depth option of find(1) to generate path names for cpio. This
eliminates problems that cpio could have trying to create files under read-only
directories.) The destination directory, newdir, must exist.

Notice that when you use cpio in conjunction with find, if you use the -L option
with cpio, you must use the -follow option with find and vice versa. Otherwise,
there will be undesirable results.

For multi-reel archives, dismount the old volume, mount the new one, and continue to
the next tape by typing the name of the next device (probably the same as the first
reel). To stop, type a RETURN and cpio will end.

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of cpio: LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_TIME, TZ, and
NLSPATH.
TMPDIR cpio creates its temporary file in /var/tmp by default.
Otherwise, it uses the directory specified by TMPDIR.

EXIT STATUS The following exit values are returned:

0 Successful completion.
>0 An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

CSI Enabled

Interface Stability Stable

SEE ALSO ar(1), cat(1), echo(1), find(1), ls(1), setfacl(1), sh( 1), tar(1), vold(1M),
archives(4), attributes(5), environ(5), fsattr(5), largefile(5),
standards(5)

NOTES The maximum path name length allowed in a cpio archive is determined by the
header type involved. The following table shows the proper value for each supported
archive header type.

198 man pages section 1: User Commands • Last Revised 22 Oct 2001
 cpio(1)

Header type Command line options Maximum path name length

BINARY “-o” 256

POSIX “-oH odc” 256

ASCII “-oc” 1023

CRC “-oH crc” 1023

USTAR “-oH ustar” 255

When the command line options “-o -H tar” are specified, the archive created is of
type USTAR. This means that it is an error to read this same archive using the
command line options “-i -H tar”. The archive should be read using the command
line options “-i -H ustar”. The options "-i -H tar" refer to an older tar archive format.

An error message is output for files whose UID or GID are too large to fit in the
selected header format. Use -H crc or -c to create archives that allow all UID or GID
values.

Only the super-user can copy special files.

Blocks are reported in 512-byte quantities.

If a file has 000 permissions, contains more than 0 characters of data, and the user is
not root, the file will not be saved or restored.

The inode number stored in the header (/usr/include/archives.h) is an

unsigned short, which is 2 bytes. This limits the range of inode numbers from 0 to
65535. Files which are hard linked must fall in this inode range. This could be a
problem when moving cpio archives between different vendors’ machines.

When the Volume Management daemon is running, accesses to floppy devices

through the conventional device names (for example, /dev/rdiskette) may not
succeed. See vold(1M) for further details.

You must use the same blocking factor when you retrieve or copy files from the tape to
the hard disk as you did when you copied files from the hard disk to the tape.
Therefore, you must specify the -B or -C option.

During -p and -o processing, cpio buffers the file list presented on stdin in a
temporary file.

User Commands 199

cpp(1)
NAME cpp – the C language preprocessor
SYNOPSIS /usr/lib/cpp [-BCHMpPRT] [-undef] [-Dname] [-Dname = def]
[-Idirectory] [-Uname] [-Ydirectory] [input-file [output-file]]

DESCRIPTION cpp is the C language preprocessor. It is invoked as the first pass of any C compilation
started with the cc(1B) command. However, cpp can also be used as a first-pass
preprocessor for other Sun compilers.

Although cpp can be used as a macro processor, this is not normally recommended, as
its output is geared toward that which would be acceptable as input to a compiler’s
second pass. Thus, the preferred way to invoke cpp is through the cc(1B) command,
or some other compilation command. For general-purpose macro-processing, see
m4(1).

cpp optionally accepts two filenames as arguments. input-file and output-file are,
respectively, the input and output files for the preprocessor. They default to the
standard input and the standard output.

OPTIONS The following options are supported:

-B Supports the C++ comment indicator ‘/ /’. With this indicator,
everything on the line after the / / is treated as a comment.
-C Passes all comments (except those that appear on cpp directive
lines) through the preprocessor. By default, cpp strips out C-style
comments.
-H Prints the pathnames of included files, one per line on the
standard error.
-M Generates a list of makefile dependencies and write them to the
standard output. This list indicates that the object file which would
be generated from the input file depends on the input file as well
as the include files referenced.
-p Uses only the first eight characters to distinguish preprocessor
symbols, and issue a warning if extra tokens appear at the end of a
line containing a directive.
-P Preprocesses the input without producing the line control
information used by the next pass of the C compiler.
-R Allows recursive macros.
-T Uses only the first eight characters for distinguishing different
preprocessor names. This option is included for backward
compatibility with systems which always use only the first eight
characters.
-undef Removes initial definitions for all predefined symbols.

200 man pages section 1: User Commands • Last Revised 1 Nov 1999
 cpp(1)
-Dname Defines name as 1 (one). This is the same as if a -Dname=1 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 Defines name as if by a #define directive. This is the same as if a
#define name def

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.
-Idirectory Inserts directory into the search path for #include files with
names not beginning with ‘/’. directory is inserted ahead of the
standard list of ‘‘include’’ directories. Thus, #include files with
names enclosed in double-quotes (") are searched for first in the
directory of the file with the #include line, then in directories
named with -I options, and lastly, in directories from the standard
list. For #include files with names enclosed in angle-brackets
(< > ), the directory of the file with the #include line is not
searched. See Details below for exact details of this search order.
-Uname Removes any initial definition of name, where name is a symbol
that is predefined by a particular preprocessor. Here is a partial list
of symbols that may be predefined, depending upon the
architecture of the system:
Operating System: ibm, gcos, os, tss and unix
Hardware: interdata, pdp11, u370, u3b,
u3b2, u3b5, u3b15, u3b20d, vax,
ns32000, iAPX286, i386, sparc,
and sun
UNIX system variant: RES, and RT
The lint command: lint

The symbols sun, sparc and unix are defined for all Sun
systems.
-Ydirectory Uses directory in place of the standard list of directories when
searching for #include files.

USAGE

Directives All cpp directives start with a hash symbol (#) as the first character on a line. White
space (SPACE or TAB characters) can appear after the initial # for proper indentation.

User Commands 201

cpp(1)
#define name token-string
Replace subsequent instances of name with token-string.
#define name(argument [, argument] . . . ) token-string
There can be no space between name and the ‘(’. Replace subsequent instances of
name, followed by a parenthesized list of arguments, with token-string, where each
occurrence of an argument in the token-string is replaced by the corresponding token
in the comma-separated list. When a macro with arguments is expanded, the
arguments are placed into the expanded token-string unchanged. After the entire
token-string has been expanded, cpp re-starts its scan for names to expand at the
beginning of the newly created token-string.
#undef name
Remove any definition for the symbol name. No additional tokens are permitted on
the directive line after name.
#include "filename"
#include <filename>
Read in the contents of filename at this location. This data is processed by cpp as if it
were part of the current file. When the <filename> notation is used, filename is only
searched for in the standard ‘‘include’’ directories. See the -I and -Y options above
for more detail. No additional tokens are permitted on the directive line after the
final ‘"’ or ‘>’.
#line integer-constant "filename"
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 filename is
interpreted as the file from where it comes. If "filename" is not given, the current
filename is unchanged. No additional tokens are permitted on the directive line
after the optional filename.
#if constant-expression
Subsequent lines up to the matching #else, #elif, or #endif directive, appear in
the output only if constant-expression yields a nonzero value. All binary
non-assignment C operators, including ‘&&’, ‘| |’, and ‘,’, are legal in
constant-expression. The ‘?:’ operator, and the unary ‘−’, ‘!’, and ‘~’ operators, are
also legal in constant-expression.

The precedence of these operators is the same as that for C. In addition, the unary
operator defined, can be used in constant-expression in these two forms: ‘defined
( name )’ or ‘defined name’. This allows the effect of #ifdef and #ifndef
directives (described below) in the #if directive. Only these operators, integer
constants, and names that are known by cpp should be used within
constant-expression. In particular, the size of operator is not available.
#ifdef name
Subsequent lines up to the matching #else, #elif, or #endif appear in the
output only if name has been defined, either with a #define directive or a -D
option, and in the absence of an intervening #undef directive. Additional tokens
after name on the directive line will be silently ignored.

202 man pages section 1: User Commands • Last Revised 1 Nov 1999
 cpp(1)
#ifndef name
Subsequent lines up to the matching #else, #elif, or #endif appear in the
output only if name has not been defined, or if its definition has been removed with
an #undef directive. No additional tokens are permitted on the directive line after
name.
#elif constant-expression
Any number of #elif directives may appear between an #if, #ifdef, or
#ifndef directive and a matching #else or #endif directive. The lines following
the #elif directive appear in the output only if all of the following conditions
hold:
■ The constant-expression in the preceding #if directive evaluated to zero, the
name in the preceding #ifdef is not defined, or the name in the preceding
#ifndef directive was defined.
■ The constant-expression in all intervening #elif directives evaluated to zero.
■ The current constant-expression evaluates to non-zero.

If the constant-expression evaluates to non-zero, subsequent #elif and #else

directives are ignored up to the matching #endif. Any constant-expression allowed
in an #if directive is allowed in an #elif directive.
#else
This inverts the sense of the conditional directive otherwise in effect. If the
preceding conditional would indicate that lines are to be included, then lines
between the #else and the matching #endif are ignored. If the preceding
conditional indicates that lines would be ignored, subsequent lines are included in
the output. Conditional directives and corresponding #else directives can be
nested.
#endif
End a section of lines begun by one of the conditional directives #if, #ifdef, or
#ifndef. Each such directive must have a matching #endif.

Macros Formal parameters for macros are recognized in #define directive bodies, even when
they occur inside character constants and quoted strings. For instance, the output
from:
#define abc(a)| ‘|a|
abc(xyz)

is:
# 1 ""
| ‘|xyz |

The second line is a NEWLINE. The last seven characters are ‘‘|‘|xyz|’’ (vertical-bar,
backquote, vertical-bar, x, y, z, vertical-bar). Macro names are not recognized within
character constants or quoted strings during the regular scan. Thus:
#define abc xyz
printf("abc");

User Commands 203

cpp(1)
does not expand abc in the second line, since it is inside a quoted string that is not
part of a #define macro definition.

Macros are not expanded while processing a #define or #undef. Thus:

#define abc zingo
#define xyz abc
#undef abc
xyz

produces abc. The token appearing immediately after an #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(greeting,
#define greeting goodbye
)

produces ‘‘ #define hello goodbye hello’’.

Output 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).

Details This section contains usage details.

Directory Search #include files are searched for in the following order:
Order
1. The directory of the file that contains the #include request (that is, #include is
relative to the file being scanned when the request is made).
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.

Newline Characters A NEWLINE character 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 value.

204 man pages section 1: User Commands • Last Revised 1 Nov 1999
 cpp(1)
Comments Comments are removed (unless the -C option is used on the command line).
Comments are also ignored, except that a comment terminates a token.

EXIT STATUS The following exit values are returned:

0 Successful completion.
non-zero An error occurred.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWsprot

SEE ALSO cc(1B), m4(1), attributes(5)

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.

NOTES When NEWLINE characters were found in argument lists for macros to be expanded,
some previous versions of cpp put out the NEWLINE characters as they were found
and expanded. The current version of cpp replaces them with SPACE characters.

Because the standard directory for included files may be different in different
environments, this form of #include directive:
#include <file.h>

should be used, rather than one with an absolute path, like:

#include "/usr/include/file.h"

cpp warns about the use of the absolute pathname.

While the compiler allows 8-bit strings and comments, 8-bits are not allowed
anywhere else.

User Commands 205

cputrack(1)
NAME cputrack – monitor process and LWP behavior using CPU performance counters
SYNOPSIS cputrack -c eventspec [-c eventspec]… [-efntvD] [-N count] [-o pathname]
[-T interval] command [args]
cputrack -c eventspec [-c eventspec]… -p pid [-efntvD] [-N count]
[-o pathname] [-T interval]
cputrack -h

DESCRIPTION The cputrack utility allows CPU performance counters to be used to monitor the
behavior of a process or family of processes running on the system. If interval is
specified with the -T option, cputrack samples activity every interval seconds,
repeating forever. If a count is specified with the -N option, the statistics are repeated
count times for each process tracked. If neither are specified, an interval of one second
is used. If command and optional args are specified, cputrack runs the command with
the arguments given while monitoring the specified CPU performance events.
Alternatively, the process ID of an existing process can be specified using the -p
option.

Because cputrack is an unprivileged program, it is subject to the same restrictions

that apply to truss(1). For example, setuid(2) executables cannot be tracked.

OPTIONS The following options are supported:

-c eventspec Specifies a set of events for the CPU performance counters to
monitor. The list of available events and the syntax of the event
specifications for the system can be determined using the -h
option. The semantics of these event specifications can be
determined by reading the CPU manufacturers documentation for
the events. See cpc_strtoevent(3CPC) for a description of the
syntax.

Multiple -c options may be specified, in which case cputrack

cycles between the different event settings on each sample.
-D Enables debug mode.
-e Follows all exec(2), or execve(2) system calls. Without this
option, cputrack terminates when the process image is overlaid
with a new executable.
-f Follows all children created by fork(2), fork1(2), or vfork(2)
system calls.
-h Prints an extended help message on how to use the utility and
how to program the processor-dependent counters.
-n Omits all header output (useful if cputrack is the beginning of a
pipeline).
-N count Specifies the maximum number of CPU performance counter
samples to take before exiting.

206 man pages section 1: User Commands • Last Revised 10 Jul 2002
 cputrack(1)
-o outfile Specifies file to be used for the cputrack output.
-p pid Interprets the argument as the process ID of an existing process to
which process counter context should be attached and monitored.
-t Prints an additional column of processor cycle counts, if available
on the current architecture.
-T interval Specifies the interval between CPU performance counter samples
in seconds. Very small intervals may cause some samples to be
skipped. See WARNINGS.
-v Enables more verbose output.

USAGE The operating system enforces certain restrictions on the tracing of processes. In
particular, a command whose object file cannot be read by a user cannot be tracked by
that user; set-uid and set-gid commands can only be tracked by a privileged user.
Unless it is run by a privileged user, cputrack loses control of any process that
performs an exec() of a set-id or unreadable object file. Such processes continue
normally, though independently of cputrack, from the point of the exec().

The system may run out of per-user process slots when the -f option is used, since
cputrack runs one controlling process for each process being tracked.

The times printed by cputrack correspond to the wallclock time when the hardware
counters were actually sampled, instead of when the program told the kernel to
sample them. The time is derived from the same timebase as gethrtime(3C).

The cputrack utility attaches performance counter context to each process that it
examines. The presence of this context allows the performance counters to be
multiplexed between different processes on the system, but it cannot be used at the
same time as the cpustat(1M) utility.

Once an instance of the cpustat utility is running, further attempts to run cputrack
will fail until all instances of cpustat terminate.

Sometimes cputrack provides sufficient flexibility and prints sufficient statistics to

make adding the event selection code to an application unnecessary. However, more
control is occasionally desired. Because the same performance counter context is used
by both the application itself and by the agent LWP injected into the application by
cputrack, it is possible for an application to interact with the counter context to
achieve some interesting capabilities. See cpc_count_usr_events(3CPC).

The processor cycle counts enabled by the -t option always apply to both user and
system modes, regardless of the settings applied to the performance counter registers.

The output of cputrack is designed to be readily parseable by nawk(1) and perl(1),

thereby allowing performance tools to be composed by embedding cputrack in
scripts. Alternatively, tools may be constructed directly using the same APIs that
cputrack is built upon, using the facilities of libcpc(3LIB) and libpctx(3LIB). See
cpc(3CPC).

User Commands 207

cputrack(1)
Although cputrack uses performance counter context to maintain separate
performance counter values for each LWP, some of the events that can be counted will
inevitably be impacted by other activities occurring on the system, particularly for
limited resources that are shared between processes (for example, cache miss rates).
For such events, it may also be interesting to observe overall system behavior with
cpustat(1M).

For the -T interval option, if interval is specified as zero, no periodic sampling is

performed. The performance counters are only sampled when the process creates or
destroys an LWP, or it invokes fork(2), exec(2), or exit(2).

EXAMPLES

SPARC EXAMPLE 1 Using performance counters to count clock cycles

In this example, the utility is being used on a machine containing an UltraSPARC 1

processor. The counters are set to count processor clock cycles and instructions
dispatched in user mode while running the sleep(1) command.
example% cputrack –c pic0=Cycle_cnt,pic1=Instr_cnt sleep 10
time lwp event pic0 pic1
2.040 1 tick 377820 202593
4.028 1 tick 0 0
6.028 1 tick 0 0
8.028 1 tick 0 0
10.028 1 tick 6930 954
10.036 1 exit 410623 212137

EXAMPLE 2 Counting external cache references and hits

This example shows more verbose output while following the fork() and exec() of
a simple shell script on an UltraSPARC machine. The counters are measuring the
number of external cache references and external cache hits. Notice that the explicit
pic0 and pic1 names can be omitted where there are no ambiguities.
example% cputrack –fev –c EC_ref,EC_hit /bin/ulimit –c
time pid lwp event pic0 pic1
0.032 101200 1 init_lwp 0 0
0.106 101200 1 fork # 101201
0.115 101201 1 init_lwp 0 0
0.179 101201 1 fini_lwp 5934 5031
0.179 101201 1 exec 5934 5031
0.399 101201 1 exec # ’basename /bin/ulimit’
0.413 101201 1 init_lwp 0 0
0.435 101201 1 fini_lwp 19780 17234
0.435 101201 1 exit 19780 17234 unlimited
0.454 101200 1 fini_lwp 63025 54583
0.454 101200 1 exit 63025 54583

208 man pages section 1: User Commands • Last Revised 10 Jul 2002
 cputrack(1)
x86 EXAMPLE 3 Counting instructions

This example shows how many instructions were executed in the application and in
the kernel to print the date on a Pentium machine:
example% cputrack –c inst_retired,inst_retired,nouser1,sys1 date
time lwp event pic0 pic1
Fri Aug 20 20:03:08 PDT 1999
0.072 1 exit 246725 339666

WARNINGS By running any instance of the cpustat(1M) utility, all existing performance counter
context is forcibly invalidated across the machine. This may in turn cause all
invocations of the cputrack command to exit prematurely with unspecified errors.

If cputrack is invoked on a system that has CPU performance counters, but on

which the packages containing the kernel support for those counters is not installed,
the following message appears:
cputrack: CPU performance counters are inaccessible on this machine

This error message implies that cpc_access() has failed and is documented in
cpc_access(3CPC). Review this documentation for more information about the
problem and possible solutions.

If a short interval is requested, cputrack may not be able to keep up with the desired
sample rate. In this case, some samples may be dropped.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcpcu (32-bit)

SUNWcpcux (64-bit)

Interface Stability Evolving

SEE ALSO nawk(1), perl(1), proc(1), truss(1), prstat(1M), cpustat(1M), exec(2), exit(2),
fork(2), setuid(2), vfork(2), gethrtime(3C), cpc(3CPC), cpc_access(3CPC),
cpc_count_usr_events(3CPC), cpc_strtoevent(3CPC), libcpc(3LIB),
libpctx(3LIB), proc(4), attributes(5)

Sun Microelectronics UltraSPARC I&II User’s Manual, January 1997, STP1031,

http://www.sun.com/sparc

Intel Architecture Software Developer’s Manual, Volume 3: System Programmers Guide,

243192, http://developer.intel.com

User Commands 209

crle(1)
NAME crle – configure runtime linking environment
SYNOPSIS crle [-64] [-a name] [-c conf] [-e env] [-E env] [-f flags] [-i name]
[-I name] [-g name] [-G name] [-l dir] [-o dir] [-s dir] [-t [ ELF
| AOUT]] [-u] [-v]

DESCRIPTION The crle utility provides for the creation and display of a runtime linking
configuration file. Without any arguments, or with just the -c option, crle displays
the contents of a configuration file, any system defaults and the command-line
required to regenerate the configuration file. When used with any other options, a new
configuration file is created or updated. The configuration file is read and interpreted
by the runtime linker, ld.so.1(1), during process start-up.

The default configuration file is /var/ld/ld.config for 32-bit objects and

/var/ld/64/ld.config for 64-bit objects. Note: It is recommended that any new
configuration file is first created in a temporary location. The environment variable
LD_CONFIG can be set to this new configuration file to cause its use by the runtime
linker instead of any default. After verification, the new configuration file can be
moved to the default location if desired. Setting the environment variable
LD_NOCONFIG to any value results in the runtime linker ignoring any configuration
files, and may prove useful during experimentation.

The configuration file may contain the following information:

Default Search Paths The runtime linker uses a prescribed search path for
locating the dynamic dependencies of an object. This
search path starts with the components of any
LD_LIBRARY_PATH definition, followed by the
components of an object’s runpath and finally any
defaults specific to the object’s type. This last
component of the search path can be expressed within
the configuration file. Note: Typical use of this facility
should augment any system defaults; see the -l
option.
Trusted Directories When processing a secure application the runtime
linker restricts the use of LD_LIBRARY_PATH and the
directories from which preload and audit libraries may
be used to known trusted directories. These trusted
directories can be expressed within the configuration
file. Note: Typical use of this facility should augment
any system defaults; see the -s option.
Directory Cache The location of shared objects within defined
directories can be maintained as a cache within the
configuration file. This directory cache can reduce the
overhead of searching for application dependencies.
Alternative Objects In conjunction with the directory cache, shared objects
may have alternative objects specified for use at

210 man pages section 1: User Commands • Last Revised 10 Oct 2001
 crle(1)
runtime. These alternate objects may be supplied by
the user, or can be created by crle as copies of shared
objects fixed to known memory locations. These fixed
alternative objects can require less processing at
runtime than their original shared object counterpart.
Environment Variables Any environment variable interpreted by the runtime
linker can be specified within the configuration file.

Defining alternative default search paths, or additional trusted directories can be

useful for administrators who wish to install third party software in a central location,
or otherwise alter the search path of applications that may not have been coded with
suitable runpaths.

Defining user supplied alternative objects provides a means of replacing dependencies

other than via symbolic links or requiring LD_LIBRARY_PATH settings.

Defining runtime linker environment variables provides a means of centralizing their

definition for all applications.

The directory cache and crle generated alternate objects can provide a means of
reducing the runtime start-up overhead of applications that require many
dependencies, or whose dependencies are expensive to relocate (this may be the case
when shared objects contain position-dependent code).

When alternate objects generated by crle are specified within a configuration file,
ld.so.1(1) performs some minimal consistency verification of the alternative objects
against their originating objects. This verification is intended to avert application
failure should an applications configuration information become out-of-sync with the
underlying system components. When this situation arises the flexibility offered by
dynamic linking system components may be compromised, and diagnosing the
application failure may be difficult. Note: No verification of directory cache
information is performed. Any changes to the directory structure will not be seen by a
process until the cache is rebuilt.

System shared objects are often well tuned and may have no benefit being cached. The
directory cache and alternative object features are typically applicable to user
applications and shared objects.

crle creates alternate objects for the shared objects discovered when using the -I and
-G options by calls to dldump(3DL). The alternate object is created in the directory
specified by the preceding -o option, or defaults to the directory in which the
configuration file is created. The flags used for the dldump() are specified using the
-f option, or default to RTLD_REL_RELATIVE.

OPTIONS The following options are supported:

-64 Specifies to process 64-bit objects, the default is 32-bit.

User Commands 211

crle(1)
-a name This option adds an alternative to name to the
configuration file. The actual alternative file must be
supplied by the user. Multiple occurrences of this
option are permitted. If name is a directory each shared
object within the directory is added to the cache. If
name does not exist, it is marked in the cache as a
nonexistent file.
-c conf Specifies to use the configuration file name conf. If this
option is not supplied the default configuration file is
used.
-e env This option specifies a replaceable environment variable,
env. Only environment variables applicable to the
runtime linker are meaningful. Multiple occurrences of
this option are permitted. This option is similar to the
-E option, but differs in how configuration file
definitions and process environment definitions of the
same name are resolved at runtime.

A definition established in a configuration file can be

overridden by a process environment definition, or be
suppressed by a null-value process environment
definition.

In other words, these configuration file definitions can

be replaced or removed by the process environment at
runtime.
-E env This option specifies a permanent environment variable,
env. Only environment variables applicable to the
runtime linker are meaningful. Multiple occurrences of
this option are permitted. This option is similar to the
-e option, but differs in how configuration file
definitions and process environment definitions of the
same name are resolved at runtime.

Environment variable definitions meaningful to the

runtime linker fall into one of two categories, that is,
singular definitions such as LD_NOLAZYLOAD=1 and
LD_DEBUG_OUTPUT=file, or list definitions which can
take one or more values such as
LD_LIBRARY_PATH=path, and LD_DEBUG=files,details.

A singular definition established in a configuration file

will take precedence over a process environment
definition. A list definition established in a
configuration file will be appended to a process

212 man pages section 1: User Commands • Last Revised 10 Oct 2001
 crle(1)
environment definition. Any definition established in a
configuration file can not be suppressed by a null-value
process environment definition.

In other words, these configuration file definitions can

not be replaced or removed by the process environment
at runtime.
-f flags This option provides the symbolic flags argument to the
dldump(3DL) calls used to generate alternate objects.
Any of the RTLD_REL flags defined in
/usr/include/dlfcn.h can be used. Multiple flags
can be or’ed together using the "|" character, and in
this case the string should be quoted to avoid
expansion by the shell. If no flags values are provided
the default flag is RTLD_REL_RELATIVE.
-i name This option adds an individual name to the
configuration cache. Multiple occurrences of this option
are permitted. name may be a shared object or a
directory. If name is a directory each shared object
within the directory is added to the cache. Note: If name
does not exist, it is marked in the cache as a
nonexistent directory.
-I name This option is the same as -i and in addition any
shared objects have alternatives created via
dldump(3DL). If the -f flag contains RTLD_REL_EXEC
then name may be a dynamic executable, for which an
alternative is created. Only one dynamic executable can
be specified in this manner as the cache created is
specific to this application.
-g name This option adds the group name to the configuration
cache. Each object is expanded to determine its
dependencies. Multiple occurrences of this option are
permitted. name may be a dynamic executable, shared
object or a directory. The name itself, if it is a shared
object, and its dependencies are added to the cache. If
name is a directory each shared object within the
directory, and its dependencies, are added to the cache.
-G name This option is the same as -g and in addition any
shared objects have alternatives created via
dldump(3DL). If name is a dynamic executable, and the
-f flag contains RTLD_REL_EXEC, then an alternative
for the dynamic executable is also created. Only one
dynamic executable can be specified in this manner as
the cache created is specific to this application.

User Commands 213

crle(1)
-l dir This option specifies a new default search directory dir
for ELF or AOUT objects. Multiple occurrences of this
option are permitted. The type of object applicable to
the search is specified by the preceding -t option, or
defaults to ELF.

The system default search path for ELF objects is

/usr/lib for 32-bit objects, and /usr/lib/64 for
64-bit objects. The system default search paths for AOUT
objects is /usr/4lib, /usr/lib and
/usr/local/lib.

Use of this option replaces the system default search

path, and thus it is normally required that a -l option
be used to specify the original system default in
relation to any new paths being applied. However, if
the -u option is in effect, and a configuration file does
not exist, the system defaults are added to the new
configuration file before the new paths specified with
the -l option.
-o dir This option specifies the directory dir in which any
alternate objects must exist (in the case of using the -a
option), or will be created (in the case of alternatives
created by crle). Without this option, alternate objects
will exist in the directory in which the configuration
file is created. Multiple occurrences of this option are
permitted, the directory dir being used to locate
alternatives for any following command-line options.
Alternative objects are not permitted to override their
associated originals.
-s dir This option specifies a new trusted directory dir for
secure ELF or AOUT objects. See SECURITY in
ld.so.1(1) for a definition of secure objects.

Multiple occurrences of this option are permitted. The

type of object applicable to the search is specified by
the preceding -t option, or defaults to ELF.

The system default trusted directory for secure ELF

objects is /usr/lib/secure for 32-bit objects and
/usr/lib/secure/64 for 64-bit objects. The system
default trusted directories for secure AOUT objects are
/usr/4lib, /usr/lib, /usr/ucblib, and
/usr/local/lib.

214 man pages section 1: User Commands • Last Revised 10 Oct 2001
 crle(1)
Use of this option replaces the system default trusted
directories, and thus it is normally required that a -s
option be used to specify the original system default in
relation to any new directories being applied. However,
if the -u option is in effect, and a configuration file
does not exist, the system defaults are added to the new
configuration file before the new directories specified
with the -s option.
-t ELF | AOUT This option toggles the object type applicable to any -l
or -s options that follow. The default object type is
ELF.
-u This option requests that a configuration file be
updated, possibly with the addition of new
information. Without other options any existing
configuration file is inspected and its contents
recomputed. Additional arguments allow information
to be appended to the recomputed contents. See
NOTES.

If a configuration file does not exist it will be created as

directed by the other arguments. In the case of the -l
and -s options any system defaults will first be
applied to the configuration file before the directories
specified with these options.
-v Verbose mode. When creating a configuration file, a
trace of the files being processed is written to the
standard out. When printing the contents of a
configuration file, more extensive directory and file
information is provided.

By default, the runtime linker attempts to read the configuration file

/var/ld/ld.config for each 32-bit application it processes or
/var/ld/64/ld.config for each 64-bit application. When processing an alternative
application, the runtime linker will use a $ORIGIN/ld.config.app-name
configuration file if present (see NOTES). Applications may reference an alternative
configuration file either by setting the LD_CONFIG environment variable (see
ld.so.1(1)), or by recording a configuration file name in the application at the time it
is built using the link-editors -c option (see ld(1)).

EXAMPLES EXAMPLE 1 Update (and display) of a new default search path for ELF objects
example% crle -u -l /local/lib
example% crle

Configuration file [3]: /var/ld/ld.config

Default Library Path (ELF): /usr/lib:/local/lib
Trusted Directories (ELF): /usr/lib/secure (system default)

User Commands 215

crle(1)
EXAMPLE 1 Update (and display) of a new default search path for ELF objects
(Continued)

Command line:
crle -l /usr/lib:/local/lib
example% crle -u -l /usr/local/lib
example% crle

Configuration file [3]: /var/ld/ld.config

Default Library Path (ELF): /usr/lib:/local/lib:/usr/local/lib
Trusted Directories (ELF): /usr/lib/secure (system default)

Command line:
crle -l /usr/lib:/local/lib:/usr/local/lib

In this example, the default configuration file initially did not exist, and thus the new
search path /local/lib is appended to the system default. The next update appends
the search path /usr/local/lib to those already established in the configuration
file.

EXAMPLE 2 Creation (and display) of a new default search path and new trusted directory
for ELF objects
example% crle -l /local/lib -l /usr/lib -s /local/lib
example% crle

Configuration file [2]: /var/ld/ld.config

Default Library Path (ELF): /local/lib:/usr/lib
Trusted Directories (ELF): /local/lib

Command line:
crle -l /local/lib:/usr/lib -s /local/lib

With this configuration, third party applications may be installed in /local/bin and
their associated dependencies in /local/lib. The default search path allows the
applications to locate their dependencies without the need to set LD_LIBRARY_PATH.
Note: The system default trusted directory has been replaced with this example.

EXAMPLE 3 Creation of a directory cache for ELF objects

example% crle -i /usr/dt/lib -i /usr/openwin/lib -i /usr/lib \
-c config
example% ldd -s ./main
....
find object=libc.so.1; required by ./main
search path=/usr/dt/lib:/usr/openwin/lib (RPATH ./main)
trying path=/usr/dt/lib/libc.so.1
trying path=/usr/openwin/lib/libc.so.1
search path=/usr/lib (default)
trying path=/usr/lib/libc.so.1
libc.so.1 => /usr/lib/libc.so.1

example% LD_CONFIG=config ldd -s ./main

216 man pages section 1: User Commands • Last Revised 10 Oct 2001
 crle(1)
EXAMPLE 3 Creation of a directory cache for ELF objects (Continued)

....
find object=libc.so.1; required by ./main
search path=/usr/dt/lib:/usr/openwin/lib (RPATH ./main)
search path=/usr/lib (default)
trying path=/usr/lib/libc.so.1
libc.so.1 => /usr/lib/libc.so.1

With this configuration, the cache reflects that the system library libc.so.1 does not
exist in the directories /usr/dt/lib or /usr/openwin/lib. Therefore, the search
for this system file ignores these directories even though the application’s runpath
indicates they should be searched.

EXAMPLE 4 Creation of an alternative object cache for an ELF executable

example% crle -c /local/$HOST/.xterm/ld.config.xterm \
-f RTLD_REL_ALL -G /usr/openwin/bin/xterm
example% ln -s /local/$HOST/.xterm/xterm /local/$HOST/xterm
example% ldd /usr/local/$HOST/xterm
libXaw.so.5 => /local/$HOST/.xterm/libWaw.so.5 (alternate)
libXmu.so.4 => /local/$HOST/.xterm/libXmu.so.4 (alternate)
....
libc.so.1 => /local/$HOST/.xterm/libc.so.1 (alternate)
....

With this configuration, a new xterm and its dependencies are created. These new
objects are fully relocated to themselves and result in faster start-up than the
originating objects. Note: The execution of this application uses its own specific
configuration file. This model is generally more flexible than using the environment
variable LD_CONFIG, as the configuration file will not be erroneously used by other
applications such as ldd(1) or truss(1).

EXAMPLE 5 Creating an alternative object cache to replace an ELF shared object

example% ldd /usr/bin/vi
libcurses.so.1 => /usr/lib/libcurses.so.1
....

example% crle -a /usr/lib/libcurses.so.1 -o /usr/ucblib

example% crle

Configuration file [3]: /var/ld/ld.config

Default Library Path (ELF): /usr/lib (system default)
Trusted Directories (ELF): /usr/lib/secure (system default)

Directory: /usr/lib
libcurses.so.1 (alternate: /usr/ucblib/libcurses.so.1)
....

example% ldd /usr/bin/vi

libcurses.so.1 => /usr/ucblib/libcurses.so.1 (alternate)
....

User Commands 217

crle(1)
EXAMPLE 5 Creating an alternative object cache to replace an ELF shared object
(Continued)

With this configuration, any dependency that would normally resolve to

/usr/lib/libcurses.so.1 will instead resolve to
/usr/ucblib/libcurses.so.1.

EXAMPLE 6 Setting replaceable and permanent environment variables

example% crle -e LD_LIBRARY_PATH=/local/lib \
-E LD_PRELOAD=preload.so.1
example% crle
.....
Environment Variables:
LD_LIBRARY_PATH=/local/lib (replaceable)
LD_PRELOAD=preload.so.1 (permanent)

.....
example% LD_DEBUG=files LD_PRELOAD=preload.so.2 ./main
.....
18764: file=preload.so.2; preloaded
18764: file=/local/lib/preload.so.2 [ ELF ]; generating link map
.....
18764: file=preload.so.1; preloaded
18764: file=/local/lib/preload.so.1 [ ELF ]; generating link map
.....

With this configuration file, a replaceable search path has been specified together with
a permanent preload object which becomes appended to the process environment
definition.

EXIT STATUS The creation or display of a configuration file results in a 0 being returned; otherwise
any error condition is accompanied with a diagnostic message and a non-zero value
being returned.

NOTES Tagging an alternative application to use an application specific configuration file can
only be achieved if the original application contains one of the .dynamic tags
DT_FLAGS_1 or DT_FEATURE_1. Without these entries any application specific
configuration file must be specified using the LD_CONFIG environment variable. Care
should be exercised with this latter method as this environment variable will be visible
to any forked applications.

The use of the -u option requires at least version 2 of crle. This version level is
evident from displaying the contents of a configuration file:
example% crle

Configuration file [2]: /var/ld/ld.config

......

218 man pages section 1: User Commands • Last Revised 10 Oct 2001
 crle(1)
With a version 2 configuration file, crle is capable of constructing the command-line
arguments required to regenerate the configuration file and to provide full update
capabilities. Although the update of a version 1 configuration file is possible, the
contents of the configuration file may be insufficient for crle to compute the entire
update requirements.
FILES /var/ld/ld.config Default configuration file for 32-bit
applications.
/var/ld/64/ld.config Default configuration file for 64-bit
applications.
/var/tmp Default location for temporary
configuration file (see tempnam(3C)).
/usr/lib/lddstub Stub application employed to dldump(3DL)
32-bit objects.
/usr/lib/64/lddstub Stub application employed to dldump(3DL)
64-bit objects.
/usr/lib/libcrle.so.1 Audit library employed to dldump(3DL)
32-bit objects.
/usr/lib/64/libcrle.so.1 Audit library employed to dldump(3DL)
64-bit objects.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWtoo

SEE ALSO ld(1), ld.so.1(1), dldump(3DL), tempnam(3C), attributes(5)

User Commands 219

crontab(1)
NAME crontab – user crontab file
SYNOPSIS crontab [filename]
crontab [-elr username]

DESCRIPTION The crontab utility manages a user’s access with cron (see cron(1M)) by copying,
creating, listing, and removing crontab files. If invoked without options, crontab
copies the specified file, or the standard input if no file is specified, into a directory
that holds all users’ crontabs.

If crontab is invoked with filename, this will overwrite an existing crontab entry for
the user that invokes it.

crontab Access Users: Access to crontab is allowed:

Control
■ if the user’s name appears in /etc/cron.d/cron.allow.
■ if /etc/cron.d/cron.allow does not exist and the user’s name is not in
/etc/cron.d/cron.deny.

Users: Access to crontab is denied:

■ if /etc/cron.d/cron.allow exists and the user’s name is not in it.
■ if /etc/cron.d/cron.allow does not exist and user’s name is in
/etc/cron.d/cron.deny.
■ if neither file exists, only a user with the solaris.jobs.user authorization is
allowed to submit a job.
■ If BSM audit is enabled, the user’s shell is not audited and the user is not the
crontab owner. This can occur if the user logs in via a program, such as some
versions of SSH, which does not set audit parameters.

Notice that the rules for allow and deny apply to root only if the allow/deny files
exist.

The allow/deny files consist of one user name per line.

crontab Entry A crontab file consists of lines of six fields each. The fields are separated by spaces or
Format tabs. The first five are integer patterns that specify the following:
minute (0−59),
hour (0−23),
day of the month (1−31),
month of the year (1−12),
day of the week (0−6 with 0=Sunday).

Each of these patterns may be either an asterisk (meaning all legal values) or a list of
elements separated by commas. An element is either a number or two numbers
separated by a minus sign (meaning an inclusive range). Notice that the specification
of days may be made by two fields (day of the month and day of the week). Both are
adhered to if specified as a list of elements. See EXAMPLES.

220 man pages section 1: User Commands • Last Revised 19 Apr 2002
 crontab(1)
The sixth field of a line in a crontab file is a string that is executed by the shell at the
specified times. A percent character in this field (unless escaped by \ ) 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. Other lines are made available to the command as standard input. Any blank
line or line beginning with a ‘ # ’ is a comment and will be ignored.

The shell is invoked from your $HOME directory with an arg0 of sh. Users who
desire to have their .profile executed must explicitly do so in the crontab file. cron
supplies a default environment for every shell, defining HOME, LOGNAME,
SHELL(=/bin/sh), TZ, and PATH. The default PATH for user cron jobs is
/usr/bin; while root cron jobs default to /usr/sbin:/usr/bin. The default
PATH can be set in /etc/default/cron (see cron(1M)).

If you do not redirect the standard output and standard error of your commands, any
generated output or errors will be mailed to you.

OPTIONS The following options are supported:

-e Edits a copy of the current user’s crontab file, or creates an empty file to
edit if crontab does not exist. When editing is complete, the file is
installed as the user’s crontab file. If a username is given, the specified user’s
crontab file is edited, rather than the current user’s crontab file; this may
only be done by a user with the solaris.jobs.admin authorization. The
environment variable EDITOR determines which editor is invoked with the
-e option. The default editor is ed(1). Notice that all crontab jobs should be
submitted using crontab. Do not add jobs by just editing the crontab file,
because cron will not be aware of changes made this way.

If all lines in the crontab file are deleted, the old crontab file will be
restored. The correct way to delete all lines is to remove the crontab file via
the -r option.
-l Lists the crontab file for the invoking user. Only a user with the
solaris.jobs.admin authorization can specify a username following the
-r or -l options to remove or list the crontab file of the specified user.
-r Removes a user’s crontab from the crontab directory.

EXAMPLES EXAMPLE 1 Cleaning up core files

This example cleans up core files every weekday morning at 3:15 am:
15 3 * * 1-5 find $HOME -name core 2>/dev/null | xargs rm -f

EXAMPLE 2 Mailing a birthday greeting

0 12 14 2 * mailx john%Happy Birthday!%Time for lunch.

User Commands 221

crontab(1)
EXAMPLE 3 Specifying days of the month and week

This example
0 0 1,15 * 1

would run a command on the first and fifteenth of each month, as well as on every
Monday.

To specify days by only one field, the other field should be set to *. For example:
0 0 * * 1

would run a command only on Mondays.

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of crontab: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.
EDITOR Determine the editor to be invoked when the -e option is
specified. The default editor is vi(1).

EXIT STATUS The following exit values are returned:

0 Successful completion.
>0 An error occurred.
FILES /etc/cron.d main cron directory
/etc/cron.d/cron.allow list of allowed users
/etc/default/cron contains cron default settings
/etc/cron.d/cron.deny list of denied users
/var/cron/log accounting information
/var/spool/cron/crontabs spool area for crontab

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

Interface Stability Standard

SEE ALSO atq(1), atrm(1), auths(1), sh(1), vi(1), cron(1M), su(1M), auth_attr(4),
attributes(5), environ(5), standards(5)

NOTES If you inadvertently enter the crontab command with no argument(s), do not
attempt to get out with Control-d. This removes all entries in your crontab file.
Instead, exit with Control-c.

222 man pages section 1: User Commands • Last Revised 19 Apr 2002
 crontab(1)
If an authorized user modifies another user’s crontab file, resulting behavior may be
unpredictable. Instead, the super-user should first use su(1M) to become super-user to
the other user’s login before making any changes to the crontab file.

When updating cron, check first for existing crontab entries that may be scheduled
close to the time of the update. Such entries may be lost if the update process
completes after the scheduled event. This can happen because, when cron is notified
by crontab to update the internal view of a user’s crontab file, it first removes the
user’s existing internal crontab and any internal scheduled events. Then it reads the
new crontab file and rebuilds the internal crontab and events. This last step takes time,
especially with a large crontab file, and may complete after an existing crontab entry is
scheduled to run if it is scheduled too close to the update. To be safe, start a new job at
least 60 seconds after the current date and time.

User Commands 223

crypt(1)
NAME crypt – encode or decode a file
SYNOPSIS crypt [password]

DESCRIPTION The crypt utility 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:
example% crypt key<clear.file> encrypted.file
example% crypt key<encrypted.file | pr

will print the contents of clear. file.

Files encrypted by crypt are compatible with those treated by the editors ed(1),
ex(1), and vi(1) in encryption mode.

The security of encrypted files depends on three factors: the fundamental method
must be hard to solve; direct search of the key space must be infeasible; “sneak paths”
by which keys or cleartext can become visible must be minimized.

crypt implements a one-rotor machine designed along the lines of the German
Enigma, but with a 256-element rotor. Methods of attack on such machines are widely
known, thus crypt provides minimal security.

The transformation of a key into the internal settings of the machine is deliberately
designed to be expensive, that is, to take a substantial fraction of a second to compute.
However, if keys are restricted to (say) three lower-case letters, then encrypted files
can be read by expending only a substantial fraction of five minutes of machine time.

Since the key is an argument to the crypt command, it is potentially visible to users
executing ps(1) or a derivative command. To minimize this possibility, crypt takes
care to destroy any record of the key immediately upon entry. No doubt the choice of
keys and key security are the most vulnerable aspect of crypt.
FILES /dev/tty for typed key

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

SEE ALSO des(1), ed(1), ex(1), makekey(1), ps(1), vi(1), attributes (5)

224 man pages section 1: User Commands • Last Revised 14 May 1997
 csh(1)
NAME csh – shell command interpreter with a C-like syntax
SYNOPSIS csh [-bcefinstvVxX] [argument…]

DESCRIPTION csh, the C shell, is a command interpreter with a syntax reminiscent of the C
language. It provides a number of convenient features for interactive use that are not
available with the Bourne shell, including filename completion, command aliasing,
history substitution, job control, and a number of built-in commands. As with the
Bourne shell, the C shell provides variable, command and filename substitution.

Initialization and When first started, the C shell normally performs commands from the .cshrc file in
Termination your home directory, provided that it is readable and you either own it or your real
group ID matches its group ID. If the shell is invoked with a name that starts with ‘−’,
as when started by login(1), the shell runs as a login shell.

If the shell is a login shell, this is the sequence of invocations: First, commands in
/etc/.login are executed. Next, commands from the .cshrc file your home
directory are executed. Then the shell executes commands from the .login file in
your home directory; the same permission checks as those for .cshrc are applied to
this file. Typically, the .login file contains commands to specify the terminal type
and environment. (For an explanation of file interpreters, see below "Command
Execution" and exec(2).)

As a login shell terminates, it performs commands from the .logout file in your
home directory; the same permission checks as those for .cshrc are applied to this
file.

Interactive After startup processing is complete, an interactive C shell begins reading commands
Operation from the terminal, prompting with hostname% (or hostname# for the privileged
user). The shell then repeatedly performs the following actions: a line of command
input is read and broken into words. This sequence of words is placed on the history
list and then parsed, as described under USAGE. Finally, the shell executes each
command in the current line.

Noninteractive When running noninteractively, the shell does not prompt for input from the terminal.
Operation A noninteractive C shell can execute a command supplied as an argument on its
command line, or interpret commands from a file, also known as a script.

OPTIONS The following options are supported:

-b Forced a “break” from option processing. Subsequent command line
arguments are not interpreted as C shell options. This allows the passing of
options to a script without confusion. The shell does not run set-user-ID or
set-group-ID scripts unless this option is present.
-c Executes the first argument, which must be present. Remaining arguments
are placed in argv, the argument-list variable, and passed directly to csh.
-e Exits if a command terminates abnormally or yields a nonzero exit status.

User Commands 225

csh(1)
-f Fast start. Reads neither the .cshrc file, nor the .login file (if a login
shell) upon startup.
-i Forced interactive. Prompts for command line input, even if the standard
input does not appear to be a terminal (character-special device).
-n Parses (interprets), but does not execute commands. This option can be
used to check C shell scripts for syntax errors.
-s Takes commands from the standard input.
-t Reads and executes a single command line. A ‘\’ (backslash) can be used to
escape each newline for continuation of the command line onto subsequent
input lines.
-v Verbose. Sets the verbose predefined variable. Command input is echoed
after history substitution, but before other substitutions and before
execution.
-V Sets verbose before reading .cshrc.
-x Echo. Sets the echo variable. Echoes commands after all substitutions and
just before execution.
-X Sets echo before reading .cshrc.

Except with the options -c, -i, -s, or -t, the first nonoption argument is taken to be
the name of a command or script. It is passed as argument zero, and subsequent
arguments are added to the argument list for that command or script.

USAGE

Filename When enabled by setting the variable filec, an interactive C shell can complete a
Completion partially typed filename or user name. When an unambiguous partial filename is
followed by an ESC character on the terminal input line, the shell fills in the remaining
characters of a matching filename from the working directory.

If a partial filename is followed by the EOF character (usually typed as Control-d), the
shell lists all filenames that match. It then prompts once again, supplying the
incomplete command line typed in so far.

When the last (partial) word begins with a tilde (~), the shell attempts completion with
a user name, rather than a file in the working directory.

The terminal bell signals errors or multiple matches. This bell signal can be inhibited
by setting the variable nobeep. You can exclude files with certain suffixes by listing
those suffixes in the variable fignore. If, however, the only possible completion
includes a suffix in the list, it is not ignored. fignore does not affect the listing of
filenames by the EOF character.

226 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
Lexical Structure The shell splits input lines into words at space and tab characters, except as noted
below. The characters &, |, ;, <, >, (, 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 character.

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 A simple command is composed of a sequence of words. The first word (that is not part
Parsing of an I/O redirection) specifies the command to be executed. A simple command, or a
set of simple commands separated by | or |& characters, forms a pipeline. With |, the
standard output of the preceding command is redirected to the standard input of the
command that follows. With | &, 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 | | 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 History substitution allows you to use words from previous command lines in the
Substitution 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 histchars variable) and may occur anywhere on the command line;
history substitutions do not nest. The ! can be escaped with \ to suppress its special
meaning.

User Commands 227

csh(1)
Input lines containing history substitutions are echoed on the terminal after being
expanded, but before any other substitutions 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 substitution, except when
followed by a space character, 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.
!?str? additional Refer to the most recent command
containing str and append additional to that
referenced command.
!{command} additional Refer to the most recent command
beginning with command and append
additional to that referenced command.
^previous_word^replacement^ Repeat the previous command line
replacing the string previous_word with the
string replacement. This is equivalent to the
history substitution:
!:s/previous_word/replacement/.

To re-execute a specific previous command

AND make such a substitution, say,
re-executing command #6,
!:6s/previous_word/replacement/.

Word Designators A ‘:’ (colon) separates the event specification from the word designator. It can be
omitted if the word designator begins with a ^, $, *, − or %. If the word is to be
selected from the previous command, the second ! character can be omitted from the
event specification. For instance, !!:1 and !:1 both refer to the first word of the
previous command, while !!$ and !$ both refer to the last word in the previous
command. Word designators include:
# The entire command line typed so far.

228 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
0 The first input word (command).
n The n’th argument.
^ The first argument, that is, 1.
$ The last argument.
% The word matched by the ?s search.
x−y A range of words; −y abbreviates 0−y.
* All the arguments, or a null value if there is just one word in the event.
x* Abbreviates x−$.
x− Like x* but omitting word $.

Modifiers After the optional word designator, you can add one of the following modifiers,
preceded by a :.
h Remove a trailing pathname component, leaving the head.
r Remove a trailing suffix of the form ‘.xxx’, leaving the basename.
e Remove all but the suffix, leaving the Extension.
s/l/r/ Substitute r for l.
t Remove all leading pathname components, leaving the tail.
& Repeat the previous substitution.
g Apply the change to the first occurrence of a match in each word, by
prefixing the above (for example, g&).
p Print the new command but do not execute it.
q Quote the substituted words, escaping further substitutions.
x Like q, but break into words at each space character, tab or newline.

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 /. 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 l uses the previous
string either from a l 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 ^l^r^ This is equivalent to the history substitution:

User Commands 229

csh(1)
!:s/l/r/.

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 lm ’ls -l \!* | more’

which when called, pipes the output of ls(1) through more(1).

Except 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.

I/O 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.
<
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, the pipeline is invoked
with the temporary file as its 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 /dev/null, unless one of the ! forms is
used. The & forms redirect both standard output and 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

230 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
one of the ! forms is used. The & forms append both the standard error and
standard output to the file.

Variable The C shell maintains a set of variables, each of which is composed of a name and a
Substitution 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.

To refer to a variable’s value, precede its name with a ‘$’. Certain references (described
below) can be used to select specific words from the value, or to display other
information about the variable. Braces can be used to insulate the reference from other
characters in an input-line word.

Variable substitution takes place after the input line is analyzed, aliases are resolved,
and I/O redirections are applied. Exceptions to this are variable references in I/O
redirections (substituted at the time the redirection is made), and backquoted strings
(see Command Substitution).

Variable substitution can be suppressed by preceding the $ with a \, except within

double-quotes where it always occurs. Variable substitution is suppressed inside of
single-quotes. A $ is escaped if followed by a space character, tab or newline.

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 @ built-in command).
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 space
characters. 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 are replaced by words from the value of var, each separated
by a space character. If var is an environment variable, its value is
returned (but ‘:’ modifiers and the other forms given below are
not available).

User Commands 231

csh(1)
$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 except for setuid shell scripts. An error occurs if the
name is not known.
$n
${n} Equivalent to $argv[n].
$* Equivalent to $argv[*].

The modifiers :e, :h, :q, :r, :t, and :x can be applied (see History
Substitution), as can :gh, :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 1 if var is set or 0 if it is not set.
$?0 Substitutes 1 if the current input filename is known or 0 if it is not.
$$ Substitutes 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 Command and filename substitutions are applied selectively to the arguments of
Filename built-in commands. Portions of expressions that are not evaluated are not expanded.
Substitutions For non-built-in 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 A command enclosed by backquotes ( ‘ . . . ‘ ) is performed by a subshell. Its standard

Substitution output is broken into separate words at each space character, tab and newline; null
words are discarded. This text replaces the backquoted string on the current command

232 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
line. Within double-quotes, only newline characters 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 Unquoted words containing any of the characters *, ?, [ or {, or that begin with ~, are
Substitution 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
dash (−), and includes all the characters in between in the ASCII
collating sequence (see ascii(5)).
{ str, str, . . . } 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.
~[user] 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 pathname component, must be matched explicitly. The
/ (slash) must also be matched explicitly.

Expressions and A number of C shell built-in commands accept expressions, in which the operators are
Operators 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 is a string, which
may represent decimal numbers.

The following C shell operators are grouped in order of precedence:

( ... ) grouping
>~ one’s complement
! logical negation

User Commands 233

csh(1)
* / % multiplication, division, remainder. These are right
associative, which can lead to unexpected results.
Combinations should be grouped 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)
| bitwise inclusive OR
&& logical AND
| | logical OR

The operators: ==, !=, =~, and !~ compare their arguments as strings; other operators
use numbers. The operators =~ 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 filename Return true, or 1 if the user has read access. Otherwise it returns
false, or 0.
-w filename True if the user has write access.
-x filename True if the user has execute permission (or search permission on a
directory).
-e filename True if filename exists.
-o filename True if the user owns filename.
-z filename True if filename is of zero length (empty).
-f filename True if filename is a plain file.
-d filename True if filename is a directory.

If filename does not exist or is inaccessible, then all inquiries return false.

An inquiry as to the success of a command is also available:

234 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
{ command } If command runs successfully, the expression evaluates to true, 1.
Otherwise, it evaluates to false, 0. Note: Conversely, command 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 built-in
command must appear as the first word on its own input line.

If the shell’s input is not seekable and a loop is being read, 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 If the command is a C shell built-in command, the shell executes it directly. Otherwise,
Execution 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 built-in command) to eliminate directories that
have no applicable files. This hashing can be disabled with the -c or -t, options, or
the unhash built-in command.

As a special case, if there is no / 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 pathname 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( )
system call (see exec(2)). The kernel then attempts to overlay the new process with
the desired program. If the file is an executable binary (in a.out(4) format) 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 and the
execve( ) call fails (see exec(2)). The C shell 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 Bourne shell is invoked.

User Commands 235

csh(1)
Signal Handling The shell normally ignores QUIT signals. Background jobs are immune to signals
generated from the keyboard, including hangups (HUP). 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 built-in command.
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 Control-z). When a command 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:
[1] 1234

To see the current list of jobs, use the jobs built-in command. The job most recently
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 % built-in commands.

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;
‘fg %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 the job finishes or becomes blocked. It normally displays a message to this
effect as it issues a prompt, in order to avoid disturbing the appearance of your input.
When set, the notify variable indicates that the shell is to report status changes
immediately. By default, the notify command marks the current process; after
starting a background job, type notify to mark it.

236 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
Commands Built-in commands are executed within the C shell. If a built-in command occurs as
any component of a pipeline except the last, it is executed in a subshell.
:
Null command. This command is interpreted, but performs no action.
alias [ name [ def ] ]
Assign def to the alias name. def is a list of words that may contain escaped
history-substitution metasyntax. name is not allowed to be alias or unalias. If
def is omitted, the current definition for the alias name is displayed. If both name and
def are omitted, all aliases are displayed with their definitions.
bg [ %job . . . ]
Run the current or specified jobs in the background.
break
Resume execution after the end of the nearest enclosing foreach 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 dir. 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.
continue
Continue execution of the next iteration of the nearest enclosing while or foreach
loop.
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.
dirs [-l]
Print the directory stack, most recent to the left. The first directory shown is the
current directory. With the -l 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 space
characters. The output is terminated with a newline unless the -n option is used.
csh will, by default, invoke its built-in echo, if echo is called without the full
pathname of a Unix command, regardless of the configuration of your PATH (see
echo(1)).

User Commands 237

csh(1)
eval argument . . .
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. See tset(1B) for an example of how to use eval.
exec command
Execute command in place of the current shell, which terminates.
exit [(expr)]
The calling shell or shell script exits, either with the value of the status variable or
with the value specified by the expression expr.
fg [%job ]
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 built-in command continue may be used to terminate the execution of the
current iteration of the loop and the built-in command break may be used to
terminate execution of the foreach command. When this command is read from
the terminal, the loop is read once prompting with ? 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 a filename and a 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. It is an error to jump to a label that occurs between a while or for
built-in command and its corresponding end.
hashstat
Print a statistics line indicating how effective the internal hash table for the path
variable 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 ‘/’. These statistics
only reflect the effectiveness of the path variable, not the cdpath variable.
history [-hr] [ n ]
Display the history list; if n is given, display only the n most recent events.
-r Reverse the order of printout to be most recent first rather than oldest
first.

238 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
-h 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: 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
...
else
...
endif
If expr is true, commands up to the first 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 [-l]
List the active jobs under job control.
-l List process IDs, in addition to the normal information.
kill [ -sig ] [ pid ] [ %job ] . . .
kill -l
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 (hangup), then the job or
process is sent a CONT (continue) signal as well.
-l List the signal names that can be sent.
limit [-h] [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. Run the sysdef(1M) command to
obtain the maximum possible limits for your system. The values reported are in
hexadecimal, but can be translated into decimal numbers using the bc(1)
command.
-h Use hard limits instead of the current limits. Hard limits impose a
ceiling on the values of the current limits. Only the privileged user may
raise the hard limits.

resource is one of:

User Commands 239

csh(1)
cputime Maximum CPU seconds per process.
filesize Largest single file allowed. Limited to the size of the
filesystem. (See df(1M)).
datasize (heapsize) Maximum data size (including stack) for the
process. This is the size of your virtual memory See
swap(1M).
stacksize Maximum stack size for the process. See swap(1M).
coredumpsize Maximum size of a core dump (file). This limited to
the size of the filesystem.
descriptors Maximum number of file descriptors. Run
sysdef().
memorysize Maximum size of virtual memory.

max-use is a number, with an optional scaling factor, as follows:

nh Hours (for cputime).
nk n kilobytes. This is the default for all but cputime.
nm n megabytes or minutes (for cputime).
mm:ss Minutes and seconds (for cputime).

Example of limit: to limit the size of a core file dump to 0 Megabytes, type the
following:
limit coredumpsize 0M

login [username | -p ]
Terminate a login shell and invoke login(1). The .logout file is not processed. If
username is omitted, login prompts for the name of a user.
-p Preserve the current environment (variables).
logout
Terminate a login shell.
nice [+n |-n ] [command ]
Increment the process priority value for the shell or for command by n. The higher
the priority 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 process
priority value to 4. The range of process priority 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 Increment the process priority value by n.
-n Decrement by n. This argument can be used only by the privileged user.

240 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
nohup [command ]
Run command with HUPs ignored. With no arguments, ignore HUPs throughout the
remainder of a script. When given, command is always run in a subshell, and the
restrictions placed on commands in simple if statements apply. All processes
detached with & are effectively nohup’d.
notify [%job] . . .
Notify the user asynchronously when the status of the current job or specified jobs
changes.
onintr [−| 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 ]
Pop the directory stack and cd 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 |dir]
Push a directory onto the directory stack. With no arguments, exchange the top two
elements.
+n Rotate the n’th entry to the top of the stack and cd to it.
dir Push the current working directory onto the stack and change to dir.
rehash
Recompute the internal hash table of the contents of directories listed in the path
variable to account for new commands added. Recompute the internal hash table of
the contents of directories listed in the cdpath variable to account for new directories
added.
repeat count command
Repeat command 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 A single word (or quoted string).
(wordlist) 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.

User Commands 241

csh(1)
setenv [VAR [word ] ]
With no arguments, setenv displays all environment variables. With the VAR
argument, setenv 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.

The environment variables LC_CTYPE, LC_MESSAGES, LC_TIME, LC_COLLATE,

LC_NUMERIC, and LC_MONETARY take immediate effect when changed within the
C shell.

If any of the LC_* variables (LC_CTYPE, LC_MESSAGES, LC_TIME, LC_COLLATE,

LC_NUMERIC, and LC_MONETARY) (see environ(5)) are not set in the environment,
the operational behavior of csh for each corresponding locale category is
determined by the value of the LANG environment variable. If LC_ALL is set, its
contents are used to override both the LANG and the other LC_* variables. If none
of the above variables is set in the environment, the "C" (U.S. style) locale
determines how csh behaves.
LC_CTYPE Determines how csh handles characters. When LC_CTYPE is
set to a valid value, csh can display and handle text and
filenames containing valid characters for that locale.
LC_MESSAGES Determines how diagnostic and informative messages are
presented. This includes the language and style of the messages
and the correct form of affirmative and negative responses. In
the "C" locale, the messages are presented in the default form
found in the program itself (in most cases, U.S./English).
LC_NUMERIC Determines the value of the radix character (decimal point (".")
in the "C" locale) and thousand separator (empty string ("") in
the "C" locale).
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 source commands.
-h Place commands from the file name on the history list without executing
them.

242 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
stop %jobid . . .
Stop the current or specified background job.
stop pid . . .
Stop the specified process, pid. (see ps(1)).
suspend
Stop the shell in its tracks, much as if it had been sent a stop signal with ^Z. This is
most often used to stop shells started by su.
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. As of this writing, the time built-in command does NOT compute the last 6
fields of output, rendering the output to erroneously report the value "0" for these
fields.
example %time ls -R
9.0u 11.0s 3:32 10% 0+0k 0+0io 0pf+0w

(See below the "Environment Variables and Predefined Shell Variables" sub-section
on the time variable.)
umask [value ]
Display the file creation mask. With value, set the file creation mask. With value
given in octal, the user can turn off any bits, but cannot turn on bits to allow new
permissions. Common values include 077, restricting all permissions from everyone
else; 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 *’.

User Commands 243

csh(1)
unhash
Disable the internal hash tables for the path and cdpath variables.
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 privileged 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
Remove variable from the environment. As with unset, pattern matching is not
performed.
wait
Wait for background jobs to finish (or for an interrupt) before prompting.
while (expr)
...
end
While expr is true (evaluates to nonzero), 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 terminal, it prompts for commands with a
question-mark until the end command is entered and then performs the commands
in the loop.
% [job ] [&]
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, set
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 |, then at least this part of expr
must be placed within parentheses.

The operators *=, +=, and so forth, 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.

244 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
Environment Unlike the Bourne shell, the C shell maintains a distinction between environment
Variables and variables, which are automatically exported to processes it invokes, and shell
Predefined Shell variables, which are not. Both types of variables are treated similarly under variable
Variables
substitution. The shell sets the variables argv, cwd, home, path, prompt, shell, and
status upon initialization. The shell copies the environment variable USER into the
shell variable user, TERM into term, and HOME into home, 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 ‘.o’.
filec Enable filename completion, in which case the Control-d character
EOT and the ESC character have special significance when typed in
at the end of a terminal input line:
EOT Print a list of all filenames that start with the preceding
string.
ESC 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 (^) for
quick substitutions.
history The number of lines saved in the history list. A very large number
may use up all of the C shell’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.
ignoreeof If set, the shell ignores EOF from terminals. This protects against
accidentally killing a C shell by typing a Control-d.

User Commands 245

csh(1)
mail A list of files where the C shell checks for mail. If the first word of
the value is a number, it specifies a mail checking interval in
seconds (default 5 minutes).
nobeep Suppress the bell during command completion when asking the C
shell to extend an ambiguous filename.
noclobber Restrict 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.
nonomatch Return 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 (/usr/bin .). One
may override this initial search path upon csh start-up by setting
it in .cshrc or .login (for login shells only). 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 ($?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 privileged user.

The setting of $prompt has three meanings:

$prompt not set non-interactive shell, test
$?prompt.
$prompt set but == "" .cshrc called by the which(1)
command.
$prompt set and != "" normal interactive shell.

246 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
savehist The number of lines from the history list that are saved in
~/.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. Built-in
commands that fail return exit status 1; all other built-in
commands set status to 0.
time Control 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.
%I 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.
%O 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, %I, %O, %F, and %W tags, in that order.
verbose Display each command after history substitution takes place.

User Commands 247

csh(1)
Large File See largefile(5) for the description of the behavior of csh when encountering files
Behavior greater than or equal to 2 Gbyte (231 bytes).
FILES ~/.cshrc Read at beginning of execution by each shell.
~/.login Read by login shells after .cshrc at login.
~/.logout Read by login shells at logout.
~/.history Saved history for use at next login.
/usr/bin/sh The Bourne shell, for shell scripts not starting with a
‘#’.
/tmp/sh* Temporary file for ‘<<’.
/etc/passwd Source of home directories for ‘~name’.

ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWcsu

CSI Enabled

SEE ALSO bc(1), echo(1), login(1), ls(1), more(1), ps(1), sh(1), shell_builtins(1),
tset(1B), which(1), df(1M), swap(1M), sysdef(1M), access(2), exec(2), fork(2),
pipe(2), a.out(4), environ(4), ascii(5), attributes(5), environ(5),
largefile(5), termio(7I)
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.

WARNINGS The use of setuid shell scripts is strongly discouraged.

NOTES Words can be no longer than 1024 bytes. The system limits argument lists to 1,048,576
bytes. However, the maximum number of arguments to a command for which
filename expansion applies is 1706. Command substitutions may expand to no more
characters than are allowed in the argument list. To detect looping, the shell restricts
the number of alias substitutions on a single line to 20.

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 built-in functions are not stoppable/restartable. 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.

248 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csh(1)
Control over terminal output after processes are started is primitive; use the Sun
Window system if you need better output control.

Commands within loops, prompted for by ?, are not placed in the history list.

Control structures should be parsed rather than being recognized as built-in

commands. This would allow control commands to be placed anywhere, to be
combined with |, 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.

The g (global) flag in history substitutions applies only to the first match in each word,
rather than all matches in all words. The common text editors consistently do the latter
when given the g flag in a substitution command.

Quoting conventions are confusing. Overriding the escape character to force variable
substitutions within double quotes is counterintuitive and inconsistent with the
Bourne shell.

Symbolic links can fool the shell. Setting the hardpaths variable alleviates this.

It is up to the user to manually remove all duplicate pathnames accrued from using
built-in commands as
set path = pathnames

or
setenv PATH = pathnames

more than once. These often occur because a shell script or a .cshrc file does
something like
‘set path=(/usr/local /usr/hosts $path)’

to ensure that the named directories are in the pathname list.

The only way to direct the standard output and standard error separately is by
invoking a subshell, as follows:
command > outfile ) >& errorfile

Although robust enough for general use, adventures into the esoteric periphery of the
C shell may reveal unexpected quirks.

If you start csh as a login shell and you do not have a .login in your home
directory, then the csh reads in the /etc/.login.

When the shell executes a shell script that attempts to execute a non-existent
command interpreter, the shell returns an erroneous diagnostic message that the shell
script file does not exist.

User Commands 249

csh(1)
BUGS As of this writing, the time built-in command does NOT compute the last 6 fields of
output, rendering the output to erroneously report the value "0" for these fields:
example %time ls -R
9.0u 11.0s 3:32 10% 0+0k 0+0io 0pf+0w

250 man pages section 1: User Commands • Last Revised 19 Aug 2002
 csplit(1)
NAME csplit – split files based on context
SYNOPSIS csplit [-ks] [-f prefix] [-n number] file arg1… argn

DESCRIPTION The csplit utility reads the file named by the file operand, writes all or part of that
file into other files as directed by the arg operands, and writes the sizes of the files.

OPTIONS The following options are supported:

-f prefix Names the created files prefix00, prefix01, . . . , prefixn. The default
is xx00 . . . xxn. If the prefix argument would create a file name
exceeding 14 bytes, an error results. In that case, csplit exits
with a diagnostic message and no files are created.
-k Leaves previously created files intact. By default, csplit removes
created files if an error occurs.
-n number Uses number decimal digits to form filenames for the file pieces.
The default is 2.
-s Suppresses the output of file size messages.

OPERANDS The following operands are supported:

file The path name of a text file to be split. If file is -, the standard
input will be used.

The operands arg1 . . . argn can be a combination of the following:

/rexp/[offset] Create a file using the content of the lines from the current line up
to, but not including, the line that results from the evaluation of
the regular expression with offset, if any, applied. The regular
expression rexp must follow the rules for basic regular expressions.
The optional offset must be a positive or negative integer value
representing a number of lines. The integer value must be
preceded by + or −. If the selection of lines from an offset
expression of this type would create a file with zero lines, or one
with greater than the number of lines left in the input file, the
results are unspecified. After the section is created, the current line
will be set to the line that results from the evaluation of the regular
expression with any offset applied. The pattern match of rexp
always is applied from the current line to the end of the file.
%rexp%[offset] This operand is the same as /rexp/[offset], except that no file will
be created for the selected section of the input file.
line_no Create a file from the current line up to (but not including) the line
number line_no. Lines in the file will be numbered starting at one.
The current line becomes line_no.
{num} Repeat operand. This operand can follow any of the operands
described previously. If it follows a rexp type operand, that
operand will be applied num more times. If it follows a line_no

User Commands 251

csplit(1)
operand, the file will be split every line_no lines, num times, from
that point.

An error will be reported if an operand does not reference a line between the current
position and the end of the file.

USAGE See largefile(5) for the description of the behavior of csplit when encountering
files greater than or equal to 2 Gbyte (231 bytes).

EXAMPLES EXAMPLE 1 Splitting and combining files

This example creates four files, cobol00 . . . cobol03.

example% csplit -f cobol filename ’/procedure division/’ /par5./ /par16./

After editing the ‘‘split’’ files, they can be recombined as follows:

example% cat cobol0[0−3] > filename

Note: This example overwrites the original file.

EXAMPLE 2 Splitting a file into equal parts

This example splits the file at every 100 lines, up to 10,000 lines. The -k option causes
the created files to be retained if there are less than 10,000 lines; however, an error
message would still be printed.
example% csplit -k filename 100 {99}

EXAMPLE 3 Creating a file for separate C routines

If prog.c follows the normal C coding convention (the last line of a routine consists
only of a } in the first character position), this example creates a file for each separate
C routine (up to 21) in prog.c.
example% csplit -k prog.c ’%main(%’ ’/^}/+1’ {20}

ENVIRONMENT See environ(5) for descriptions of the following environment variables that affect the
VARIABLES execution of csplit: LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, and
NLSPATH.

EXIT STATUS The following exit values are returned:

0 Successful completion.
>0 An error occurred.

252 man pages section 1: User Commands • Last Revised 20 Dec 1996
 csplit(1)
ATTRIBUTES See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Availability SUNWesu

CSI Enabled

Interface Stability Standard

SEE ALSO sed(1), split(1), attributes(5), environ(5), largefile(5), standards(5)

DIAGNOSTICS The diagnostic messages are self-explanatory, except for the following:
arg − out of range The given argument did not reference a line between
the current position and the end of the file.

User Commands 253

ct(1C)
NAME ct – spawn login to a remote terminal
SYNOPSIS ct [options] telno…

DESCRIPTION The ct utility dials the telephone number of a modem that is attached to a terminal
and spawns a login process to that terminal. The telno is a telephone number, with
equal signs for secondary dial tones and minus signs for delays at appropriate places.
(The set of legal characters for telno is 0 through 9, -, =, *, and #. The maximum length
telno is 31 characters). If more than one telephone number is specified, ct will try each
in succession until one answers; this is useful for specifying alternate dialing paths.

ct will try each line listed in the file /etc/uucp/Devices until it finds an available
line with appropriate attributes, or runs out of entries.

After the user on the destination ter