800 1108 01E_System_Interface_Manual_for_the_Sun_Workstation_Jan84 01E System Interface Manual For The Sun Workstation Jan84

800-1108-01E_System_Interface_Manual_for_the_Sun_Workstation_Jan84 manual pdf -FilePursuit

800-1108-01E_System_Interface_Manual_for_the_Sun_Workstation_Jan84 800-1108-01E_System_Interface_Manual_for_the_Sun_Workstation_Jan84

User Manual: 800-1108-01E_System_Interface_Manual_for_the_Sun_Workstation_Jan84

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

Download800-1108-01E_System_Interface_Manual_for_the_Sun_Workstation_Jan84 800-1108-01E System Interface Manual For The Sun Workstation Jan84
Open PDF In BrowserView PDF
Part Number 800-1108-01
Revision: E of 7th January 1984
For: Sun System ReleaSe 1.1

System Interface Manual
for the

Sun Workstation

Sun Microsystems, Inc.,
2S50 Garcia Avenue
Mountain View
California 94043
(415) 960-1300

Credits and Acknowledgements

This manual is composed of parts of the original UNIX Programmer's Manual, plus two other
papers from University 01 California at Berkeley. The authors' names and the titles 01 the original works appear here.
Interprocel' Communication Primer
is based on the document 4.eb,tllnter,roce" Communication, Primer by Samuel J. Lemel',
Robert S. Fabry and William N. Joy, of the Computer Systems Research Group, U.C.
Berkeley.
S"lfem Inter/ace Overview
is based on the -I.eBSD SIIItem Inter/ace Overview by William Joy, Eric Cooper, Robert
Fabry, Samuel Leffier, Kirk McKusick and David Mosher; released by the Computer Systems Research Group at U.C. Berkeley in July, Ig83.

Trademark. '
Multibus is a trademark of Intel Corporation.
Sun Workstation is a trademark of Sun Microsystems Incorporated.
UNIX is a trademark of Bell Laboratories.
Copyright © 1gS3 by SUD Microsystems.
This publication is protected by Federal Copyright Law, with all rights rese"ed. No part of
this publication may be reproduced, stored in a retrieval system, translated, transcribed, or
transmitted, in any form, or by any means manual, electric, electronic, electro-magnetic,
mechanical, chemical, optical, or otherwise, without prior explicit written permission from SUD
Microsystems.

- ii -

Revision History

Revision

Date

Comments

A

23 February 1983

B

15 April 1983

Second Release 01 this manual involved many corrections to
manual pages.

C

I August 1983

Third Release 01 this manual involved many corrections to
manual pages. Added glossary 01 system calls and system
error responses.

D

I November 1983

Fourth Release 01 this manual involved many corrections to
manual pages. Fixed numerous incorrect cross-relerences
between pages. Added a SII,tem Interface Overview and the
Interproce., Communication Primer as a tutorial.

E

7 January 1984

Filth Release 01 this manual involved many corrections to
manual pages.

First release 01 this Manual.

- iii -

System Interface Manual
Table of Contents

Section I. Overview·
System Interface Overview
Summarizes the facilities provided by the this release of the UNIX operating system
for the Sun Workstation.

Section D. Reference Manual Pages
1. System Calls - previously section 2 of the UNIX Programmer's Manual.
2. C Library Functions - section 3.
3. Compatibility Functions - section 3C. Covers those functions which are included
for compatibility with older versions of the C Library.
4. Mathematical Functions - section 3M.
5. Network Library Functions - section 3N.
6. Standard I/O Library Functions - section as.
7. Miscellaneous Library Functions - section ax.
8. Special Files and Hardware Support - section 4.
o. File Formats - section 5.

Section m. Tutorials
Interprocess Communication (IPC) Primer

PERMUTED INDEX
geUa ble( SC)
getta.ble - get NIC format host tablell from a hOllt
• • • • • • •
newsrc(S)
information file for readnewlI(1) and checknfws(1)
newarcnice(l)
no~,p - rua a command at low priority (lIh only)
nice,
•••••
which(l}
prol~m file iaciuding aliasee and paths (cllh only) . which - locate a
••••
@: arithmetic on shell variables.
csh(l)
. • • • • sh(l)
login, newgrp. read,! sh, for, case, if, while, :, " break, continue, cd, eval, exec, exit, export.
newsrc(S)
•••••••••••••
- informa.tion file for readnewlI(l) and chechewlI( 1). newsrc
newsrc(S)
• ••••••••
newlrc - information file for readnews( 1) and checknew8(1).
vp(iS)
interface. vp - Ikon 10071-5 Multibus Versatec parallel printer
tm(4S)
• •••••
tm - tape master 1/2 inch tape drive.
ar(4S)
lor - Archive 1/4 inch Streaming Ta.pe Drive.
m~ti(4S)
mti - Syatech MTI-800/ 1600 multi-terminal interface.
tm(4S)
•••••
tm - tapemallter 1/ 2 inch tape drive.
ip(4S)
••••••••
ip - Disk driver for Interphase 2180 SMD Disk Controller.
vpc(4S)
printer interface. vpc - Syatech VPC- 2200 Versa.tec printer/plotter and Centronics
•••••
ec(4S)
ec - SCom 10 Mb/8 Ethernet interface.
•••••••
ar(4S)
ar - Archive 1/ 4 inch Streaming Tape Drive.
st(4S}
n - Driver for Sysgen SC 4000 (Archive) Tape Controller. • • • • • •
vp(4S)
vp - Ikon 10071· 5 Multibus Versatec pa.rallel printer interface.
sd(4S)
lid - Diek driver for Adaptec ST- 506 Disk Controllers. • • • • • • • •
mti(4S)
•••••
mti - SYlltech MTI- 800/1600 multi-terminal interface,
Is(4S)
III -lilog 8530 SCC aerial comunicationa driver.
abort(3)
abon - generate a fault,
•••••••••
abort(3F}
abort - terminate abruptly with memory image.
index(3F}
index, rindex, Inblnk, len - tell about character objectl. ••
getrnsage(2)
getrulllce - get information about rellource utilisation.
vtimes(3C)
vtime. - get information about relource utililation.
fstab(S)
• • • •
fstab - IIta.tic information about. the filesysteml.
abort(3F}
&bon - termina.te abruptly with memory image.
abs(3)
abl - integer ablolute value.
abs(a)
&bl - integer ablolute value. • • • • • • • • •
floor(3M)
fab., 800r, ceil - ablolute value, floor, ceiling functionl.
ac(S)
ac - login a.ccounting. • • • . • • • •
accept(2)
accept. - accept a connection on a locket.
accept(2)
&capt - accept a connection on a 80cket.
access(3F)
accellll - determine accellllability of a file.
access(2)
accell - determine accessibility of file.
getgroups(2)
getgroup. - get group &cceSI list.
i nitgro u ps( 3)
initgroup. - initialise group accel. list. • • • • • • •
setgroups(2)
letgroupl - let group accellll list. • • • • •
access(3F)
&ccee. - determine access ability of a file.
access(2)
accea. - determine acceslibility of file.
ac(S)
&C - login accounting.
sa.(S)
•••••
la., &ccton - Iystem accounting.
acct(5)
&cct - execution accounting file. •••
pac(S)
p&c - printer/plotter accounting information.
acct(2)
• • • •
acct - turn accounting on or off.
acct(5)
acct - execution accounting file.
acct(2)
acct - turn accounting on or off.
sa.(S)
•
sa, acctoD - .ystem accounting.
sin(3M)
lin, COli, taD, asin, acos, lotan, atan2 - trigonometric functions.
aignal(3F)
•••••••
ligna.l - change the action for .. sipal.
eact(l)
.act - print current SCCS file editing activity. • • • • • • • • • • • •
• •••••••••••
fortune(6)
fonu •• - pri.t a random, hopefully intereltinl, adage.
ad(4S)
.d - Di.k driver for Adaptec ST-506 Dillk Controllers,
adb(l)
ad b - debugger.
••••••.•
• • • • • '. • • • •
• • • • • adbgen(S)
adb,en - genen.te adb IICript.
adbgen(S)
••••••••
a.dbgen - generate .. db script.
awapon(2)
lIWapon - add a swap device for interleaved paging/swapping.
add bib - create or extend bibliographic database.
addbib(l)
•••••••••••••••
adduser(S)
add user - procedure for addinl new users.
•
swapon(S)
swapon - Ipecify additiona.l device for pa.ging and nrappinl.
• inet(3N)
inetJna.of, inet_netof, inet_ntoa - Internet addrell8 manipulation. /inet_network, inet_maJceaddr,
••••••••
loc(3F)
loe - return the addrells of an object.
addresll resolution display a.nd control.
arp(SC)
alp a.rp(4P)
Addrells Resolution Protocol.
alp •••.•••
mailaddr(7)
mailaddr - mail addreslling description.
adduser(S)
add user - procedure for adding new users. •••
adjacentscreens(l)
physical relationshiplI of IIcreens. adjacent screens - notify the window driver of the
admin(l)
admin - create and administer SCCS files.
admin(l)
admin - create and administer SCCS files.
adventure - an exploration game.
adventure(6)

SUD System Release 1.1

. i-

Jan uary 1Q84

Permuted /rades
va.dvise - give
80ck - apply or remove aD
yeJ - be repetitively
baseDame - strip fileDame
bi! - mail
time.
unalial: remove
which - locate a program file indudins
Dewaliases - rebuild the data base for the mail
aliase. valloe malloc, free, realloc, calloc, elree,
free, realloc, calloe, elree, &lloca - memory
valloe - aliped memory
eyace - modified yace
imemte.t - .tand
pte.t - Itand
dias - General-purpose staad·
lcandir,
limit:
reniee el ••:
lex - senerator of lexical
error aDalyse - Vinual UNIX pOltmortem eruh
WOrmi raiD bcd ~ conven to
exit - terminate a procell &fter IUlhiDS
lock -

number - convert
besraphiel/ opeD pi, erase, label, line, circle,
cpio - format of epio
arartar - tape
arIt - Driver for SysgeD SC 4000 (
tar -. tape
cpio ,- copy file
ranlib - cODvert
w - who ie OD and what they
usell - compact list of usen who
Slob: filename expaDd
shift: maaipulate
varars. - variable
echo: echo
echo - echo
getars, iarlc - returD command liDe
expr - evaluate
getopt, optarg, optiDd - get ,option letter from
mout, pow, lcd, rpow - multiple precisioD iDteser
bc '. arbitra.ry-precillion

0:
news - USENET network news
expire - remove outdated .news
iDews - submit Dews
postDews - submit DeWI
readDewe - read newl
recDewe - receive uDprocessed
recDews - receive unprocessed
sendDews - seDd DeWI
uurec - receive processed DeWI

Ja.nua.ry 1984

vadvile(2)
flock(2)
yee(l)
ba.ename( 1)

advice to pagiDI system.
advisory lock on an OpeD file.
affirmative.
•••••••
atrlXel;.
•••••••••

al&l1lL-

••••••••••••

• •

bi~l)

alarm(3F)
alarm - execute a subroutine after a epecified
alarm(3C)
alarm - schedule signal after specified time.
clh(l)
alias: Ihell macrol.
••••••
csh(l)
alias e..
•••••••••••
aliuee(5)
alias.. - aliu.. file for eeDdmailo
which(l)
aliases aad pathl (ah only).
llewaliases(8)
aliase. file. • • • • • • • •
aliase. file for eeDdmail. , • •
aliaaes(S)
valloc(3)
aliped memory allocator.
m&l10c(3)
alloca - memory allocator.
malloc(3)
allocator. malloc,
valloc(3)
allocator.
•••••••••••
ey&Cc(l)
allowiDI much improved error recovery.
imemtest(Sa)
alone memory test. • • • • • • • • • •
ptest(8s)
alone telt for the Sun video graphicl board.
dia.g(8s)
alone utility package. • • • • • • • •
alphuon - .can a directory. • • • • •
Ica.ndir(3)
alter per-procell resource limitation•.
csh(l)
alter priority of fUnninl procellel.
reniee(8)
alterDative command..
•••••••
cah{l)
analYli. programl.
•••••••••••••••
lex(l)
aaalYle - Virtual UNIX postmortem crash aDalYler.
analYIe(S)
analYle and dilpene compiler error mell&leJ.
errore!)
•••••• •••••••
aDalYler.
analYIe(8)
animate worm. on a display terminal.
worma(S)
animated raindropl display. • • • • •
fain(S)
aDtique media. • • • • • • • • • • •
bcd(S)
aDy peDdinl output.
••••••••
exit(S)
a.out - ulembler and liDk editor output.
••
a.out(S)
apply or remove an advisory lock on an open file.
lock(2)
ar - Archive 1/4 iDch Streaming Tape Drive.
ar(4S)
ar - archive and library maiDtainer.
ar(l)
lor - archive (library) file format. • • • • • •
ar(S)
Arabic numerall to Englilh. • • • • • • • •
number(S)
arbitrary-precilion arithmetic tucuase.
• • • • • • bC(I)
arc, move, CODt, point, liDemod, Ipace, dOlepl plot(SX)
archive. • • • • • • • • • • • • • • •
cpio(S)
Archive 1/4 inch Streaminl Tape Drive.
ar(4S)
archive aDd library maiDtainer.
a.r(l)
archive file format.
tar(S)
archive (library) file format.
ar(S)
Archive) Tape CODtroller.
st(4S)
archiver.
• •••••••
tar(l)
archivel iD .. Dd out.
cpio(l)
archives to random libraries.
ranlib(l)
are doiDI.
w{l)
are OD the system.
usenl(l)
argument list.
csh(l)
argumeDt list.
csh(l)
argumeDt lilt.
vararga(3)
argumeDt •.
csh(l)
arguments.
echo(l)
argumeDtl.
• ••••••
letarg(3F)
argumeDtI as aD expressioD.
expr(l)
argv.
• •••••••••••••••••
getopt(SC)
arithmetic. itom, m&dd, msub, mult, mdiv, mi.,
mp(3X)
arithmetic - provide drill iD Dumber factI.
arithmetic{S)
arithmetic language.
•••••••••••
bC(I)
arithmetic on shell variables. ••• • • • • •
cah(l)
arp - addrelll resolution display and control.
arp(SC)
arp - Addreel Resolution Protocol.
arp(4P)
a.rticle, utility filel.
newe(S)
articles.
expire(S)
articles. • • • • •
incws(l)
articlel. • • • • • •
postncws(l)
articlet.
readnewe(l)
art iclel via mail.
recnewe(l)
articles via mail.
•••••
recnew.(S)
articlel via mail.
leDdncws(8)
articles via mail. ••
uurec(S)
aa - mc68000 asaembler.
as(l)

- ii -

Sun System Release 1.1

Permuted lndez
expr - evaluate argumentlll as an expression. • • • • • • • • • • •
timelone, dysile - conveR date and time to ASCII. ctime, locaitime, gmtime, asctime,
getdate - conveR time and date from ASCII.
• •••••••••••
ascii - map of ASCII character set.
ucii - map of ASCII character set.
••••••
• •••••••••
od - oda.l, decima.I, hex, ascii dump.
atol, atoi, atol - convert ASCII to numbel'3. • • • • • • •
to ASCII. dime, localtime, gmtime, asctime, timezone, dysire - convert date and time
sin. COli, tan, asin, acos, a.tan, ata.n2 - trigonometric functions.
help - ask for help. • • • • • • • • •
u - mc68000 assembler. • • • • • • • • • • •
a..out - assembler and link editor output.
ass en - program verification.
•
letbul, letbulu, letlinebul - assign bulering to a IItream.
at - execute commands at a later time .
•••••••••
• hutdown - clole down the system at a given time.
at - execute commandl at a later time. • • • • • • • • • •
•••••••
nice. nohup - run a comma.nd at low priority (sh only).
lin, cos, tan, alin, &COI, atan, atan2 - trigonometric functions.
• •
lin. co•• tan, uin, aCOlI, atan, atu2 - trigonometric functions.
atof, atoi, atol - convert ASCII to numbers.
atol, atoi, atol- convert ASCII to numbers.
at of, atoi. atol - convert ASCII to numbers.
interrupt. lIigpaule- a.tomically releaDe blocked signals and wait for
rc - comma.nd script for &uto-reboot a.nd da.emon8. • • • • • • • • • •
wait - awa.it completion of process. • • • . • • • •
awk - pattern scanning and processing language.
••••••••••••
backgammon - the game of backga.mmon.
backga.mmon - the game of backgammon.
bg: pla.ce jo b in background. • • • • • • • • • • • • •
wa.it: wa.it for background processes to complete.
buner - print large buner on printer.
ba.nner - print large banner on printer.
gettytab - terminal configuration data base.
hostll - host name da.ta base.
networks - network name data baBe.
phon. - remote ho.t phone nllmber data base.
printcap - printer capability data base.
protocol. - protocol name data halt.
lerven - inet server data baBe.
lervicel - lerviee name data baB'.
• ••••••••
termeap - terminal capability data bas..
newaliuel - rebuild the data base Cor the ma.iI aliases file.
ttytype - data bait of terminal types by pon.
fetch ••tore, delete. Ii rsttey, nextkey - data. balle subroutines. dbminit,
vi - .creen oriented (vilual) dill play editor ba.sed on ex. • • • • • • • • • •
baBename - strip filename affixes.
• ••
bc - arbitrary-precision arithmetic language.
bcd - convert to antique media.
••••.••
bcopy, bcmp. bJero, Is - bit and byte string operations.
opera.tionl. bcopy. bcmp, blero, fs - bit and byte string • •
Di.play. bdemos - demonstrate Sun Monochrome Bitmap
yel - be repetitively affirmative.
cb - C program beautifier.
uptime - .how how lonl system hu been up.
jO, jl, jn. yO. yl, YD - belIBel functions.
cha.nsinll random, lrandom, initltate, setst&te - better random number generator; routines for
bg: place job in background.
•••••••••••
addbib - create or extend bibliographic databa.se.
•••••••••••
rolbib - run 01 bibliographic databue.
• ••••••••••
lIortbib - lion bibliographic databue.
a bibliography .br lookbib - find references in a bibliography. indxbib - make inverted index to
bibli0lr&phy. hulxbib - mate inverted index to a bibliography .br lookbib - find references in a
bil - mail alarm. • • • • • • • •
comlll,t - bilserver. • • • • • • • • • • •
whereis -locate SOUfCel binary, and/or manual Cor program.
- find printable strings in an object, or other binary, file. strings • • • • • • •
lll1encode,l1l1decode - encode/decode a binary file Cor transmission via mail.
fread, Iwrite - bulered binary input/output. • • • • • •
bind - bind a name to a Bocket.
• • •
bind - bind a name to a socket
/ bin/mail - send or receive mail among users.
bcopy. bemp. bzero, 111- bit and byte string operations.. • • • •
• ••••••••••
bdemoll - demonstrate Sun Monochrome Bitma.p Display.
., ••••••••••••••
nrip - remove eymbolll and relocation bits.
communication. bk - line discipline for machine-machine
0

SUD System Release 1.1

. iii •

••••••

expr(l)
ctime(3)
getdate(3)
ascii(7)
&3cii(7)
od(l)
atof(3)
ctime(3)
lIin(3M)
help(l)
1.8(1)
a.out(S)
a8sert(3)
aetbuf(3S)
at(l)
ahutdown(8}
at(l)
nice(l)
sin(SM)
ain(SM)
&tof!S)
ato! S)
atof S)
lIigpause(2)
re(8)
wait(l)
&"'k(l)
backgammon(6)
backgammon(6)
csh(l)
csh(l)
banner(6)
banner{6}
gettytab(S)
hoste(S)
networks(S)
phones(S)
printcap(S)
protocols(S)
80rvel'8(S)
services(5)
termcap(5)
newaliases(8)
ttytype(5)
dbm(SX)
vi(l)
ba8ename(1)
be(l)
bed(6)
bstring(3)
bstring(S)
bdemos(6)
yes(l)
cb(l)
uptime(l)
jO(SM)
random(S)
csh(l)
addbib(l)
roflbib(l)
80rtbib(1}
indxbib(l)
indxbib(l}
bifr(l)
comsat(8C)
whereis(l)
strings(l}
uuencode(lC)
fread(SS)
bind(2)
bind(2)
binmail(l)
bstring(3)
bdemos(6)
strip(l)
bk(4)
January 1984

Permuted Indez
bw - Sua
lIync - upda.te the lIuper
lIync - update IlUperlIync - update the lIuper
update - periodically update the lIuper
lIigblock lIisp&use - atomically releue
IlUm - sum a.nd count
- IItud alone teat for the Sun video graphici
bocgle - play the lame of
chinl- the
reboot - UNIX
mille - play Mille
indxbib - make inverted index to a bibliography
switch: multi-way command
locin, newgrp,/ IIh, for, case, if, while, :, .,
fl:
more, pacebw - SUI black and white frame
fread, fwrite Itdio - IIta.ndard
letbuf, lIetbuler, aetlinebuf - alli,D
fbio - leneral propertia of frame
lenerate a dump of the operatinlBYatem'a prolile
mkDod cODII- priDt out muu&! palellj find maDua' informatioD
mkltr - create aD error mellale lile
ttytype - data bue of terminal typel
ntoha - cODvert values between hoat aDd network
bcopy, bcmp~ blero, I. - bit and
awab -awap
bcopy, bcmp,
cc cpp - the
cb indent - indent and format
lint - a
xlltr - extract Itrin" from
mkltr - create AD error mellase lile by muaasinl
hypot,
de - dellk
cal - display
BY.caU - indirect IIYlltem
Iprof - dillplay
lehid, letlid - ,et user or group ID of the
malloc, free, realloc,
intro - introduction to lIyatem
canleld, cfllcora - the 1I0litaire card game
c&afield.
print cap - printer
termcap - terminal
oct - Central Data octal serial
ca.n field , dllcores - the 1I0litaire
cribbace - the
exec, exit, export, login, newgrp, read,/ IIh, for,
c,"~maD - create the
ccat - compress and uncomprellll files, and
default:

them. compact, uncompact,
IIh, for, cue, if, while, :, ., break, continue,

January 1984

black and white frame buler.
block.
block. • • • •
block. • • • •
block. • • •
block aignals.
••••••••
blocked lIignalll and wait for interrupt.
block! in a file. • • • • • • • •
board. ptelt
••••••••
boggle.
• ••••••••••
bocgle - play the lame of boggle.
book of chanles and other cookies.
bootltrappinc procedura.
Bonel. • • • • • • • • • • • •
• • •
. br lookbib - Ind referenca in a biblioCraphy.
branch. • • • • • • • • • • • • • • • • • • • • • •
break, continue, cd, eval, exec, exit, export,
break: exit while/foreach loop.
breaksw: exit from Iwitch.· • • • • • •
brinl job into foreground. • • • • • •
brk, sbrk - chance data leement lile.
browse throuch a text file. ••• •
bluacube - view 3-0 Sua 1010.
buler.
• ••••••••••
bulered biaary input/output.
bull'ered input/output pa.ckace.
bull'erinc to a Itream.
bull'en.
• ••••••••••
bull'en. kcmoD - • • • • • •
build special file. • • • • • • •
build ayltem conlcuratioD filea.
•
bw - SUIl black and white frame bull'er.
by keyword.. ma.n
by mallacinl C source.
by port. • • • • • • •
byte order. htonl, 'htonl, ntohl,
byte .trinl operations.
bytee. • • • • • • • • • • • • • • • •
bsero, II'It - bit aad byte Itrinl operation •.
C compiler.
• ••••
C lancuale preproceslor.
C procn.m beautifier.
C prolram 1I0uree.
C prolram veriler:
•••••••
C procn.m to impiemen~ Ihared atrin".
•••••
C souree.
••••••••
• • • • •
cab. - Euclidean dilltance.
cal - dillplay calendar.
•
calculator. • • • • • • •
calendar.
• •••••••
calendar - reminder service;
••••••••••
call.
call graph profile data.
caller. • • • • • • • • • • • • • • •
calloc, cfree, alloca - memory allocator.
calls and error numben. • • • • • • •
canfield. • • • • • • • • • • • • • •
canfield, dllcores - the lolitaire card game
capability data bue.
capability data bue.
card.
• ••••••
card game canfield.
card game cribbale.
•••••••••••
C&lle, if, while, :, ., break, continue, cd, evaJ,
cue: selector in IIwitch.
• • • • • •
cat - concatenate and display.
cat filea for the ma.nua.1.
cat them. compact, uncompact,
catchall clause in switch.
• • • • • •
catma.a - create the cat filea for the manual. • • • • • •
cb - C program beautifier. • • • • • • • • • •
cc - C compiler.
•••••••••••••
ccat - compresll an4 uncomprellll filell, and cd
cd - change working directory. • • • • • • • •
cd: change directory.
••••••••••••
cd, eval, exec, exit, export, login, newgrp, read.!

• iv·

bw(4S)
aync(l)
lIync(2)
lIync(S)
update(S)
ailblock(2)
ligpaulle(2)
sum(l)
pteat{Ss)
bocgle(6)
boggle(6)
ching(6)
reboot(S)
mille(6)
indxbib{l)
cllh(l)
.h{l)
Cllh!l)
cllh 1)
cah 1)
brk(2)
more(l)
bsuDcube(6)
bW{4S)
Iread{3S)
intro{3S)
.etbuf(3S)
fbio(4S)
tgmon(S)
mknod(S)
config(S)
bW(4S)
man(l)
mkatr(l)
ttytype(5)
byteorder{3N)
blltring{S)
IIwab(3)
bstring(S)
cC{l)
cpp{l)
cb(l)
indent(l)
lint{l)
xatr{l)
mkatr(l)
hypot(SM)
cal{l)
dC(l)
cal(l)
calendar{l)
11IIcal1(2)
IProf(l)
letuid{3F)
maUoc(S)
iDtro(2)
canfield(6)
canfield(6)
printcap{S)
'ermca.p(S)
oct(4S)
canfield(6)
cribbage(6)
Ih{l)
cah(l)
cat{l)
eatman(8)
compact{l)
cllh(l)
catman(8)
cb(l)
cC(l)
compact(l)
cd(l)
csh{l)
ah(l)

Sun System Release 1.1

Permuted Indez
delta.
fabs, floor,
fab., 800r, ceil - absolute value, floor,
oct - Systech VPC-2200 Venatec printer/plotter and
maJlGc, free, reallot, calloc,
canfield,
chdir brk, sbrkchdir chsh cd:
chdir:
ioinit chgrp puswd chmod chmod chmod, fchmodumask:
chown chown, fchown chroot .ignalcdc rename delta - make a delta (
set:
cd ching - the book of
... better raadomnumber generator; routines for
vi - view a file without
pipe - creat. aa iaterprocell commuaicatioa
ungetc - pUlh
/i.ucii, ia,faph, toupper, tolower, toa.cii eqachar - special
,etc, f,etc - ,et a
index, rinda, Inblnk, len ... tell about
,etc, ,etchar, fsetc, ,etw - ,et
pute, putchar, fputc, putw ... put
alcii ... map of ASCII
putc, fputc ... writ. a
teet ... establilb termiaal
tr - traaalate
snake, snscore - display

dcbeck ... fil. system directory consistency
ichec:k ... file system storase consistency
fptype fsck - file system consistency
cbecknewa cbecknr eqn, neqn,
futhalt ... reboot/halt the system without
newl network.
ae.lre ... iaformatioa fil. for readnewa(l) and

closep' - craphicl/ openpl, erase, label, line,
isrnph, toupper, tolower, toascii - character
default: catchall
uueleaa ... uttcp spool directory
clri -

SUD System Ilplease 1.1

cdc - change the delta commentary of an SCCS
ceil - absolute value, floor, ceiling functions.
ceiling functions. • • • • • • • •
Central Data octal serial card. • • • • •
Centronics printer interface. vpc • • • •
elree, alloca - memory allocator.
elscores - the solitaire card game canfield.
• • • • •
cg - Sun color graphics interface.
change current working directory.
change data segment size.
• • • • •
change default directory.
change default login shell.
• • . • •
change directory. • • • • •
change directory, • • • • •
change 177 I/O initialization.
change group.
change login password.
change mode.
change mode of a file.
change mode of file.
• • • •
change or display file creation mask.
change owner. • • • • • • • •
chaage owner and group of a file. •
change root directory. •• • • • •
chan,e the action for a signal.
• • • • •
change the delta commentary of an sees delta.
change the name of a file.
• • • • •
change) to aa sees file.
change value of shell variable.
chan,e workin, directory.
changes and other cookies.
•••••••••
chan,in, generaton. /srandom, initstate, setstate
chaa,ia, it usin, tbe vi visual editor.
channel. • • • • • • • • • • • • • • • • • •
character back into input stream.
•••••
character classification and convenion macros.
cbaracter definitions for tqn. •• •
character from a logical unit.
character objects.
•••••••
character or integer from stream.
character or word on a stream. ••
character set.
••••••••
character to a FORTRAN logica.l unit.
characteristics for the environment. ••
•••••••••••
characten.
chaae - Try to escape to killer robots.
chase ,ame. • •••
cbdir - change current working directory.
chdir - change default directory.
• • • • •
chdir: change directory,
check.
••••••••••
check.
."......,...
• • • • •
check a floating point number.
check &ad interactive repair. •••
• • . • • • • •
•
cbeck if uller has news on the USENET news network.
check nro./tro' files. • • • • • • • • • • • • • •
checkeq - typeset mathematics.
•••••••••••
checkin, the disks. fa.atboo' ,
••••••••••
checknews - check if user has news on the USENET
checknews(n
•••••••••••••••
checknr - cbeck nro./trof filea,
•••••••
chgrp - change group.
••..•.•••••
cbin,- the book of changes and other cookies.
.••••••••••
chmod - change mode.
chmod - change mode of a file. • • • • • • • •
chmod, fchmod - change mode of file. •• • • •
chown - change owner. • • • • • • • • • • •
chown, fchown - change owner and group of a file.
chroot - change root directory. • • • • • • • •
chsh - change default login shell. • • • • • • •
circle, arc, move, cont, point, linemod, spa.ce,
classification and conversion macros. /isascii,
clause in switch. • • • • • • • • • • • •
clean-up.
••.••••••••••••
dear - dear worksta.tion or terminaJ screen.
clear i-node. • • • • • • • • • • • • • • • •
<

- v·

•

•

•

•

•

•

•

cdc( I)
floor(3M)
floor(3M)
oct( 4S)
vpc(4S)
malloc(3)
canfield(6)
cg( 4S)
chdir(2)
brk(2)
chdir(3F)
chsh(l)
csh(l)
csh(l)
ioinit(3F)
chgrp(l)
passwd( I)
chmod( I)
chmod(3F)
chmod(2)
csh(l)
chown(8)
chown(2)
chroot(2)
signal(SF)
cdc( I)
rename(2)
delta.(l)
csh(l)
cd(l)
ching(6)
random(3)
view{l)
pipe(2)
ungetc(3S)
ctype(a)
eqnchar(7)
getc(3F)
index(3F}
getc(3S)
putc(3S)
ascii(7)
putc(3F)
iIIet(l)
tr(l)
chase(6)
snake(6)
chdir(2)
chdir{3F)
csh{l)
dcheck(8)
icheck(S}
fptype(3F)
fsck(S)
checknews{l}
checknr(l)
eqn(l)
fastboot(S)
checknews{l}
newsrc(S)
checknr(l}
chgrp{l}
ching(6)
chmod(l)
chmod{3F)
chmod(2)
chown(S)
chown{2}
chroot(2}
chsh(l)
plot(3X)
ctype(3)
csh(l)
uuclean(8C)
dea.r(l}
dri(8)

January 1984

cleu ferror, feof,
csh - a shell (comm&Jld interpreter) with
cron shutdown fclose, mush opendir, readdir, telldir, seekdir, rewinddir,
syslol, openlol,
circle, arc, move, cont, point, linemod, space,
pi - Pucal interpreter

101. dme.colordemol - demonstrate SUD
CC - SUD
Display.
pr - print tile(s), possibly in multiple
colrm - remon
comb tilel.
exec: overlay shell with .peeitied
time: time
- routine. for returning a stream to .. remote
rexec - retUrD stream to a remote
system - inue a .hell
.y.tem - execute a UNIX
test - conditioD
time - time ..
nice, nohup - ruD a
awitch: multi-way
uux - unix to unix
rehuh: recompute
unhash: dillcard
hashlltat: print
nohup: run
cah - a shell (
whatis - describe what a
readonly, let, shift, timet, trap, umuk, wait eetarl, iarcc - retUrD
repeat: execute
rc onintr: process interrupti in
goto:
else: alternative
intro- introduction to
- introduction to lIystem ma.intenance and open.tion
at - execute
while: repeat
lutcomm - show last
source: read
cdc - chanle the delta
comm - eelect or reject linell
bk - IiDe dillcipline for machine-machine
socket - crelote an endpoint for
pipe - create an interprocell
usen filell, and cat them.
dil - dilerentiaJ tile and directory
cmp tlcclldildifrS - ~"a.y dilerential tile
intro - introduction to
cc - C
f77 - FORTRAN-77
pc - Pucal
yacc - yet a.nother compilererrOf- ana.lyse a.nd dispent
ya.cc - yet another
wait: wait for ba.ckground processell to
wait - a.wa.it
compact, uncompact, ccat -

Ja.nuary 1984

cleu workstatioD or terminl.lscreen.
• • • • •
elearerr, fileDo - stream sta.tus inquiries.
C-Iike syntax.
•••••••••••
clock daemoD. • • • • • • • • • • •
• • • • •
close - delete & dellcriptor. • • • • • •
dose dOWD the system at & given time.
dose or flush & strea.m.
•••••••
dosedir - directory operl.tion..
doselol - control system 101.
• • •
elosepl - graphics interface. /erue, label, IiDe,
clri - deu i-Dode.
•••••••
cmp - compare two tilel.
••••••••••••••
code translator.
••••••••••••••••••
col - tilter revene paper motion.. • • • • • •
col crt - tilter Drol output for CRT previewinl.
collect system diagnostic messa.ges to form error
Color Gn.phics Display. • • • • • • • • • • • • • • •
color graphics interface. • • • • • • • • • •
colordemo. - demonstn.te SUD Color Gn.phic. • • • • •
colrm - remove column. from a tile.
• • • • •
••••••••••••••
column..
columnl from a tile. ••• • • • • • • • • • •
comb - combine SCCS deltu. • • • • • • •
combine SCCS deltu.
•••••••••••
comm - select or reject linel common to two sorted
command. • • • • • • • • • • •
command. • • • • • • • • • • •
command. rcmd, rresvpon, ruserok
command.
command.
command.
command.
command. • • • • • • • • • • •
• • • • •
command at low priority (sla only).
• • • • •
command branch.
command execution.
• • • • •
command huh ta.ble.
• • • • •
command huh table.
• • • • •
commaJld huhing statistics.
command immune to hanlups. • a • • •
comma.nd interpreter) with C-like syntax.
command is. • • • • • • • • • • • • • • • • • • • •
command language. lexport, login, newgrp, read,
command line arguments. • • • • • • • • • •
command repea.tedly. . • • • • • • • • • • •
command script for a.uto-reboot and daemonll.
comma.nd scripts.
comma.nd transfer.
commands.
• • • • •
command..
commands. intro
•
• • • • •
commands at a later time.
commands conditionally.
••••
command. executed in revene order.
command. from tile.
•••••
commentary of an SCCS delta.
common to two sorted tilell.
• • • • • •
•••••••••
communication.
communication.
••••••••
communication chaDnel. • • • • • • • •
compact list of ullen who are on the lIystem. • • • •
compact, uncompact, ccat - compress and uncompress
•
compan.tor. ' . . . . . . . . . .
•••••••••
compare two tiles.
compare two venions of &Il SCCS tile.
comparison. . . , . . . . . .
compatibility library functiolll.
• • • • •
compiler.
compiler.
• •• " . . .
compiler.
••••••••
• • • • •
compiler.
••••••••
• • • • •
compiler error mes!I&ges.
compiler-compiler.
• • • • •
•••••••
• • • • •
complete.
completion of procc!!s. •• • • • • • • • • • •
compress and uncompret!s filell, a.nd cat them.
•••••

dea.r(l)
ferror(3S)
csh(l)
cron(8)
close(2)
.hutdown(8)
felose(SS)
directory(3)
.yslog(S)
plot(SX)
clri(S)
cmp(l)
pi(l)
col(l)
colcrt(l)
dmellg(8)
colordemos(6)
cg( 4S)
colordemos(6)
colrm(l)
pr(l)
colrm(l)
comb(l)
comb(l}
comm(l)
csh(l)
csh(l)
rcmd(SN)
rexec(SN)
system(S)
.ystem(SF)
test(l)
time(l)
nice(l)
csh(l)
uux(IC)
csh(l)
cllh(l)
clh(l)
cllh(l)
csb(l)
whatis(l)
IIh(l)
geta.rg(SF)
csh(l)
rc(8)
csh(l)
cllh(l)
csh(l)
intro(l)
intro(8)
at(l)
csh(l)
lutcomm(l)
csh(l)
cdc(l)
comm(l)
bk( 4)
.ocket(2)
pipe(2)
ulleItl(l)
compact(l)
diO'(l)
cmp(l)
sccsdifl'(l)
dil3{l)
intro(aC)
cC(l)
177(1)
pC(l)
ya.cc(l)
error(l)
y&cc(l)
csh(l)
wait(l)
compact(l)

Sun System Release 1.1

Permuted Indez
ha.ngma.a II -

lilog 8530

sec seria.!

ca.t testendil: termina.te
if:
while: repea.t comm&nds
gettytab - termina.l
cOllfig - build system
ifconfig tip, cuget peern&me - get n&me of
socketp&.ir - create a p&ir of
IhutdowD - Ihut dOWD part 01 a full-duplex
accept - accept a
connect - initi&te a
listeD - listen for
dcheck - file system directory
icheek - file system storage
fsck - file system
con. - driver lor SUD
mkf. Dewl. mkproto derol- remove nrol, trol, tbl &nd eqn
letrlimit - control muimllm lIystem rellource
vlimit - control muimllm lIystem rellource
openpl, erue, label, Iille, circle, are, move,
II -list
.iptacic - let and/or get sipullt&ck
10ckllcreeD - maiDt&in wiDdow
Dewgrp,/ Ih, for, cue, if, while, :, " break,
arp - addre.. relolution dilplay and
Icntl - file
, nd - network dillk
ioctlinit - proce••
getrlimit, letrlimit vii mit icmp - Internet
dkio - generic dillk
fcntl - file
Ipc - line printer
tcp - Internet Tr&n.miuion
IYlllog, openlog, dOllelog vhuCUp - virtually "hangup" the current
ip - Dilk driver lor Intorphue 2180 SMD Di.k
It - Driver lor SYIgell SC 4000 (Archive) Tape
Id - Dilt driver lor Adaptec ST·508 Dilk
xy - Dilt driver for Xylogici SMD Di.k
ecvt, fevt, gcvt - output
prilltl, Iprintl, .prilltl - form&tted output
Icanl, fllcaDf, Illcanl - formatted input
tolower, toalcii - character clulification alld
ullita v.wap dd number ranlib &tol, atoi, atol loca.ltime, Imtime, uctime, time.one, dysiJe htable getd&te bcd htonl, htoDII, ntohl, ntoh. chinl - tho book of change. a.nd other
rcp - remote file
uucp, uulog - unix to unix
dd - convert and
cpio cp-

SUD System Release 1.1

Computer version of the game hangman.
comsat - bift' server.
comunications driver.
concatenate &nd display.
condition command.
•••••••
conditionaJ.
conditional statement.
condition&lIy.
•••••
config - build system configuration filell.
configuration da.ta. base. • • • • • • • •
cOllfiguration files.
••••••••••
configure Iletwork interfa.ce pa.rametelll.
connect - initiate a. connection on a. lIocket.
connect to a remote system.
connected peer.
cOllnected IIOCketS.
cOllllectioll.
connection on a lIocket.
connection on &socket.
cOllllectiolls on a socket. • •
COil. - driver for SUIl console.
conllistellCY check.
cOllsistellcy check.
•
cOllsistellcy check and interactive repair.
console. • • • • • • • • • • •
construct a file system.
COIlStruct a new file system.
construct a prototype file system.
COllstruCtS.
••••••••••
consumption. getriimit, • • • • •
consumption.
••••••••••••••
cont, point, linemod, IIpace, closepl - graphics/
conteDts 01 directory. • • • • • • • • •
context. • • • • • • • • • • • • • • •
context until "Iogill". • • • • • • • • •
continue, cd, ev&l, exec, exit, export, login,
continue: cycle in loop.
•••••
control.
control. • • • • • •
control. • • • • • •
cODtrol device.
control initiaJiution.
control maximum system resource cODllumption,
control maximum lIystem resource consumption.
COlltrol Message Protocol.
control operation •.
cOlltrol options.
control program. ••
Control Protocol. ••
control sYlltem log.
cOlltrol terminu.
Controller.
Controller.
Controllen.
Controllen.
convenion.
convenion.
•••••••••••••••
convenion.
convenioll macros. /is&seii, isgra.ph, toupper,
convenion program.
••••••
convert a foreign lont file.
convert and copy & file. • • • • •
convert Ar&bic numeralll to English.
convert archives to random librariell.
convert ASCII to numbers.
• •
convert date and time to ASCII. dime,
convert NIC standard lormat host tables. • • • • •
convert time and date Irom ASCII.
convert to antique media. • • • • • • •
•
convert values between host and network byte order.
cookies.
copy. • • • • • • • • • •
copy. • • • • • • • • • •
copy a file.
• ••••••
copy file archives in and out.
copy files. • • • • . • • •

- vii •

hangman(6)
comsa.t(8C)
Is(4S)
cat(l)
test(l)
csh(l)
csh(l)
csh(l)
config(S)
gettytab(S)
config(S)
ifconfig(SC)
connect(2)
tip(lC)
get peername( 2)
lIocketpair(2)
IIhutdown(2)
accept(2)
connect(2)
listen(2)
cons(4S)
dcheck(S)
icheck(S)
Isck(S)
cons(4S)
mkfs(S)
newrs(S)
mkproto(S)
deroft'(l)
getrlimit( 2)
vlimit(3C)
plot(3X)

18(1)
lIigsta.ck(2)
locbcreen( 1)
IIh(l)
csh(l)
arp(SC)
Icntl(2)
nd(SC)
ioctl(2)
init(8)
getrlimit(2)
vlimit(3C)
icmp(4P)
dkio(4S)
Icntl(5)
Ipc(S)
tcp(4P)
lIyslog(3)
vhangup(2)
ip(4S)
st( 4S)
sd(4S)
xy(4S)
ecvt(3)
printr(3S)
sca-nr(3S)
ctype(3)
unitll(l)
vswap(1)
dd(1)
number(6)
ranlib(l)
ator(3)
ctime(3)
htable(S)
getdate(3)
bcd(6)
byteo rder(3N)
ching(6)
rcp(lC)
uucp(lC)
dd(l}
cpio(l)
cp(l)
January 1984

Permuted ["des
fork(SF)
••••••
fork - create a copy of this process.
tee(l)
tee - copy .tandard output to ma.ny file •.
core(S)
core - format of memory image file.
lavecore(S)
tl&vecore - lIave a core dump of the operatinl SYltem.
Icore(l)
Icore - let core images of runnins procelles.
fsync(2)
• • • • • •
fsync - lIynchronile a file's in- core Itate with that on disk.
lin(SM)
functionll. lIin, cos, tan, uin, loCO., atu, atan2 - trigonomehic
.inh(3M)
lIinh, cOllh, tanh - hyperbolic functionl.
wc{l)
••••••••••••
wc - word count.
lum(l)
lIum-lIum and count blocks in a file. • • • • • •
cp(l)
cp - copy filel. • • • • • • • • •
cpio(l)
cpio - copy fil. archivel in ud out.
cpio(S)
cpio - format of cpio archive.
cpio(S)
cpio - format of cpio archiv.. • • • • • • • • • •
cpp(l)
cpp - the C IUlUase preprocelllor. • • • • •
cruh(SI)
cruh - what happenl when the Iyltem cruhes.
aDalYIe(S)
au lYle - Virtual UNIX postmortem crub analYler.
cruh(Ss)
cnlh - what happeD. wheD the Iyltem cruhe.. • • • • • • • • • • • •
creat(2)
creat - create a new file.
fork(SF)
fork - create a copy of thill procesl. •• •
tmpnam(SC)
tmpDIom- create a name for a temponry file.
creat(2)
crnt - create a new file. • • • • • • •
open(2)
OPeD - opeD a fil. for rea.diDI or WritiDI, or create a new file. • • • • • • •
fork(2)
fork - create a Ilew procelll. • • • • •
locketpair(2)
locketpair - create a pair of connected socket•.
cbp(l)
etap - create a tap file. • • • • • • • • •
•••
.ockct(2)
lOCket - create an endpoint for communication.
mkltr(l)
mkltr- create an error mealas. file by malnsinl C .ource.
pipe(2)
pip.- create an interproceaa communica.tioll channel.
admin(l)
admia - create alld adminilter SCCS filea.
addbib{l)
addbib - create or extend bibliosnphic database.
catman(S)
catma.a ~ create the ca.t filelfor the mallual.
cllh(l)
umuk: chaDS' or dilplay fil. creatioll muk. • • • • • • • • •
••••••
umuk(2)
umuk - 1ft fil. creatioll mod. muk.
cribbage(6)
• ••••••••••
cribb". - the card I,m. cribb"..
cribbage(6)
cribbal' - the card lame cribb....
croa - clock daemoll. • • • • • • • • •
cron(S)
crontab - table of tim. to rull periodic job•.
crontab(S)
pxref - Pucal croll-reference program. • • • • • • • •
pxref{l)
colcn - filter nro' output for CRT previewinl. • • • • • • • • • • • • •
colcrt(l)
crypt - en co de/ decode.
••••••••••
crypt(l)
crypt, letkey, encrypt - DES encryptioll.
•••
crypt(S)
lIynta.x. cllh - a .hell (comma.ad interpreter) with C-like
csh(l)
locate a prosram fill includinl alia.ael a.nd pathl ( cllh only). whicll ~ • • • • • • • • • • • • •
which(l)
ctap - create a taSI file.
••••••••••
ctap(l)
- convert date and tim. to ASCII. dime, locattime, gmtime, uctime, timelone, dYliae
ctime(3)
tip, cu - connect to a remote lIystem.
tip(IC)
vhanlup - virtually ICha.nCUp" the current control terminal.
vhangup(2)
lethostid - let unique identifier of current holt. • • • •
sethostid(2)
setho.tume, lIetholltname - let/let name of current ho.. • •••
cetholltname(2 )
hOltnm - let ume of current holt. • • • •
hoatnm(SF)
hOlltid - print identifier of current holt system.
hoatid(l)
hOltume - .et or print name of current bolt system.
•••••
holtname(l)
jobl: print current job lilt.
••••••••
clh(l)
IUn - il current machine a sun workstation.
IUn(l)
vax -il current machine a va.x.
vax(l)
lIact - print current SCCS file editiDs activity.
.aet(l)
lIipet.muk - lIet current lipal muk.
lipetmask(2)
whoami - display elective current username.
•••••••
whoami(l)
chdir - chanl' current workinl directory.
chdir(2)
letcwd - get pathume of current workinl directory.
•
• • • • • getcwd(SF)
letwd - let current workins directory pathname. • • • • •
letwdl3)
motion. cun.. - screen functions with "optimal" cunor
cunes SX)
cuneI - IIcreen (unctions with "optimal" cunor motion.
cunes3X)
spline - interpolate smooth curve. • •••
spline(lG)
continue: cycle in loop.
cllh(l)
blUncu be - view S- D Sun loso.
bsuncube(6)
cron - clock daemon.
cron(S)
inetd - int.ernft servicel daemon.
inetd(SC)
Ipd - line printer daemoll.
Ipd(S)
routed - network routing daemon. • ••••
routed(SC)
rc - command script (or auto-reboot and daemonll.
• ••••••••••
rc(S)
ftpd - DARPA Int.ernet File Tranafer Protocoillerver.
ftpd(SC)
telnetd - DARPA TELNET protocol server. • • • • •
t.elnetd(SC)
timed - DARPA Time server. • • • • • • • • • • •
timed(8C)
tftpd - DARPA Trivial File Tranafer Protocol server.
tftpd(SC)

. . ..

Ja.nua.ry 1984

- viii -

Sun System Release 1.1

Permuted Indez
eval: r~valuate shell
sprol- display call graph profile
prol - display profile
tty. - terminal initialilation
settytab - terminal configuration
hoats - host Dame
networke - network name
phona - remote ho.t phone number
printeap - printer capability
protocol. - protocol name
serven - inet server
service. - lIervice name
termcap - terminaJ capability
new&liua - rebuild the
ttytype dbmiDit, letch, store, delete, fimkey, Dextkeyoct - Central
brk, .brk - chaDge
Dulltype. - primitive lIystem
addbib - create or extend bibliosraphic
rolbib - ruD olf bibliosraphic
sortbib - sort bibliosraphic
joiD - relatioDaJ
udp - IDtemet User
date - display or let the
lettimeolday, settimeolday - set/let
time, ftime - set
IIDtim., asctime, time,oDe, dysi.e - CODvert
rdate - set system
setdate - convert time aDd
touch - update
ida.te, itime - retUrD
data bue subroutiDe•.

adb dbx od - octal,
tp crypt - eDcode/
uueDcode,uudecode - encode/
chdir - change
chsh - change
kbd - keyboard traDslation table format aDd
eqDchar - speciaJ character
clOI. dbminit, fetch, store,
cdc - chaale the delta commentary of aD SCCS
delta - make a
cdc - chaDg. the
rmdel - remove &
comb - combine SCCS
colordemo. bdemo. mesl - permit or
CODltructl,
crypt, setkey, encrypt whati. mailaddr - mail add rei ling
remote - remote host
close - delete a
dup, dup2 - duplicate a
setfstype, letfsent, endfsent - set file system
setfd - get the file
setdtablesile - set
dc access accen file drum - pagins

SUD System Release 1.1

data.
data.
data.
data.
data base.
data base.
data base.
data base. • ••••
data base.
data base. • ••••
data base. • ••••
data base. • ••••
data base. • • • • • • • • • •
data bale for the mail aliases file.
data base of terminal typea by port.
data base aubroutines.
Data octal aerial card.
data sesment aile.
data sink. • ••••
data types.
databue.
databue.
databue.
databue operator.
Datagram Protocol.
date.
• ••••••
date - display or set the date.
date and time, • • • • • •
date and time. . . . . . . . .
date &ad time to ASCII. ctime, loca.ltime,
date from a remote host.
date from ASCII. • • • • • • • • • • •
date lut modified of a file.
••••••
date or time iD Dumerical form.
dbminit, fetch, store, delete, fintkey, nextkey dbx - debugger.
••••••••••••••
dc - desk calculator.
•••••••••••
dcheck - file Iystem directory conllistency check.
dd - convert and copy a file.
debugger. • • • • • • •
debugger. • • • • • • • •
decimal, hex, udi dump.
DEC/mas tape formata.
decode. • • • • • • •
• ••••••••••
decode a. biDary file for tranllmillsion via mail.
default: catchall claulle in switch.
default directory. ••
default login shell.
default table.
definition. for eqn.
delete a descriptor..
• • • • • • • • •
delete, fintkey, nextJeey - data bue subroutines.
delta. • • • • . • • • • • • • • • • • • • • • • • •
delta - make a delta (change) to an SCCS file.
delta (change) to an SCCS file. ••
delta commentary of aD SCCS delta.
delta from an SCCS ile.
deltu.
• •••••••••••
demonRrate Sun Color Graphics Display. • ••
demonstrate Sun Monochrome Bitmap Display.
deny meslage.. • • • • • • • • • • •
••• • • •
derol - remove nrol, trolf, tbl and eqn
DES encryption. • • • • •
describe what a command is.
description.
••••
description file. • • • • • •
descriptor. • • • • • • • •
descriptor. • • • • • • • • • • • • •
descriptor file entry. /getfsspec, getfsfile,
descriptor of an extema.lunit number.
descriptor table sile.
••••••
dellk calculator.
determine acce8sability of a file.
determine accessibility of file.
determine file type.
device.
• •• " • • • • •

>......

- ix -

csh(l)
gprof(l)
prof(l)
ttys(S)
gettytab(S}
hosts(S)
networks(S)
phones(S)
printcap(S)
protocols(S}
servers(5)
IIcrvices(5)
termcap(S)
newaliases(8}
ttytype(s}
dbm(3X}
oct(4S)
brk(2}
null(4)
types(S}
addbib(l}
roffbib(l)
sortbib(l}
join(l}
udp(4P}
date(l)
date(l}
gettimeofday(2)
time(3C)
ctime(S)
rdate{8}
getdate{3}
touch(l)
idate(3F)
dbm(3X)
dbx(l)
de(l)
dcheek(8)
dd(l}
adb(l)
dbx(l)
od(l)
tp(S)
crypt(l}
uuencode(lC)
csh(l)
ehdir(3F)
chsh(l)
kbd(S)
eqnchar(7)
c1ose(2)
dbm(3X)
cdc(l)
delta.{l)
delta.{l)
cdc(l)
rmdel(l)
comb(l)
colordemos(6)
bdemos(6)
mess{l)
deroff(l)
crypt (3)
whatis(l)
mailaddr{7}
remote{S)
close(2)
dup(2)
getfsent(3 )
getfd(3F)
getdta blesize( 2}
dC(l}
access(3F)
access(2)
file(l)
drum(4}

January 1984

Permuted Intlez
fold - fold Ion! lines for finite width output
ioctl - control
swapon - add a swap
awapon - specify additional
Bmin, Bmax, dBmin,
8min, 8 max ,
package.
dmesl - collect system
ratfor - rational Fortran
dildif3 - 3-way
dir - format of
rm,rmdir - remove (unlink) filee or
rmdir, rm - remove (unlink)
cd - chanle workinl
chdir - change current workinl
chdir - chanse default
chroot - chanle root
cd:chanle
chdir: chule
setcwd - get pathname of current workinl
Is - list content. of
mkdir - make a
sc&ndir, alphason - SC&Jl a
uuclean - uuep spool
dif - diferential file and
dcheck - file Iystem
unlink - remove
unlink - remove a
mkdir - make a
rmdir - remove a
pwd - print workinl
readdir, teHdir, aeekdir, rewinddir, cloaedir,etwd - let current workinl
popd: pop Ihell
pushd: pUlh Ihell
lJetquota - enable/
unhuh:
unitt:
bk - line
- Iynchronin a file'l in-core IItate with that OD
nd - network
dkio - !eneric
ip - Disk driver for Interphue 2180 SMD
Id - Dilk driver for Adaptec ST-60S
xy - Dilk driver for Xylocici SMD
nd - network
Id ContrOller. ipxyquota - manipulate
df - report free
d. - summarile
- reboot/halt the Iystem without checkinl the
mount, umount - mount and
C!fror - allalyse and
bdemo. - demonstrate Sun Monochrome Bitmap
cat - concatenate and
colordemo. - demonstrate Sun Color GraphiclI
raiD - animated raindrop.
arp - addrelll resolution
cal!prof snake, snscore vi - screen oriented (visual)
whoami umaak: chaDle or
hew perfmoD - gra.phical
date prof worma - animate worms OD a

Ja.nua.ry 1984

device.
••••••••••••••
device.
•••••••••••••••
device for interleaved pagill!/swappins.
device for pagin! and swappin,.
df - report free disk space on file systelDJ.
dBmax, inmax - return extreme valuea. • ••
d8min, dBmu, inmu - return extreme valuell.
dill - General-purpose stand-alone utility •••
dia.gnostic messales to form error 101. • • • • •
dialed.
••••••••••••••••••••••
dil- differential file and directory comparator.
dilS - 3-way dilerential file comparison.
dilerential file and directory comparator.
dilerential file comparison.
dir - format of diredorie•.
diredoriel.
directoriel.
directori.. or fil ...
directory.
directory.
directory.
directory.
directory.
directory.
directory.
directory.
directory.
directory. • ••
directory clean-up.
directory comparator.
directory conlistency check.
directory entry.
•••••••
directory entry.
•••••
directory file.
directory file.
directory name.
• •
directory operationl. opelldir,
directory pathname.
•••••
directory stack.
•••••••
directory ltack.
•••••••
disable quotas on a file system.
discard command hash table.
discard Ihell variabl...
• • • • • • •
discipline for machine-machine communication.
disk. fsync
••••••
disk control. • • • • • •
disk control operationl.
Disk Controller.
Disk Controllen.
Disk Controllen.

fold(l)
ioctl(2)
.wapon(2)
swapon(S)

eIf(l)
ruge(SF)
rallge(SF)
diag(Ss)
dmeag(S)
ratfor(l)
ditf{l)
diIS(I)
ditf{l)
difr3(1)
di~5)

:(~J

rmdir(l)
cd(l)
chdir(2)
chdir(SF)
chroot(2)
csh(l)
csh(l)
setcwd(SF)
Is(l)
mkdiI{l)
Icandir(3)
uuclean(SC)
dil(l)
dcheck(8)
unlink(2)
unlink(3F)
mkdiI(2)
rmdir(2)
pWd(l)
directory(3)
Cetwd(3)
csh(l)
elh(l)
letquota,(2)
csh(l)
csh(l)
bk(4)
'lync(2)
nd(8C)
dkio(4S)
ip(4S)
.d(4S)

xy(4S)
. • • • • • . . • • • • • • • nd(4P)
Disk driver for Adaptec ST-60S Disk Controllen.
Id(4S)
Dilk driver for Interphue 2180 SMD Disk ••
ip(4S)
Dilk driver for Xylocicl SMD Disk Controllen.
xy(4S)
di.k driver.

disk quotas. • • • • • • •
disk Ipace on file systeml.
disk usage.
• ••••••
disks. futboot, fasthalt • •
dismount file system.
• • • •
dispene compiler error messages.
Display.
display. • • • • •
Display. • • • • •
displa7· • • • • •
display and control.
display calendar. • • • • •
display call !faph profile data.
display chue lame, • • • • • • •
display editor bued on ex.
•••
display elective current username.
display file creation muk.
display fint few lines of specified files.
display of general system statistics.
display or set the date.
display profile data.
display terminal.
- x •

quota(2)
df(l)
dU(I}
falltboot(8)
mount(8)
error(l)
bdemos(6)
eat(l)
colordemoll(6)
rain(6)
arp(SC)
cal(l)
!prof(l)
sllake(6)
vi(l)
whoami(l)
esh(l)
head(l)
pedmon(l)
date(l)
prof(l)
worm.a(6)

Sun System Release 1.1

Permuted lndez
ta.il- display the last part of a file.
•••••••••
cabs - Euclidean distance.
• • • • • • • • • • • • • • • • • ••
dkio - generic disk control operations.
•••••
error log. dmeag - collect sYlltem dia.gnostic messages to form
refer - &nd and insen literature references in documents.
• •••••••••••
trof - typese~ or forma~ documents.
• •••••••••••
w - who is on and what they are doing. • • • • • • • • • • • • • • •
shutdown - shut down pa.rt of a fuU-duplex connection.
shutdown - elose down the system a.t a given time. •
draw - interactive graphics drawing.
graph - draw a graph.
• ••••
draw - interactive graphics drawing.
arithmetic - provide drill in number facti.
ar - Archive 1/4 inch Streaming Tape Drive.
tm - tapemuter 1/2 inch tape drive.
nd - network disk driver.
pty - pseudo terminal driver.
• • • •
• • • •
•
II - .ilOI 8580 SCC lerial comunicationl driver.
Id - Disk driver for Adaptec ST-SOS Disk Controllers. •
ip - Disk driver for Interphase 2180 SMD Disk Controller.
••••••••••
coni - driver for Sun conlole.
Controller. It- Driver for Sysgen SC 4000 (Archive) Tape •• • • • • •
xy - Dilk driver for Xylogics SMD Disk Controllers. ••
adjacentlcreenl - notify the window driver of the physicaJ relationships of screens.
term - terminal driving tables for nrol.
term - terminal driving tables for nrol.
drum - paginc device.
•
du - lummari .. disk usage.
• ••••••••
dump - incremental file system dUmp.
• ••••• ,..
•
od - octal, decimal, hex, ucii dump.
dUmp - incremental file system dump.
• ••
dump, dumpdates - incremental dump format.
dumpfl - dump file Iystem information.
•••••••••••••••••••
dump, dumpdatel - incremental dump format.
II&vecore - lave a core dump of the operating system. • • • • • • •
kemon - lenerate a dUmp of the operating system's profile bufers.
dump, dumpdatel - incremental dump format.
dumpfl - dump file system information.
dup, dup2 - duplicate a descriptor.
dup, dup2 - duplicate a descriptor.
•••••
.hutdown - .hut down part of a full· duplex connection. • • • • • • • • • •
•••••••
dup, dup2- duplicate a descriptor.
dim., local tim., gmtim., uctim., timeioDe, dysilC - convert date and time to ASCII.
ec - 8Com 10 Mb/s Ethernet interface.
echo - echo arguments.
• • • • •
echo: echo arcuments.
••••••••
••••••••
echo - echo arguments.
echo: echo arcuments. •• • • • •
ecvi, fcvi, gevi - output conversion.
•••••••
ed - text editor,
end, etext, edata - lut locations in program.
ex, edi~ - text editor.
vipw- edit the pusword file.
.act - print current SCCS &Ie editing activity.
ed - text editor.
ex, edit - text editor,
Id -link editor,
sed - stream editor.
view a II. without changing it using the vi vilual editor. vivi - .creeD oriented (vilual) display editor based on ex.
a.out - assembler and link editor output,
whoami - display elective current username.
setregid - let real and elective group ID.
letreuid - let real and elective uller lD's.
• • • •
vfork - spawn new procesl in a virtual memory emcient way.
grep, egrep, fgrep - search a file for a pattern.
insque, remque - insert/remove element from,. queue.
soelim - eliminate .110'15 from nrof input.
else: alterna.tive commands.
••••••••
• • • •
tektool - Tektronix 4014 terminal emulator tool.
eD - Sun S Mb/II experimental Ethernet interfa.ce.
setquota - enable/disable quotu on a. file system.
•••••••••••
uuencode - format of an encoded uuencode file.
crypt - encode/decode, •• . • • • • • • • • • • • •
mail. uuencode,uudecode- encode/decode 3. binary file for tranllmission via.
crypt, setkey, encrypt - DES encryption.
••••••••
hypo~,

SUD System R~lease 1.1

- xi·

bil(l)
hypot(3M)
dkio(48)
dmesg(8)
refer(l)
trofT(l)
w(l)
shutdown(2)
shutdown(S)
draw(6)
graph(IG)
draw(6)
a.rithmetic(6)
ar(48)
tm(48)
nd(4P)
pty(4)
'15(48)
Id(48)
ip(48)
cons(4S)
It(48)
xy(48)
a.djacentscreens(l)
,term(S)
term(S)
drum(4)
duel)
dump(S)
od(l)
dump(S)
dump(S)
dumpfs(S)
dump(S)
savecore(S)
kgmon(S)
dump(S)
dumpfs(S)
dup(2)
dup(2)
shutdown(2)
dup(2)
ctime(3)
ec(48)
echo(t)
csh(l)
echo(l)
csh(l)
ecvt(3)
ed(t)
end(3)
ex(l)
vipw(S)
sad(l)
ed(l)
ex(l)
Id(l)
sed(l)
view(l)
vi(l)
a..out(5)
whoami(t)
setregid(2)
aetreuid(2)
vfork(2)
grep(l)
insque(3)
soelim(l)
csh(l)
tektool(l)
en(48)
lIetquota,(2)
uuencode(S)
crypt(l)
uuencode(lC)
crypt (3)

January 1984

Permuted Indez
•••••••••••••••
crypt, setkey, encrypt - DES encryptioa.
•••••••••••••
makekey - senerate encryption key.
end, etext, edata - last locations in program.
•••••
sccs - front end for the .SM SCCS subllystem.
losout: end .e••ion. • • • • • • • • • • • • • • • • • • • •
end: terminate loop.
••••••••••••••••
/setfaspec, setfs&le, setfstype, setfsent, endfsent - get file system descriptor file entry. • • • • •
•••••••
setsrent, setsrsid, setsrnam, setsrent, endsrent - let croup &Ie entry.
setholtbyaddr, setholtbyn&Dle, lIethostent, endholtent - let network hoat entry. letholtent,
end if: terminate conditional.
•••••••
setnetent, setnetbyaddr, sebetbyname, letnetent, endnetent - let network entry.
•••••••
locket - create an endpoint for communicatioa.
setprotobynumber, setprotobyname, letprotoent, endprotoent - let protocol entlY. letprotoeDt,
setpwent, setpwuid, setpwnam, letpwent, endpwent -let paslword &Ie entry. • ••
setlervbyport, cet1ervbyname, letlervent, endlervent - let semce entlY. cetaervtnt,
endsw: terminate switch.
number - convert Arabic numerall to Enclish. • • • • • • • • • • • • • • •
xllend, xcet, enroll - secret mail. • • • • • • • • • •
•••••••••••
nlilt - get entriel from name lilt.
endfllent - get &Ie syltem descriptor &Ie eatry. /cetfsspec, getfllile, cetfltype, setflent, • • • • •
getgnaam, lIetcrent, endcrent - get croup &Ie entry. leterent. CetCreid, • • • • • • • • • • • • • •
lethostent, endhostent - set network holt entry. cetholltent, cetholltbyaddr, cetho.tbyname,
•••••••
setnetbyname, letnetent, endnetent - get network eatry. cebetent, cetaetbyaddr,
letprotoent, endprotoent - set protocol entry. /cetprotobynumber. getprotobyaame,
•••••
setpwnam, letpwent, endpwent - set pUlword &Ie entry. cetpwent, Cetpwuid, • • • • • • • • •
letlervent, endlervent - get lIervice entry. cetaervent, cetaervbyport, cetservbyname,
• • • • • • •
IYIIOI - make Iystem 101 entry.
unlink - remove directory eatry. • • • • • • • •
unlink - remove a directory entry. •• _ • • • • ••
execl, exeeY, execle, execlp, execYp, environ - execute a file.
enviroa - uler environment.
letenv; let variable in environment.
environ - uler environment.
printenv - print out the environment.
luntool. - the Suntooll window environment.
tlet - eltablilh terminal charaeteriltica for the environment.
••
leteDv - value for environment name.
unletenv: remove environment variabltl.
let.Dv - let value of environ meat variabl ...
eqncbar - Ipecial character definitionl for eqa.
• ••••••
derol- remove Drol, trol, tbl aDd eqa con.tructl. • • • • • • • • • • •
eqa, aeqa, checkeq - typeset mathematica. •••
eqnchar - Ipecial character definitions for eqa.
linemod, Ipace, cloaepl - sraphael/ openpl, erue, label, line, circle, arc. move, cont, poiat,
perror, SYI_errlilt, Iyl_nerr, ermo - sy.tem error mesllac... • • • • •
meslagtl. error - analyse and dispel'le compiler error
dmeal - collect IIYltem dialnoltic mesllasea to form error 10C.
••••••••••••••
mbtr - create aD error melllage &Ie by musaginl C lource.
error - analy.e and dillpene compiler error meslasea.
• • • •
perror, IY'_errlin, ,yI_nerr, errno - Iystem error mellagd.
perror, lerror, iermo - set Iyltem error mellagea.
intro - introduetion to systemcaUs and error numben,
eyacc - modi&ed yace allowinl much improved error recovery.
Ipell, spelli., apeUout - &nd spellinl erron.
• ••
cha.e - Try to escape to killer robot..
••••••••
e."ironment. tld- eetablilh terminaichar&eteriltics for the
end, etext, edata - lut location. in prolf&m.
ec - 3Com 10 Mb/. Ethernet interface. • • • • • • • • •
en - Sun S Mb/I experimental Ethernet interface. • • • • • • • • •
hypot, cab. - Euclideaa distance. • • • • • • • • • • • • •
for, cale, if, while, :, ., break, continue, cd, eval, exec, exit, export, login, newcrP, read,! sh,
eVal: re-evaluate shell data.
•••••••••
expr- evaluate arcumenta &I loa exprellllioa. • • • • •
eval: re- evaluate IIheU data.
history: print hiltory event Iiat. • • • • •
- IIcreen oriented (visual) display editor bued on ex. vi
••••••
ex, edit - text editor.
Ipq - spool queue examination prosram.
•••••••••••
/ealle, if, while, :, ., break, continue,cd, eval, exec, exit. export, login, newgIp, read, readonly./
exec: overla.y ahell with apeci&ed command.
••
execute a &Ie. exed, execv. execle, exeelp, execvp, environ ex ecl , execv, exede, execlp. execYp, environ - execute a file. • • • • •
execl, execv, exeele, execlp, execvp, environ - execute a &Ie.
sticky - executable &Ie. with peniatent text.
exec', execv, exede, exedp, execYp, environ - execute a file.
execve - execute a file.
•••••••••

January 1984

- xii -

crypt(S)
makekey(S)
end(S)
.ces(l)
csh(l)
c.h(l)
cetfsent(S)
cetsrent(S)
cetho.tent(SN}
cah(l)
letaetent(SN}
.ocket(2)
cet protoent( 3N)
cetpwent(S)
letlervent(SN)
c.h(l)
aumber(6)
xlend(l}
alilt(3)
cetfaent(S}
cetcrent(S)
cethostent(SN)
cetnetent(SN)
cetprotoent(SN)
cetpwent(S)
cetaervent(SN)
.yaloc(l)
1lnlink(2)
1lnlink(SF)
execl(S)
environ(5)
c.h(l)
environ(5)
printenv(l)
I1lntoola( I)
betel)
cetenv(3)
csh(l)
cetenv(3F}
eqnchar(7)
deroB'{l)
eqn(l)
eqnchar(7)
plot(3X)
perror(S)
error(l)
dmesc(S)
mbtr(l)
error(l)
perror(3)
perror(SF)
intro(2)
eyacc(l)
.pell(l)
chase(6)
,set(l)
end(S)
ec(4S)
en(4S)
hypot(3M)
sh(l)
cllh(l)
expr(l)
cah(l)
Cllh(l)
vi(l)
ex(l)
Ipq(l)
sh(l)
cah(l)
execl(3)
execl(3)
execl(3)
sticky(8)
ex ecl (S)
execve(2)

Sun System Release 1.1

Permuted Inclez
alarmsystem repea.t:
at lutcomm - show la.at commands
uu - unix to unix command
acdsleep - suspend
sleep - suspend
sleep - suspend
monitor, !Donatanup, moncontrol - prepare
pxp - Pa.acaJ
rexecd - remote
profilpix - Palcal interpreter and
file. exed,
exed, execv, exede, execlp,
link. symlnk - make a link to aD
tunefl - tuDe up aD
pendiDloutput.

/il, whil.,

:•. , bruk. conti Due. cd. eva.l. exec,
breaksw:
break:
logarithm. power, Iquare root.
Ilob: fileume
expand. unexp&lld vena.
en - SUI. 3 Mb/I

adveDture - aD
frup. Idap. modI - split iDto maDtina and
exp. 101. 10110. pow •• qrt /while. :•.• break. conti Due. cd. eval. exec. exit.
apr - evaluate a!'lUmeDt. u aD
re_comp. re_exec - regula.r
addbib - create or
letfd -let the &1. descriptor of an
strinl'. x.trrecovery.
ioinit - change
tclo.e, tre&d. hrrite, trewin, tlkipf, tstate fUDctionl.
sip'" - simplifted software .i,ul
• igvec - software signa.!
arithmetic - provide drill in number
patat - print sy.tem
true,
iDet - Internet protocol
without checkinl the disks.
the dilks. futboot,
abort - generate I.
trptpe, fpeclt - trap and repair Bolotin I point
chmod,
chown,

ecvt.
fopen. freopen,
ferror,
inquiries.
bale subroutines. dbminit,
head - display first
fdose,
beopy, bcmp, blero,
getc,
stream. getc, get char,

SUD System Release 1.1

execute a subroutine after a specified time.
execute a UNIX command.
execute command repeatedly.
execute commands at a later time.
executed in reverse order.
execution. • • • • • •
execution accounting file.
execution for an intelYaJ.
execution for an intelYaJ.
execution for interval.
execution profile.
execution profiler.
execution server.
execution time profile.
executor.
• ••••
execv, exede, execlp, execvp, environ - execute a
execve - execute a file.
execvp, environ - execute a file.
existing file. • • • • • •
existing file system. • • • • • • •
_exit - terminate a procesl.
exit - termiute a procen after flushing any
• •
exit - termiute procesl with status.
exit, export, lolin, newgrp, read, readonly, set.!
exit from switch.
••••••••••
exit: leave shell.
exit while/foreach loop. • • • • • • • •
exp, 101, log10, pow. sqrt - exponential,
expand arsument lillt. • • • • • • • • •
expand tabs to spaces, and vice versa.
expand, unexpand - expand tabs to spaces, and vice
experimental Ethernet interface.
expire - remove outdated news art ides.
exploration lame.
•••••••••
exponent. • • • • • • • • • • • • •
exponential, logarithm, power, square root.
export, lolin, new,rp, read, readonly, set, shift.!
expr - evaluate argumentll as an expression.
expressioD.
• •••••••
expression handler. • • • • • •
exteDd bibliographie da.ta.base.
external unit number. •• • • •
extract .trings from C programe to implement shared
eyacc - modified yacc allowing much improved error
177 - FORTRAN-77 compiler.
177 I/O initialilatioD. • • • • • • • • • • •
177 tape I/O. topen, • • • • • • • • • • •
fab., floor, ceil - absolute value, floor, ceiling
facilities.
• • • • •
faciliti •.
fact •.
fact..
" •••••
II. lIe - provide truth values.
lalse, true - provide truth values.
family.
•• '. •
<
•
•
.'
•
•
•
•
faatboot, luthalt - reboot/halt the system
••
lion halt - reboot/halt the system without checking
f&ult. • • • • • • • • • • • • • • •
laultl.
•••
fbio - general properties of frame buffers.
Ichmod - change mode of file.
IchoWD - change owner and group of & file .
felole, mush - close or flush &IItream. • • • • •
fcntl - file control.
••••.•
Icntl - file control options. • • • • • •
fcvt, gm - output conversion.
fdopeD - opel. & stream. • • • • • . •
feof, dearerr, fileno - stream sta.tus inquiries.
ferror, feof, dearerr, fileno - stream status •
fetch, store, delete, first key, nextkey - da.ta.
few lines of ilpecified files.
mush - dose or flush a stream. • •
fFs - bit and byte string operations.
f,: bring job into foreground.
fgetc - get a character (rom a logica.l unit.
.fgetc, getw - get character or integer (rom
0

- xiii -

'0

•

•

•

•

•

•

•

•

•

•

•

•

a.1a.rm(3F)
system(3F)
csh(l)
a.t(l)
la.atcomm(l)
uux(IC)
acct(S}
IIleep(l)
IIleep(3F)
sleep(3)
monitor(S)
pxp(l)
rexecd(8C)
profil(2)
pixel)
exed(S)
execve(2)
exed(S)
link(3F)
tunefs(8)
exit(2)
exit(S)
exit(SF)
IIh(l)
csh(l)
csh(l)
csh(l)
exp(SM)
csh(l)
expand(l)
expa.nd(l)
en(-iS)
expire(S)
adventure(6)
frexp(S)
exp(SM)
sh(l)
expr(l)
expr(l)
regex(S)
addbib(l)
getfd(SF)
xstr(l)
eyacc(l)
177(1)
ioinit(3F)
topen(3F)
floor(3M)
signal(3)
.igvec(2)
arithmetic(6)
pstat(S)
true(l)
false(l)
inet(-iF)
fastboot(S)
fast boot (S)
a.bort(3)
trpfpe(3F)
fbio(-iS)
chmod(2)
chown(2)
Iclose(3S)
fcntl(2)
fcntl(S)
ecvt(3)
fopen(3S)
ferror(3S)
ferror(3S}
dbm(3X)
head(l)
fclose(3S)
bstring(3)
esh(l)
getc(3F}
getc(3S)
January 1984

Permuted [nde.

.

lets,
rrep, f!grep,
accell - determiDe accessibility of
accell - determiDe accesllability of a
acd - executioD accouDtiDe
chmod, fchmod - chaDge mode of
chmod - chaDse mode of a
chowD, fchowD - chaDle OWDer aDd group of a
colrm - remove columDs from a
core - format of memory imale
creat - create a new
louree: read commaDdl from
ctass - create a bp
dd - cODvert aDd copy a
delta - make a delta (chaDle) to loa sees
execY, execle, execlp, exec:vp, eaviroa - execute a
execve - execute a
- apply or remove loa advilory lock oa loa opea
fpr - priat Fortraa
let - let a venioD of aD soes
croup - IrouP
liDk - make a hard liak to a
liDk, symlak - make a liak to &a existiDI
mkdir - make a directory
mkaod - make a Ipecial
mkDod - band .pecial
more, pace - browse throalh a text
- rebuild the data bue for the mail aliuel
opea a file for readial or writiDl, or create a Dew
pUlWd - pUlWord
pn - priDt &a sees
remote - remote holt descriptioa
renme - chaale the Dame of a
reDame - reDame a
rev - revene lia.. of a
rmdel - remove a delta from aD sees
rmdir - remove a directory
Iccldi. - compar. two venioal of &a sees
,cCllle - format of sees
lile - .ile of loa object
printable ItriD11 iD aa object, or other biDary,
lam - 111m &ad coaDt blocb iD a
I)'mliDk - make .ymbolic liDk to a
tail - dilplay the lut part of a
tmpnam - create a aame for a temporary
touch - update date lut modified of a
unlet - undo a previoul let of loa sees
aniq - report repeated linel iD a
uueacode - format of an encoded auencode
val- v&lidate sees
vipw - edit the punord
VIW&P - conven a foreip font
write, write" - write on a
dil - dilereDtial
cpio - copy
mbtr - create aD error mellale
dilS - S-way dilferential
fcntlfcntlrcp - remote
umuk: chaale or dillplay
umuk -let
letfd - cet the
Bad - priDt current sees
setfsent, eDdfseDt - get file system descriptor
getgrgid, getgrnam, setgrent, endgrent - let croup
getpwnm, setpwent, endpwent - let pUlIWord
grep, egrep, fgrep - search a
opeD - open a
Dewsre - informatioD
aliueI - aliues
uueDcode,uudecode - eDcodt/decode a binary
lor - archive (library)
tar - tape arehive
which - locate a program

January 1984

fgeh - Ce\ a ItriDI from a stream.
fgrep - search a file for a pattern.
file.
file. • • • • •
file.
file.
&Ie.
file.
file.
file.
file.
file.
file.
file. • • • • •
file. ••
file. exed,
fil.. • • • • •
file. lock
file.
file.
lie.

lets(SS)
lrep(l)
accesll(2)
accesll(SF)
acd(S)
chmod(2)
chmod(SF)
chown(2)
colrm(l)
core(S)
creat(2)
csh(l)

«ap(l)

dd{l)
delta.(l)
exeel(S)
execve(2)
lock(2)
(pr{l)
let{l)
erouP(S)
link(2)
II.. . ••••
Iink(SF)
file.
file.
mkdir(2)
mknod(2)
II•.
fil •.
mknod(8)
more(l)
fil.. • • • •
newaliases(S)
fil.. newaliueI
file. OpeD ••••••
open(2)
palllwd(S)
file.
pn(l)
fil •.
remote(S)
fil •.
reDame(2)
fil •.
II•.
rename(SF)
II•.
rev(l)
file.
rmdel(l)
rmdir(2)
II•.
fil •.
Iccsdif(l)
II•.
Iccsfile{S)
II.. • • • . • • .
lile(l)
lie. ItriDP - Ind
Itrinls(l)
file.
I11m(l)
fil •.
,ymliDk(2)
II•.
tail(l)
II•.
tmpn&m(Se)
II•.
toach(l)
II•.
.neet(l)
fil •.
aniq(l)
II•.
1Iuencode(S)
file.
val(l)
II•.
vipw(S)
fil •.
vlwap(l)
II.. . . . . • • •
write(2)
II. - determine file type.
•
ile(l)
fil. load directory comparator.
•••••
dil{l)
file archivee in and ou'" ••
cpio(l)
file by mUlacinl 0 louree.
mkstr(l)
file compariloD.
diIS(I)
file control.
fcntl(2)
file control optionl.
fcntl(S)
file copy.
rcp(IO)
file creatioD mask.
clh(l)
file creation mode mask. • • • • • • •
1Imuk(2)
file descriptor of an external unit Dumber.
letfd(SF)
file editiDI activity. • • • • • • • • •
lad(l)
fite entry. /Ietfsspec, letfsfile, letfstype,
letfseDt(S)
fite entry. letgrent,
•••••••••
letgreDt(S)
file entry. letpwent, getpwuid,
letpweDt(3)
file for a pattern< • • • • • • • • • • • • • •
lrep(l)
file for readinl or writiDl, or create a new file. • • • • • opeD(2)
file for readDews(l) and checkDews(I).
Dewarc(S)
file for 8IDdmail. • • • • •
aliues(S)
file for transmillllioD via mail.
1Iuencode(10)
file format.
••••••••••••
ar{S)
file format.
••••••••
• •
tar(S)
file iDcludiDI aliases &Dd paths (ellh oDly).
which(l)
- xiv-

Sun System Releue 1.1

Permuted lndez
fspli~

- spli~ a multi-routine Fortran
split - split a
pmerge - pucal
mktemp - make a unique
fseek, Itell - reposition a
stat, Istat, fstat - get
mkfs - construd a
mkproto - construct a prototype
mount, umount - mount or remove
mount, umount - mount and dismount
newfs - construct a new
8etquota - enable/disable quotas on a
tunefs - tune up an existin,
repair. fsdesetidle, getfstype, setlsent, endfsent - get
dcheck dump - incremental
hier dumpls - dump
quo~ - summarile
restore - incremental
icheck mtab - mounted
fs, inode - format of
df - report free disk space on
utime - set
utima - set
uusend - send a
truncate, ltruncate - truncate a
ltp ltpd - DARPA Internet
tftpd - DARPA Trivial
tile - determine
editor. vi - view a
buename - strip
glob:
ferror, leof, clearen,
Admin - create and administer sees
checknr - check nroff/troff
cmp - compare two
comm - sel.n or reject lin •• common to two sorted
confic - build l)"Item confi,uration
cp - copy
tind - tind
split a multi-routine Fortran tile into individual
head - display fin~ l.w lina of specified
install - install
MAKEDEV - make system special
mv - move or rename
Il.W. - USENET network news ..niele, utility
rmdir, lID - remove (unlink) directoria or
sort - sort or mer,e
~ .. - copy standard output to many
what - identify the venion of
comp&C~, uncompact, ccat - com pres. and uncompre..
intro - introduction to special
catman - create the cat
lsync - synchronise a
lID, lIDdir - remove (unlink)
pr - print
• ticky - executable
fstab - static information about the
colcrt -'
colplot - graphic.

(split(l)
tile into individual tiles.
file into piece3.
spiit(l)
tile merger.
pmerge(l)
mktemp(3)
file name.
• ••••
tile on a logical unit.
fseek(3F)
file status.
stat(2)
mkfs(8)
tile system.
mkproto(8)
tile system.
mount(2}
tile system.
mount(8)
tile system.
newfs(S)
tile system.
setquota(2}
tile system.
tunefs(8)
tile system.
• ••••••••••••
tile system consistency check a.nd interactive
fsck(8)
tile system descriptor tile entry. /getfsspec,
getfsent(3)
tile system directory consistency check.
dcheck(8)
tile system dump.
dump(S)
tile system hierarchy,
hier(1)
dumpfs(S)
tile system information.
quot(8)
tile system ownership. ••
tile system restore.
• • • • •
restore(8)
tile system storage consistency check.
icheck(S)
mtab(5)
tile system table.
Is(5)
tile system volume.
df(l)
tile systems.
utime(3C)
file times. • • • • •
utimes(2)
tile times.
tile to a remote host.
uusend(lC)
trunca.te(2)
tile to a specitied length.
ftp(lC)
tile transfer program.
File Transfer ProtoeolselVer.
Itpd(SC)
tftpd(8C)
File Transfer ProtocolselVer.
• •••••••••••••
tile type.
file(l)
tile without cha.nging it using the vi visual
view(l)
• ••••••
tilename afrlXes.
basename(l)
csh(l)
tilename expa.nd argument list.
ferror(3S)
tileno - stream statUI inquiriee.
tiles.
admin(l)
tila.
checknr(l)
cmp(l)
fila.
comm(l)
tila.
config(S)
tila.
cp(l)
tila.
tila.
•••
tind(l)
tila. fsplitfsplit(l)
hea.d(l)
fila.
install(l)
fila.
fila.
makedev(8)
tila.
mv(l)
fila.
news(S)
rmdir(l)
fila.
fila.
sort(l)
tee(l)
tila.
• ••
what(t}
tila.
tila, and cat them.
compact(l)
tiles and hardware support.
intro(4)
fila for the manna.i.
• • • •
catman(S)
tile'. in-core state with tha.t on disk.
fsync(2)
tiles or directoriel.
•••••••
rm(l}
tile(s), possibly in multiple columns.
pr(l)
tila with persistent text .
sticky(S}
tilesystems.
•••••••••••••
Istab(S)
colert(l)
tilter nro' output for CRT previewing.
tilter reverse paper motions. • • • • •
col(l)
tilters.
•••••••••••••••
• • • • • plot(lG)
tind(l)
tind - tind tiles.
• •••••••••••••
refer(l)
refer - tind a.nd insert literature references in documents.
find(l}
• ••••••••••••
tind - find tile..
••••••
look(l)
look - tind lines in a sorted list.
man(l}
man - print o~t manual pages; tind manual information by keywords.
ttyname(3)
ttyname, isatty, ttyslot - find name 01 a terminal" • • • • • • •
ttynam(3F)
ttynam, isatty- tind name ol a terminal port.
•
lorder{l)
lorder - tind ordering rela.tion lor an object library.
••
strings(l)
binry, tile. string1- tind printa.ble strings in an object, or other
indxbib(l)
inverted index to & bibliogra.phy .br lookbib - tind references in a bibliography. indxbib - make
spell(l)
spell, "pellin, spell out - find spelling errors. • • • • • •
0

SUD System Release 1.1

- xv·

•

•

•

•

•

•

•

•

January H)84

Permuted /ndes
fold - fold long linea for inite width outpu~ device. • • • • • • •
head - display ir~ few line. of .peaied ilee. • • • • • • • • • •
dbmini~, fe~eh, store, delete, inttey, nex~tey - dab bue subrou~inee.
••••••••••••••••••••
ish - play "Go Fish".
ish - play "Go Fish n.
••••••••
valuea, 8min, 8mu, d8mia, dlma.x, inma.x - retUrD extreme
extreme valuel. Imia, 8mu, dlmin, d8ma.x, inma.x - re~um
•••••••••••
~rpfpe, fpec:D~ - ~rap and repair loating poin.~ fa.ul~l.
•••••••••••
fptype - check a 10Ating point aumber.
isinf, isnan - teat for indeterminate 80Atini point v&!Utl. • • • • • • • • • • • •
open ile. lock - Apply or remove aa advi.ory lock oa ...
functionl. fabl, loor, ceil - Ab.olute v&!ue, loor, ceilin,
•••••••
fabl, loor, ceil - ablolute value, loor, ceilinl functionl.
IUlh - IUlh output. to I. 101ic&! uait.. •••••
fclose, lIulh - close or lush I. Itream. • • • • • •
lush - lush output. to I. losic&! uait..
exit - terminate a procesl alter lushia, Aay peadia, output
fmt - .imple text formatter..
••
device. fold - fold 10a,lia" for fiaite width outpu~ • • • • • •
fold - fold 10a,liael for inite width output device. • •••••
Vlwap - convert I. foreiga foat file. •• • • • • • • • • • • • • •
••••••••••••
vfoat - foat formAt..
fopea, freopea, (dopea - opea I. etreAm.
breAk: exit while/ fore loch loop. • • • • • • • •
fore&eh: loop over lilt of aames.
(,: brin, job into foreground.
• • • • • • • ••
•••••••
VIWAP - conven I. foreip foat file.
fork - creAte I. copy of thi. procell.
fork - cre..te .. aew procell.
idAte, itime - retura dAte or time ia aumerie&! form.
dmeal - collect. SYltem diagaostic messagtl to fQrm error 101.
lor - archive (libnry) ile formAt.
dump, dumpda.tes - iacremeat&! dump form.."
.' •
tar - tape Archive ile formA"
••••
kbd - keybOArd tnaslAtioa tAble formAt aad defaul~ t .. bl•.
iadeat - iadeat &ad formAt 0 prognm lource.
~
trol - typeset or formAt documents.
• • •
htAble - coaven MO .t&adArd form..t. ho.t tabltl.
,.tt.Able - get NIO formAt hOlt ~Abltl from I. ho.~ .
uueacod. - form ..t of An eacoded uuencod. fil•.
cpio - form ..' of cpio Archive.
dir- form..t. of direet.ories.
fI, iJlod.- formAt. of fil. ')'It.em volum•.
core - form ..t of memory im"lt file.
.ccslle - formAt of soes file.
tbl- form ..t t&bltl for arol or trol.
tp - DEC/ma.c tape form ..t.. • • • • • • • • •
vfoat. - foat form..t.. • ••••••••
.c..nf, feeaaf, IlcAaf - formAt.ted input. eoavereioa.
priatf, fpriatt, Ipriatf - formAtted output. convenioa.
fm~ - .impl. tex~ formAtter.
• •••••••
arol- text. form&ttia, And typellett.ing.
IDI - text form ..tt.iJlI mAcrOI.
me - macrol for format.tia, p..pen.
ntfor - r..tioaal Fortm diAlect.
•••••
fpr - priat Fortna file.
•
f.plit - spli~ a multi-routia. Fortm file iato individu&! ile•.
iatro -iatroductioa to FORTRAN library functioal.
• ••••
putc, fpu~c - write I. character to I. FORTRAN logic&! uait..
177- FORTRAN·77 compiler.
• • • • • • •
Adage. fonuae - print. a random, hopefully intereating,
trpfpe, fpeeat - trap And repair loatinl poiJlt fAulh.
fpr - prin~ Fonr... file. • • • • • • • • • •
priatf, fprintf, Iprintf - formatted output convenioa.
fptype - check a loatinl point number.
uait., putc, fputc - write a character to a FORTRAN logical
putc, put char, fpute, putw - pu~ character or word on a etream.
pute, fputs - put a IItring on a etream. • • • • • • • • • • •
bw - Sua black and white frame buller. • • • • • • • • • • • • • •
fbio - gener&! propeniee of frame bulen.
•••••••••••••••
fread, fwrite - bultred binAry input/output.
df - report free disk space Oil file system.. • •.•••••
allocator. ma.lIoc, free, realloc, calloc, efree, Alloa - memory •••
fopea, freopen, fdopen - open a stream. • • • • • •
exponent frexp, Idexp, modf - spli~ into mantiSSA and
from - who is my mail fromT.
••••••••••••••••

Ja.nuary 1984

- xvi -

fold(l)
head(l)
dbm(SX)
fiah(6)
ish(6)
range(SF)
range(SF)
~rpfpe(3F)

fptype(SF)
iainf(S)
8ock(2)
loor(3M)
100r(SM)
lush(SF)
fclose(SS)
8uah(SF)
exit(S)
fmt(l)
fold(l)
fold(l)
Vlwap(l)
vfont.(S)
fopen(SS)
cahIll
c.h 1
cah 1
Vlwap(l)
fork(SF)
fork(2)
idate(3F)
dmeag(8)
Ar(S)
dump(S)
t.ar(S)
kbd(S)
indent(l)
~rol(l)

htAble(8)
,e~table(8C)

uuencode(S)
cpio(S)
dir(S)
"(5)
core(S)
Icceile(5)
~bl(l)

tp(S)
vfont(S)
ICAnf(SS)
printf(SS)
fmt(l}
nrol(l)
ms(7)
me(7)
ra.tfor(l)
fpr(l)
fllplit(l)
intro(SF)
putc(SF)
177(1)
fonune(6)
trpfpe(3F)
fpr(l)
printf(SS}
fptype(SF)
putc(SF)
pute(SS)
puta(SS)
bW(4S)
fbio(4S)
fread(SS)
df(l}
malloc:(S}
fopen(3S)
frexp(S)
from{l)

Sun System Release 1.1

Permuted Indez
sccs scanf,
interactive repair.
unit.
individual filell.
stat, 1st at,
on disk.
fIIeek,
fseek,
time,

tha~

server.
truncate,
IIhutdoWD - shut dowD part of a
,amma - 101 ,amma
fabl, loor, ceil - ablolute value, loor, ceilinl
intro - introductioD to library
intro - introduction to compatibility library
intro - introductioD to FORTRAN library
intro - introduction to mathema.tical library
intro - introduction to network library
jO, jl, jn, yO, yl, yn - bessel
cos, to, asiD, aCOI, ataD, atan2 - tri,onometric
linh, c08h, tanh - hyperbolic
cunes - screen
fread,
adventure - an exploration
monop - Monopoly
Inake, snscore - displa.y chue
trek - trekkie
worm - Play the srowin, worm
cofield, cfscorel - the solita.ire card
eribba.ce - the card
hancman - Computer version of the
back,ammon - the
bossle - play the
wump - the
,amm& -101
itom, madd, mlub, mult, mdiv, min, mout, pow,
ecvt9 fcvt,
bulen. k,monabort adb,en makekeyncheck raad, Brand - random number
lex /initetate, sets tate - better random number
random number ,enerator, routines for chansinl
dkio perror,

inteser from stream.
from IItream. ,etc,
directory.
,etsid,
,etuid,
unit number.
8etfleni, endfsen~ - ,e~ file system descriptor/
ile system de8criptor file/ getfsent, getfsspec,
- let file lIystem descriptor file/ getfsent,
descriptor 6.le/ letfseDt, getfsspec, getfsfile,
getuid,
g~ group file entry.
file entry. getgrent,

SUD

System Release 1.1

front end for the .SM SCCS subsystem.
fs, inode - forma.t of file system volume.
fscanf, 8scanf - forma.tted input conversion.
fsck - file system conllilltency check a.nd
flleek, ftell - reposition a file on a logical
flleek, ftell, rewind - repositioD a. stream.
fspli~ - split a multi-routine Fortran file into
fstab - static information about the filesystems.
fstat - get file sta.tus. • • • • • • • • • • •
fIIync - synchronize a. file's in-core state with
ftell - reposition a file on a logical unit.
ft ell , rewind - reposition a. stream.
•••••
ftime - get date and time. • • • • • • • • • • • • • •
ftp - file tra.nsfer program.
••••••••
ftpd - DARPA Internet File Transfer Protocol
ftruncate - truncate a file to a specified length.
full-duplex connection.
function.
functions.
functions. • • • • •
functions.
functionl.
functionl.
functionl.
functions.
functionl. sin,
functions.
• •
•
functionl with "optimal" cursor motion.
fwrite - bulered binary input/output.
,lome.
,lome.
,lome.
,lome.
,lome. •
,lome ca.nfield.
,lome cribba,e.
,lome han,man.
,lome of back,ammon.
,ame of bossle.
,ame of hunt-the-wumpus.
,amma - 10, ,amma function.
,amma function. • • • • • • • • • • • • •
,cd, rpow - multiple precision inteser arithmetic.
Icore - ,et core ima,es of runnin, processes. • •
sm - output convenion.
••••••••••
,enerate a dump of the operating system'lI profile
,enerate a fault..
•••••••
,enerate adb IICript.
••••••
,enerate encryption key.
,enerate Dames from i-numbers.
,enerator. • • • • • • • • • • • •
,enerator of lexical analysis programs.
•
•
,enerator, routinell for changing generators.
generators. /srandom, initsta.te, sehtate - better
,eneric disk control operations.
••••••
gerror, ierrno - ,et sYlltem error melllla.ges. •••
setaTS, iarsc - return comma.nd line arguments.
,etc, fgetc - ,et a character from a logica.l unit.
,etc, ,etchar, fgetc, ,etw - ,et character or • • • • • •
,etchar, f,ete, ,etw - ,et character or integer
,etcwd - ,et pathname of current 'Working
,etdate - convert time a.nd date from ASCII.
,etdtablesize - ,et descriptor table sire.
getesid - get group identity. • • • • • • . •
,etenv - get value af environment variables.
getenv - value for environment name. •• • •
geteuid - get uller identity.
••••••••
getfd - get the file descriptor of a.n externa.l
getfllent, getfllllpec, ,etfsfile, getfstype,
getfllfile, getfstype,setfsent, endfsent - get • •
,etfllllpec, getfsfile. getfstype, lIetfsent, endfsent
getfstype, setfllent, endfllent. - get file system • •
getgid - get uller or group ID of the ca.ller. •••
getgid, getegid _. ge~ group identity.
•..••
getgrent, getgrgid, getgrnam, setgrent, endgrent getgrgid, getgrnam, lIetgrent, endgrent - get group
- xvii -

sces(t)
fs(5)
scanf(SS)
fsck(8)
fseek(3F)
fseelc(SS)
fsplit(l}
fstab(S)
stat(2}
fsync(2)
fseek(SF)
fseelc(SS)
time(SC)
ftp(tC)
ftpd(8C)
truncate(2)
shutdown(2)
gamma.(SM)
Ooor(3M)
intro(3)
intrO!SC)
intro SF)
intro SM)
intro(SN)
jO(SM)
sin(3M)
sinh(3M)
cUfBes(SX)
fread(SS)
adventure(6)
monop(6)
snalce(6)
trelc(6)
worm(6)
canfield(6)
cribbage(6)
hangman(6)
baclcga.mmon(6)
boggle(6)
wump(6)
gamma(3M)
gamma(SM)
mp(SX)
gcore(t)
eevt(3)
kgmon(8)
abort(S)
adbgen(S)
makekey(S}
ncheck(8)
ra.nd(SC)
lex(l)
random(S)
random(S)
dkio(4S)
perror(SF}
getarg(SF)
getc(3F)
getc(SS)
getc(3S)
,etcwd(SF)
getdate(S}
,etdtablesire(2)
getgid(2}
getenv(SF)
getenv(S)
getuid(2)
getfd(SF)
getfsent(S)
getfsent(3 )
getfsent(3)
getfsent(3 )
getuid(3F}
getgid(2)
getgrent{3}
getgrent(3)
Ja.nua.ry 1984

Permuted Indez
entry. getgrent,

get~d,

endhostent - get network host entry. gethostent,
network host entry. gethostent, gethostbyaddr,
letholtent, endholtent - get network host entry.

getgrnam, lIetlrent, endgrent - get group file
get groups - get group access list. • • • • • • • • • • •
gethostbyaddr, gethostbyname, sethostent,
gethostbyname, sethostent, endhostent - get
gethostent, gethostbyaddr, gethostbyuame,
••
gethostid - get unique identifier of current host.
•
gethostname, lethostname ~ get/set name of current
getitimer, setitimer - get/set value of intelV&1 • • • • •
getlol - let user's login name. • • • • • •
getlogin - let login name. ••
getaetbyaddr, get net byname , setnetent, endnetent getnetbyname, .etnetent, endnetent - get network
letnetent, letnetbyaddr, getaet byname, letnetent,
getopt, optarg, optind - get. option letter from
getp&lOlile - get system page sile.
letpul - read a pusword.
getpeername - cet name of connected peer.
letpgrp - get proces. group.
letpid - cet proceu id.
• • • • •
getpid, getppid - get proces. identification.
letppid - let procell identification.
let priority, letpriority - let/let program
•
letprotobyname, letprotoent, endprotoent - get
letprotobynumber, getprotobyname, letprotoent,
letprotoent, letprotobynumber, getprotobyname,
letpw - get name from uid.
•
letpwent, letpwuid, letpwnam, setpwent, endpwent letpwnam, letpwent, endpwent - let password file
letpwuid. letpwnam, letpwent, endpwent - get.
letrlimit, letrlimit - control maximum system
letrull&le - let information about resource
getl, fleh - get a strinlfrom a stream.
• • • • •
letlervbyaame, lIetselVent, endservent - let
letlervbyport, cetselVbyname, letlervent,
getlervent, getservbyport, getservbyaame,
letsockname - get socket name.
letlockopt, setsockopt - get and set options on
gettable - get NIC format host tables from a host
lettimeofday, settimeofday - let/set date ud
letty - let terminal mode.
lettytab - terminal configuration data bale.
••
getuid, geteuid - let uller identity.
getuid, letlid - let user or group ID of the
getw -let character or integer from stream.
letwd - get current working directory pathname.
live advice to paginlsystem.
given time.
• •••••
Ilob: filename expand argument list.
•••
Imtime, uctime, timelone, dysile - convert date
Go Fillh". • • • • • • •
0

get network entry. getnetent,
entry. getnetent, getnetbyaddr,
endnetent - get network entry.
a1"gV.

0

0

0

0

0

0

let P&IISWOrd file entry.
entry. getpwent, letpwuid,
pusword file entry. letpwent,
resource consumption.
utilil&tion.
selVice entry getservent, letselVbyport,
endllervent - get selVice entry. letselVent,
setselVent, endselVent - let lIelVice entry.
locket •.
time.

•

0

0

0

0

0

00

0

0

•

0

0

0

0

0

0

0

0

0

0

vadvise IIhutdown - clolle down the lI,Y11tem at a

0

0

0

0

0

0

0

••••

0

•

•

•

0

0

0

0

0

0

0

0

•

0

0

•

•

0

0

•

•

0

•

0

••

0

•

0

0

•

•

•

•

0

•

0

0

0

0

0

&nd time to ASCII. ctime, localtime,
fish _ play U
lIetjmp, longjmp - non-local lotO. . . . . . . . . . . . . . . . . .
goto: comm&lld trusler.
•••••
gprof - dillplay call graph profile data.
• ••••••••••••
graph - draw & graph.
graph - draw a graph.
• •••••
Drof - display call Ira ph profile data.
••••••••••••
perlmon - lraphical dilplay of general system Itatiltics.
ptest - stand alone test for the Sun video graphiCl board.
colordemol - demonstrate Sun Color Graphics Dillplay.
draw - interactive graphics drawinl.
plot - lraphics filten.
CI - Sun color graphics interlace.
••••••••••
arc, move, cont, point, linemod, Ipace, dOllepl - graphics interlace. /erue, label, line, circle,
plot - graphics interface.
••••••••••••
grep, egrep, fgrep - search a file for a pattern.
vgrind - grind nice listings of programa.
chgrp - change group.
get pgrp - get process group.
killpl - send signal to a process group.
set pgrp - set process group.
• ••••
group - group file.
getgroups - get group access list.
initgroups - initialile gro u p accell list.
let groups - set gro up acces. list.
group - group 61e.
getgrgid, getgmam, setgrent, endgrent - get group 61e entry. getgrent,
0

0

0

0....

caller,
letc, letchar, fletC.

0

0

0

getpid,
IIcheclulinl priority.
protocol entry. letprotoent, getprotobynumber,
endprotoent - let protocol entry. letprotoent,
lIetprotoent, endprotoent - let protocol entry.

0

0

0

January 1984

- xviii -

•

0

letgrent(S)
getgroups(2)
gethostent(SN)
getholtent(SN)
getholtent(SN)
gethostid(2)
get hOltname(2)
getitimer(2)
letlog(SF)
letJogin(S)
getnetent(SN)
letnetent(SN)
getnetent(SN)
getopt(SC)
get pagOlile(2)
getpus(S)
get peername(2)
getpgrp(2)
get pid( SF)
letpid(2)
letpid(2)
getpriority(2)
letprotoent(SN)
get protoent(SN)
letprotoent(SN)
letpw(S)
getpwent(S)
getpwent(S)
getpwent(S)
letrlimit(2)
getrusage(2)
letl(SS)
letservent(3N)
getservent(3N)
gehervent( 3N)
letsockname(2)
gehockopt(2)
gettable(8C)
gettimeofday(2)
getty(8)
gettytab(S)
letuid(2)
letuid(3F)
letc(3S)
getwd(S)
vadvise(2)
Ihutdown(8)
csh(l)
dime(S)
fish(6)
letjmp(3)
clh(l)
gprof(l)
graph(lG)
graph(lG)
gprof(l)
perfmon(l)
ex test (8a)
colordemoa(6)
draw(6)
plot(lG)
cg(4S)
plot(3X)
plot(S)
grep(l)
vgrind(l)
chgrp(l)
getpgrp(2)
killpg(2)
letpgrp(2)
group(S)
getgroupa(2)
initgroups(S)
setgroups(2)
group(S)
getgrent(3)

Sun System Release 1.1

Permuted Indez
setregid - set rea.! and effective
setruid, setgid, setqid, setrgid - set user and
getuid, getgid - gd user or
getgid, getegid - get
groupll - show
chown, fchown - change owner and
make - maintain program
worm - Play the
litty,
graphics board.
lItop:
reboot - reboot lIystem or
f&Rboot, fastha.!t - reboot/
rmailre_comp, re_exec - regular expresllion
hangman - Computer version of the game
vhangup - virtually U
nohup: run command immune to
crash - what
link - make a
intro - introduction to speeiaJ file. and
uptime - show how long sYlltem
checknew. - check if uller
rehallh: recompute command
unhuh: discard command
huhstat: print command
leave - remind you whea you
help - uk for
od - oetal, deeimaJ,
hier - file sYlltem
history: print
fort uno - print a random,
gethonid - get unique identifier of cuttent
getholtD&m., letholtnam. - get/let Dame of current
hOlltnm - let name of current
rdate - .et BY.tom date from a remote
u uleDd - lend a file to a remote
gettabl. - got NIC format host tables from a
htoDI, Dtohl, Dtohl - cODvert value. betwoeD
remote - remote
letholtent, endholtent - cet network
hoR. phones - remote
ruptime - show
hostid - print identifier of current
hodname - let or print Dame of current
htabl. - convert Me standard format
gettabl. - get NIC format
lIystem.
uptime - IIhow
betweeD host aDd network byte order.
and Detwork byte order. htonl,
wump - the game of
SiDh, cosh, tanh getarg,
getpid - get proce"
setregid - set real loud elective group
setgid, letqid, letrgid - set user and group
getuid, getgid - get user or group
su - substitute user
form.
getpid, getppid - get proce"
SUD

System Release 1.1

group 10. • • • • • • • •
group 10. setuid, seteuid,
group 10 of the caller.
group identity. ••
group memberships.
group of & file.
groups. • • • • •
• •••
groupll - show group memberships.
growing worm game.
••••••
gtty - set and get terminal state. • • • •
gxtest - stand alone test for the Sun video
halt - stop the proc~sor.
•••••••
bit a job or process. • • • • • • • • •
halt processor. • • • • • • • • • • • •
bit the sYltem without checking the disks.
••••••
bndle remote mail received via uucp. • ••
handler. • • • • • • • • • • • • • • • • • • • • • •
haDgman. • • • • • • • • • • • • • • • • •
h&ngman - Computer version of the game hangman.
hangup" the current control termina.!.
hangups.
• ••••••••••
happens when the system crashes.
••••••
hard link to a file.
hardware support.
••••••
has beeD up. • • • • • • • • • • • •
has news on the USENET news network.
• ••••••••••••
hash table.
hash table.
• ••••••••••••
hashing statistics.
••••••••••
halhstat: print. command hashing sta.tistics. • • • • • •
have to leave.
help.
• •••••••••
help - ask for help.
hex, ucii dump.
• ••••
hier - file system hierarchy.
hierarchy. • • • • • • • •
history event list. • • • • • • •
hiltory: print history event list.
hopefully iDtereltinl, adage.
host.
hOlt.
hoat.
hon.
hOR.
host. • • • • • • • • • • • • •
host and network byte order. htonl,
host deacription file.
•••••••••
host entry. /gethostbyaddr, gethostbyname,
host name data bue. • • • • •
host phone number data bue.
hoat ltatul of local machines.
host system. • • • • • •
host system. • • • • • • •
hOR tablea.
• ••••••
host tablea from a host.
•
• • • • • •
hostid - print identifier of current host lIystem.
hostname - set or print name of current host
hostnm - get name of current hOllt. • • • • • •
hosts - host name data bue.
••••••••
how long system hu been up.
••••••••
htable - convert NIC standard format host tables.
htonl, htons, ntohl, ntohs - convert values • • •
htons, ntohl, ntohs - convert valu~ between host
hunt-the-wumpus.
••••••••••
hyperbolic functions.
••••••••••••
hypot, ca.bs ~ Euclidean distance. • • • • • • •
iargc - return command line arguments. • • • •
icheck - file sYlltem storage consistency check.
icmp - Internet Control M~8age Protocol.
id.
• ••••••••••
10. • • • • • • • • • • •
10. setuid, lIeteuid. setruid,
10 of the caller.
•••••
id temporarily. • . • • • • • • • • • • • • •
idate, itime - return date or time in numerical • • • • •
identification.
• > • • • • • • • • • • • • •

- xix -

setregid(2)
setuid(3)
getuid(3F)
getgid(2)
groups(l)
chown(2)
make(l)
groups(l)
worm(6)
stty(3C)
gxtest(8s)
halt(8)
csh(l)
reboot(2)
fast boot(8)
rmail(8)
regex(3)
hangman(6)
hangman(6)
vhangup(2)
csh(l)
cruh(8s)
link(2)
intro(4)
uptime(l)
checknews( I)
csh(l)
csh(l)
csh(!)
csh(l)
leave(t)
help(l)
help(l)
od(l)
hier(7)
hier(7)
csh(l)
csh(l)
fortune(6)
gethostid(2)
gethostname(2 )
hostnm(3F)
rdate{S)
uusend(IC)
gettable(SC}
byteorder(3N)
remote(5)
gethostent(3N)
hosts(5)
phones(S)
ruptime(IC)
hostid(l)
hostname( I)
htable(S)
gettable(SC)
hostid(t)
hostname(t)
hostnm(3F)
hosh(5)
uptime(l)
htable(8)
byteo rder(3N)
byteo rder(3N)
wump(6)
sinh(3M)
hypot(3M)
getarg(3F)
icheck(8)
icmp(4P)
getpid(3F)
lIetregid(2)
setuid(3)
getuid(3F)

sU(I)
idate(3F}
getpid(2)

January 1984

Permutetl

Intle~

gethostid(2)
identifier of current hOlt.
hostid(l)
identiier 01 current host system.
what(l)
identify the venion of iles.
getgid(2)
••••••••••
identity.
getuid(2)
identity.
• • • • • • • • ••
.etreuid(2)
ID'I.
• . • • • • • • • • ••
perror(SF)
ierrno -let .ystem error messagee. • ••
if(4N)
if - general propertie. of network interlaeee.
csh(l)
if: conditional .tatement.
••••••••••
checbews(l)
checknews - check if uaer hu news on the USENET news network.
.h(l)
exit, expon, login, newp'p, read,/ sh, lor, cue, if, whil., :, ., break, continue, cd, enl, exec,
ifconfig(SC)
ilconis - conigure network inhrlace parameten.
interlae.. vp- Ito. 10071-5 Multibus Venatee parallel printer
vp("S)
.•••••.•••••••
• • • • • abon(SF)
abon - terminate abruptly with memory imas-e.
core(5)
con - lormat 01 memory imace file. • . . . . . . . . . . . . .
leore(l)
scon - let cor. imaces of fUnnins processes. • • • • •
imemtest(Ss)
imemtest - st&ad alone memory test.
csh(l)
•••••
notify: request immediate notiication.
cah(l)
nohup: run command immune to hangup•.
xstr{l)
xstr - extract strinl' lrom C prosralDl to implement Ihared Itrinp.
eyacc(l)
eyace - modiied yace allowins much improyed error recovery.
• • • • • ar(..S)
ar - Archive 1/4 inch Streaminl Tape Drive.
tm(..S)
••••••••••
tm - tap.muter 1/2 inch tape drive.
which - locat. a prosram il. ineiudinl aliuee and path. (cah only).
WhiCh!ll
dump 5
dump, dumpdate. - incremental dump format. • • • • • •
dump- incremeDtal flle .ystem dump.
• • • • • dumpS
reriore(S)
restor. - incremental lie .ystem reltore. • • • • •
indent(l)
indent - indont &ad format C prolram .ouree.
•
indent(l)
indent - indent and format C program .ource.
t,.tlal, tletstr, tloto, tput. - terminal independont operation routin.. tletent, teetnum,
t.ermcap(SX)
isid, isnan - test lor indeterminate loatinl point valu... • • • • • •
ililll(S)
ptx - permuted index. • • . • . • • • • • • • • • • • • .
ptx(l)
.trncat, .tfcmp, strncmp, .trcp" Itrncpy, Itrlen, index, rindex - Itrinl operation.. streu,
ItrinC(3)
object.. index, rindex, Inblnk, Ie. - tell about character
index(SF)
indxbib{l)
relereacee iD 1./ indxbib - make iDverted iDdex to a bibliography .br lookbib - find
lut- indicate lut login. of usen and teletypel.
lut(!)
s)'lcall- indinc$ aystem cal.l.
•••••••••
.Ylcall(2)
f.plit - 'plit a multi-routine Fortran &I. iDto individual filee. ••• • • • • • • • • •
faplit(l)
indxbib(l)
.br lookbib - ind relereDc" in a bibliolrap,1ty. indxbib - make inverted index to a bibliolraphy
inet - Internet protocol'amily. • • • • • • • •
inet("F)
le"en - inet .erver data base. • • • • • • • • • • • • •
It"ers(5)
iDet_D.tol, inet;..Dtu - Internet addrtll/ inet_addr, inet..aetwork, in.jDakeaddr, inetJllaof,
illet(SN)
inetd - internet ,,"ieee daemoD. • • • • • • •
inetd(SC)
addre.,./ inet_addr, ind_network, inet_makeaddt, inetJnaof, inet_netof, inet_ntoa - Internet
inet(SN)
Internet addrelll/ inet_addr, inet_network, inet_makeaddr, inetJnaof, inet_netof, inet_ntoa inet(SN)
inet..addr, inet_network, inet_ma.keaddr, inet_luol, lnet_netof, inet..ntoa - Internet address/
illet(SN)
iDet_netol, inet..ntoa - Internet/ inet_addr, inet_network, inet_makeaddr, inetJna.of,
inet(SN)
/inetjDakeaddr, inetJuol, inet_netol, inet_ntoa - Internd addren manipula.tion.
illet(SN)
inew. - lubmit news articles.
inews(l)
dumpls - dump file system. inlormatio.. • • • . . • • • • • • • •
dumpfs(S)
pac - printer/plotter aeeoulltinu informatio.. • • • • • • • • • • • •
pac(S)
letrosase - se~ information a.bout resource utili.atio•.
Setrosage(2)
vtimee -11$ information about resource utili.ation.
vtimes(SC)
Istab - .tatic information about the &lel)'ltelDl.
fsbb(5)
ma.a - print out manul pase'j ind manual inlormation by keyword.. • • • • • • • • • •
man(l)
Dewarc - inlormation filo for readnew.{l) and cheeknewa(l).
newsrc(5)
mi.cellaneou. - mi.ceUa.neou. u.elul informatioD pas-. • • • • • • • ••
intro(7)
init - procel' control initiali.atio.. ••
init(S)
initlrouP' - initiali •• sroup accen tift.
initlroupa(s)
init - procell cOll,rol initialiution.
••••••
i.it(S~
ioinit - chanle 177 I/O initialiut.ion.
••••••••
ioinit 8F)
tty. - termiul initialiut.ion data.
••••••
tty.(&
initgroup. - initialise group accen lin.
initlroupa(8)
conDeet - initiate a connection o. a locket. •••
connect(2)
popen, pelole- initiate I/O to/from a proces...
••
popen(SS)
lenerator; routinel lor ehanginl/ random, srandom, initatate, .etstate - better random number
random(S)
Bmin, Bmax, dBmin, dBmax, inmax - return extreme yalull.
range(SF)
clri - clear i-node.
••.. ~ • • • . • . . • •
clri(S)
II, inode - lormu of file system volume.
la(5)
read, ready - read input. • • • • ••
read(2)
loelim - eliminate .so'alrom nroff input. • • • • • • •
.oelim(l)
scanl, CscanC, sscanC - Cormatted input cOllversioD. ••
scanl(SS)
ungetc - push character back into input atream.
ungetc(SS)
fread, Cwrite - buffered binary input/output.
fread(8S)
stdio - standard buffered input/output package.
iDtro(SS)
ferror, feoC, dearerr, fileno - stream statuI inquiries.
•••••
ferror(SS)
sethostid - set unique
hostid - print
whusetsid, setesid - set sroup
sehid, leteuid - set user
•etreuid - 'et real and effective user
perror, lerror,

January 1984

• xx·

Sun System Release 1.1

Permuted Indez
refer - find and insert literature references in documents.
insque, remque- insert/remove element from a queue.
•
queue. insque, remque - insert/remove element from a
install - install iiles.
•••••••
install - install files.
draw - interactive graphics drawing.
lick - file system consistency check and intera.ctive repair.
lortune - print a ra.ndom, hopefully interesting, ada.ge.
cg - Sun color graphici interface.
ec - 3Com 10 Mb/s Ethernet interface.
eli - Sun 3 Mb/s experimental Ethernet interface.
10 - soltware loopback network interface.
mti - Syetech MTI-800/1600 multi-terminal interface.
• ••••••••••••••••
mtio - UNIX magnetic tape interface.
cont, point, linemod, space, closepl - graphics interface. Ie rase, label, line, circle, arc, move,
plot - graphic. interface.
tty - genera.l terminal interface.
• ••••••••••
•••••••••
-Ikon 10071-6 Muitibull Verll&tec parallel printer interface. vp
Versatec printer/plotter &Ild Centronics printer interface. vpc - SYBtech VPC-2200
ifconfi, - configure network interfa.ce pa.rameters. • • • • • •
telnet - uller interface to the TELNET protocol.
if - general properties 01 network interface.. • • • • • • • •
swapon - add a nap device for interleaved paging/swapping.
••••••••
• •••
•endmail - lend mail over the internet.
inet_makeaddr, inetJnaol, inet_netol, inet_ntoa - Internet address manipulation. /inet_network,
icmp - Internet Control Message Protocol.
Itpd - DARPA Internet File Transfer Protocol server.
ip - Internet Protocol.
•••••••
inet - Internet protocol family.
•••••
inetd - internet servicell daemon.
tcp - Internet Tra.nsmilllion Control Protocol.
udp - Internet Uller Datagram Protocol.
ip - Disk driver lor Interphase 2180 SMD Disk Controller.
spline - interpolate smooth curve.
••••••
pti - phototypesetter interpreter.
•••••••
px - Pascal interpreter.
pix - Pascal interpreter and executor.
•
pi - Pascal interpreter code translator,
csh - a IIhell (comm&Dd interpreter) with C-like syntax.
pipe - create aD interprocell' communication cha.nnel.
- atomically release blocked lignalll and wait lor interrupt. lIigpause • • • • • •
onintr: process interrupti in command SCriptll.
Illeep - suspend execution lor aD interval. • • • • • • • • •
lleep - sullpend execution for interval. • • • • • • • • • • •
sleep - luspend execution for aD interval. • • • • • • , •••
••••
intro - introduction to commands.
intro - introduction to compatibility library lunctions.
intro - introduction to FORTRAN library functions.
intro - introduction to libra.ry functions. • • • • • •
intro - introduction to mathematical library functions.
intro - introduction to network library functions.
intro - introduction to other libraries. • • • • • • .
intro - introduction to special file. and hardware support.
intro - introduction to system call. and error numbers.
command.. intro- introduction to Iystem maintenance and operation
ncheck - generate nametl from i-numbers. • • • • • • • • • • • • • • • • •
find referencell in a bibliography. indxbib - make inverted index to a bibliography .br lookbib tread, twrit., trewin, tlkipf, tstate - (77 tap. I/O. topen, tdole,
ioinit - change (77 I/O initialil&tion.
select - synchronou. I/O multiplexing.
mem, kmem, mbmem, mbio - main memory and I/O Ipace. • • • • •
•
iostat - report I/O Itatistics.
popea; pdol. - initiate I/O to/from a procesl.
•••••
ioctl - control device. • • • • • •
ioinit - change (77 I/O initialisation.
iostat - report I/O statistics.
• • • • • •
Controller. ip - Disk driver lor Interphase 21S0 SMD Disk
ip - Internet Protocol.
••••••••
lail - multi-user wooden ships and iron men. • • • • • • • • • • • • • •
•••••••.•••••••••
whatis - describe what a command is.
isalpha, isupper, islower, isdigit, isxdigit, isalnum. isspace, ispunct, isprint, iscntrl,J
isalnum, isspace, ispunct, isprint, iscntrl,f isalpha, isupper, is lower, isdigit, isxdigit,
/isalnum, issp&ee, ispunct, isprint, iscntrl, isudi, isgraph, toupper, tolower, toa.scii -/
ttynam, isatty - find name of a terminal port.
ttyname, isatty, ttyslot _. find name of a termina.1.
lisxdigit. isalnum. isspa~. ispunct, isprint, iscntrl, isa.scii, isgraph, toupper, tolower,f

SUD System Release 1.1

- xxi·

refer(l)
insque(3)
in!lque(3)
install(l)
instaJl(l)
draw(6)
(sck(S)
fortune(6)
cg(4S)
ec(4S)
en(4S)

10(4)
mti(4S)
mtio(4)
plot(3X)
plot(5)
tty(4)
vp(4S)
vpc(4S)
ifconfig(8C)
telnet(IC)
if(4N)
swapon(2}
sendma.il(8}
inet(3N)
icmp(4P)
ftpd(8C)
ip(4P)
inet(4F)
inetd(8C)
tcp(4P)
udp(4P)
ip(4S)
spline(lG)
pti(l)
pX(I)
pix(l)
pi(l)
csh(l)
pipe(2)
sigpause(2)
csh(l)
sleep(l)
sleep(3)
sleep(3F)
intro(l)
intro(3C)
intro(3F)
intro(3)
intro(3M)
intro(3N)
intro(3X)
intro(4)
intro(2)
intro(S)
ncheck(8)
indxbib(l)
topen(3F)
ioinit(3F)
aelect(2)
mem(4S)
iostat(S)
popen(3S)
ioctl(2)
ioinit(3F)
iostat(S)
ip(4S)
ip(4P)

sa.iJ(6)
whatis(l)
ctype(3)
ctype(3)
ctype(3)
ttynam(3F)
ttyname(3)
ctype(3)

Ja.nua.ry 1984

Permuted [ndes
isprint, iscntrl,f isalpha, isupper, islower,
/isspace, ispunct, isprint, iscntd, isascii,
point valuel.
ispunct, isprint, iscntd,/ isalpha, ilupper,
nlues. ilinf,
/isdicit, iudigit, isalnum, iss pace, ispunci,
/islower, isdieit, iudigit, isalnum, isspace,
/isupper, islo"er, isdigit, iudigit, iu.lnum,
system isspace, ispunct, isprint, iscntrl,/ isalpha,
iscntrl,/ isalpha, isupper, is lower, isdiCit,
vi - view a file without changing
idate,
rpow - multiple precisioD integer arithmetic.
suspend: sullpeDd a IIhell, relluming
jO,
jO, jl,
be: place
fe: brine
jo bl: print current
stop: halt a
crontab - table of tim. to ruD periodic
kill: kill
Iprm - remove
default table.
makekey - eenerate encryptioD
table. kbdprint out maDual pasel; find manual informatioa by
profile bulen.
procelli.
kill:
chait - Try to ellcape to
mem,
quiJ - test your
linemod, space, closepl - graphiclI/ openpl, erue,
awk - patterD scaDninl &nd procellsinl
bc - arbitrary-precillion arithmetic
set, shift. timell, trap, uma.k, wait - command
cpp - the 0
order.
freXp.
leave - remind YOll when you have to
exit:
index, riDdex, Inblnk,
ftruncate - truncate a file to a specified
letopt, optal'l, optind - set optioD
lex - generator of
intro - introductioD to other
ranlib - CODven archivel to random
lorder - find ordering relation for an object
ar - archive (
intro - introductioD to
iDtro - introductioD to compatibility
intro - introductioD to FORTRAN
intro - introduction to mathematical
intro - introduction to network
lor - archive and
csh - a. shell (command interpreter) with 0limit: alter per-process resource
unlimit: remove resource
ulimit - get and set user
getarg, iargc ~ return command
spaJ;e, dosepl - gra.phiclI/ openpl, erase, label,
bk Ipr- 01

Ja.nua.ry 1984

isdigit, iudigit, isalnum, isspace, ispunci,
•
illgraph, toupper, tolower, toucii - character/
isinf, isnaD - test for indeterminate Boating
islower, isdigit, iudigit, isalnum, iss pace,
isnaa - test for indeterminate Boatinl poiDt • • • • • •
illprint, iscntd, ilaacii, iagraph, toupper./
ilpund, iaprint, iacntrl, iaalcii, iagraph,/
iallpa.ce, illpunci, illprint, iscntd, isascii,/
iSlue a Ihell command.
••••••••••••
isupper, islower, isdigit, isxdigit, isalnum,
iudigit, illalnum, ill II pace, ispunct, iapriDt,
it usin, the vi visual editor.
•••••••••••••
itime - return date or time in numerical form. •••
itom, madd, mlub, mult, mdiv, miD, mout, pow, lcd,
its superior.
•••••••••••
jO, jl, jn, yO, yl, yn - bellllel functionl.
jl, jn, yO, yl, yn - beuel functions.
jD, yO, yl, yn - bellsel function •.
job iD background.
job into foreerou,d.
job list. • . . . . . .
jo b or prOCelll.
job..
• ••••••
jobl and prOCellllei.
jobl from the line printer llpooline queue.
jobs: print current job list.
••••••
join - relational databalle operator.
•
kbd - keyboard tran.lation table format and
key.
•••••••••••••••••
keyboard translaijoll table format and default
••••••••••••••
keywords. maD kgmoD - generate a dump of the operating system's
kill - lend a signal to a procell..
•••••••
kill - lend Ii signal to a prOCell', or terminate a
kill - lend lipal to a proceSI.
•••••
kill jobs aDd processe..
••••••
kill: kill jobs aDd process e..
•••••
killer robots. •• .• • • • • • • • • • •
killpe - lIend lignal to a procels croup.
•••••
kmem, mbmem, mbio - maia memory and I/O space.
knowledge.
• •••••••••••••••
label, line, circle, arc, move, cont, point, • • • •
language.
• ••••••••••••••••
language.
• ••••••••••••••••
language. /export., 10giD, newerp, read, readonly,
language preprocesllor.
•••••••••••••
lutcomm - show lut commands executed iD reverse
ld - link editor.
••••••••••••••
Idexp, modf - IIplit into mantilllla and exponent.
leave. • • • • •• " . . . . . . . . . .
leave - remind YOll wheD you have to leave.
leave ahell.
• ••••••••
leD - tell about character object•.
length. truncate, . . . . . . . . ; . . .
letter from argv. • • • • • • • • • • •
lex - generator of lexical analysis Proln.mII.
lexical analyail proeraml.
libra.riel.
•••••
librariet.
library.
•• ,. • • •
library) file format.
library f unctio ns. • • • • •
library functionl. •
library functions. ••
library functionl.
library functions.
library ma.intainer.
like syntax.
• • • • • • • • • •
limit: alter per-prOCell resource limitations.
limitations.
limitiations. • • • • • • • • • • • • •
Ii mit II.
• • • ~. • • • • • • • • •
•••••••••••
line a.rgumentl.
line, cirde, arc, move, cont, point, linemod,
••
line dillcipline for machine-machine communication.
line print. • • • • • • • • • • • • • • • •

.. .
,

- xxii -

ctype(3)
ctype(3)
iliDl(S)
ctype(S)
isiDl(S)
ctype(S)
ctype(S)

ctype(3~3)
Iystem
ctype(S
ctype(S
view(l)
idate(SF)
mp(SX)
cllh(l)
3M
jO(
jO(SM
jO(SM
csh(t)

I

CSh!11
cllh
1
cllh 1
croDtab(S)

CSh(l~

Iprm 1)
cllh(l
join(l)
kbd(S)
ma.kekey(8}
kbd(S)
man(t)
kgmon(8)
kill SF)

11

kill
kill 2
cllh 1
ellh 1
chue(6)
killpg(2)
mem(4S)
quiJ(6)
plot(3X)
awk(l)

bC(I)
IIh(t)
cpP(l)
la.stcomm(l)
Id(l)
frexp(S)
leave(l)
leave(t)
csh(l)
iDdex(3F)
trunca.te(2)
geiopt(SO)
lex(l)
lex(l)
intro(SX}
ra.nlib(l}
10rder(1)
ar(S)

intr~s)
intro
SO)
intro SF)
intro SM)
intro SN)
ar(l)
Cllhll!
cllh 1
cllh I
cllh 1)
ulimit(SO)
leiarg(SF)
plot(SX)
bk(4)
IpI{l)

Sun System Release 1.1

Permuted In.dez

Ipc- line printer control program.
Ipd Iprm - remove jobs from the
/erase, label, line, circle, arc, move, cont, point,
comm - seled or reject
fold - fold long
uniq - report repeated
look - find
rev - reverse
hea.d - displayfim few
readlink - rea4 va.lue of a symbolic
Id a.out - assembler and
link - make a hard
lIymlink - ma.ke symbolic
link, symlnk - make a
In - make

••• • • •
Jine printer daemon.
•••••••••
line printer spooling queue.
••••••
linemod, space, dosepl - graphics interface.
lines common to two sorted files.
lines for finite width output device.
lines in a file.
lines in a sorted list.
Jines of a file.
lines of specified files.
link.
•••••••
•
link - make a hard link to a file.
link editor.
••••••••••••
link editor output.
•••••••••••••••••
link, symlnk - make a link to an existing file ..
link to a file. ••• •
link to a file. • • • • • • •
link to an existing file.
Jinks. • • • • • • • • • •
lint - a C program verifier.
lin.
list.
lin.
lin.
lin. • • • • •
lin.
lin.
lin. • • • • •

glob: filename expand argument
history: print history event
jobs: print current job
shift: manipulate argument
getgrouPII - get group accells
initgroups - initjalile group accells
look - find lines in a lIorted
nlin - get entries from n&me
nm - print name lin.
lIetgroUPS - set group accellll lin. •
v&rargl - variable argument lin.
Is - lin contents of directory.
foreach: loop over lin of names.
•••••
usen - compact lin of usen who are on the SYlltem. • ••
listen - listen for connections on a lIocket.
tisten - listen for connectionll on a socket.
vgrind - grind nice listings of programs.
• ••••••••
refer - find and inllert literature references in documents.
In - make linb.
•••••••••••
index, rindex, Inblnk, len - tell about character objects.
10 - lIoftware loopba.ck network interface.
loc - return the addrellll of an object.
convert date and time to ASCII. ctime, localtime, gmtime, allctime, timelone, dysile (cah only). which- loc&te a program file including aliaaes and paths
whereis - locate source, binary, and/or manual for program.
end,etext, edata - Ian locations in progra.m. •
lock - apply or remove an advisory lock on an open file.
••••••••••••
"login", lockllcreen - maintain window context until
- collect Iystem diagnostic menages to form error log. dmellg
•••
Iyslog, openlog, closelos - controlsylltem 10C.
• ••••••••••••••
lIyslog - make system log entry.
•••••••••••
gamma - log gamma function.
power, IIquare root. exp, log, log10, pow, IIqrt - exponential, logarithm,
SYllloI - log sYlltems messages. • • • • • • • • • • •
IIqua.re root. exp, log, log10, pow, IIqrt - exponential, loga.rithm, power,
exp, 10" 10,10, pow, sqrt - exponential, logarithm, power, square root.
nrho - who's logged in on local machines.
"
lush - lush output to a logical unit.
flleek, ftell - repollition a file on a logical unit.
getc, fgetc - get a character from a logical unit.
putc, fputc - write a character to a FOR TRAN logical unit.
lockllcreen - maintain window context until" login".
rlogin - remote login.
login - lIign on.
ac- login accounting.
login: login new user.
getlog - get user'lI login name.
get login- get login name.
login: login new user.
• • •
•
• • •
/., break, continue, cd, evat; exec, exit, export, login, newgrp, read, readonly, set, IIhift, timett,/
passwd - change login pa.ssword.
utmp, wtmp- login records.
••••••
.; 'rlogind - remote login server. • • • • • • •
chllh - c·hange default login shell. • • • • • • • •
last - indicate lallt logins of usen and teletypes.
• •••••••
blluncube - view 3-D Sun logo.
0

•••

0

••••

0

•

•

•

•

•

•

•

0

•

.."0 ................ .

SUD System Release 1.1

- xxiii •

Ipc(S)
Ipd(S)
Iprm(l)
plot(3X)
comm(l)
fold(l)
uniq(l)
look(l)
revel)
hea.d(l)
readlink(2)
link(2)
Id(l)
a..out(S)
link(3F)
link(2)
symlink(2)
link(3F)
In(l)
lint(l)
csh(l)
csh(l)
csh(l)
csh(l)
getgroups(2)
initgroups(3)
look(l)
nlist(3)
nm(l}
setgroups(2)
vara.rgs(3)
IS(l)
csh(l)
users(l)
listen(2)
listen(2)
vgrind(l)
refer(l)
In(l)
index(3F)
10(4)
loc(3F)
ctime(3)
which(l)
whereis(l)
end(3)
lock(2)
lockscreen( I)
dmettg(8)
syslog(3)
syslog(l)
gamma(3M)
exp(3M)
syslog(8)
exp(3M)
exp(3M)
nrho(IC)
8ush(3F)
fseek(3F)
getc(3F)
putc(3F)
10ckscreen(l)
rlogin(IC)
login(l)
ac(S)
csh(l)
getlog(3F)
getlogin(3)
esh(l)
sh(l)
pa.sswd(l)
utmp(S)
rlogind(SC)
chsh(l)
l&8t(l)
bsuncube(6)

January 1984

Permuted [ndez
logout: end session. • • • • • • • • • •
eetjmp, lonsjmp - non-loea.l COto. • • • • • • •
look - ind linee in a.oned list.
/- make inverted index to a bibliography .br lookbib - ind references in a. bibliocraphy.
• ••••••••
break: exit while/foreach loop.
• ••••.•••••
continue: cycle in loop.
• •••••••••
end: termina.te loop.
forea.ch: loop over list of names.
10 -Ioftware loop back network interface. • • • • • •
library. lorder - ind orderinc rela.tion for aD object
Ipc - lineprinter control progra.m.
Ipd - line printer da.emoa. • • • • • • •
lpq - Ipool queue examina.tion procra.m. ••
Ipr - offline print. . . . . . . . . . ' . . . .
queue. Iprm - remove job. from the IiDe printer apoolia,
I. - list contentl of directory.
beek, tell - move read/write pointer.
latat, fata.t - cet &le statui.
m4 - macro proceslor.
••
lun - il'CUrrent machine a aUn worketatioa.
vax - is current machine a vax. • • • • •
•••
bk - line discipline for machine- machine communica.tion.
bk - line discipline for machine-machine communication.
ruptime - show host statuI of loc&l machines.
rwho- who'. locsed in on loc&l ma.chines. • • • • • • • • • • •
m4- ma.cro processor. • • • • • •••
aliu: shell macro.. . •. __ . . • • . • • . . . • •
toalcii - chara.cte::t clusifica.tion a.nd convenion ma.cro.. /isucii, isgra.ph, toupper, tolower,
macro.. • • • • • • • • • • • • • • • • •
IDS - text formattinl
•••••
me- ma.cro. for forma.ttinc pa.pen.
ma.a- ma.cro. to typeset manu&l. • • • • • • • • • • • •
- multiple precision intecer a.rithmetic. itom, madd,lDSub, mult, mdiv, min, moat, pow, ccd, rpow
•••••••••
tp-DEC/ mac tape lonnatl.
mtio- UNIX macnetic tape interfa.ce. • • • • • • •
mt- mapetic bp. manipulatinl procram. • • • • •
rmt - remote magtape protocol module.
ma.il - send and receive mail.
prma.il - print out waitin, mail.
recnewl - receive unprocesledarticlel via mail.
recnewl - receive unproceaaed artielel via mail.
• ••••••••
•endnew. - lead new. articlelvia mail.
- encode/decode a binary &Ie for tDnsmiaaion via mail. lluencode,uudecode
•••••••••
uurec - receiveproces.e~ aewl articlel via mail.
••••••••••
x.end, XC., earoll - .ecret mail.
mail - .end a.:ad receive mail.
••••
/hanl mail -,end or receivema.il amonc ullers.
ma.iladdr - mail addrellinl description.
bil- mailala.rm.
new&lia..el - rebuild the data. baee for the mail aliue. &te.
Ibia/ma.i1- ,ead or receive mail amonl u.era.
from -who il my mail fromT.
lendm.ail - ,ead mail over the intefD~.
•••••
• ••••••
nnail - ha.ndle remote mailrecehted via uuep.
maila.ddr - mail addre.sinc de.cnption.
mem, kmem,mbmem, mbio - main memory and I/O .pa.ce.
• ••••
m.ak~­ maintaia pro,ra.m·croupl. • • • • • • •
lockecreea - maintain window context until "Iosin".
lor - archive load libra!)' maintainer.
• ••••••••••••
intro - introduction to .yatem maintena.nce load opera.tion comma.nda.
•
make - maintain procram group..
delta - make a delta (ehance) to &D secs file.
mkdir- make a directory.
•••••
mkdir- make a directory fik.
link - ma.ke a. hard link to a. file.
link, symlnk - make a. link to Ion existinc &Ie. • • • • •
mknod - make a. .pecia.l ile. • • • • •
mktemp - ma.ke a unique ile name.
• • • • • • • •
- find references in a. bibliogra.phy. indxbib- ma.ke inverted index to a bibliogra.phy .br lookbib
In - make Iinke.
• ••••••
symlink - make symbolic link to a. file.
sysloC - make .yatem 10C entry.
MAKEDEV- make system specialfilee.
•
script - make typescript of terminal session.
MAKEDEV - ma.ke system apecia.l &Iea.
makekey - generate encryption key.
••
memory allocator. manoc, free, realloc, calloe, cfree, a1loca. January 1984

• xxiv·

cah(l)
.etjmp(S)
look(l)
indxbib{l)
cah(l)
cah(l)
cah(l)
cah(l)
10(4)
10rder(1)
Ipc(S)
Ipd(S)
Ipq(l)
Ipr(l)
Iprm{l)
la(l)
Iseek(2)
It&t(2)
m4(1)
IUn(l)

vU(l)
bk(4)
bk(4)
ruptime(lC)
rwho(lC)
m4(1)
csh(l)
ctype(3)
ms(7)
me(7)
man(7)
mp(3X)
tp(S)
mtio(4)
mt{l)
rmt(SC)
ma.il(l)
pnnail(l)
recnews(l)
recnews(S)
aendnews(S)
uuencode(lC)
uurec(S)
xsend(l)
mail(l)
binmait(t)
mailaddr(7)
bil{t}
new&liases(S)
bi.mail(l)
Itom{l)
sendmail(S)
rmail(S)
mailaddr(7)
mem(4S)
make(l)
lockscreen( 1)
ar(l)
intro(S)
make(l)
delta.{l)
mkdir(l)
m1cdir(2)
link(2)
link(3F)
mknod(2)
mktemp(3)
indxbib{l)
In(l)
aymlink(2)
ayslog(l)
makedev(S)
acript(l)
makedev(S)
makekey(S)
malloc(3)

Sun System Release 1.1

Permuted Indez

information by keywords.
shift:
quota route - manually
mt - magnetic tape
inet_Detof, inet_Dtoa - Internet address
frexp, Idexp, modf - split into
catmu - create the cat files for the
man - macros to typeset
wherei. -locate source, binary, and/or
maD - print out manual pages; find
man - print out
route tee - copy st&Ddard output to
umuk: change or display file creation
• ipetmalk - let current signal
umuk - lIet file creation mode
mbtr - create an error melea.ge file by
intro - introduction to
eqn, neqn, checkeq - typeset
getrlimit, letrlimit - control
vlimit - control
mem, kmem, mbmem,
mem,kmem,
ec - SCom 10
en - Sun 3
u-

precision integer/ itom, madd, msub, mult,
bcd - conven to antique
II pace.
groups - IIhow group
mmap - map pages of
munmap- unmap pages of
malloc, free, realloc, ca.1loc, dree, alloca valloc - aligned
mem, kmem. mbmem. mbio - main
vfork - IIpawn new procells in a virtual
abort - terminate abruptly with
core - format of
vmstat - repon virtual
imemteet - stand alone
llail - multi-uler wooden ships &Dd iron
lion -110" or
pmerge - pucal file
mk~r - create an error
recv, recvfrom, recvmsg - receive a
send, lIendto, sendmsg - lIend a
icmp - Intemet Control
error - analy.e ud dispene compiler error
mesl - permit or deny
sYl_errlilt, IYI_nerr, ermo - SYltem error
perror, lerror, ierrno - get SYlltem error
plipal, SYII_siglist - system sipal
mlog - log systems
dmesl - collect .system diagnostic

mille - play
inteser arithmetic. itom, madd, lDaub, mult, md,iv,
pages.
miscellaneou. -

C souree.
chmod - change
getty - lIet terminal
umuk - set file creation

SUD System Release 1.1

man - macros to typeset manual. • • • • • •
man - print out manual pages; find manual
manipulate argument list.
manipulate disk quota.8. • • • • • • • •
manipulate the routing tables. • • • • •
manipulating program.
••••••••
manipulation. /inet_makeaddr, inet_lnaof,
mantissa and exponent.
manual. • • • • •
manua.1. • • • • • • • •
manual for progra.m.
manual information by keywords.
• • • • •
manual pages; find manual information by keywords.
manually manipulate the routing tables.
• ••••
many files.
ma.8k. • • • • • •
mask. • • • • • • •

mask . • • • . • •
massaging C 1I0urce.
mathematical library functions.
ma.thema.tics.
• •••••••
maximum system resource consumption.
maximum system resource consumption.
mb - Multibus.
• ••••••••••
mbio - main memory and I/O space. • •••
mbmem, mbio - main memory and I/O Ipace.
Mb/. Ethemet interface.
•••••••
Mb/s experimenta.1 Ethernet interface.
mc68000 &8sembler. ••• • • • • • •
mdiv, min, mout, pow, gcd, rpow - multiple
me - macros for formatting papen. • • • • • •
media.
• •••••••••••••••••••
mem, kmem, mbmem, mbio - main memory and I/O
membenhips.
• .•
memory.
• •••
memory.
memory allocator.
memory allocator.
•
memory and I/O space.
memory efficient way.
memory image. ••
memory image file.
memory statistiCIJ ..
memory test.
men.
• •••••
merge filel.
.,.
merger. • • • • •
mesl - permit or deny messages.
mes.age file by malsaging C lource.
mes.age from a lOCket.
message from a socket.
Me.sage Protocol. .
messages.
message•.
mes.age.. perror,
messages.
meslages.
messagel.
messagel to form error log.
mille - play Mille Bomes.
Mille Bomes.
•••••••
• •••••
min, mout, pow, gcd, rpow - multiple precision
miscellaneous - miscellaneous useful information
miscellaneous useful information pages.
mkdir - make a directory.
mkdir - make a directory file.
•••••
mkfs - construct a file system.
mknod - build special file.
mknod -make a special file.
• • • •
mkproto - construct a prototype file system.
mkstr - create an error message file by masuging
mktemp - make a unique file na.me.
mma.p - map pages of memory.
mode . • • • •
mode . • • • •
mode ma.8k.

- xxv-

man(7)
man(l)
csh(l)
quota(2)
route(SC)
mt(l)
inet(3N)
frexp(3)
ca.tman(8)
man(7)
whereill{l)
man(l)
man(l)
route(8C)
tee(l)
csh(l)
sipetmask(2)
uma.8k(2)
mbtr{t)
intro(3M)
eqn(l)
getrlimit(2)
vlimit(3C)
mb(4S)
mem(4S)
mem(4S)
ec(4S)
en(4S)
as(l)
mp(3X)
me(7)
bcd(6)
mem(4S)
groups(t)
mmap(2)
munmap(Z)
malloc(3)
valloc(3)
mem(4S)
vforlc(Z)
abort(3F)
core(S)
vmstat(8)
imemtest(8s)
ea.il(6)
sort(l)
pmerge(l)
mesg(l)
mbtr{l)
recv(Z)
send(Z)
icmp(4P)
error(t)
mesg(t)
perror(3)
perror(3F)
psignal(3)
syslog(8)
dmesg(8)
miJIe(6)
miJIe(6)
mp(3X)
intro(7)
intro(7)
mkdir{t)
mlcdir(2)
m Icfs (8)

mknod(S)
mknod(2)
mlcproto(8)
mbtr{l)
mJctemp(3)
mmap(2)
chmod(l)
getty(S)
umaslc(Z)

Ja.nua.ry 1984

Permuted [ndez
mode of a tile. • • • • • • • • • • • •
mode of tile. • • • • • • • • • • • • • • • • • • • •
modf - Iplit into mutissa ud exponent.
modi tied ofa tile. • • • • • • • • • • •
moditied yacc allowinl much improved error
module. • • • • • • • • • • • • • • • • •
moncontrol - prepare execution protile .
monitor, mOllstartu.p, moncontrol .- prepare • • • • • •
Monochrome Bitmap Display.
monop - Monopoly game. • • • • • • • •
monop - Monopoly lame. • • • • • • • • • • • •
profile. monitor, monn&rtup, moncontrol - prepare executioa
more,· page - browse through a text tile.
cunes - screen functions with lIoptimAl" cunor motion. • • • • • • • • • • • •
. . . . • . . • • • • • • • •••••
col - tilter revene paper motionl.
mount, umoua~ - mount and dismount tile Iystem.
•••••
mount, umount - mount or remove tile Iystem.
mount, umount - mount and dismount tile. eystem.
mount, umount· - mount or remove tile eystem.
mtab- mounte,d tile eystem table. • • • • • • • • • • •
••••••••••••••••••
mouse - SUD mouse.
mouse - Sua mOllo.
••••••••••••
arithmetic. itom, madd, mlub, mult, mdiv, miD, mout, pow, Icd,rpow - multiple precision integer
Itaphics/ openpl, era.e, label, line, circle, arc: move, cont, point, linemod, Ipace, c:losepl mv- move or rename tiles.
Iseek, tell - move read/write pointer.
•••••••
m. - text formattilll macro..
•••••
multiple precision inteler arithmetic. itom, madd, mlub, mult, mdiv,min, mout, pow, gcd, rpowmt - mapetic tape muipulatinl program.
mtab - mounted tile Iystem table.
interface. mti - Systech MTI-SOO/1600 multi-terminal
mti - Systech MTI..sOO/ USoo multi-termiDaI interface.
mtio - UNIX mapetic tape interface. • • •
eyacc - moditie4 yacc allowinl much improved error recovery. • • • • • • • •
preci.ion inteler arithmetic. itom, madd, mlub, mult, mdiv, min, mout, pow, lcd, rpow - multiple
mb- Multibus. • • • • • • • • • • • • • • •
vp - Ikon 10071·5 Multibll' Venatec parallel printer interface.
pr - prin~ &le(s), possibly in multiple column..
•••••••••••
mnb, mult, mdiv, min, mout, pow, gcd, rpow- mUltiple precision inteler arithmetic. itom, madd,
select - synchronous I/O multiplexinl·
•••••••••••••••
fsplit - Ipli~ a multi-rout in. Fortran til. into individual tiles. • • • • •
mti - Systech MTI.SOO/USOO multi-terminal interface.
••••••
nil- multi.u.er wooden shipland iroa meD.
switch: multi-way command brandl. •••
muamap - uamap pagel of memory.
my - move or rename tile•.
from - who is my mail fromT.
letenv - value for environment Dap1O.
letlol - let uler'l losia aallle.
letlolia - let losi- name.
letlockllame - let locket name.
mktemp - make a unique &Ie name.
pwd - priJ),t workinl dir~ctory name.
tty - let termiaal aame.
• .'.
hOltl - hon Dame data bue.
networks - network name data bue.
protocols - protocol a.ame data bue.
servic~. - service Dame data bue.
•••••
tmpnam - create a Dame for a temporary tile.
getpw - let n.ame from uid.
nlist - let entries from Dame lin.
nm - prillt Dame lin.
rename - change the na.me of a tile.
ttyname, isatty, ttyslot - tind Dame of a termiaal. • •
ttynam, isatty - find Dame of a terminal pon.
getpeemame - get name of connected peer.
gethostname, sethostna.me - get/set na.me of current hon.
hORnm - get name of current host. •••
hostna.me - sd or print Dame of current host eystem.
bind - bind a name to a socket.
foreach: loop over list of names.
• ••••••••
ncheck - generate aame. from i-numben.
• • • • • •
ncheck -Ienerate aames from i-numben.
nd - network disk control. • • • • •
ad - network disk driver. • • • • • •
eqD, neqn, checkeq - typeset mathematics.
chmod - cba-Ilge
chmod, fchmod - challge
frexp, Idexp,
touch - update date Ian
recovery. eyaccrmt - remote magtape protocol
.monitor, monstartup,
execution profile.
bdemo. - demonnrate Sun

January 1984

- xxvi ..

chmod(3F)
chmod(2)
frexp(3)
~ouch(l)

eyacc(l)
rmt(SC)
monitor(3)
monitor(3)
bdemos(6)
monop(6)
monop(6)
monitor(3)
more(l)
curses(3X)
col(l)
mount(S)
mount(2)
mount(S)
mount(2)
mtab(S)
mouse(.fS)
mouse(4S)
mp(3X)
plot(3X)
mv(l)
lseek(2)
ms(7)
mp(3X)
mt(l)
mtab(S)
mti(4S)
mti(4S)
mtio(4)
eyace(l)
mp(3X)
mb(4S)
vp{4S)
pr(l)
mp(3X)
.elect(2)
fsplit(l)
mti(4S)
8&il(6)
csh(l)
munmap(2)
mv(l)
from(l)
letenv(3)
letlog{3F)
letlogin(3)
letsoekname(2)
mktemp(3)
pwd(l)
tty(l)
hosts(5)
networks{S)
protoeols(S)
aervices{S)
tmpnam(3C)
letpw(3)
nlist(3)
nm(l)
rename(2)
ttyname(3)
ttynam(3F)
getpeemame(2)
cethostname(2 )
hostnm(3F)
hostname(l)
bind(2)
csh(l)
neheek(S)
Ilcheek(S)
nd(SC)
nd{4P)
eqn(l)

Sun System Release 1.1

Permuted lndez

- check if user has news on the USENET news
ntohl, ntohs - conven values between host and
nd nd getnetbyname, setnetent, endnetent - get
gethostbyname, setholltent, endhostent - get
10 - software loopback
ifconfig - configure
if - general properties of
intro - introduction to
networb news - USENET
routing - system supporting for local
routed netstat - sh~w
creat - create a
- open a file for readinl or "ritine. or create a
newfs - construct a
fork - create a
vfork - IIpawn
login: login
adduser - procedure for adding
aliuee file.
/continue, cd, eval, exec, exit, export, login,
newe - USENET network
expire - remove outdated
inews - eubmit
post news - eubmit
readnews - read
eendnews - send
uurec - receive processed
checknewl - check if user hu news on the USENET
checknew8- check if UIIer hu
checbews( 1).
dbminit, fetch, store, delete, fimkey,
gettable - get
btable - convert
vgrind - grind
only).

netstat - IIhow network status. • •
network. checknews
•••••
network byte order. htonl, htons,
network disk control. • • • • • •
network disk driver.
• •••••
network entry. getnetent, getnetbyaddr,
network host entry. gethostent, gethostbyaddr,
network interface.
network interface parameters.
network interfaces. • • • • •
network library functions.
network name data bue.
network news article, utility files.
network packet routing. ••• • •
network routing daemon.
network status.
••••••••
networks - network name data base.
new file. • ••
new file. open • • • • • • • • • •
new file sYlltem.
••••••••••
new process. • • • • • • • • • • • •
new procellll in a virtual memory efficient way.
new user.
•• t • • • • • • • • • • • • • • • • • •
new ullers. • • • • • • • • • • • • • • • • •
newalias.. - rebuild the data. base for the mail
newfs - conlltruct a new file system.
newgrp, read, readonly, set, shift, times, trap.!
newl - USENET network news article, utility files.
news article, utility filell.
newl articles.
news articles.
newl articles.
newl articlel.
newl articlel via mail.
news articlel via mail.
news network.
newl on the USENET news network. •••
neWBrC - information file for readnews{l) and
nextkey - data bale subroutinel.
NIC format host tablel from a host .
NIC Itandard format host ta.blea.
•••••
nice - let program priority.
nice liltings of programs.
••••••••••
nice, nohup - run a command at low priority (sh
nice: run low priority procesl.
nlist - get entries from name list. • • • • • • •
nm - print name list. • • • • • • • • • • • •

clri - clear i- Dode. . . . . . . , . . . . . . . . . . . . . .
nice, nohup - run a command at low priority (sh only).
nohup: run command immune to bngups.
eetjmp, longjmp - non-local goto. • • • • • • • • • • •
notify: request immediate notification. • • • • • • • • • • • • •
notify: request immediate notifica.tion.
relationllhips of screenll. adjacentllcreens- notify the window driver of the physical
term - terminal driving tabltl! for nroB'. • • • • • • • • • • • • • • • •
term - terminal drivinl tabl" tor nroB'. • • • • • • • • • • • • • • • •
nroB' - text formatting and typesetting.
• •••••••••
1I0elim - eliminate .so's from nroB' input.
~........
tbl- format tablea for nroB' or troB'.
colcn - filter nroB' output for CRT previewing.
deroll' - remove nroB', troB', tbl and eqn constructs.
checknr - check nroB'/troB' filel. • • • • • • • • •
network byte order. htonl, htone, ntohl, ntohl - convert values between host and
byte order. btonl, htons, ntohl, ntohs - convert values between host and network
null - data link. • • • • • • • • • • • • • •
fptype - chock a floating point number. • • • • • • • • • • • • • • • • • •
- g~ the file descriptor of an external unit number. getfd • • • • • • • • • • • • • • •
number - convert Arabic numerals to English.
phonell - remote host phone number data bue.
•••••••••••••••
arithmetic - provide drill in number facts.
•••••••••••••
rand, Brand - r&ndom number generator.
/BraDdom, initlltate, setstate. - better random number generator; routinel for changing generators.
atof, atoi, atol ~conven ASCII to numbers.
intro - introduction to system calls and error numbers.
ncheck - genera.te namea from i- numbers.
number - convert Arabic numerall to English.

. ...

Sun System Release 1.1

- xxvii •

netstat(S)
checknewB( I)
byteorder{3N)
nd(SC)
nd(4P)
getnetent(3N)
gethoatent(3N)
10(4)
ifconfig(8C)
if(4N)
intro(3N)
networks{S)
news(S)
routing( 4N)
routed(SC)
netstat(S)
networks(5)
crea.t(2)
open(2)
newf8(8)
fork(2)
vfork(2)
csh(l)
addu8er(8)
newaliases(8)
newfs(S)
sh(l)
news(S)
new8(S)
expire(S)
inews(l)
postnews(l)
readnews( 1)
sendnews(8)
uurec(S)
checknews(l)
checknews(l)
newsrc(S)
dbm(3X)
gettable(SC)
htable(S)
niee(3C)
vgrind(l)
nice(l)
csh(l)
nlist(3)
am(l)
clri(S)
nice(l)
csh(l)
lIetjmp(3)
csh(l)
csh(l)
adjacentscreens(l)
,term(S)
term(S)
nroft'(l)
soelim(l)
tbl(l)
colert(l)
deroft'(l)
checknr{l)
byteorder{3N)
byteorder{3N)
nulI(4)
fptype(3F)
getfd(3F)
number{6}
phones(S)
a.rit hmeti c( 6)
ra.nd(3C)
ra.ndom(3)
atof(3)
intro(2)
ncheck(S)
number(6)
January 1984

Permuted Indez
idate, itime - retura date or time in
twrite, trewin, tskipf, tstate - "7 tape 1/
loc - retura the &ddress of &D
sile - sile of &D
lorder - find ordering relation for an
atrinsa - find printable atrings in an
index, rindex, Inblnk, len - tell about cha.r&eter
od od - Central Data
acd - turn accountinl on or
10giD - sign
nice, nohup - run a command at low priority (sh
a program file indudinl aliues and paths (csh
create a new file.
file. openfopen. freopen, fdopen lock - apply or remove aD advisory lock on an
closedir - diredory operations.
ayslol,
cont, point, linemod, spa.ce, closepl - sraphics/
savecore - save a core dump of the
ksmon - senerate a dump of the
intro - introduction to aystem maintenance and
tgetstr, tgoto, tpuh - terminal independent
bcopy, bcmp, blero, la - bit and byte strinl
telldir, seekdir, rewinddir, closedir - directory
dkio - generic disk control
strepy, atracpy, strlen, index, ARdex - strinl
join - relati~h&1 databue
setopt,
cunes - screen function. with II
setopt, optall,
getopt, optall, optind - set
fcntl - file control
atty- set terminal
getsockopt, setsockopt - get and set
- convert values between holt and network byte
lutcomm - show last commands executed in revene
lorder - find
vi - screen
cpio - copy file archives in and
expire - remove
a.out - assembler and link editor
- terminate a process after fIullhinl any pendinl
. fread, fwrite - bulered binary input/
em, fm, Scn printf, fprint', IIprint{ - formatted
fold - fold lonllines for finite width
colcrt - filter Bro'
atdio - IItandard bufered input/
IUllh - flush
tee - copy standard
foreach: loop
seadmail - lend mail
exec:
chown - chust
chown, fchown - change
quot - IlUmmarile file system
dias - General-purpose stand-alone utility
etdio - standard bufered input/output
routins - sJlltem IlUpportinl for local network
more,
getpagesiJe - get system
pagesile - print system
miscellaneous - miscellaneous useful informatioD
maD - print out manual
mmap - map
lDunmap - unmap
swapon - specify additional deviee for
drum ndv;'e - give advice to

January 1984

•••••
numerical form.
O. topen, tdoee, tread,
••••••••
object.
object file. • • • • • • •
object library. • • • • •
object, or other bin&l')', file.
objects. • • • • • • • • • • • •
oct - Central Data octal serial card.
octal, decimal, hex, ascii dump.
octal serial card. • • • • • • • •
od - odal, d~cima.l, hex, ascii dump.
of. • • • • • • • • • • • • • •
on. • • • • • • • • • • • • • • •
onintr:proces. interrupts in command scripta.
only}. • • • • • • • • • • • • • • • • • • •
only}. which - locate • • • • • • • • • • •
open - open a file for reading or writing, or
open a file for readinl or writinl, or create a new
open a stream. • • • • • • • • • • • •
open file.
• •••••••••••••
opendir, readdir, telldir, seekdir, rewinddir,
openlo" doselo, - control system log. • •
openpl, erue, label, line, circle, are, move,
operating lIystem.
••••••••••
operatinl syltem'. profile bufen.
operation command.. • • • • • • • • • ••
operation routines. tgetent, tgetnum, tgetlag,
operation..
• ••••••
operations. opendir, readdir,
••••••••
operation..
• •••••••••••••
operations. strcat, stracat, atremp, strncmp,
•••••
operator.
•••••••••••••••••
optall, optind - get option letter from &flY.
optimal" cunor motion. • • • • •
optind - set option letter from allY.
option letter from arev.
option.. • • • • • • • • • • • •
option.. • • • • • • • • • • • •
option. on lOCketS. • • • • • • •
order. htonl, htons, ntohl, ntohs
order. • • • • • • • • • • • • •
orderine rela.tion for an object library.
•
oriented (visual) display editor based on ex.
out.
• ••••••
outdated new. artielea.
output.
output. exit • • •
output. • ••••
output convenion.
output convenion.
• • •
output device.
output for CRT previewinl.
output package.
output to a logical .nit.
output to many file •.
over lilt of names.
over the internet. • • • • • • • •
overlay .hell with specified command.
owner.
• ••••••••••••
owner and sroup of a file. • • • • •
ownership.
• •••••••••••••
pa.c - printer/plotter accountin, information.
package.
• •••••••••
package.
• •••••••••
packet routinl.
••••••••
page - browse through a text file.
page li.e. • • • • • • • • ••
page sile. • • • • • • • • • •
pa.gel. • •
pages; find manual information by keyworda.
pagel of memory.
• ••••••
page. of memory.
•••••••
pagesile - print ~ystem page sile.
paging and nappin,.
paging device.
paging system.
0

• xxviii·

•

•

•

•

•

•

•

•

•

•

•

•

•

•

•

•

idate(SF}
topen(SF}
10c(SF}
siJe(I}
lorder(l}
etrinSs(I}
index(3F}
oct(4S)
od(l)
oct(4S}
od(l)
acct(2}
login(l}
csh(l)
niee(l)
which(l)
open(2)
open(2)
ropen(3S}
tlock(2)
directory(3)
syslog(S)
plot(3X)
savecore(S}
kgmon(S)
intro(S)
termcap(3X)
bstring(3)
directory(S)
dkio(..S)
string(3)
join(l)
Setopt(3C)
cunes(3X)
getopt(3C)
getopt(3C)
fcntl(5)
stty(l)
setsockopt(2)
byteorder(3N)
Iastcomm( 1)
lorder(l)
vi(l)
cpio(l)
expire(S)
a.out(S)
exit(3)
fread(3S)
ecn(3)
printf(3S)
rold(l)
colen(l)
intro(3S)
tlush(3F)
tee(l)
csh(l)
sendmail(S)
csh(l)
chown(8)
chown(2)
quoteS)
pac(S)
dia.g(Ss)
intro(3S)
routing( 4N)
more(l)
setpageaile(2}
pagelliJe( I}
intro(7)
man(l)
mmap(2)
munmap(2}
pagesiJe( 1)
Iwapon(S}
dmm(.. )
vadvise(2)

Sun System Release 1.1

Permuted Indez
nrapon - add a swap device for interleaved
socket pair - create a
col - filter reverse
me - macros for formatting
vp - Ikon 10071-5 Multibus Versatec
ifcollfil - configure network intedace
pc pxref pxp pmergepx pix pi get pass - read a
punrd - change login
puswd vipw - edit the
getpwuid, getpwnaM, setpwent, endp1l'ent - get
getwd - get current workinl directory
getcwd - get
- locate a program file inciudinl aliases and
lrep, egrep, fgrep - search a file ~r a

aile -

popen,
getpeername - get name of connected
exit - termina.te a proce.1 after flushing any
statisticl.
crontab - table of timel to run
meslptx limit: alter
meas",el.
error meluge•.
It icky - executable lie. with
phone. - remote hoat
pti adjacentlcreen. - notify the win.dow driver of the
spli' - Iplit a Q.le into
channel.
bl:
Isla mille boggle wormpac - printer/
vpc - SYltech VPC-2200 Versatec printer/
trpfpe, fpecnt - trap and repair floatinl
era.e, label, line, circle, arc, move, cont,
fptype- check a floatinl
i.inf, isnaD - teat for indeterminate floating
Iseek, tell ~ move rea.d/write
popd:
ttynam, isatty - Ind -name of a terminal
ttytype - data bue of terminal types by
pr - print file(s),
analy.e - Virtual UNIX
itom, ma.dd, Msub, mult. mdiv, min, mout,
root. exp, log, log10,
101, log10, pow, sqrt - exponential, logarithm,

be - arbitrarymult, mdiv, min, mout, pow, sed', rpow - multiple
monitor, monstartup, moncontrol -

SUD System Release 1.1

paging/nrapping.
pair of connected sockets.
paper motions. • • • . •
papers.
• •••••.•
parallel printer intedace.
parameters.
••••.•
Pucal compiler.
Pucal cross-reference program.
Pucal execution proftler.
pascal file merger.
•.•••
Pucal interpreter.
•.•••
Pucal interpreter and executor.
Pucal interpreter code tranIJlator.
passwd - change login pa.ssword.
pa88wd - password file.
pasll1rord.
password.
pa88word file.
password file.
•
password file entry. getpwent,
pathname. • • • • • • • • • •
pathname of current working directory.
paths (Cllh only). which • • • • • • • •
pattern. • •• ~ • • . • • • • • • • •
pattern scanning and procealJing language.
pause - stop until signal.
••••••
pc - Pucal compiler.
•••••••••
pclose - initiate I/O to/from a process.
••••••••••••••••
• ••••
peer.
pending output.
•••••••••••
perfmon - graphica.l display of general system
periodic job..
•••••••••
permit or deny mess"es.
permuted index.
• ••••••
per-process resource limitations.
perror, gerror, ienno - get system error
perror, .ys_errlist, sys_nerr, errno - system
pereistent text. •• • • • • • • • • • •
phone number data bue.
•••••••
phonea - remote host phone number data bue.
phototypesetter interpreter.
••••••
physical relationships of screens.
pi - Pascal interpreter code translator.
pieces.
• •••••••••••••
pipe - create tninterprocess communication
pix - Pascal interpreter and executor.
place job in background.
play "Go Fish".
play Mille Bornel.
play the game of boggle.
•
Play the growing worm game.
•••••
plot - graphicI filters. •••
plot - graphicI intedace,
plotter accounting information.
plotter and Centronics printer intedace.
pmerge - pucal file merger.
••••••
point faultl. • • • • • • • • • • • • •
point, linemod, space, dosepl - graphics/ open pi,
point number.
point valuea. ••• • • • • •
pointer. • • • • • • • • • •
pop shell directory stade.
popd: pop shell directory stack.
••••••
popen, pclose - initiate I/O to/from a process.
port.
• •••••••••
port.
• ••••••••••
possibly in multiple columnl.
postmortem crash iLnalyser.
poatnews - submit news articles. • • • •
pow, gcd, rpow - multiple precision integer/
pow, sqrt - exponential, logarithm, power, square
power, square root. exp,
••••••••••
pr - print file(s), possibly in multiple columns.
•••••••
precision arithmetic language.
precision integer arithmetic. itom, madd, msub,
•••••••••••
prepare execution profile.
• xxix •

swapon(2)
IJoeketpair(2)
col(l)
me(7)
vp(4S)
ifeonfig(SC)
pe(l)
pxref(l)
pxp(l)
pmerge(l)

pX(I)
pix(l)
pi(l)
passwd(l)
passwd(5)
getp&8s(3)
passwd(l)
passwd(S)
vipw(S)
getpwent(3)
getwd(3)
getewd(3F)
whieh(l)
grep(l)
aWk(l)
pause(3C)

pC(I)
popen(3S)
get peername(2)
exit(3)
pedmon(t)
crontab(5)
meag(l)
ptx(l)
csh(l)
perror(3F)
perror(3)
Itieky(S)
phones(5)
phones(S)
pti(l)
adjaeentscreens( 1 )
pi(l)
split(l)
pipe(2)
pix(l)
csh(l)
fish(6)
mille(6)
boggle(6)
worm(6)
plot(IG)
plot(S)
pac(S)
vpc(4S)
pmerge(l)
trpfpe(3F)
pJot(3X)
fptype(3F)
isinf(3)
lIIee1c(2)
csh(l)
csh(l)
popen(3S)
ttynam(3F)
ttytype(S)
pr(l)
anaJyze(S)
postnews(l)
mp(3X)
exp(3M)
exp(3M)
pr(l)
be(l)
mp(3X)
monitor(3)
January 1984

Permuted /ndea
cpp - the C lupale
colcn - ilter Dro' output for CRT
unlel - undo a
type. Ipr - o'line
fortune pnhuh.tu:
job.:
• ad-

prfprhistoly.
ho.tid buner nm honname - .el or
keyword.. muprintenT prmailpstu pa.gesile pwd i1e. strinl' - ind
banner - print lalle baDner on
printcap Ipc -line
Ipd -line
vp - Ikon 10071-5 Multibu. Venatec parallel
VPC-2200 Venatec printer/plotter and Centronics
Iprm - remOTe job. from the line
pac\'PC - Sy.tech VPC-2200 Venatec
convenion .
• etpriority - let/sel procram schedulinl
Dice - set prolram
renice - alter
Dice: fUa low
Dice, nohup - ran a command at low
add user reboot - UNIX bootstrappinl
nice: fUn low priority
stop: halt a job or
_exit - terminate a
fork - create a new
fork - create a copy of this
kiD - lend a sipal to a proces., or terminate a
kill - lend sipal to a
kill - send a .ipal to a
popeD, pelose - initiate I/O to/from a
wait - await completioD of
exit - terminate a
init letpcrp - let
killPi - send .ipal to a
.
.etpcrp - set
letpid -let
letpid, letppid - pt
vf'ork - .pawn new
onintr:
kill - lend a .ipal to a
limit: alter perp. times -let
wait - wait for a
wait, wait3 - wait for
ptrace exit - termiaate
uurec - receive
kill: kill jobs and
gcore - get core images of fUnnin!
renice - alter priority of fUnnin!
wa.it: wait for ba.ckground

preproeellor.
••••••
previewinl.
•••••••
previous lel of aD sces lie.
primitive IYItem data typel.
print. • • • • • • • • • • • • • • • •
print a nndom, hopefully interestinl, adap.
print aD SCCS ile. • • • • • • • • • •
print commud hashinl statistic•.
print current job list. • • • • • • • • •
print current SCCS i1e editinl activity.
print 1Ie(.), po••ibly in multiple columai.
•••••••••
print Fortnn lie.
print history event list. • • • • • • • •
print identiier of current hon IYItem.
•••••
print l&fIe baDner OD printer.
print name list.
••••••••••
print nam' of curreDt ho.t ."tem. • • • • • • • •
print out manual palel; ind maDual informatioa by
print out the environment.
print out waitinC mail.
print IYItem fact.. • • • • • •
print syItem pa.ge .ile.
print workinl diredory Dame. • • • • • • •
printable strinl' in aD objed, or other biDary,
priDtcap - priDter capability data bue.
printenT - priDt out the environment. • • • • •
printer. • • • • • • • • •
printer capability data baH.
printer control prolr&lll.
•••••
printer daemon.
priDter iDterface. • • • • • • •
printer interface. "Pc - SyRech
printer .poolinc queue.
• • • •
printer/plotter accouDtiDc information. • ••
priDter/plotter aDd CeDtronic. printer iDterface.
printf, fprintf, .print( - formatted output
priority. letpriority,
priority. •• • • • • • • •
priority of nDDiDC procellel.
priority procell.
•••••
priority (s1a only).
• • •
prmail - print out waitiDI mail.
procedure for addiDI Dew usen.
procedure•.
procel,.
procel'.
proce...
procel'.
procel•.
proc....
proce••.
procell.
proc....
proce... • • • • • • • • • • • • • • •
proc... after Su.hinc any ptndinc output.
proce•• control initialilatioa.
proc... croup.
.
proce•• croup.
proceu croup.
proce •• id. • •
proc... identificatioa. • • • • • • • •
proc... in a virtual memory eficient way.
proc... intern pt. in command .cript•.
proces., or terminate a procell.
process resource limitation•.
proces. statu•.
••••••
procell times.
procesl to terminate.
procell to terminate or stop.
••••••
procesl trace.
proces. with R&t.l, • • • • • • •
procelled newl mides via mail.
processel. • ••••
processel. • ••••
processel. • ••••
processel to complete.
- xxx -

cpP(l)
coleri(l)
unlet(l)

typea(5)
Ipr(l)
fonune(6)
pn(l)

ah(l)
c.h(l)
.aet(1)
pr(l)
fpr(l)
clh(l)
.onid(l)
baDDer(S)
nm(l)
.0nDame(1)
mull)
printenv(l)
prmail(l)
pltat(S)
palesile( 1)
pWd(l)
.triDgs(l)
priDteap(5)
printenv(l)
banDer(S)
printcap(S)
Ipe(S)
Ipd(S)
VP(4S)
vpc(4S)
Iprm(l)
pae(S)
'Y])c(4S)
printf(SS)
letPriority(2)
nice(SC)
renice(S)
ah(l)
niee(l)
prmail(l)
adduser(S)
reboot(S)
csh(l)

csh(l)
exit(2)
fork(2)
fork(SF)
kill(l)
kill(2)
kill(SF)
popen(SS)
waite!)
exit(S)
init(8)
letPcrp(2)
killpc(2)
.etpcrp(2)
letpid(SF)
letpid(2)
vfork(2)
clh(l)
kill(l)

csh(l)
ps(l)
times(SC)
wait(3F)
wait(2)
ptnce(2)
exit(SF)
uuree(S)
csh(l)
gcore(l)
reDice(S)
csh(l)

Sun System Release 1.1

Permuted lndez
awk - pattern scanning and
h&J~ - stop the
m4 - macro
reboot - reboot system or halt
monstanup, moncontrol - prepare execution
profil - execution time
kgmon - generate a dump of the operating system's
gprof - display call graph
prof - display
pxp - Pucal execution
end, etext, edata - lut locations in
ftp - file transfer
Ipc - line printer control
Ipq - spool queue examination
mt - magnetic tape manipulating
pxref - Pucal crollll-reference
units - conversion
where is - locate Bource, biD&ry, and/or manual for
cb- C
onty). which - locate a.
,make - maintain
nice - set
getpriority, lIetpriority - get/llet
indent - indent and forma~ C
allllert lint - a C
lex - generator of lexical analYllill
vgrind - grind nice listings of
xstr - extract strings from C
!bio - general
if - general
arp - Address Rellolution
icmp - Internet Control Message
ip -Internet
tcp - Internet Transmission Control
telnet - user interface to the TELNET
udp - Internet Uller Datagram
getprotobyname, setprotoent, -endprotoent - get
inet - Internet
mi~ "': remote magtape
protocols ftpd - DARPA Internet File Transfer
telnetd - DARPA TELNET
tftpd - DARPA Trivial File Transfer
trpt - transliterate
mkproto - conlltruct a
arithmetit faille, true true, false pty -

diag - Generalungetc pushd:
puts, fputllpute, putchar, fputc:, putw logical unit.
on a stream.
stream. putc,
pute., putchar, fputc,

SUD System Release 1.1

processing Ia.nguage.
processor.
processor.
processor.
•
prof - display profile da.ta. •
profil - execution time profile.
profile. monitor,
profile.
profile bufl'ers.
profile data.
profile data.
profiler.
program.
program.
program.
program.
program.
program.
• ••••
program.
• ••••
program.
• •••
program beautifier. • • • • • • • • • •
program file including aliases and paths (csh • • • • • •
program groups. • • • • •
program priority. • • • • •
program scheduling priority.
program source.
program verification.
program verifier.
programs. • • • • •
programs. • • • • •
programs to implement shared strings.
properties of frame bufl'ers.
properties of network interfaces.
Protocol.
• ••••
Protocol.
•••••
Protocol.
Protocol.
protocol.
•••••
Protocol.
•••
• • •
• ••
protocol entry. getprotoent, getprotobynumber,
protocol family.
protocol module.
protocol name data base.
Protocol server.
protocol server.
Protocoillerver.
protocol trace.
• •
protocols - protocol name data base.
prototype file SYlltem.
provide drill in number facts.
provide truth values.
provide truth values.
pn - print an sces file.
ps - procesll status. •••
pseudo terminal driver. • • • • • • • •
psignal, sysJiglist - system signal messages.
pstat - print system factll. • • • •
pti - phototypelletter interpreter.
ptrace - process trace,
•••••
ptx - permuted index.
• ••••
pty - plleudo terminal driver.
••
purpose stand-alone utility package.
pUllh character back into input lit ream.
pUllh shell directory IIta.ck.
pUllhd: push IIhell directory stack.
put a string on a stream.
put character or word on a stream.
• • •
putc, fputc - write a. character to a FORTRAN
putc, putchar, fputc, putw - put character or word
putchar, fputc, putw - put character or word on a
puts, fputs - put a string on a stream..
•• • • •
putw - put characier or word on a stream.
pwd - print working directory name.
px - Pascal interpreter. • • • . • • • • •
pxp - Pascal execution profiler.
pxref - Pascal crosll-reference program.

- xxxi -

aWk(l)
halt(8)
m4(1)
reboot(2)
prof(1)
profil(2)
monitor(3)
profil(2)
kgmon(S)
gprof(l)
prof(l)
pxp(l)
end(3)
ftp(IC)
Ipc{S)
Ipq(l)
mt(l)
pxref(l)
units(l)
whereis(l)
cb(l)
which(l)
make(l)
nice(3C)
get pri oritY(2)
indent(l)
assert(3)
lint(l)
lex(l)
vgrind(l)
xlltr(l)
fbio(.fS)
if(4N)
arp(4P)
icmp(4P)
ip(.fP)
tcp(.fP)
telnet(IC)
udp(4P)
get protoent(3N}
inet(4F)
rmt(SC)
protocols(S)
ftpd(SC)
telnetd(SC)
tftpd(SC)
trpt(SC)
protocols( s)
mkpfoto(S)
arithmetic(6)
false(l)
true(l}
pI'8(I}

pS(I)
pty(4}
psignal(3)
pstat(S}
pti(l)
ptrace(2)
ptx(l)
pty(4)
diag(Ss)
ungetc(3S)
csh(l)
csh(l)
puts(3S)
putc(3S)
putc(3F)
putc(3S)
putc(3S)
puts(3S)
putc(3S)
pWd(l)

pX(I)
pxp(l)
pxref(l)

January 1984

Permuted [ndez

i~lIque, remque - inllen/remove element from a
Iprm - remove jobl from the line printer IIpooling
Ipq -llpool
qllortqllort-

quota - manipulate dillk
lIetquota - enable/ dilable
rain - animated
fonune - print a
rulib - convert archives to
rand, lII'and random, llrandom, initlltate, lIetstate - better
random number generator; routines for chuging/
rattor a IItream to.a remote command.

qllon - quick Ion.
qllon - quicker 1I0rt.
queue.
• •••••
queue.
• ••••
queue examination procn.m.
quick 1I0rt. • • • • • • • •
quicker Ion. • • • • •
qui. - test your lenowledge.
quot - lummari.e tile SYlltem ownenhip.
quota - manipulate disk quota•.
quotu.
••••••••
quotu on a tile IYIItem. •
rain - a.nima.ted raindrop. dillplay.
•••
raindrop. display.
rud, .rand - random number generator.
random, hopefully interesting, adace.
random libraries. • • • • • •
ra.ndom number generator.
••
rudom number generator; routines for changing/
rudom, Brudom, initstate, setatate - better
ranlib - convert a.rchivel to random librariell.
rattor - ration&l Fortru dialect. •
ra.tional Fonran dialec'. • • • • • • • • • •
rc - command IICript for auto-reboo' and daemonll.
rcmd, rrellVport, roserole - routinell for returning
rcp - remote tile copy.
•
rdate - ad lIystem date from a remote hOlt.
read a pusword.
read comma.nda from file.
read input.
••••••
read newll anielel.
• • •
read, readonly, let, IIhirt, timel, trap, umask,
••••••••••
read, readv - read input.
read value of a Iymbolic link.
••••••••••••
readdir, telldir, lIeekdir, rewinddir, c:lolledirreading or writing, or create a new tile.
rea.dlink - read va.lue of a lIymbolic link. • • • •
readnew. - rea.d newl a.rtielell.
readnews(l) a.nd checknewll(l). • • • • • • • •
readonly, .et, IIhift, times, trap, umuk, wait-/
readv - rea.d inpu'.
read/write pointer.
real and elective group ID.
•••••
real and elective uller 10'11.
rea.lIoc, c&lloc, cfree, a.lloca - memory allocator.
reboot - reboot lIystem or halt procesllor.
reboot - UNIX bootlltrapping procedures.
reboot and daemon...
rebootSYlltem or halt procellllOr.
reboot/halt the .ystem without checking the disks.
rebuild the data bue for the mail aliuell tile.
receive a melllla.ge from a locket.
receive mail. •••
receive mail amonl ullen. • • • • • • •
receive procellsed new. anides via mail.
receive unproceslled anielell via mail.
receive unprocelllled anielell via mail.
received via uucp.
•••••••
• • • •
reeDeWI - receive unproceslled articles via mail.
reenewa - receive unproceslled articles via mait.
re_comp, re_exec - regular expression handler.
recompute command huh table. •
record.. • • • • •
reco.very.
•
recv, recvfrom, reevmsg - receive a mesll&p from a
recvfrom, recvmsg - receive a mellsage from a
recvmsg - receive a JDesllage from a locket.
re-evaluate IIhell data.
re_exec - regular expression handler.
• • •
refer - find and insert literature referencel in
reference program.
referencell in a bibliography. /- make inverted • • • • •
referencell in documents.
•••••
regular expression handler.
•
rehuh: recompute command huh table.
reject lines common to two 1I0rted filell.
0

•

0

•

•

0

0

•

•

•

0

•

•

0

0

getpul 1I0urce:
read, ready readnewll wait/ lcd, eval, exec, exit, export, login, newgrp,
rea.dlink directory opera.tion.. opendir,
open - open a tile for
newBrc - informa.tion tile for
/ cd, eval, exec, exit, export. login, newgrp, rea.d,
read,
Illeek, tell - move
letregid - lid
lIetreuid - let
malloc, free,
rc - comma.nd IICrip' for autoreboot fa.lltboot, futhalt newaliallea recv. rernrom, recvmllgmail - lend &n.d
/bin/ma.il- lend or
uurec recnewllrecnewlrmail - handle remote mail

rehuh:
!ltmp, wtmp -Iogia
eyac:c - moditied yac:c allowing much improved error
locket.
locket. recv,
recv, recvfrom,
ev&!:
re_comp,
documents.
pxref - Pucal crollllindex to a bibliography .br lookbib - tind
refer - find and inllert literature
re_comp. re_exec (omm - lIeled or

•

•

•

0

0

0

0

•

•

•

•

0

•

•

•

0

•

•

•

•

0

•

•

•

•

•

0

•

•

•

•

0

0

0

0

•

0

0

•

•

0

•

0.......

0

o.

0

•

0

0

0

•

•

•

•

0

0

0

•

•

0

0

0

•

•

•

•

••

0

•

•

0

•

0

0

0

•

•

0

•

0

•

0

•

0

0

0

0

•

0

0

00

•

0

•

0

•

•

0

0

•

0

0

0

0

0

o. .

0...

- xxxii -

0

•

•

•

0

•

•

0

•

0

•

0

•

•

•

qsort(SF)
qllort(S)
inllque(S)
Iprm(l)
Ipq(l)
qllon(SF)
qson(s)
quil(6)
quot(8)
quota.(2)
quota.(2)
aetquota(2)
rain(6)
rain(6)
rnd(SC)
fonune(6)
rnlib(l)
rud(SC)
random{S)
rudom(S)
rnlib(l)
ratfor{l)
rattor{l)
rc(S)
rcmd(SN)
rcp(lC)
rdate(8)
get pus(S)
csh(l)
read(2)
readnews(l)
sh(l)
rea.d(2)
readlink(2)
directory(S)
open(2)
readlink( 2)
readnews{1)
newsrc(5)
IIh(l)
rea.d(2)
lseek(2)
aetregid(2)
aetreuid(2)
malloc(S)
reboot(2)
reboot(S)
rc(8)
reboot(2)
fast boot (8)
newalialles(8)
recv(2)
mail(l)
binmail(l)
uurec(S)
reaews(l)
reenews(8)
rmail(8)
recnews(1)
recnews(8)
regex(S)
csh(l)
utmp(S)
eyac:c(l)
recv(2)
recv(2)
recv(2)
csh(l)
regex(S)
refer{l)
pxref(l)
indxbib{l)
refer{l)
regex(S)
csh(l)
comm(l)

SUD System Release 1.1

Permuted Indez
lorder - find ordering
join - notify the window driver of the physical
sigpause - atomically
strip - remove symbols and
leave calendar ruseroBe - routines for returning a stream to a
rexee - return stream to a
rexecd rcp rdate - set. system date from a
uusend - send a file to a
remote phones rlogin rlogind rmtrmail - handle

nhnhd tip, cu - connect to a
rmdelunlink rmdir unaliu:
Bock - apply or
colnn unlink insque, rem que - insert/
unsetenv:
mount, umount - mount or
Iprmderolexpire unlimit:
strip rmdir, nn rm, rmdir iBsque,
rename mv - move or
- file system consistency check and interactive
trpfpe, fpecnt - trap and
while:
uniet - report
repeat; execute command
yes - be
dfiostat uniqvmstat fseek, (tell fseek, ftell, rewind notafy:
state.
reset arp - address
arp - Addres.
getrlimit, setrlimit - control maximum lIystem
vlimit - control maximum lIystem
limit: alter per-process
unlimit: remove
get.rusage - get information about
vtimes - get.. information about
restore - incremental file lIystem
o

sullpe,d: lIullpend a IIhell,
getarg, iarge idate, itime Bmin, Bmax, dBmin, dBmax, inmax -

Sun System Release 1.1

relation for an object library.
relational databa.:se operator. • • • • • •
relationships of screens. adjacentscreen8
release blocked signals and wait for interrupt.
relocation bits. • • • • • • • • •
remind you when you have to leave.
reminder service. • • • • • • • •
remote - remote host de3cription file.
remote command. rcmd, rresvport.
remote command.
remote execution server.
remote file copy.
remote host. • • • • • • •
remote host. • • • • • •
remote host description file.
remote host phone number data base.
remote login.
•••••••••
remote login server. • • • • • • •
remote magtape protocol module.
remote mail received via uucp.
remote shell.
remote shell server. • • • • •
remote system. • • • • • • • • •
remove a. delta from an SCCS file.
remove a directory entry.
remove a directory file.
remove alialles.
• • • • •
remove an advisory lock on an open file.
remove columnll from a file.
remove directory entry.
remove element from a queue.
remove environment variable•.
remove file system. • • • • • •
• • • •
remove job. from t·he line printer IIpooling queue.
remove nrol, trol, tbl and eqn constructs.
remove outdated newlI articles.
remove resource limitia.tions.
remove symbols and relocation bits.
•••••
remove (unlink) directoriell or files. • • • • •
remove (unlink) files or directories. • • • • •
remque - insert/remove element from a queue.
rename - change the Dame of a file.
rename - rename a file.
rename a file.
•••••••••
rename file.. • • • • • • • • • •
renice - alter priority of running processes.
repair. fsck • • • • • • • • •
repair Boating point faults.
•••••
repeat command. conditionally.
repeat: execute commud repeatedly.
repeated lines in a file.
repeatedly.
••••••••••••
repetitively affirmative. • • • • • • •
report free disk space on file systems.
report I/O statistics.
••••••
report repeated lines in a file.
report virtual memory lltatistic•.
repollition a file on a logical unit.
•••••
reposition a IItream.
request immediate notification. •
rellet - reset the teletype bits to a sensible
rellet the teletype bits to a lIenllible state.
rellolution dillplay &pd control.
Resolution Protocol.
rellource conllumption.
resource consumption.
resource limitations.
rellource limitiations.
resource utilization.
resource utilisation.
restore. • • • • •
restore - incremental file system restore.
resuming its superior. • • • • • • •
return command line arguments.
return date or time in numerical form.
return extreme values.
••••••••
• xxxiii -

lorder{l)
join(l)
adjaeentsereens( I)
sigpause(2)
strip(l)
leave{l)
calendar{l)
remote(5)
remd(3N)
rexec(3N)
rexecd(SC)
rep(IC)
rdate(S}
uusend(IC)
remote(5)
phones(5)
rlogin(IC}
rlogind(SC)
nnt(SC)
nnail(S)
rsh(IC)
rshd(SC)
tip(IC)
nndel(l)
unlink{SF)
rmdir(2)
cllh(l)
floek(2)
colnn(l)
unlink(2)
insque(S)
csh(l)
mount(2)
lpnn(l)
deroff(l)
expire(S)
csh(l)
strip(l)
rmdir{t)
rm(l)
insque(S)
rename(2}
rename(3F)
ren&me(3F)
mv{t)
renice(S)
f"ek(S)
trpfpe(3F)
csh(l)
csh(l)
uniq(l)
csh(l)
yes(l)
df(l)
iostat(S)
uniq(l)
vmstat(S)
fseek(3F)
f"eek(SS)
csh(l)
reset(l)
reset(l)
arp(SC)
&rp(4P)
getrlimit(2)
vlimit(3C)
csh(l)
esh(l)
getrusage(2)
vtimes(3C)
restore(S)
restore(S)
esh(l)
getarg(3F)
idate(3F)
range(3F)
January 1984

Permuted Indez
rexec - returD stream t.o a remote command.
loc - return the address of aD object.
rcmd, rresvport, ruserok - routines for retUrDiD, a st.ream to a remote command.
rev - revene line. of a file.
rev- revene line. of a file.
••••••
lastcoQlm - show l&IIt commands executed in revene order.
col- filter revene paper motion•.
•••••
fseek, ftell, rewind - repollitioD a stream.
opendir, re4Lcldir, telldir, leekdir, rewinddir. cJolledir - directory operatioDI.
rexec - return st.ream to a remote command.
rexecd - remote execution lerver.
strcmp, strncmp, strcpy, stmcpy, strlen, index, rindex - string operation.. atreat, atrDc&t,
object.. index, rindex, Inblnk. leD - tell about character
rlogiD - remote login. • • • • • • • • •
rlogind - remote tOgiD server.
•••••••
• ••
rmdir, rm - remove (unlink,) directories or files.
rm, rmdir - remove (unlink) file. or directoriet.
rmail - handle remote mail received via uucp.
rmdel - remove a delta from an SCCS file.
rm, rmdir - remove (unlink) filel or directoriel.
rmdir - remove a directory file.
••••••
rmdir, rm - remove (unlink) directories or filel.
rmt - remote magtape protocol module.
•••••••••••••••
chue - Try to escape to killer robots.
rotfbib - run 01 bibliographic databa.e.
pow, Iqrt - exponential, IOlarithm, power, square root exp, 101, 10110, • • • • • • • • •
chroot - chanle root directory, • • • • • • • • • • • • • •
route - manually manipub.te the routinl table•.
routed - network routinl daemon.
••••••
fsplit - .plit a multi- routine Fortran file into individual files.
tloto, tpute - terminal independent operation routinel. t.letent. tldnum. tletlac. tcetstr.
.etltate - better random number lenerator. routinel for changinl I ..eraton. /initstate,
command. rcmd, rrellVport, ru.erok - rout in.. for returninl a stream to a remote
- sy.tem IlUPportinl for local network packet routinl. routing • • • • • • • • • • • •
packet routinl. routing - Iystem supportinl for local network
routed - network routinl daemon. • • • • • • • • • • • • • •
route - manually manipulate the routinl tablel. • • • • • • • • • • • • • • •
itom, madd, msub, mult, mdiv, min, mout, pow, lcd, rpow - multiple precisioD integer arithmetic.
Itream to a remote command. rcmd, rresvport. ruserok - routina for returDing a
nh - remote shell.
•••••••••
nhtl - remote .hellserver. • • • • • •
nice, nohup - run & command at. low priority (sh only).
nohup: run command immune to haniupl.
nice: run low priority process.
rotfbib - run 01 bibliographic databaH.
••••••
crontab - table of times to run periodic jobs.
••••••
Icore - Cd core iQlage. of runninl proceslles.
renice - alter priori'~y of running processes.
•••••••••••
ruptime - show host statu. of local machines.
remote command. rcmd, rrelVport, rullerok - routines for returDinc a stream to a
rwho - who's lOlled in on local machines.
rwhod - sy.tem IItatu. server.
ec - SCom to Mb/ s Ethernet interface.
•••••
en - Sun 3 Mb/ • experimental Ethernet intedace.
pr - print file( .). pOllllibly in mUltiple columns.
II.. acctoD - Iystem accountiDI..
•
lad - print current SCCS file editinl activity.
lail - multi-uler woodeD Ihip. aDd iroD meD.
lavecore - lave & core dump of the operatinc system. •
system. lancore - save a core dump of the operatinc
brk, Ibrk - change data 'segmeDt sise.
st - Driver for SysgeD SC 4000 (Archive) Tape Controller. ••
Icandir, alphuort - scaD a directory. • • • • • • • • • • • •
scandir. alphasort .:. scaD a directory. • • • • •
conversioD. Icanf. bead, IIIcanf - formatted inpu~
awk - patterD scanDinl and proceninl language.
18 - lilogSS30 SCC lerial comunicationl driver.
••••••
sca - front end for the .SM SCCS IlUbsystem.
cdc - change the delta commentary of aD SCCS delta.
comb - combiDe SCCS deltu.
delta - make a delta (change) to aD SCCS filo.
get. - get. a version of an SCCS 61e.
pre - print. an SCCS 61e.
rmdel - remove a delta from aD SCCS 61e.
sccsdil - compare two versions of an SCCS file.
scesfile - format. of sces file.

. .
~

January IgS4

- xxxiv -

rexec(3N)
loe(SF)
rcmd(SN}
rev{l)
rev{t)
l&IItcomm( t)
col(t)
fseek(SS}
directory(3)
rexec(3N)
rexecd(SC)
Itring(S)
index(3F)
rlogin(tC)
rlogind(SC)
rmdir(t)
nn(t)
nnail(S)
nndel(t)
nn(l)
nndir(2)
nndir(l)
rmt(SC)
chase(6)
rotfbib(t)
exp(SM)
chroot(2)
route(SC)
routed(SC)
fsplit(l)
termcap(SX)
random(S)
rcmd(SN}
routiDg( 4N)
routing( 4N)
routed(SC)
route(SC)
mp(SX}
rcmd(3N)
nh(lC)
nhd(8C)
nice(t)
csh(l)
csh(l)
rotfbib(t)
crontab(5)
Icore(l)
renice(S)
ruptime(lC)
rcmd(SN)
rwho(lC)
rwhod(SC)
ec(4S)
eD(4S)
pr(l)
1&(8)
sact(l}
lail(6)
savecore(S)
lavecore(S)
brk(2)
It(48)
scandir(3)
scudir(3)
scaDf(SS)
aWk(l}
Is(4S)
Ica(l)
edc(t)
comb(l)
delta.{t)
set(t}
pn(t)
rmdel(l)
Icceditr( t)
Icafile(S}

Sun System Release 1.1

Permute d Index
unget - undo a previous get. of an
val - validat.e
sad - print. current
admin - create and administer
sca - front end for the .SM
alarm getpriority, setpriority - get/set. program
clear - clear workstat.ion or t.erminal
curses ex. vit.he window driver of the physical relationships of
adbgen - generat.e adb
rc - command
onintr: prOCelll interrupti in command
Controllen.
grep, egrep, fgrep xlend, xcet, enroll operationl. opendir, readdir. t.elldir,
brk, Ibrk - change dat.a
commcase:
uusend lend, lendto, lendmsg killkillmaillendmailsendne'Wl/bin/maillOCket
killkillp, aliuel - aliuel filo for
lend. sendto,
..
lend,
reset - reset the teletype bit, to a
oct - Central Data octal
n - lilo, 8530 SCC
comsat - bil
ftpd - DARPA Internet File Transfer Protocol
rexecd - remot.e execution
rlosind - remote login
I'IIhd - remote shell
rwhod - system statuI
telnetd - DARPA TEL NET protocol
tftpd - DARPA Trivial File Transfer Protocol
timed - DARPA Time
serven - inet
calendar - reminder
inetd - internet
logout: ebd
Icript - make typescript of terminal
ueii - map of ASCII character
stty, st.tyliptack sigsetmask gettimeofday, lettimeofday - getl
umask utime utimelletgrouplgethostname, lethostname - getl
getsockopt, letsockopt - get. and
host.name setpgrp niceSUD

System Release 1.1

SCCS file. • • • • • • • •
SCCS file. • • • • • • • •
SCCS file editing activity.
SCCS files.
• •••••
SCCS subsystem.
• • •
•
sccsdiff - compare t.wo versions of an SCCS file.
sccsfile - format of sces file.
• • • • •
schedule signal after specified time. • • • • • •
scheduling priority. • • • • • • • • • • • • •
screen.
• •••••••••••••••••
screen functions with "optimal" cursor motion.
screen oriented (visual) display editor based on
screens. adjacentscreeDs - notify •• • • • •
script.
••••••••••••••••
script - make typescript. of terminal session.
Icript for auto-reboot. and daemons.
•••••••••••••••
scriptl.
sd - Disk driver ror Adapt.ec ST-506 Disk
search a file for a pattern. • • • • • •
secret mail.
••••••••••••
sed - stream editor.
••••••••
seekdir, rewinddir, closedir - directory
legment lile.
•••••••••••••••
lelect - synchronoul I/O multiplexing.
••
select or reject lines common to two sorted files.
lelector in switch.
•••••••••••••
send a file to a remote host. • • • • • • • •
send a meslage from a socket. • • • • • • • •
send a signal to a procells. • • • • • • • • •
send a lignal to a prOCellS, or terminate a process.
send and receive mail. • • • • •
•••••••••
send mail over the internet.
lend news articles via mail.
•••••••••
send or receive mail among users.
••••••
send, sendto, sendmsg - send a message from a
send signal to a procells. • • • • • • • •
send signal to a procells group.
sendmail.
••••••••••••••
aendmail - send mail over the internet.
sendms, - send a message from a socket.
sendne'W1 - lend newl articles via mail. • • • •
aendto, lendms, - Bend a mellage from a socket.
sensible state.
••••••
serial card.
......,.
aerial comunication, driver.
server.
server.
server.
server.
server.
eerver.
server.
server.
server.
eerver data base. • • • • •
serven - inet server data base.
service.
eervices - service name dat.a base.
servie_s daemon.
session. • • • • • • • • •
lessiod. • • • • • • • •
set. • • • • • • • • • •
set and get terminai state. • • • •
let and/ Of get signal stack context.
set: change value of shell variable.
set current signal mask.
set date and time.
set file creation mode mask.
set file times.
•••••
let. file times.
•••••
set group access list.
•••
lOt name of current host.
let options on sockets.
••
set or print name of current host system.
set process group.
set program priority. • • • • • • • •
0.••••••••••

• xxxv-

unget(l)
val(l)
sact(l}
a.dmin(l}
sces(l)
scesdiff(l}
sccsfile(S)
alarm(3C)
getprioritY(2)
clear{l)
curses(3X)
vi(l)
adjacentscreens(l)
adbgen(S)
script(l)
rc(S)
(sh(l)
sd(4S)
grep(l)
xsend(l)
sed(l)
directory(3)
brk(2)
select(2)
comm(l)
csh(l)
uusend(IC)
send(2)
kill(3F)
kill(l)
mail(l)
sendmail(S)
sendnews(S)
binmail(l)
send(2)
kill(2)
killpg(2)
aliases(S)
sendmail(S)
send(2)
lendnews(S)
.end(2)
reset(l)
oct(4S)
18(4S)
comsat(SC)
ftpd(SC)
rexecd(SC)
rlogind(SC)
rshd(SC)
rwhod(SC)
telnetd(SC)
tftpd(SC)
timed(SC)
servers(S)
servers(S)
calendar{ I)
services(S)
inetd(SC)
csh(l)
script(l)
ascii(7)
stty(3C)
sigstack(2)
csh(l)
sigsetmask(2)
gettimeofday(2}
umask(2)
utime(3C)
utimes(2)
setgroups(2)
gethostname(2)
getsockopt(2 )
hostname(l)
setpgrp(2)
nice(3C)

January 1984

Permuted [ndez
get priority, setpriority - get/
setregid letreuid /exec, exit, export, login, newgrp, read, readODly,
rdate cetty Ittydate - dilplay or
eeteuid, letruid, letgid, letegid, letrgid ulimit - cet and
cetitimer, aetitimer - cetl
leteJaY:
to a Itream.
stream. letbuf,
aetuid, leteuid, aetruid, I.tcid,
user and group 10. aetuid,
file/ getf.ent, getfsapec, getlefile, getfstype,
•etuid, seteuid, aetruid,
getgreut, getgrgid, cetgrDam,
gethostent, gethostbyaddr, gethostbyname,
gethoatuame,
getitimer,
crypt,
aetbuf, aetbuler,
getnetent, cetnetbyaddr, getnetbyname,
get priority,
getprotoent, getprotobyuumber, getprotobyuame,
getpwent, getpwuid, cetpwnam,

letuid, seteuid, aetruid, setgid, setegid,
consumption. getrlimit,
group 10. letuid, lIeteuid,
getlerveut, getservbyport, cetaervbyname,
getlockopt,
routinel for changingl random, srandom, initstate,
gettimeofday,
- let user and group 10.
cd, eval, exec, exit, export, login, newcrP, re&d.!
nice, nohup - run a command at low priority (
- extract IItringll from C programll to implement
ch.h - change default login
exit: leave
rsh - remote
system - issue a
csh - a
eval: re-evaluate
popd: pop
pUllhd: pUllh
aliu:
IUS pend: IUS pend a
nhd - remote
aet: change value of
0: arithmetic on
unlet: discard
exec: overlay
exit, export, login, newgrp, read, readonly, set,
sail - multi-uller wooden
grOUpllruptimeuptime la.stcomm nebbt shutdown connection.
login pause - atop until
signal - change tbe action for a

Ja.nua.ry 1984

set program scheduling priority.
••••••
set. real and elective group 10. • • • • • • •
set real and elective user 10'11. • • • • • • •
set, shin, times, trap, umule, wait - commandl
let aystem date from a remote host.
let terminal mode.
• ••••
aet terminal optionl.
let the date.
• • • • • •
let uler and group 10. letuid,
let uler limit.. • • • • • • •
let value of interval timer. • •
.et variable in environment. • • • • • • • •
letbul, .etbuler, aetlinebul- ulip bulerinc
.etbuler, .etlinebuf - a'lip bulering to a • •
letegid, letrgid - aet uler and group 10. • • • • • • • •
letenv: let variable in euvironment. •• • • •
leteuid, letruid, letgid, letegid, letrgid - let
letfaent, endfllent - get file BYltem descriptor
..tgid, letecid, letrgid - let uler and group 10.
lIetgrent, endgrent - get group file entry.
letgrouplI - let group accelll lin. • • • • • • • • • • •
letholltent, endhostent - get network host entry.
letholltname - get/let name 01 current host.
letitimer - get/let value 01 interval timer.
letjmp, loncjmp - non-Iocalgoto.
letkey, encrypt - DES encryptioa.
aetlinebul - aasign bulering to a stream.
• • • • •
• • • • •
letnetent, endnetent - get network entry.
letpgrp - let procell group. • • • • • • • • •
letpriority - cet/aet program acheduling priority.
letprotoent, endprotoent - get protocol entry.
letpwent, endpwent - cet pusword file entry. • • • • •
letquota - enable/dill able quotu on a file ayltem.
lIetrecid - aet real and elective group 10.
letreuid - let real and elective uler 10'1.
letrgid - set uller and group 10.
.etrlimit - control maximum system resource
letruid, letgid, setegid, .etrgid - let uler and
.etservent, endllervent - get service entry.
.et.ockopt - cet and let optionl on locket •.
.etatate - better random number generator;
lettimeolday - get/set date and time.
.etuid, seteuid, aetruid, setgid, aetegid, letrgid
sh, lor, cue, if, while, :, ., break, continue,
ah only).
ahared stringl. xstr
IIhelf·
.hell. • • • • • •
Ihell. • • • • • • •
Ihell comma.d.
••••••••••••••••••
Ihell (command interpreter) with C-like syntax.
.hell data.
Ihell directory atack.
shell directory atack.
Ihell macrol. • • • •
Ihell, resumin, its luperior.
I hell Ie rver.
••••••
Ihell variable.
Ihell variablel. • • • • •
.hell variablel. • • • • • •
Ihell with specified comm&nd.
.hift: manipulate argument list.
•••••••••
Ihift, times, trap, umuk, wait - commandl /exec, •
ahipi and iron men.· • • • • • • • • • • • • • •
ahow group membenhips. • • • • • • • • • •
show hon natul of local machines. • • • • •
Ihow how long system hal beeD up. •• • • • •
IIhow lut commandll executed in revene order. • • • • •
IIhow network status. • • • • • • • • • • • •
IIhut down part 01 a full-duplex connection.
••
IIhutdown' - dose down the lIystem at a given time.
shutdowD - shut down part of a full-duplex
sigblock - block lIignals.
sign OD.
• ~
signal.
lIignal.

- xxxvi·

getpriority(2)
letregid(2)
setreuid(2)
sh(l}
rdate(S)
cetty(8}
sUy(I)
date(l)
.etuid(3}
ulimit(3C)
cetitimer(Z}
csh(l}
.etbur(3S}
aetbur(SS)
setuid(3)
csh(l)
aetuid(3)
cetrsent(3)
.etuid(S)
cetgrent(3)
letgroups(Z)
cethostent(SN)
gethostname(Z)
getitimer(Z)
lIetjmp(3)
crypt(S)
lIetbur(aS)
getnetent(SN)
setpgrp(Z)
cetpriority(2)
get protoent(SN)
getpwent(S)
lIetquota,(2)
aetregid(2)
lIetreuid(2)
aetuid(S)
getrlimit(2)
aetuid(S)
cetservent(SN)
getsockopt(Z)
random(3)
gettimeorday(2)
.ehid(S)
.h(l)
Dice(l)
xlltr(l)
chllh(l)
csh(l)
nh(IC)
system(S)
cllh(l)
cllh(l)
cllh(l)
csh(l)
cllh(l)
cllh(l)
nhd(SC)
csh(l)
cllh(l)
csh(l)
cah(l)
cllh(l)
sh(l)
sail(S)
groups(l)
ruptime(l C)
uptime(l)
la.stcomm( I)
aetstat(S)
ahutdown(2)
ahutdown(S)
ahutdown(2)
lIigblock(2)
login(l)
pause(3C)
signal(SF}

Sun System Release 1.1

Permuted Indez

alarm - schedule
signal - limplified I oft ware
ligvec - software
lIipetm&8k - set current
psipal, sY'Jiglist - system
sigst&ek - let and/or get
kill-lend
kill-send a
killpg - lend
kill - lend a
• igblock - block
sigpause - atomically release blocked
wait for interrupt.

lipaltrigonometric functions.
null- data
brk, ebrk - change data segment
getdtablesi.e -let delcriptor table
let pageli.e - let system pale
pagesi.e - print Iystem pale
si.e -

sces - front end for the
ip - Disk driver for Interphue 2180
xy - Disk driver for Xylosic.
IIpline - interpolate
snake,
accept - a.ccept a connection on a
bind - bind a name to a
connect - initiate a connection OD a
listeD - listeD for connectionl on a
reel', recvfrom, recvmsg - receive a menale from-a
lend, Bendto, lendml - Bend a melllale from a
getsockname - get
letlockopt, setllockopt - let and let options on
lOCket pair - create a pair of connected

sipal - change the action for a signal.
signal - lIimplified software signal facilities.
lIignal after specified time.
signal facilities.
lIignal facilities.
signal muk.
sipal mess agel.
••
signal stack context.
lipal to a procesl.
signal to a proceSIl. ••
signal to a proceSII group.
••••
lIignal to a process, or terminate a process.
signal..
• •••••••••••••••
signals and wait for interrupt. • • • • • • •
lIigpaulle - atomically releue blocked signals and
lipetmask - let current signal muk. • • • • •
liptack - let and/or get signalltack context. • • • • •
sigvec - 1I0ftware lipal facilities. • • • • •
.implified loftware signal facilitiel.
lin, COli, tan, uin, acos, atan, atan2 - •
lIinh, cOllh, tanh - hyperbolic functionl.
sink.
.ilt.
li.t.
lilt.
li.e.
•••••••
li.e - lise of an object file.
lilt of an object file.
• • • • • • • • • • • • •
.Ieep - 'lUll pend execution for aD interval.
sleep - IUllpend execution for an interval.
Ileep - luspend executioD for interval.
• ••
.SM sces subsystem.
SMD Disk Controller. • • • • • •
SMD Dillk Controllers.
• ••••
smooth curve.
•• ~ • • • • • •
lnake, Inscore - display challe game.
••••••••••
Inlcore - display chue game.
.OCke!.
.ocke .
IOOke .
locket
locket.
•••
• ••••••••••••
socket.
locket - create aD endpoint for communicatioD.
locket name. • • • • • • • • • • • • • • • •
locketpair - create a pair of connected sockets.
1I0cketl. • • • • • • • • • • • • • • •
locketl. • • • • • • 4 • • • • • • • •
loelim - eliminate .SO'II from nroB' input.
loftware loopback network interface.
1I0ftware signal facilities.
loftware lignal facilities.
• • • • • • • • • •
lo,itaire card game canfield.

10 signal - simplified
lIigvec canfield, cfscore. - the
••.•.•..•
qson - quicker 10ft
• •••••••••
qson - quick soii.
. •...•..•.
tson - topolosical 10K.
Ion - lort or merge filel.
sorttlb - sort bibliographic database.
• • •
son - Ion or merge filel.
Bortbib - Bort bibliographic databue. • • • • •
eomm - .elect or reject linel common to two lorted filel.
look - find linell in a Borted list. • •
soelim - eliminate
indent - indent and format C program source.
- create an error mesllage file by mUllaginl C source. mkstr . , . . . . . . . . . .
whereill - locate source, binary, and/or manual for program.
source: read commandll from file.
mem, kmem, mbmem, mbio - main memory and I/O Ipace. • • • • • • • • • • • •
line, circle, arc, move, cont, point, linemod, Ipace, closepl - graphics interface. /Iabel,
df - report free disk space on file systems. • • • • • • • • •
•••••••••••
expand, unexpand - expand tabs to spaces, and vice vena.
way. vfork- Ipawn new process iD a virtual memory efficient
exec:. overlay shell with Ipecified command.
head - display first few lines of IIpecified files.
•••••
truncate, ftruncate - truncate a file to a specified length.
alarm - Ichedule sipal after specified time.

SUD System Release 1.1

- xxxvii -

signal(3F)
signal(3)
alarm(3C)
signal(3)
sigvec(2)
lIigsetmask(2)
psignal(3)
sigstack(2)
kill(2)
kill(3F)
killpg(2)
kill(t)
lIigblock(2)
sigpause(2)
sigpause(2)
sigsetmask( 2)
sigstack(2)
sigvec(2)
signal(3)
sin(3M)
sinh(3M)
null( 4)
brk(2)
getdtablesile(2)
getpagesise(2)
pagesile( t )
siseCl)
siseCt)
sleep(l)
sleep(3F)
sleep(3)
IICes(t)
ip(4S)
xy(4S)
IIpline(tG)
snake(6)
IInake(6)
accept(2)
bind(2)
connect(2)
listen(2)
recv(2)
lIend(2)
socket(2)
getsockname(2)
socketpair(2)
getsockopt(2)
lIocketpair(2)
soelim(t)

10(4)
lIignal(3}
lIigvec(2)
canfield(6)
qsort(3)
qsort(3F)
hort(t)
1I0rt(t}
sortbib(l)
sort(t)
sortbib(t)
comm(t)
look(t)
indent(t)
mkstr(l)
whereis(t)
csh(t)
mem(4S)
plot(3X)
df(t)
expand(t)
vlork(2)
csh(t)
head(t)
truncate(2)
alarm(3C)
January Ul84

Permuted Indez
alarm(SF)
alarm - execute a. subroutine after a specified t.ime. •
awapon(S)
napon - specify additi01lal device lor paging and swapping.
spell(l)
spell, spellin, spellout - find spelling erron.
spell(l)
spell, spellin, spellout - find spelling erron.
spell(l)
spell, spellin, spellout - find spelling erron. ••
apell(l)
o.
llpell,spellin, spellout - find spelling erron.
apline(lG)
spline - interpolate smooth curve.
aplit(l)
split - split a file into pieces. ••
split(l)
split - Iplit a file into pieces.
fsplit(l)
filea. fsplit- split a multi-routine Fortn.n file int.o individual
frexp(S)
frexp, Idexp, modf - split into mantissa and exponent.
uuclean(80)
uuclean - uucp spool directory clean-up.
Ipq(l)
Ipq- spool queue examination program.
lprm(l)
Iprm - remove jobs from the line printer spooling queue. •
printf(3S)
printf, fprintf, .printl - lormatted output convenion.
exp(SM)
exp, log, 10110, pow, sqrt - exponential, logarithm, power, square root.
exp(SM)
loC10, pow, Iqrt - exponential, locarithm, power, squa.re root. exp, log,
rud(3C)
rand, srand - random number ,enerator. o.
random(S)
number ,enerator; routine. for ch&nein,/ random, srandom, initst&te, setatate - better n.ndom
seuf(SS)
•
Ic&nf, fsunl, IIcanr - formatted input convenion.
It(4S)
Controller. st - Driver lor Sysgen SO 4000 (Archive) Tape
sd(4S)
Id - Disk driver for Ad&ptec ST-506 Disk Controllen.
cllh(l)
popd: pop shell directory stack.
csh(l)
pUBhd: push shell directory .tack. •
sigstack(2)
siptack - set and/or get sipal stack context, • • • •
imemtest(Ss)
imemtest - stand alone memory test.
gxtest(Ss)
gxtest- sta.nd alone test for the Sun video graphics board.
diag(8s)
•
dias - Genen.l-purpose stand-alone utility packase.
intro(SS)
atdio - standud buffered input/output. package.
htable - convert NIO standard format. host tables. •••
htable(S)
tee{l}
tee - copy Itandard output to many filet.
Itat, latat, fatat. - get. file Itatus.
ltat(2)
reset - reset the teletype bits to a sensible state.
reset(l)
stty, gtty - set &nd get terminal state.
Itty(3C)
fsync(2)
fsync - synchronile a file's in-core state with that. on disk. • • • • •
if: conditional statement. • • • • • • • • • •
csh(l)
fstab(S)
btab - static information about. the filesystelDJ.
hashstat: print command hashin, statistics.
csh(l)
iostat - report I/O ltatistic•.
iostat(S)
pedmon - craphical display of general system .t&tiatic•.
pedmon(l)
vmlt&t - report virtual memory ltatistic•.
vmstat(8)
exit - terminate process with Itatus.
exit(3F)
nehtat - Ihow network statuI.
netstat(8)
ps - procen .t&tu•.
ps(l)
atat, Istat, btat - let file statu..
••
stat(2)
ferror, feof, clearerr, fileno - stream It&tUI inquiries.
•
ferror(SS)
ruptime - show hoat status of local machines.
ruptime(lC)
• • • • • • • • • •
rw hod - IYltem status server.
rwhod(SC)
stdio - standard buffered input/output package.
intro(3S)
.ticky - executable files with persistent text. • • • • • • .ticky(S)
wait, waitS - wait for process to terminate or stop.
wait(2)
ItOp: halt a job or process.
csh(l)
halt - stop the procell8or.
halt(S)
pause - stop until signal.
pa.use(SC)
icheck - file syatem storage consistency check. •
ieheck(S)
lIubroutines. dbminit, fetch, Itore, delete, fimkey, nextkey - data base
dbm(3X)
strlen, index, rindex - atring operations. streat, stmeat, IItrcmp, stmcmp, strepy, stmcpy,
.tring(3)
rindex - Itring operationll. strcat, IItrncat, strcmp, stmcmp, strcpy, strnepy, strlen, index,
Itring(3)
operationll. IItrcat, strncat, strcmp, strncmp, strcpy, atmcpy. strlen, index, rindex - IItring
atring(S)
fclose, mush - close or flush a stream. • • • • • •
fclose(SS)
fopeD, freopen, fdopen - opeD a Itream. • • • • • •
ropen(3S)
fleek, (tell, rewind - repositioD a stre&m.
fleek(3S)
fletc, getw - get character or integer from strea.m. getc, letchar,
,etc(3S)
get II, fgetll - get a It ring from a .tream.
lets(3S)
putchar, fputc, putw - put character or word on a stream.' putc,
putc(3S)
puh, fpuh - put a string on a stream.
puts(3S)
set buffer , settinebuf - a.asigu buffering to a stream. set buf,
letbuf(3S)
unletc - push character back into input stream.
unletc(3S)
sed - stream editor.
led(l)
ferror, feof, clearerr, fileno - .tream status inquiries. • • • • •
ferror(SS)
rrenport, ruserok - routines for returning a stream to a remote command. rcmd, • • • • •
rcmd(3N)
rexec - return IItream tt) a remote command.
rexec(3N)
lor - Archive 1/4 inch Streaming Tape Drive.
ar(4S)
leta, fgetll - let a IItrinl from a stream.
Sets(3S)
puts, fputs - put a strinl on a stream.
puts(3S)
·bcopy, bcmp, blero, fIs - bit and byte strinl operations.
bstring(3)
0

•

0

0

0

•

0

0

0

0

0

0

0

•

0

•

•

0

0

0

0

0

•

0

0

0

0

•

0

•

0

0

0

0

0

•

0

0

0

•

0

•

0

0

0

0

0

0

0

0

0

0

0

0

0

•

0

•

•

0

0

0

0

0

•

0

0

0

0

0

0

0

0

0

•

•

0

0

0

•

•

0

0

•

0

•

0

•

0

0

0

0

•

0

•

0

0

00

0

0

0

0

0...........
0.'

0

0

0

•

0

•

0

0

0

0

0

0

••••

0

•

•

•

•

0

0

January 1984

• xxxviii -

•

•

0

•

••••

•

•••••

Sun System Release 1.1

Permuted Indez
strncmp, strcpy, stl1lepy, strleD, iDdex, rindex extra.et etlingl from C programs to implement shared
other binary, file.
stringe. xstr - extr&et
stringl - find printable
buename strca.t, strncat, stremp, stl1lcmp, strcpy, strncpy,
inde..'t, rinelee - Btring operations. strut,
string operation.. strcat, strncat, strcmp,
atreat, stmcat, strcmp, strncmp, ,trcpy,

ine1fs postne1fs alarm - execute a
store, delete, finthy, nathy - data but
IU 8ce. - front end for the .SM sees
lIumdu quot eD bwcoJordemol - demoDlltrate
cg CODI - driver for
b8uIlcuhe - view 3-D
bdemol - domoDltn.te
mouse phet - stand aloDe teat for the
WiDBUD - il cumnt machiDe a
IUntool, - the
sync - update the
8Ync - update the
upda.te - periodically update the
IYDC - update
suspend.: IUspend .. shell, relUming its
aatre - introduction to special fil.s and hardware
routing - ,ystem
I,upend:
Ileep Ileep Ileep ,wab IwapOD - add a
paginl/nappinl·
nappinl·
IwapOD - add. a nap device for . iDterieaved pagiDI/
napOD - 'pecify additional device for paliDg and
breabw: exit frOID
cue: selector iD
default: catchall clause iD
- .end ... : terminate
readlink - read value of &
Iymlink - make
IItrip - remove
link,

disk. fSYDCselect csll - a IIhell (commaDd interpreter) with C-Iike
messages. perror,
lit - Driver for

Sun Syetem R,lease 1.1

string operations. strcat, strncat, strcmp,
strings. xstr - • • • • • • • • • • • •
IItrings - find printable strings in an object, or
strings from C programs to implement shared
stringll in an object, or other binary, file.
IItrip - remove lIymbolll and relocation bits.
IItrip filename affixes. • • • • • • • • •
strlen, index, rindex - string operations. •
strncat, strcmp, strncmp, strcpy, 8trncpy, 8hten,
strncmp, strcpy, strncpy, shlen, index, rindex strncpy, strlen, index, rindex - string/
stty - set terminal options.
stty, gtty - set and get terminal state.
su - substitute uller id temporarily.
submit newlI articlell. • • • • • •
submit news articles. • • • • • •
,ubroutine after a specified time.
lubroutines. dbminit, fetch,
substitute uler id temporarily.
subsystem.
• •••••••••
lum - lum and count blocb in a file.
sum and count blocb in a file.
summarize disk ullage.
•••••••
summarile file Iystem ownership. • • • •
sun - ill cumnt machine a sun worbtation.
Sun 8 Mb/II experimental Ethernet interface.
Sun black and white Crame buler.
Sun Color Graphics Display.
Sun color lraphics interface.
Sun conllole. • • • • • • •
Sun logo.
• •••••••
Sun Monochrome Bitmap Display.
SUD moulle.
• ••••••
SUD video graphics board.
Sun window SYlltem.
SUD workstation.
• • • • • • •
luntoolll - the 8untoolll window environment.
8untoolll window environment. • • • • •
lIuper block.
• • • • •
IUper block.
lIuper block.
.uper-block.
lIuperior.
• ••••
.upport. ••
• •••
supporting for local network packet routing.
IUllpend a IIhell, resuming its lIuperior.
sullpend execUtiOD for an interval.
suspend execution for aD interval.
sullpend execUtiOD for interval. ••
sullpend: sullpend a Ihell, re8uming its lIuperior.
swab - IIwap byte.. • • • • • • • • • • • • • • • • •
IIwap byte..
• •••••••••••••••
IIwap device for interleaved. paging/llwapping.
swapOD - add a nap device for interleaved
••
.wapOD - Ipecify a.dditional device for paging and
.wappinl. • ••.••
.wappinl·
.witch.
IIwitch.
.witch.
Iwitch.
• •••••••••••
Iwitch: multi-way command branch.
•••••••••
Iymbolic link.
symbolic link to a file.
•••••
lIymbols and reloea.tioD bit II.
• •
symlink - make symbolic link to a file.
symlnk - make a link to an exi8ting file.
lyDC - update super-block.
•••••
lIync - update the super block. • • • • •
lIync - update the lIuper block.
• •
synchronile a file'll in-core sta.te with that OD
synchronoull I/O multiplexing. • • • • •
syntax.
• ••••••••••••••
IIYllcali - indirect eystem call.
•••••
sYII_errlist, lIyll_nerr, errno - system error
Sy8gen SC 4000 (Archive) Tape Controller.

- xxxix -

string(3)
x8tr(1)
IItrings(l)
x8tr(1)
IItrings(l)
strip(l)
basename(l)
string(3)
string(3)
IItring(3)
string(3)
sttY(l)
stty(3C)
lIu(l)
inew8(1)
postnews( 1)
alarm(3F)
dbm(3X)
lIu(l)
sees(l)
sum(l)
sum(l)
duel)
quot(8)
lIun(l)
en(4S)

bW(4S)
colordemos(6)
cg(4S)
con8(4S)
b8uncube(6)
bdemos(6)
mouse(4S)
gxte8t(8s)
win(4S)
sun(l)
suntools(1)
suntools(l)
sync(l)
sync(8)
update(8)
sync(2)
csh(l)
intro(4)
routing( 4N)
csh(l)
sleep(l)
sleep(3F)
IIleep(3)
csh(l)
IIwab(3)
swab(3)
IIwapon(2)
swapon(2)
IIwapon(8)
swapon(2)
IIwapon(8)
csh(l)
csh(l)
CSh!l!
cllh I
csh 1
readlink(2)
symliDIc(2)
IItrip(1)
symlinlc(2)
link(3F)
sync(2)
lIync(t)
sync(8)
Csync(2)
select (2)
csh(l)
lIyscall(2)
perror(3)
8t(4S)

January 1984

Permuted I",dez

perror,

syB_errlis~,

psi pal.
mtiCentronica printer intedace. vpchostid - print identifier of current hon
hostname - set or print name of current hon
mkf. - connrud a file
mkproto - construd a prototype file
mount, umount - mount or remove file
mount, umount - mount and dismount file
newfs - construd a new file
savocore - save a core dump of the operatinl
setquota - enable/dillable quotu on a file
tip, cu - conned to a remote
tunef. - tune up an exilltinl file
ulln - compact lin of u.en who lor. OD the
vadvi.e - give advice to paginl
who - who i. OD the
wiD - Sun wiDdow
df - report fr" di.k Ipace OD fil.
11.101 - 101
kimoD - eenerate a dump of the operatinl
rehuh: recompute commaad huh
unhuh: dilcard commaad huh
- keyboard traallatioD table format and default
mtab - mounted file IYlltem
kbd - keyboard tranlllatioD
croDtab getdtableli.e - eei delcriptor
htable - conven NIC Itandard format hon
route - manually manipulate the routinl
term - terminal drivinl
term - terminal drivinl
tbl- format
eettable - eet NlC format hon
expand, unexpand - expand
ctap - create a
talk functionl. liD. cos,
linh, cOllh,
tartar .t - Driver for SY'eeD SO 4000 (Archive)
lor - Archive 1/4 inch Streaminl
tm - tapemalter 1/2 inch
tp - DEC/mac
mtio - UNIX macnetic
tread, twrite, trewiD, t.kipf, t.tate - f77
m~ - ma,Detic
tm-

derol - remove nrof, trol,
f77 tape I/O. topeD,

teboolreset - resd the
last - indicate last logins of ullen and
beek,
index, rindex, lnblnk, len operationll. opendir, readdir,
telnet - user intedace to the
telnetd - DARPA
su - substitute user id
tmpnam - create a name for a

Janua.ry 1984

syslol - loe synems messaces. • • • • • • •
sysioc - make synem 101 entlY.
• •••••
lyslOl, openlol, closeloe - controllyetem loe.
Iys_nerr, ermo - system error mess aces. • • •
sys_siglis~ - system signal messases.
•
Systech MTI-80o/1600 multi-terminal interface.
Systech VPC-2200 Venatec printer/ploUer and
system.
Iystem.
Iystem.
Iyltem.
syltem.
syltem.
syltem.
Iyltem.
syltem.
syltem.
·Yltem.
.yltem.
Iyltem.
.yltem.
.yltem.
.yltem.
.yltem mellIale•.
Iystem'. profile bufen. • • • • •
table.
table. • • • • • • • • •
~able. kbd
••••••
~abl..
• •••••••••
table format and default table. ••
table of ~imea ~o run periodic job•.
table .i...
tabltl.
table•.
table. for Drof.
•••••••
table. for nrol.
table. for nrol or trol.
~able. from a hod..
•
tab, to spacel, aDd vice vena. • • • • •
tagll file. •• • • • • • • • • •
tail - display the last part of a file.
talk - talk to another uller.
talk t.o another uler.
•••••••••
taD, allin, loCOS, lotan, atan2 - ~ri,onometric
taDh - hyperbolic function•.
tape archive file forma~.
tape archiver.
Tape Con~roller. • • • • •
Tape Drive.
tape drive.
~ape forma~ •.
tape interface. •••
tape 1/0. topen, ~clo,e, ••
tape manipulatinl program. •••
tapemuter 1/2 inch tape drive.
tar - tape archive file lorma~.
~ar - tape archiver.
•••••••
tbl - forma~ table. for nrol or trol.
~bl and eqn construch.
• •••••••
tclose, tread, twrite, trewin, ~lIkipl, ~state ~cp - Internd TransmissioD Control Protocol.
tee - copy Itandard output to many filet. ••
tektool - Tektronix 4014 terminal emulator tool.
Tektronix 4014 terminal emulator tool.
teletype bit. to a .ensible IItate.
teletypell.
• ••••••••••••
tell - move read/write pointer. • • • • •
~ell a.bou~ character object..
•••••••••
~elldir, teekdir, rewinddir, closedir - diredolY
•••••
telnet - user interface to the TELNET protocol.
TEL NET protocol. • • • • • • • • • • • • • • • • •
TELNET protocol server. • • • • • • • • •
~elnetd - DARPA TEL NET protocol server.
~emporarily.
••••••••••••
temporalY file. • • • • • • • • • • • •
term - terminal drivinl tables lor nrol.

- xl·

'YSI~8}

.yslo 1}
.yslo 3}
perror(3)
psipal(3}
mti(4S}
vpc(4S}
hOlltid(l)
hostname{l)
mkfe(S)
mkproto(S)
mount(2}
mount(S)
newfs(S)
eavecore(8}
.etquota.(2}
tiP(IC}
tunefe(S)
useJ:!l(I)
yadviec(2)
who(t}
win(4S)

eif(l)
.yeloc(S)
kgmon(8)
csh(1 }
csh(l)
kbd(S)
mtab{S)
kbd(S}
crontab(5)
eetdtableeiJe(2)
htable(S}
route{8C)
,term(S}
tenn(S)
tbl(t)
lettable(SC}
expand(1)
ctage(1}
tail(l}
talk(l}
blk(t)
ein(8M)
.inh(3M}
tar(S)
br(l)
.t(4S)
ar{4S)
tm(4S)
tp(S)
mtio(4)
topen(3F)
mt(1}
tm(4S)
tar(S)
tar(l)
tbl(l)
derotf{t)
topen(SF}
tcp(4P}
tee{l}
tektool(l)
tektool(t)
reset(l)

1&St(I}
lseek(2)
index(3F}
directory(3)
telnet(IC)
telnet(10}
telnetd(SC)
telnetd(8C}
1O(1}
tmpnam(SC)
,term(S)

Sun System Release 1.1

Permuted lndez

ttYDame, isaUy, ttyslot - find name of a

vha.ncup - yinaally "ha.Dgup" the current control
animate worm. on a di.play
termcap tid - establish
gettytab pty - pseudo
term term tektool - Tektronix 4014
tcetnum, tcetBac, tcetnr, tcoto, tputs tty. mti - Synech MTI-800/1600 multitty - ceneral
cetty -sd
tty - gd
• tty -.d
ttynam, isatty - find name of &
clear - clear workstation or
• cript - make typellcript of
Itty, Itty -.et and Cd
ttytype - data bue of
wait - wait for a procesl to
exit kill - lIend a .ienal to a pro~lIl, or
output. exitabort endi':
end:
wait, waitS - wait for procelll to
exit endllw:
imemten - stand alone memory
WOI'IDI -

isinf, isun pten - stand alone
quilIticky - executable filee with penistent

edex, editmore, page - brow lie through a
fmt -llimple
nrolmII-

lerver,
- terminal independent operation routine•.
independent operation routine•. tgetent, tcetnum,
terminal independent operation routine.. tcetent,
opera.tion routinel. tgetent, tgetnum, tgetBac,
routinel. tgetent, tgetnum, tgetBac, tgetstr,
fllync - lIynchronile a file'8 in-core state with
ccat - compre.. and uncompresl files, and cat
w - who ill on and what
more, pace - browse
alarm - IIchedule lignal after specified
alarm - cxecute a subroutine alter a specified
at - execute command. at a later
gettimeofday, settimeofday- cet/set. date and
• hutdown - clolle down the system a.t a given
time, f~ime - get. date and
timegetdate - convert
time:
idate, itime - return da.te or
profil - execution
timed - DARPA
asctime, timelone, dysi•• - conven da.te and
getitimer, .etitimer - get/set.. value of interval
times - get proces.
utime - set file

Sun Slltem ReleaR 1.1

term - terminal driving tables (or nrol.
termcap - terminal capability data base.
terminal.
• •••••••
terminal.
• ••••••••••••
terminal.
• ••••••••••••
terminal capability data base.
terminal characteristics for the environment.
terminal configuration data baBe.
terminal driver.
• ••••••
terminal driving tables (or nrol.
terminal drivinC tables for nrol.
terminal emulator tool.
• • • •
terminal independent operation routines. tgetent,
• • • • •
terminal initialization data.
terminal interface.
terminal interface.
terminal mode. •••
terminal name. •
terminal options .
terminal port.
terminalllcreen.
terminalllession .
terminal Itate. •••
terminal tYPei by pon.
terminate. • • • • • • • •
terminate a procen.
terminate a proces..
• • ••
•
terminate a proces. after BUllhinc any pendinc • • • • •
termina.te abruptly with memory image.
terminate conditional. • • • • •
terminate loop. • • • • • • • •
terminate or stop.
••••••
terminate procesll with statu•.
terminate IIwitch. • • • • • • •
ten.
. •.
e
_
•••••
ten - condition command.
-~
ten for indeterminate loatlnc point value•.
ten for the Sun video graphics board.
ten your knowledge.
text.
text editor.
text editor.
text file. ••
text formatter.
• • •
text formattinl and typesettinC.
text formatting ma.cro•.
tftpd - DARPA Trivial File Transfer Protocol
tgetent, tgetnum, tgetBag, tgetlltr, tgoto, tput.
tgetlag, tgebtr, tcoto, tputs - terminal
tgetnum, tgetla.g, tgetstr, tgoto, tputs tgetstr, tgoto, tputll - terminal independent
tgoto, tputs - terminal independent operation
that on disk. • • • • • • •
them. compact, UnCompact,
they are doing. •••
throuCh a tcxt file.
time.
time.
time.
time.
time .
time. • • • • • • •
time - time a command.
time a command. ••••
time and date (rom ASCII.
time command.
• • •
time, ftime - get date and time.
time in numerical (orm.
time profile. • • • • • • • • •
Time server. • • • • • • • • •
time: time command.
• • • •
time to ABCD. dime, localtime, gmtime,
timed - DARPA Time server.
timer.
time.. • ••
times. • ••
0

- xli •

8

..

term(S)
termca.p(S)
ttyname(3)
vhangup(2)
worms(6)
termcap(S)
tBet(l)
gettyta.b(S)
pty(4)
,term(S)
term(S)
tektool(l)
termcap( 3X)
ttYB(S)
mti(4S)
tty(4)
getty(S)
ttY(l)
sttY(l)
ttynam(3F)
c1ear{l)
script(l)
stty(3C)
ttytype(S)
wait(3F)
exit(2)

kill(l)
exit(S)
a.bort(SF)
csh(l)
csh(l)
wa.it(2)
exit(SF)
csh(l)
imemtest(8s)
test(l)
isinf(S)
gxtest(Ss)
qui.(6)
sticky(S)

:~g
more(l)
fmt(l)
nrol(l)
ms(7)
tCtpd(SC)
termcap(3X)
termca.p( SX)
termcap(SX)
termcap(SX)
termcap(SX)
fBync(2)
compa.ct(l)
w(l)
more(l)
alarm(3C)
alarm(3F)
at(l)
gettimeofday(2)
shutdown(S)
time(SC)
time(l)
time(l)
getdate{S)
csh(l)
time(SC)
idate(SF)
profil(2)
timed(SC)
csh(l)
ctime(3)
timed(8C)
getitimeI(2)
times(3C)
utime(SC)
Ja.nua.ry 1984

Permute~ [tItles

utimel - set file 'imel. . . . . . . . . . • • • . . . • . . .
times - let process tim... • • • • • • • •
crontI.b - t&ble Gf times to' run periodic joba. • • • • • • • • • •
/ex pGrt , IGlin, newcrP, read, re&dGnly, set, shin, times, trap, um&sk, wai~ - command lanlu&le.
ASCII. dime, IGcaltime, cmtime, &sdime, timelGae, dyeiae - conven d&te and ~ime to'
tip, cu - conDed ~G & remO'teayatem.
tm - t&pemuter 1/2 inch tape drive. • • • • •
tmpnam - cre&te a n&me fO'r a temporary file.
/iscntrl, isuai, iSgJ'&ph, tGupper, tGIGwer, to'&scii - char&cter cl&saific&tion and cGnveniGn/
•••••
/isprin~, iscntrl, isucii, iSgJ'&ph, tGupper, to'IGwer, tG&lcii - ch&racter elusificatiGn &nd/
••••••••••••••••
tektoGI - Tektronix 4014 termin&l emul&tGr tool.
tet&te - 177 tape I/O. to'pea, ~clOH, tread, twrite, trewin, hkipf,
•••••••••••
teGn - to'PolGgical .ori.
to'uch - upd&te d&te lut mO'dified of a file.
•
ispuaet, ilpriDt, iscDtrl, is&scii, iSlraph, to'upper, tolGwer, to'uai - ch&raeter/ /illpace,
tp - DEC/mal t&pe formats.
• ••••••
tput. - hrmin&l indepeJldeJlt oper&tioa rGutiJl".
tr - tranll&te char&cten.
ptrue - procell trace. • • • • • •
trpt - transliterate protGcol trace. • • • • • • • •
•••••••
loto: cGmmand transfer.
ftp - file transfer prolram.
ftpd - DARPA Internet File Transfer PrGtocGI It"er.
tftpd - DARPA Trivi&l File Transfer PrO'tocol se"er.
tr- translate char&eten.
•••••••••
kbd - keybo&rd transla.tioJl t&ble fO'rm&~ &Jld default table.
pi - Pucal interpreter cGde traJlsla.tGr. • • • • • • • • • • • • • •
transliter&te prO'tocol trace.
••••••
trp~ tcp - Interne~ TranlmissiGn Control PrG~ocGI.
- encode/ decGde a bin&ry file fO'r transmiaaioJl viI. mail. uuencGde,uudecode
trpfpe, fpecn~ - trap and repair IG&tinl PGin~ f&ult..
• • •
IGCiD, newlrp, read, readonly, set, shin, timet, trap, umuk, wait - command lanp&Ie. /expon,
I/O. tGpea, telGIO, tread, ~write, ~rewia, tskipf, t.t&te - f77 tape
trek - trekkie I&me.
••••••
trek - trekkie I&me.
•••••••••••
tGpeD, telGse, tre&d, twrite, trewin, ~skipf, tst&te - f17 tape I/O.
.iD, CG., taD, &sia, &COI, &t&n, &tan2 - ~rilO'DOmetric functiGn.. • • • • • • •
tftpd - DARPA Trivial File Tr&nafer ProtocGI
•••••••••••••••••••
tbl - fGrm&t t&blet fGr DrGI Gr trol.
trol - typesd Gr fGrm&~ dO'cumeJlts.
•••••••••••
chec1tnr - check nrGI/ trol file..
derO'I - remO've Drol, trol, tbl &nd tqn CGnstructl. • • • • • • • •
f&ult.. ~rpfpe, fpeat - ~rap &Jld repair IG&tinl PGin~
~rp~ - tranaliterate protocO'l trace.
f&llO, ~rue - prGvide truth valuel.
•••••
true, false - prO'vide truth v&lUei.
truncate, ftrunc&te - truncate & file to &.peafied leneth. •••
specified length. ~ruJlc:ate, ftruncate - trunc&te & file to' a
f&lae, true - provide ~ruth value.. • • • • • • • • • • • •
true, f&IH - provide truth value.. • • • • • • • • • • • • •
chu. - Try to esc&pe to' kiDer robGts.
• •
eDvirGnment. tset - est&blish termin&l char&eteristics for the
tGpeD, telO'se, tre&d, twrite, trewin, tskipf, tstate - f77 tape I/O. ••
tlO'ri - to'pO'IGgical SGrt.
tGpen, telGae, tre&d, twrite, trewin, la~ii>f, tst&te - 177 tape I/O. • • • • • •
tty -seDeral termiDal interf&ee.
tty - let terminal name.
• • • • • •
ttyn&m, isatty - find namce Gf a terminal pGri.
terminal. ttYD&me, is&tty, ttyelo~ - find name Gf &
ttye - terminal initialil&tioJl d&ta..
••••••
ttyname, is&tty, ttyslGt - find n&me of a terminal. • • • • • • •
ttytype - d&ta base Gf terminal typea by pGri.
tuners - tune up an existing file ayatem.
•••••
tunef. - tune up &D existinl file ayatem. • •
topen, telGse, tread, twrite, trewin, tskipf, tstate - 177 tape I/O.
file - determine file type.
•••••••••••••
types - primitive system d&t& typel. • • • • • • • • • • • • •
typee - primitive system dab types.
ttytype - d&t& b&se of terminal types by pO'rt.
••••••
script - m&ke typescript Gf termin&l sessiGn.
m&n - m&cros to' typeset manual.
•••••
eqa, neqn, checkeq - typeset mathem&tic•.
trol- typeset O'r fO'rmat documents.
nrol - text form&ttinl &nd t ypesett inl.
•••••••••••••
udp - Intemet User Datagram PrGtocGI.
getpw - get n&me from uid.. • • • • • • 0. . . . . . . . . . .
9

,,"er.

Ja.nua.ry 1984

- xlii •

•

•

•

•

•

utimell(2)
~imea(SC)

erGDtab(S)
.h(l)
etime(S)
~ip(lC)
~m(4S)
~mpnam(SC)

etype(S)
etype(S)
~ektGGI(l)

~Gpen(SF)
~80rt(l)
~Gucb(l)

ctype(S)
~p(S)

hrmc&p(SX)
~I{l)

ptraee(2)
hpt(SC)
csb(l)
ftp(lC)
ftpd(SC)
tftpd(SC)
tI{l)
kbd(S)
pi(l)
~rpt(SC)

tcp(4P)
uuencode(lC)
trpCpe(SF)
sb(l)
tGpen(SF)
trek(6)
trek(6)
~Gpen(3F)

.in(3M)
tftpd(SC)
tbl(l)
trotr{l)
checknr(l)
derotr{l)
~rpfpe(SF)

trpt(SC)
fallle(l)
true(l)
truDc&te(2)
truncate(2)
f&llIe(l)
true(l)
chue(6)
taet(l)
tGpen(3F)
~IIGrt(l)
~Gpen(3F)

tty(4)
tty(l)
ttynam(3F)
Uyn&me(S)
ttys(S)
ttyn&me(3)
ttytype{S)
tunefll(S)
tuneC8(S)
~opeD(3F)

file{l)
typee(S)
typee(S)
ttytype{s)
.cript(l)
man(7)
eqn(l)
~rotr{l)

DrGtr{l)
udp(4P)
setpw(s)

Sun System Release 1.1

Permuted Indez

newgrp, read, readonly, lIet, IIhift, timee, tra.p,
mount,
mount,
and cat them. compact,
compad, uncompad, ccat - compreall and
ul- do
unget expand,

mktemp - make ..
gethoetid - get
t1ullh - flush output to .. logical
flleek, nell - repollitioa .. lile on .. logical
gete, fgete - get .. character from .. logical
fpate - write a character to a FORTRAN logical
getfd - let the lile descriptor of aa external
reboot IIYlltem - execute a
aux - unix to
uuep, uulOI - nix to
mtioanaly.e - Virtual
uux uuep, uulOI-

rmdir, rm - remove (
rm, rmdir - remove (
munmap recnns - receive
recn ...s - receive
uptime - show how lonssyetem h... beea
uudeu - uaep spool directory cleantanefa - tune
touch .ync • ync • yncupdate - periodically
du - .ummari.e dillk
miscellaneoal - milcellaneou.
DewS -

eh.cka.... - ch.ck if uler hu newl on the
login: login new
talk - talk to nother
write - write to another
aeteuid, aetruid, letgid, .etecid, letrcid - lIet
udp - Internet
environ checknewl - check if
8U - IJU betitate
getuid, geteuid - get
letreuid - Jet real and elective
telaet uJimit - get and let
lehid, getgid -let
uil - multiwhoami - display elective current
adduler - procedure for adding new
/bin/mail - send or receive mail amonl
wall - write to all
s)'lltem.

SUD System Relean 1.1

ul - do underlining. • • . • • • • • • . • • .
•••••
ulimit - get and set uller limits.
umallk - lIet file creation mode mallk.
umallk: change or display lile creation mallk. •.
umallk, wait - command language. jexport, login,
umount - mount and dismount file system.
umount - mount or remove file system.
unaliall: remove alialles. • • • • • • • • • • •
uacompact, ccat - compress aad uacompress files,
uacompress liles, &ad cat them.
underlining. • • • • • • • • • • • • • • • •
undo a previous get of an SCCS file.
•••••
unexpand - expand ta.bll to spaces, and vice versa.
ungc$ - undo a previous get of an SCCS file. • •
ungete - push character back into input etrea.m.
unha.sh: discard command hash table.
uniq - report repeated lines in a file.
unique liIe name. • • • • • • • •
unique identifier of current host.
unit.
unit.
unit.
unit. putc,
unit number.
units - conversion program.
UNIX bootstrapping procedures.
UNIX command.
unix command execution.
unix copy. • • • • • • •
UNIX mapetic bpe interface. ••
UNIX postmortem crash analYlOr.
unix to unix command execution.
unix to unix copy.
•••••••
unlimit: remove resource limitiations.
unlink - remove a directory entry.
unlink - remove directory entry.
unlink) directories or filell.
unlink) liIes or directories.
unmap pages of memory.
unprocessed articles via mail.
unprocessed articles via mail.
unset: discard shen variables.
unlletenv: remove environment variables.
up. • • • • • • • • • •
• •••••
up. •
up an existing lile system. • • • • • • •
update - periodically update the super block.
update date last modilied of a file.
update luper-block. • • •
update the luper block .
update the luper block .
update the luper block.
uptime - Ihow how long system h... been up.
ulage. • • • • • • • • • • • • • • • •
uleful information pages.
•••••••
USENET network news article, utility lilel.
USENET newl network.
user.
•••••••••
Uler.
user.
• ••••••••
user and group 10. .etaid,
Uller Datagram Protocol.
uler environment.
•• • •
user haa newl on the USENET news network.
user id tempora.rily. • • • • • • • • • •
uler identity.
•••••••••••
Uler 10'..
••••••••••••••
Uler interface to the TELNET protocol.
user limit..
• •••••••••
user or group ID of the caller.
user wooden ships and iron men.
Username. • • • • •
usen. • • • • • • • • • • • • •
usen.
useD. • • . • • • . . . . • . .
usen - compact lil!l\ of users who are on the
0

•

- xliii·

•

•

•

•

•

•

•

•

•

•

•

•

•

•

ul(l)
ulimit(3C)
umask(2)
csh(l)

8h(1)
mount(8)
mount(2)
csh(l)
compact(l)
compact(l)
ul(l)
unget(l)
e.xpand{l)
unget{l)
ungetc(3S)
csh(l)
uniq(l)
mktemp(3)
gethostid(2)
8ush{3F)
fseek(3F)
getc(3F)
putc(3F)
getfd(3F)
units(l)
reboot(S)
aystem(3F)
uux(lC)
uucp{IC)
mtio(4)
analYlo(S)
uux(lC)
uucp(lC)
csh(l)
unlink(3F)
unlink(2)
rmdir(l)
rm{l)
munmap(2)
recnews(l)
recnews(8)
csh(l)
csh(l)
uptime(l)
uudean{SC)
tanefs(S)
update(S)
touch{l)
sync(2)
lIync(l)
sync(S)
update(S)
uptime(l)
duel)
intro(7)
news(S)
checknews{l)
csh(l)
blk(l)
write(l)
.etuid(3)
udp(4P)
environ(5)
checknews(l)
lu(l)
getuid(2)
setreuid(2)
telnet(IC)
ulimit(3C)
getuid(3F)
uil(6)
whoami(l)
adduser(S)
binmail(l)
wall(l)
users(l)
January 1984

Permutecl Inclez
Ian - iDdicatelan 10liDI of
ptlol-Iet
usen - compact list of
vi - view a file without chugiDI it
Dewl - USENET Detwork Dewl article,
diae - Genel'&l-purpo.e nud-aloDe
letrulase - let iDformatioD about re.ouree
nimel - let iDforma.tioll about relouree

rmail - handle remote mail received via
uudeu tra.nlJlli"ion via mail. uueDcode,
uuencode - format of an encoded
for tl'&n.mi.lioD via mail.
uucp,

nl-

lIaen aDd teletype.. • • • •
ueer'1 IOSill name.
ulln who are on the l)"Stem.
uaiDI the vi viaual editor.
utilit, file..
•
utility padcase.
utililation.
••
utililation.
utime -.et file times.
•••••
utimel - Ht file timel.
1ltmp, wtmp - locin record.. •••
1l1lcle... - 1lUCP lpool diredory dua-1lp.
1lUCp. • • • • • • • • • • • • • • • •
1luep .pool directory dean-1lp. • • • • •
1luep, 1111101 - 1lDix to lI1lix copy.
•
uudecode - eDcode/decode a binary lie lor
1l1leDcode - format of &Il encoded uuencode lIe.
uueDcode ·1·le.
••••••••••••
uuencoele,uudecode - ellCode/elecoele a binary &Ie
1luIOI - unix to 1lDix cop,. • • • • • • • • • •
1lurec - receive procea.ed newl a.rticlet via mail.
1lulencl- Hnd a file to a remote ho.t.
1lUS - uaix to 1lDix commncl executioa.
vaelvi •• - live advice to papnl SYltem.
val - validate SCCSlIe.
validate sces file. • o. .. • •
vallO( - aliped memory allocator.
value.
val1le, loor, ceilial fuadionl.
vat.-e for environment name. ••
val1le of a symbolic link.
value of environment variablel.
val1leof interval timer.
value of .hell variable.
v&luet.
valuea. iainf,
valuet. lmin,
0

•

•

a.bl - tnteler ablolute
fabl, loor, ceil - ..hlohlte
leteDv rea.dlink - reael
letellv - let
letitimer, .etitimer - let/eet
let: chance
fal.e, true - proviele truth
ilDU - ten for iDdetermiuateloa.tiul poiDt
Imax, dlmin, dlmax, iDmax- return extreme
•
• • • • • • • • • • •
true, fal" - provide trut'Ja val,...
htoDl, hton.,lltoJal,lltohl - convert valuetbetwlenhOl' aDd network byte order.
V&rarp - variable arpment Ii.t.
•
let: chnl.v&lueof ahell variable.
vararp - variab1eall1lmeDtlillt.
seteav:aet varia:ble inenvironmen'.
0: arithmetic on.hell variabl...
UD.et: di.ca.rd ahell variabl...
un.ete1lv:remOVeellvlrOameat variables.
leteDv -let value ofeavironmen. vl.riablel.
••••
vax - i. current machine a vax..
,...... ' YU -i,c1lmntmachiaea vax.
uatH -pro.r&d verUie&tio a. • • • • •
:IiDt -& b proll'&ib ·veriier. ••
~
expa.cl,uaupaDcl - expaDcltab.tolP&cel, aDel vice yena. . • . . • . • • • • . ••
vp -lkOD 10071-6 Multib1ll Vmatecparallel. printerintetface.
••
interface. vpc - s."teela VpO.;2200 VenatecpriDterlptotteraDd CentroDic'printer
18 -Ie\& venin of uSCCS tie.
wot - identify "the yenion ofllet. ••
haDemaD -Computer venioa of :thee&me h&nlm&a .
•cc.dil - compare two veniolt. of an SCCS'le.
vfOllt -foDtlormat..
• • • • • • • •
eliaeat "a,. ¥fork -Ipa"nnew procell ina vinaal memory
vCriDd - :srind nicelilltinp olproll'&lDI. • • • •
terminal. vhaDI'lP - virt1lally IChaDI1lP" the current cODtrol
01l«. vi - acreen oriented (viaual) diaplay editor baaed
visual editor. vi- view a lie without chanc1DI i' 1l.iDI the vi
vi - view a &Ie without chanliDI ituaiq ne vi viaualeditor.
reeDew. - receive uDprocened article. via ·mail.
••••
reeDew. - receive uDprocesaed article. via ·mail.
• •••••••
aeDdDew. - aeDd DeWI articlel via 1Il&i1.
••••••••
- eDcode/ decode a biDary file for truamjaaion via mail. u1lencoele,uudecode
uurec -receive proceaaed Dewa articlea via m&il.
•••••
rmail - haDdle remote mail received via uucp.
expaDd, uDexpaDd - expaDd tab. to apacea, aDd vice vena. • ••
exten - staDd aloDe ten for the Sun video Il'&phics board.
bauDcube - view S-D SUD logo. ••
editor. vi- view a 61e withoutchaDginc it 1llliDI the vi visual
vipw - edit the paaaword 61e.
••
0

0

0

•

0

•••••

0

•

•

Q

0

•

•

•

•

0

•

•

•

•

•

0

00

•

•

•

•

•

•

0

•

0

0

0

- xliv -

0

0

0

0

0

0

•

•

•

•

0

•

•

•

0

•

0

•

•

•

•

•••
0

January 1984

0

0

•

•

•

•

•

•

•

0

•

•

0

•

•

lan(1)
lettOl(SF)
asen(l)
view(l)
aew.(6)
diac(S.)
letrullaee(2)
nimea(SC)
1ltime(SC)
atimea(2)
1ltmp(6)
aucleaD(SC)
rm&i1(S)
1lucleu(SC)
aucp(IC)
aueDcode(IC)
auencode(S)
llueDcode(S)
1l1lencode(IC)
a1lcp(IC)
1lurec(S)
aU..Dd(IC)
1lu(IC)
vadviae(2)
val(l)
val(l)
vallot(S)
aba(S)
100r(SM)
letellv(S)
readliDk(2)
letenv(SF)
getitimeI(2)
cah(l)
f&lse(l)
isinf(S)
ruge(SF)
true(l)
byteorder(SN)
Y&l'&rgs(S)
cah(l)
yal'&rgs(S)

clJh(1)
cah(l)
cah(l)
cah{l)
,ete1lv(SF)
vaxtl)
vax(t)
allaert(S)
lint(l)
expaDd(l)

VP(4S)
vpc(4S)
let(l)
wha.t(t)
laanIm&D(G)
.ccadilf{1)
vfont(S)
vfork(2)
verilld(l)
vha.llguP(2)
vi(l)
view(l}
view(l)
reenewa(1)
flenewa(S)
leDdDewa(S)
lIueDcoele( 1C)
lIurec{S)
rmail(S)
expaDd(l)
pteat(SII)
bsuDcube(G)
view(l)
vipw(S)

Sun System Release 1.1

Permuted lndez
vfork - spawn new process in &
vmab.~ - report
&nalYle vhangup vi - acreen oriented (
vi - view a ile withou~ chuging i~ using the vi
consump~ion.

fa, inode -

form&~

of &Ie lIystem
printer interface.
and Centronics printer interfa.ce.
printer interfa.ce. vpc - Systech
utililation.
rea.d, rea.douly, set,

ahif~, ~ime8,

trap, umuk,
wai~

wait:
8iepu8e - atomically releue blocked sipals and
wait, waitSstop.
wai~,

prmail - print out
- spawn new procell in a virtual memory elicient
whati8 - describe
cruh w - who i8 on and
cruh - what happen8
leave - remind you
progra.m.
and path8 (esh only).
export, login, newCI'P, read.! sh, for, cue, if,
break: exit
bw - Sun black a.nd
ulen - com pad 1i8t of us en
from -

wwho rwho fold - fold lonlline8 for inite
locbcreen - maintain
8cretnl, adja.centecretn8 - notify the
suntools - the Sun tool.
win - Sun
vi - view & 6Ie
lutboot, luthalt - reboot/halt the system
uil - multi-user
wcpute, putchar, fputc, putw - put character or
cd - chance
ehdir - change current
getcwd - get path name of current
pwd - print
getwd - get current
aUD - is current machine a sun
clear - clear
worm - Play the growing
worms - animate
pute, fpute: write, writev Iseek, tell - move read/
.all-

SUD System Releas, 1.1

virtual memory efficient way.
• .•••
virtu&) memory statistics. • • • • • • •
Virtual UNIX postmortem e:rash analYler.
virtually "hangup" the current control terminal
visual) display editor based on ex.
visu&) editor.
••••••••••••
vii mit - control maximum system resource
vms tat - report virtual memory statistics.
volume. • • • • • • • • • • • • • • •
vp - Ikon 10071-5 Multibus Versatec parallel
vpc - Systech VPC-2200 Versatec printer/plotter
VPC-2200 Versatec printer/plotter and CentroniclI
vswap - convert a foreign font file.
vtime8 - gd information a.bout resource • • • • • •
w - who i8 on and what they are doing. • • • • • •
wait - awai~ completion of procells. • • • • • • • •
wait - command language. /export, login, ncwgrp,
wait - wait for a process to terminate.
wait for & procesl to terminate.
wait lor background processes to complete.
wait for interrupt.
••••••••••
wait lor process to terminate or stop.
• • •
wait: wait for background procellses to complete.
wait, waitS - wait for procell. to terminate or
waitS - wait for proces. to terminate or stop.
waiting mail.
wall - write to all ullers.
way. vfork
•••••
wc - word count. • • • • • • • •
what - identify the version of files.
what a command is.
••••••••
what happens when the system crashes.
••••••••
what they are doing.
whati. - describe what a command is.
when the system crashe..
••••••
when you have to leave. • • • • • • • • • • •
whereis - locate source, binary, and/or manual for
which - locate a program 6Ie including aliases
while, :, '1 break, continue, cd, eval, exec, exit,
while: repeat commands conditionally.
while/foreach loop.
white frame bufer.
who - who is on the system.
who are on the system.
who is my mail Irom?
who is on and what they are doing.
who is on the system. • • • • • • • •
whoami - dilplay efective current username.
who's logged in on loca.! machine•.
width output device.
win - Sun window aystem.
window context until II login".
• •••
window driver of the physical relationships of
window environment. • • • • • • • • • • •
window system.
••••••••••••••••••
without changing it using the vi visual editor.
without checking the disks.
wooden ships and iron meD.
word count.
word on a atream.
working directory.
working directory.
working directory.
working directory na.me.
working directory pathname.
workstation. • • • • • • •
workstation or termina.l screen.
worm - Pla.y the growing worm game.
worm game. • • • • • • • • • • • •
worms - animate worms on a displa.y terminal.
worms on a display terminal.
• •••••••
write - write to another user.
•••••••
write a character to a FOR TRAN logic&) unit.
write on a file.
write pointer.
write to all usen. • • • • •

- xlv.

vfork(2)
vmstat(S)
analYJe(S)
vhangup(2)
vi(l)
view(l)
vlimit(3C)
vmstat(8)
f8(5)
vp(4S)
vpc(4S)
vpc(4S)
vswap(t)
vtimes(3C)
w(l)
wait(t)
sh(t)
wa.it(3F)
wait(3F)
esh(l)
sigpaulle(2)
wait(2)
csh(l)
wait(2)
wait(2)
prmail(l)
wall(t)
vfork(2)
wc{t)
what(l)
whatis(t)
cruh(8s)
w(l)
whatis{t)
cruh(8s)
leave(t)
whereis(l)
which(l)
sh(l)
csh(l)
csh(1 )
bW(4S)
who(l)
users(l)
from(l)
w(l)
who(l)
whoami{l)
rwho(IC)
fold(l)
win(4S)
locbcreen( 1)
adjacentscreens( 1)
suntools( 1)
win(4S)
view(l)
fastboot(S)
sail(6)
wc{t)
putc(3S)
cd(l)
chdir(2)
getcwd{3F)
pWd(t)
getwd(3)
sun(t)
clear(t)
worm(6)
worm(6)
worms(6)
worms(6)
write(l)
putc.{3F)
write(2)
lseek(2)
wall(t}
January 1984

Permutell [nllez
write write,
open - open a &Ie for readinc or
utmp,
wump - the game of hunt-thexllend,
implement IIhared strinp.
Controllen.
xy - Dillk driver for
jO, jl, jn,
jO, jl, j., yO,
eyace: - modified
jO, j1, jD, yO, y1,
lean - remind you when
leave - remind
II -

January 19S4

write to another user. •••
write, .. ritev - write on a &Ie.
writev - write on a &Ie.
writinc, or create a new file.
wtmp - login records.
• • • • •
wump - the ca.me ofhunt-the-wumpul.
wumpull.
• ••••••••••••
xget, enroll - eecret mail.
••••••
xllend, xget, enroll - lIecret mail.
xlltr - extract etringll from C procra.ml to
xy - Disk driver for Xylogics SMD Disk
XylogiCi SMD Dilk Controllen.
yO, yl, ya - belllel function.. •• • • • •
yl, y. -beallel functioDII.
• ••••••
yace: - yd &Dother compiler-compiler.
yacc allowinc much improved error recovery.
yel - be repetitively aJrirmative.
ya - benel fUDctioD'.
•••••••••
you have to leave.
••••••••••
you when you have to leave. • • • • • •
Iilog 8530 sec lIeriai comunieationl driver.
••
II - lilog 8530 sec lerial comunicatioDII driver.

- xlvi -

write{l)
write(2)
write(2)
opeD(2)
utmp(5)
wump(6)
wump(6)
xlend(l)
xlend(l)
xlltr(l)
xy(4S)
xy(4S)
jO(SM)
jO(SM)
yaee(l)
ey&Ce(l)

yesCI)
jO(SM)
leave(l)
leave(l)
18(4S)
Is(4S)

Sun System Release 1.1

SystelD Interface Overview

Table of Contents

Part I -

Kernel Primitives ............................................................................................................

3

1. Processes and Protection .........................................................................................................
1.1. Host and Process Identifiers ........................................................................................
1.2. Process Creation and Termination ..........................................................................
1.3. User and Group Ids ..........................................................................................................
1.4. Process Groups and System Terminals .:...............................................................

"

2. Memory management ................................................................................................................
2.1. Text, Data, and Stack ....................................................................................................
2.2. Mapping Pages ....................................................................................................................
2.3. Page Protection Control ................................................................................................
2.4. Giving and Getting Advice ..........................................................................................

7

3. Signals .................................................................................................................................................
3.1. Signal Types ..........................................................................................................................
3.2. Signal Handlers ....................................................................................................................
3.3. Sending Signals ....................................................................................................................
3.4. Protecting Critical Sections .........................................................................................
3.S. Signal Stacks .........................................................................................................................

9
9
10
10
11
11

4. Timers .................................................................................................................................................
4.1. Real Time ...............................................................................................................................
4.2. Interv-al Time ........................................................................................................................

12
12
12

-i-

4

4
5
6

7
7
8
8

5. Descriptors ........................................................................................................................................
5.1. The Reference Table ........................................................................................................
5.2. Descriptor Properties .......................................................................................................
5.3. Managing Descriptor References ...............................................................................
5.4. Multiplexing Requests .....................................................................................................

14
14
14
14
15

8. Resource Controls ........................................................................................................................
6.1. Process Priorities ............ ..... ........................... ...................... ................................ ..............
6.2. Resource Utilization .........................................................................................................
6.3. Resource Limits ..................................................................................................................

18
16
16
17

7. System operation support .......................................................................................................
7.1. Bootstrap Operations .......................................................................................................
7.2. Shutdown Operations ......................................................................................................
7.3. Accounting .............................................................................................................................

18
18
18
18

Part II -

System Facilities ...........................................................................................................

20

8. Generic Operations ......................................................................................................................
8.1. Read and Write ...................................................................................................................
8.2. Input/Output Control ....................................................................................................
8.3. Non-Blocking and Asynchronous Operations ....................................................

21
21
21
22

II. File System ................................ "....................................................................................................
9.1. Naming .....................................................................................................................................
9.2. Creation and Removal ....................................................................................................
9.2.1. Directory Creation and Removal...................................................................
9.2.2. File Creation ..............................................................................................................
9.2.3. Creating References to Devices .......................................................................
9.2.4. File and Device Removal....................................................................................
9.3. Reading and Modifying File Attributes ...............................................................
9.4. Links and Renaming ........................................................................................................
9.5. Extension and Truncation ............................................................................................
9.6. Checking Accessibility .....................................................................................................
9.7·. Locking .....................................................................................................................................
9.8. Disk Quotas ............................................................................. ;.............................................

23
23
23
23
24

10. hiterprocess Communications ............................................................................................
10.1. Interprocess Communication Primitives ............................................................
10.1.1. Communication Domains .................................................................................
10.1.2. Socket Types and Protocols ...........................................................................
10.1.3. Socket Creation, Naming, and Service Establishment ...................
10.1.4. Accepting Connections ......................................................................................
10.1.5. Making Connections ............................................................................................
10.1.6. Sending and Receiving Data ..........................................................................

211
29
29
29
30
30
31
31

- ii -

24
25
25
26
26
27
27
28

10.1.7. Scatter/Gather and Exchanging Access Rights .................................
10.1.8. Using Read and Write with Sockets .........................................................
10.1.9. Shutting Down Halves of Full-Duplex Connections ........................
10.1.10. Socket and Protocol Options ......................................................................
10.2. UNIX Domain ....................................................................................................................
10.2.1. Types of Sockets ...................................................................................................
10.2.2. Naming ........................................................................................................................
10.2.3. Access Rights Transmission ...........................................................................
10.3. INTERNET Domain .....................................................................................................
10.3.1. Socket Types and Protocols ...........................................................................
10.3.2. Socket N aming .......................................................................................................
10.3.3. Access Rights Transmission ...........................................................................
10.3.4. Raw Access ...............................................................................................................

32
32
32
33
33
33
33
33
33
34
34
34
34

11. Devices .............................................................................................................................................
11.1. Structured Devices ..........................................................................................................
11.2. Unstructured Devices ....................................................................................................

36
35
35

12. Debugging Support ..................................................................................................................

38

Part III -

Summary of Facilities ..............................................................................................

37

A. Summary of Facilities ..............................................................................................................

3'1
37
37
37
38
38
38
39
39
39
39
39
40
40
40

A.I. Kernel Primitives ..............................................................................................................
A.1.1. Process Naming and Protection ....................................................................
A.l.2. Memory Management ..........................................................................................
A.l.3. Signals ...........................................................................................................................
A.IA. Timing and Statistics ..........................................................................................
A.I.5. Descriptors ..................................................................................................................
A.I.6. Resource Controls ..................................................................................................
A.I.7. System Operation Support ...............................................................................
A.2. System Facilities ................................................................................................................
A.2.1. Generic Operations ................................................................................................
A.2.2. File System ................................................................................................................
A.2.3. Interprocess Communications .........................................................................
A.2.4. Devices ..........................................................................................................................
A.2.5. Debugging Support ...............................................................................................

- iii -

System Interface Overview

Revised for Sun Release 1.1, April 1984
This document summarizes the facilities provided by the 1.1 and later releases of the UNIXt
operating system for the Sun Workstation. It does not attempt to act as a tutorial for use of
the system nor does it attempt to explain or justify the design of the system facilities. It gives
neither motivation nor implementation details, in favor of brevity. This document is in three
major parts:
Part I describes the basic kernel functions provided to a UNIX process: process naming and
protection, memory management, software interrupts, object references (descriptors),
time and statistics functions, and resource controls. These facilities, as well as facilities
for bootstrap, shutdown and process accounting, are provided solely by the kernel.
Part II describes the standard system abstractions for files and file systems, communication,
terminal handling, and process control and debugging. These facilities are implemented by the operating system or by network server processes.
Part III is an appendix containing a summary of the facilities described in parts I and II.

Notation and Types
The notation used to describe system calls is a variant of a C language call, consisting of a pr~
totype call followed by declaration of parameters and results. An additional keyword result,
not part of the normal C language, is used to indicate which of the declared entities receive
results. As an example, consider the read call, as described in section 8.1:
cc - read(fd, buf, nbytes);
result int cc; int fd; result char *buf; int nbytes;
The first line shows how the read routine is called, with three parameters. As shown on the
second line cc is an integer and read also returns information in the parameter buf.
Description of all error conditions arising from each system call is not provided here; they
appear in the S"ltem Inter/ace Manual. In particular, when accessed from the C language,
many calls return a characteristic -1 value when an error occurs, returning the error code in the
global variable errno. Other languages may present errors in different ways.
A number of system standard types are defined in the <,,,,/type,.II> include file and used in
the specifications here and in many C programs. These include caddr_t giving a memory

t

UNIX is a

~rademark or Bell Laboratories.

Revision E of 7 January 1984

1

System Interface Overview
address (typically as a character pointer), ofF_t giving a file offset (typically as a long integer),
and a set of unsigned types u_char, u_short, u_int and u_loD8, shorthand names for
unsigned char, unsigned short, etc.

2

Revision E of 7 January 1984

System Interface Overview

Part I -

Kernel Primitives

Kernel Primitives

The facilities available to a UNIX user process are logically divided into two parts: kernel facilities directly implemented by UNIX code running in the operating system, and system facilities
implemented either by the system, or in cooperation with a ,erver proce,a. The kernel facilities
are described in this part or the document.
The facilities implemented in the kernel are those which define the UNIX virtual machine which
each process tuns in. Like many real machines, this virtual machine has memory management
hardware, an interrupt facility, timers and counters. The UNIX virtual machine also allows
access to files and other objects through a set of de,criptorl. Each descriptor resembles a device
controller, and supports a set of operations. Like devices on real machines, some of which are
internal to the machine and some of which are external, parts of the descriptor machinery are
built-in to the operating sY5.tem, while other parts are often implemented in server processes on
other machines. The facilities provided through the descriptor machinery are described in Part
II.

Revision E of 7 January 1984

3

Processes and Protection

System Interface Overview

1. Processes and Protection
1.1 .. Host. and Process Identifiers
Each UNIX host has associated with it a 32-bit host id, and a host name of up to 255 characters.
These are set (by a privileged user) and returned by the calls:
sethostid(hostid) ;
long hostid;
hostid == gethostidO;
result long hostid;
sethostname{name, len);
char *name; int len;
gethostname(buf, buflen);
result char *buf; int buflen;
The host id is not used in this release of the system. The bul containing the host name returned
by gethodnome is null-terminated (if space allows).
On each host runs a set of proce"e,. Each process is largely independent of other processes,
having its own protection domain, address space, timers, and an independent set of references to
system or user implemented objects.
Each process in a host is named by an integer called the proce" itl. This number is in the range
1-30000 and is returned by the getpitl routine:
pid == get pidO;
result int pid;
On each UNIX host this identifier is guaranteed to be unique; in a multi-host environment, the
(hostid, process id) pairs are guaranteed unique.

1.2. Process Creation and Termination
A new process is created by making a logical duplicate of an existing process:
pid == forkO;
result int pid;
The lork call returns twice, once in the parent process, where pitl is the process identifier of the
child, and once in the child process where pitl is o. The parent-child relationship induces a
hierarchical structure on the set of processes in the system.
A process may terminate by executing an ezit call:
exit(status );
int status;
returning 8 bits of exit status to its parent.
When a child process exits or terminates abnormally, the parent process receives information
about any event which caused termination of the child process. A second call provides a non-

4

Revision E of 7 January 1Q84

System Interface Overview

Processes and Protection

blocking interface and may also be used to retrieve information about resource3 consumed by
the process during its lifetime.
#indude 
pid - wait(astatus);
result int pid; result union wait *astatus;
pid - wait3(astatus, options, arusage);
result int pid; result union waitstatus *astatus;
;pt options; result struct rusage *arusage;
A process can overlay itself with the memory image of another process, passing the newly
created process a set of parameters, using the call:
execve(name, argv, envp)
char *name, **argv, **envPi
The specified nome must be a file which is in a format recognized by the system, either a binary
executable file or a file which causes the execution of a specified interpreter program to process
its contents.

1.3. User and Group Ids
Each process in the system has associated with it two user-id's: a real u,er id and a effective
u,er id, both non-negative 16 bit integers. Each process has an real accounting group id and an
effective accounting group ;d and a set of ocee" group id',. The group id's are non-negative 16
bit integers. Each process may be in several different access groups, with the maximum concurrent number of access groups a system compilation parameter, the constant NGROUPS in
the file , guaranteed to be at least 8.
The real and effective user ids associated with a process are returned by:
ruid == getuidO;
result int ruid;
euid == geteuidO;
result int euid;
the real and effective accounting group ids by:
rgid == getgidO;
result int rgid;
egid == getegid();
result int egid;
and the access group id set is returned by a getgroup, call:
ngroup8 == getgroups(gidsetsize, gidset);
result int ngroups; int gidsetsize; result int gidset(gidsetsize);
The user and group id's are assigned at login time using the ,etreuid, ,etregid, and ,etgroup,
calls:

Revision E of 7 January 1984

5

Processe$ and Protection

System Interfaee Overview

setreuid(ruid, euid);
il'\~ ruid, euid;
setregid( rgid, egid);
int rgid, egid;
setgroups(gidsetsize, gidset);
int gidsetsize; int gidset[gidsetsize];
The .etreuid call sets both the real and effective user-id's, while the ,dregitl call sets both the
real and effective accounting group id's. Unless the caller is the super-user, raid must be equal
to either the current real or effective user-id, and rgid equal to either the current real or effective
accounting group ide The ,dgroup, call is restricted to the super-user.

1.4. Process Groups and System Terminals
Each process in the system is also normally associated with a proce" group. The group of
processes in a process group is sometimes referred to 38 a iob and manipulated by high-level system software (such as the shell). The current process group of a process is returned by the
getpgrp ca.ll:
pgrp = getpgrp(pid);
result int pgrp; int pid;
The process group associated with a process may be changed by the ,etpgrp call:
setpgrp(pid, pgrp);
int pid, pgrp;
Newly created processes are Msigned process id's distinct from aU processes and process groups,
and the same process group as their parent. A normal (unprivileged) process may set its process
group equal to its process ide A privileged process may set the process group of any process to
any value.
When a process is in a specific process group it may receive software interrupts affecting the
group, causing the group to suspend or resume execution or to be interrupted or terminated. In
particular, every system terminal has a process group and only processes which are in the process group of a terminal may read from the terminal, allowing arbitration of terminals among
several different jobs. A process can examine the process group of a terminal via the ioctl call:
ioctl(fd, TIOCGPGRP, pgrp);
int fd; result int .pgrp;
A process may change the process group of any terminal which it can write by the ioctl call:
ioctl(fd, TIOCSPGRP, pgrp);
int fd; int .pgrp;
The terminal's process group may be set to any value. Thus, more than one terminal may be in
a process group.
Each process in the system is usually associated with a control terminal, accessible through the
file / dey /tty. A newly created process inherits the control terminal of its parent. A process
may be in a different process group than its control terminal, in which case the process does not
receive software interrupts affecting the control terminal's process group.

6

Revision E of 7 January 1984

System Interface Overview

Memory management

2. Memory management
This section represents the interface planned for later releases of the system. Of the calls
described in this section, only ,brk, etpage,ize, and mmap are included in the current release.
Note that mmap is restricted in that it only works with certain character devices such as the
framebuffer and devices like mbmem.

2.1. ':Qext, Data, and Stack
Each pr<*fess begins execution with three logical areas of memory called text, data and stack.
The text area is read-only and shared, while the data and stack areas are private to the process.
Both the. data and stack areas may be extended and contracted on program request. The call
addr = sbrk(incr);
result caddr_t addr; int incr;
changes the size of the data area by incr bytes and returns the new end of the data area, while
addr =:II sstk(incr);
result caddr_t addr; int incr;
changes the size of the stack area. The stack area is also automatically extended as needed.
On the VAX the text and data areas are adjacent in the PO region, while the stack section is in
the PI region, and grows downward.

2.2.

~apping

Pages

The systfJD supports sharing of data between processes by allowing pages to be mapped into
memory. :: These mapped pages may he ,hared with other processes or private to the process.
Protection and sharing options are defined in  as:

,*

,*,*
,*
,*,*

*, *,

protections are chosen from these bits, or-ed together
#define PROT_READ
Ox4
pages can be read
*define PROT_WRITE
Ox2
pages can be written
#define PROT-.EXEC
Ox!
pages can be executed

'*

*,*,

*,*,
*,

sharing types; choose either SHARED or PRIVATE
*define MAP_SHAR ED
1
share changes
*define MAP_PRIVATE
2
changes are private

The cpu-~.,pendent size of a page is returned by the getpage,ize system call:
p~lesize == getpagesize();
re;.ult int pagesize;

The call:
mmap(addr, len, prot, share, fd, pos);
caddr_t addr; int len, prot, share, fd; off_t pos;
causes the pages starting at addr and continuing for len bytes to be mapped from the object
represented by descriptor fil, at absolute position po,. The parameter ,hare specifies whether
modifications made to this mapped copy of the page, are to be kept private, or are to be ,hared
with other references. The parameter prot specifies the accessibility of the mapped pages. The

Revision

,

1

of 7 January 1984

7

System Interface Overview

Memory management
i!t

addr, len, and po, parameters must all be multiples of the pagesize.
A process can move pages within its own memory by using the mremap call:

mremap(addr, len, prot, share, fromaddr);
caddr_t addr; int len, prot, share; caddr_t fromaddr;
This call maps the pages starting at /romaddr to the address specified by addr.
A mapping can be removed by the call
lIl~nmap(addr,
c~dr_t

len);
addr; int len;

This causes further references to these pages to refer to private pages initialized to zero.

2.3. Page Protection Control
A process can control the protection of pages using the call

mprotect(addr, len, prot);
caddr_t addr; int len, prot;
This call changes the specified pages to have protection prot.

2.4. Giving and Getting Advice
A process that has knowledge of its memory behavior may use the mad";,e call:

madvise(addr, len, behav);
caddr_t addr; int len, behav;
Bellav describes expected behavior, as given in :

*define
#define
=H=define
*define
*define

MADV_NORMAL
0
MADV.-RANDOM
1
MADV_SEQUENTIAL
MADV_WIL L NEED 3
MADV_DONTNEED 4

1* no further special treatment *1
1* expect random page references *1
2/* expect sequential references *1
I * "ill need these pages */
1* don't need these pages *1

Finally, a process may obtain information about whether pages are core resident by using the
call
mincore(addr, len, vee);
eaddr_t addr; int len; result ehar *vee;
Here the current core residency of the pages is returned in the character array vee, with a value
of 1 meaning that the pa.ge is in-core.

8

Revision E of 7 January 1984

System Interface Overview

Signals

3. Signals
The system defines a set 01 ,ignal, that may be delivered to a process. Signal delivery resembles
the occurrence of a hardware interrupt: the signal is blocked from further occurrence, the
current process context is saved, and a new one is built. A process may specify the handler to
which a. signal is delivered, or specify that the signal is to be blocked or ignored. A process may
also spepify that a de/au/t action is to be taken when signals occur.
Some si~als will cause a process to exit when they are not caught. This may be accompanied
by crea~lon of a core image file, containing the current memory image of the process for use in
post-m~rtem debugging. A process may choose to have signals delivered on a special stack, so
that sophisticated software stack manipulations are possible.
All signals have the same priority. If multiple signals are pending simultaneously, the order in
which they are delivered to a process is implementation specific. Signal routines execute with
the signal that caused their invocation blocked, but other signals may yet occur. Mechanisms
are provided whereby critical sections of code may protect themselves against the occurrence of
specified signals.

3.1. Signal Types
The signals defined by the system fall into one of five classes: hardware conditions, software
conditions, input/output notification, process control, or resource control. The set of signals is
defined in the file < signal.h > .
Hardware signals are derived from exceptional conditions which may occur during execution.
Such signals include SIGFPE representing floating point and other arithmetic exceptions,
SIGILL for illegal instruction execution, SIGSEGV for addresses outside the currently assigned
area of memory, and SIGBUS for accesses that violate memory protection constraints. Other,
more cpu-specific hardware signals exist, such as those for the various customer-reserved
instructions on the VAX (SIGIOT, SIGEMT, and SIGTRAP).
Software signals reflect interrupts generated by user request: SIGINT for the normal interrupt
signal; SIGQUIT for the more powerful quit signal, that normally causes a core image to be generated; SIGHUP and SIGTERM that cause graceful process termination, either because a user
has "hung up", or by user or program request; and SIGKILL, a more powerful termination signal which a process cannot catch or ignore. Other software signals (SIGALRM, SIGVTALRM,
SIGPROF) indicate the expiration of interval timers.
A process can request notification via a SIGIO signal when input or output is possible on a
descriptor, or when a non-blocking operation completes. A process may request to receive a
SIGURG signal when an urgent condition arises.
A process may be dopped by a signal sent to it or the members of its process group. The SIG. STOP signal is a powerful stop signal, because it cannot be caught. Other stop signals
SIGTSTP, SIGTTIN, and SIGTTOU are used when a user request, input request, or output
request respectively is the reason the process is being stopped. A SIGCONT signal is sent to a
process when it is continued from a stopped state. Processes may receive notification with a
SIGCHLD signal when a child process changes state, either by stopping or by terminating.
Exceeding resource limits ma.y cause signals to be generated. SIGXCPU occurs when a process
nears its CPU time limit and SIGXFSZ warns that the limit on file size creation has been
reached.

Revision E of 7 January 1984

9

System Interface Overview

Signals

3.2. Signal Handlers
A process has a handler associated with each signal that controls the way the signal is delivered.
The call
*include 
struct sigvec {
int
int
int
};

( ·sv_handler X);
sv_mask;
sv_onstack;

sigvec( signo, sv, osv)
int signo; struct sigvec .sv; result struct sigvec .osv;
assigns interrupt handler address ,v_htJndler to signal ,ifJfIo. Each handler address specifies
either an interrupt routine for the signal, that the signal is to be ignored, or that a default
action (usually process termination) is to occur if the signal occurs. The constants SIG_IGN
and SIG_DEF used as values for ,v_htJndler cause ignoring or defaulting of a condition. The
Iv_mtJlk and .v_ondtJck values specify the signal mask to be used when the handler is invoked
and whether the handler should operate on the normal run-time stack or a special signal stack
(see below). If OlV is non-zero, the previous signal vector is returned.
When a signal condition arises for a process, the signal is added to a set of signals pending for
the process. If the signal is not currently blocked by the process then it will be delivered. The
process of signal delivery adds the signal to be delivered and those signals specified in the associated signal handler's Iv~mtJ.k to a set of those mtJ.ked for the process, saves the current process
context, and places the process in the context of the signal handling routine. The call is
arranged so that if the signal handling routine exits normally the signal mask will be restored
and the process will resume execution in the original context. If the process wishes to resume in
a different context, then it must arrange to restore the signal mask itself.
The mask of blocked signals is independent of handlers for signals. It prevents signals from
being delivered much as a raised hardware interrupt priority level prevents hardware interrupts.
Preventing an interrupt from occurring by changing the handler is analogous to disabling a device from further interrupts.
The. signal' handling routine' ,v.:,..htJntller is called by a C caU of the form
( .sv_h-andler Xsigno,' code, sep);
int signo; long code; struct sigcontext .scp;
The ';fJfIO gives the number of the signal that occurred, and. the code, a word of information
snpp,lied by the hardware. The .ep parameter is a pointer' to a machine-dependent structure
containing the information for restoring the context before the signal.

3.3,. Sending Signals
A process can send a signal to another processor group of processes with the calls:

10

Revision E of 7 January 1984

System Interface Overview

Signals

kill(pid, signo);
int pid, signo;
killpgrp(pgrp, signo);
int pgrp, signo;
Unless the process sending the signal is privileged, it and the process receiving the signal must
have the same effective user ide
Signals are also sent implicitly from a terminal device to the process group associated with the
terminal when certain input characters are typed.

3.4. Protecting Critical Sections
To block a section of code against one or more signals, a ,;gblock call may be used to add a set
of signals to the existing mask, returning the old mask:
oldmask =- sigblock(mask);
re$ult long oldmask; long mask;
The old mask can then be restored later with ,;g,etma,k,
oldmask ==- sigsetmask(mask);
re:sult long oldmask; long mask;
The 'igblock call can be used to read the current mask by specifying an empty ma,k.
It is possible to check conditions with some signals blocked, and then to pause waiting for a signal and restoring the mask, by using:
sigpause(mask);
long mask;

3.5. Signal Stacks
Applications that maintain complex or fixed size stacks can use the call
struct sigstack {
ss..:.,sp;
caddr_t
ss,:;..onstack;
int
};
sigstack(ss, oss)
struct sigstack *ss; result struct sigstack *oss;
to provide the system with a stack based at ,,_,p for delivery of signals. The value ,,_onltack
indicates whether the process is currently on the signal stack, a notion maintained in software
by the system.
When a signal is to be delivered, the system checks whether the process is on a signal stack. If
not, then the process is switched to the signal stack for delivery, with the return from the signal
arranged to restore the previous stack.
If the process wishes to take a non-local exit from the signal routine, or run code from the signal
stack that uses a different stack, a ';g,tack call should be used to reset the signal stack.

Revision

~

of 7 January 1984

11

System Interface Overview

Timers

4. Timers
4.1. Real Time
The system's notion of the current Greenwich time and the current time zone is set and
returned by the calls:
*include 
settimeofday( tvp, tzp);
struct timeval *tp;
struct timezone *tzp;
gettimeofday(tp, tzp);
result struct timeval *tp;
result struct timezone *tzp;
where the structures are defined in <,",/time.A> as:
struct timeval {
long
long
};

tv_sec;
tv_usec;

struct time zone {
tz_minuteswest;
int
tz_dsttime;
int
};

/* seconds since Jan I, 1970 */
/ * and microseconds */

I * of Greenwich *I
I * type of dst correction to apply *1

Earlier versions of UNIX contained only a I-second resolution version of this call, which remains
as a library routine:
time(tvp)
result long *tvp;
or
tv - time(O);
result long tv;
returning only the tv_sec field from the gettimeoldfJII call.
~

4.2. Interval Time
The system provides each process with three interval timers, defined in :
*define ITIMER_REAL
0
*define ITIMER_VIRTUAL 1
*define ITIMER_PROF
2

1* real time intervals */

/* virtual time intervals *,
/* user and system virtual time *,

The ITIMER_REAL timer decrements in real time. It could be used by a library routine to
maintain a wakeup service queue. A SIGALRM signal is delivered when this timer expires.

12

Revision E

ot 7 January

1984

System Interface Overview

Timers

The ITIMER_VIRTUAL timer decrements in process virtual time. It runs only when the process is executing. A SIGVTALRM signal is delivered when it expires.
The ITIMER_PROF timer. decrements both in process virtual time and when the system is running on behall 01 the process. It is designed to be used by processes to statistically profile their
execution. A SIGPROF signal is delivered when it expires.
A timer value is defined by the itimertJal struct ure:
struct itimerval {
struct
timeval it_interval;
/ * timer interval */
timeval it_value; / * current value */
struct

};
and a timer is set or read by the call:
getitimer(which, value);
int which; result struct itimerval *value;
setitimer(which, value, ovalue);
int which; struct itimerval *value; result struct itimerval *ovalue;
The third argument to ,etitimer specifies an optional structure to receive the previous contents
01 the interval timer. A timer can be disabled by specilying a timer value 01 o.
The system rounds argument timer intervals to be not less than the resolution 01 its clock. This
clock resolution can be determined by loading a very small value into a timer and reading the
timer back to see what value resulted.
The alarm system call 01 earlier versions 01 UNIX is provided as a library routine using the
ITIMER~EAL timer. The process profiling lacilities 01 earlier versions 01 UNIX remain
because it is not always possible to guarantee the automatic restart 01 system calls after receipt
01 a signal.
pWfil(bul, bufsize, offset, scale);
result char *buf; int bulsize, offset, scale;

Revision E

ot 7 January

1984

13

Descriptors

System Interface Overview

5. Descriptors
Each process has access to resources through de.er;ptor.. Each descriptor is a handle allowing
the process to reference objects such as files, devices and communications links.

5.1. The Reference Table
Rather than allowing processes direct access to descriptors, the system introduces a level of
indirection, so that descriptors may be shared between processes. Each process has a tle.eriptor
referenee table, containing pointers to the actual descriptors. The descriptors themselves thus
have multiple references, and are reference counted by the system.
Each process has a fixed size descriptor reference table, where the size is returned by the gddtable,;ze call:
nds == getdtablesizeO;
result int nds;
and guaranteed to be at least as large as the constant NOFILE defined in . The
entries in the descriptor reference table are referred to by small integers; for example if there are
20 slots they are numbered 0 to 19.

5.2. Descriptor Properties
Each descriptor has a logical set of properties maintained by the system and defined by its 'we.
Each type supports a set of operations; some operations, such as reading and writing, are common to several abstractions, while others are unique. The generic operations applying to many
of these types are described in section 8. Naming contexts, files and directories are described in
section 9. Section 10 describes communications domains and sockets. Terminals and (structured and unstructured) devices are described in section 11.

5.3. Managing Descriptor References
A duplicate of a descriptor reference may be made by doing
n~'W == dup(old);
result int new; int old;

returning a copy of descriptor reference old indistinguishable from the original. The new chosen
by the system will be the smallest unused descriptor reference slot. A copy of a descriptor reference may be made in a specific slot by doing
dup2( old, new);
int old, new;
The dupe call causes the system to deallocate the descriptor reference current occupying slot
new, if any, replacing it with a referen~e to the same descriptor as old. This deallocation is also
performed by:
dose(old);
int old;

14

Revision E of 7 January 1984

Descriptors

System Interface Overview

5.4. Multiplexing Requests
The system provides a standard way to do synchronous and asynchronous multiplexing of
operations.
Synchronous multiplexing is performed by using the ,elect call:
nds =- select(nd, in, out, except, tvp);
result int nds; int nd; result *in, *out, *except;
struct timeval *tvp;
The ,elect call examines the descriptol'8 specified by the sets in, out and ezcept, replacing the
specified bit masks by the subsets that select for input, output, and exceptional conditions
respectively (nd indicates the size, in bits, of the bit masks). If any descriptors meet the following criteria, then the number of such descriptors is returned in nd, and the bit masks are
updated.
• A descriptor selects for input if an input oriented operation such as read or receive is possible, or if a connection request may be accepted (see section 10.1.4).
• A descriptor selects for output if an output oriented operation such as write or ,end is possible, or if an operation that was "in progress", such as connection establishment, has completed (see section 8.3).
• A descriptor selects for an exceptional condition if a condition that would cause a SIGURG
signal to be generated exists (see section 3.1).
If none of the specified conditions is true, the operation blocks for at most the amount of time
specified by tvp, or waits for one of the conditions to arise if tvp is given as o.
Options affecting i/o on a descriptor may be read and set by the call:
dopt =- fcntl(d, cmd, arg);
result int dopt; int d, cmd, arg;

I * interesting values for cmd */
*define
*define
*define
*define

F _SETFL
F _GETFL
F _S ET OWN
F _GETOWN

3
4
5
6

/ * set descriptor options */
/ * get descriptor options */
/* set descriptor owner (pid/pgrp) */
/* get descriptor owner (pid/pgrp) */

The F _SETFL cmd may be used to set a descriptor in non-blocking i/o mode and/or enable signalling when i/o is possible. F _SETOWN may be used to specify a process or process group to
be signalled when using the latter mode of operation.
Operations on non-blocking descriptors will either complete immediately, note an error
EWOULDBLOCK, partially complete an input or output operation returning a partial count, or
return an error EINPROGRESS noting that the requested operation is in progress. A descriptor which has signalling enabled will cause the specified process and/or process group be signaled, with a' SIGIO for input, output, or in-progress operation complete, or a SIGURG for
exceptional conditions.
For example, when writing to a termina.l using non-blocking output, the system will accept only
88 much data as there is buffer space for and return; when making a connection on a ,ocket, the
operation may return indicating that the connection establishment is "in progress". The ,elect
facility can be used to determine w hen further output is possible on the terminal, or when the
connection establishment attempt is complete.

Revision E of 7 January 1984

15

System Interface Overview

Resource Controls

6. Resource Controls
6.1. Process Priorities
The system gives CPU scheduling priority to processes that have not used CPU time recently.
This tends to favor interactive processes and processes that execute only for short periods. It is
possible to determine the priority currently assigned to a process, process group, or the processes
of a specified user, or to alter this priority using the calls:
#define PRIO_PROCESS
#define PRIO_PGRP
*define PRIO_USER

0
1
2

,*

process *1
1* process group *1
1* user id *1

prio == getpriot'ity(which, who);
result int prio; int which, who;
setpriority(which, who, prio);
int which, who, prio;
The value prio is in the range -20 to 20. The default priority is 0; lower priorities cause more
favorable execution. The getprioritll call returns the highest priority (lowest numerical value)
enjoyed by any of the epecified processes. The ,etprioritu call sets the priorities of all of the
specified processes to the specified value. Only the super-user may lower priorities.

6.2. Resource Utilization
The re!!ources used by a process are returned by a getrultJge caU, returning information in a
structure defined in < sys/resource.h > :
#define R USAGE_SELF
0
#define R USAGE_CHILDREN

,. usage by this process

*,

*/

-1/ * wsage by all children

getrusage(who, rusage);
int who; result struct rusage *rusage;
struct rusage {
struct
struct
int
. int
int
int
int
int
int
int
int
int
int
int
16

timeval ru_utime;
timeval ru_stime;
ru_maxrss;
ru_ixrss;
ru_idrss;
ru_isrss;
ru_minflt;
ru_majflt;
ru_nswap;
ru_inblock;
ru_oublock;
ru_msgsnd;
ru_msgrcv;
ru_nsignals;

*,

,* user time used *,
,* system time used
,* maximum core resident set size: kbytes *,
,* integral shared memory size (kbytes*sec) */
,* unshared data " *,
,* unshared stack" *,
,* page-reclaims *,
,* page faults *,
,* swal>s *,
,* block input operations *,
,* block output" .,
,* messages sent *,
,* messages received */
I * signals received *,
Revision E of 7 January 1984

System Interlace Overview
int
int

Re50urce Control5

ru_nvcsw;
ru_nivcsw;

/* voluntary context switches */
/* involuntary" */

};
The WAD parameter specifies whose resource usage is to be returned. The resources used by the
current process, or by all the terminated children or the current proce5S may be requested.

6.3. Resource Limits
The resources or a process ror which limits are controlled by the kernel are defined in
< sys/resource.h > , and controlled by the getrlimit and ,etrlimit calls:
*define
*define
*define
*define
#define
#define

/* cpu time in milliseconds */
/* maximum file size */
/* maximum data segment size */
/* maximum stack segment size */
/* maximum core file size */
/* maximum resident set size */

RLIMIT_CPU
RLIMIT_FSIZE
RLIMIT_DATA
RLIMIT_STACK
RLIMIT_CORE
RLIMIT_RSS

1
2
3
4
5

#define RLIM_NLIMITS

6

*define RLIM_INFINITY

Ox7rrrrrrr

struct rlimit {
int
int

0

rlim_cur;
rlim_max;

};

/ * current (sort) limit */
/ * hard limit */

getrlimit(resource, rip);
int resource; result struct rlimit *rlp;
setrlimit(resource, rip);
int resource; struct rlimit *rlp;
Only the super-user can raise the maximum limits. Other users may only alter rlim_cur within
the range rrom 0 to rlim_mtJz or (irreversibly) lower rlim_mtJz.

Revision E of 7 January 1984

17

System operation support

System Interface Overview

7. System operation support
The calls in this section are permitted only to a privileged user.

7.1. Bootstrap Operations
The call
mount(blkdev, dir, ronly);
*blkdev, *dir; int ronly;

~par

extends the UNIX name space. The mount call specifies a block device blktlev containing a UNIX
file system to be made available starting at tli,. If ,only is set then the file system is read-only;
writes to the file system will not be permitted and access times will not be updated when files
are referenced.
The call
swapon(blkdev, size);
char *blkdev; int size;
specifies a device to be made available for paging and swapping.

7.2. Shutdown Operations
The call
unmount( dir);
char *dir;
unmounts the file system mounted on di,. This call will succeed only if the file system is not
currently being used.
The call
syncO;
schedules input/output to dean all system buffer caches.
The call
reboot(how);
int how;
causes a machine halt or reboot. The call may request a reboot by specifying how as
RB_AUTOBOOT, or that the machine be halted with RB_HALT. These constants are defined
in < sys/reboot.h > .

7.3. Accounting
The system optionail y keeps an accounting record in a file for each process that exits on the
system. The format of this record is beyond the scope of this document. The accounting may
be enabled to a· file name by doing

18

Revision E of 7 January 1984

System Interface Overview

System operation support

acct(path);
char .path;

If pGtla is null, then accounting is disabled. Otherwise, the named file becomes the accounting
file.

Revision E of 7 January 1984

19

System Interface Overview

System Facilities

Part II -

System Facilities

This part of the document discusses the system facilities that are not considered part of the kernel.
The syst~m abstractions described are:
Director.~

Conte:tI,
A d ectory context is a position in the UNIX file system name space. Operations on files
and· ther named objects in a file system are always specified relative to such a context.
File,
Files are used to store uninterpreted sequence of bytes on which random access read, and
write, may occur. Pages from files or devices may also be mapped into process address
space. A directory may be read as a filet.
Communication, Domain,
A communications domain represents an interprocess communications environment, such as
the communications facilities of the UNIX system, communications in the INTERNET, or the
resource sharing protocols and access rights of a resource sharing system on a local network.
Socket,
A soclcet is an endpoint of communication and the focal point for IPC in a communications
domain. Sockets may be created in pairs, or given names and used to rendezvous with
other sockets in a communications domain, accepting connections from these sockets or
exchanging messages with them. These operations model a labeled or unlabeled communications graph, and can be used in a wide variety of communications domains. Sockets can
have different type, to provide different semantics of communication, increasing the flexibility of the model.
Terminal, and other device,
Devices include terminals, providing input editing and interrupt generation and output flow
control and editing, magnetic tapes, disks and other peripherals. They often support the
generic read and write operations as well as a number of ;octls.
Proce"e,
Process descriptors provide facilities for control and debugging of other processes.

t

Support for

20

mappin~

files is not included in this release.

Revision E of 7 January 1984

System Interface Overview

Generic Operations

8. Generic Operations
Many system abstractions support the operations read, write and ioctl. We describe the basics
of these common primitives here. Similarly, the mechanisms whereby normally synchronous
operations may occur in a non-blocking or asynchronous fashion are common to all systemdefined abstractions and are described here.

8.1. Read and Write
The read and write system calls can be applied to communications channels, files, terminals and'
devices. They have the form:
cc == read(fd, buf, nbytes);
result int cc; int fd; result caddr_t buf; int nbytes;
cc == write(fd, buf, nbytes);
result int cc; int fd; caddr_t buf; int nbytes;
The read call transfers as much data as possible from the object defined by /d to the buffer at
address bu/ of size nbgte,. The number of bytes transferred is returned in ce, which is -1 if a
return occurred before any data was transferred because of an error or use of non-blocking
operations.
The write call transfers data from the buffer to the object defined by /d. Depending on the type
of Id, it is possible that the write call will accept some portion of the provided bytes; the user
should resubmit the other bytes in a later request in this case. Error returns because of interrupted or otherwise incomplete operations are possible.
Scattering of data on input or' gathering of data for output is also possible using an array of
input/output vector descriptors. The type for the descriptors is defined in  as:
struct iovec {
caddr_t
int

iov_msg;
iov_len;

/ * base of a component *,
/* length of a component */

};
The calls using an array of descriptors are:
cc == readv(fd, iov, iovlen);
result int cc; int fd; struct iovec *iov; int iovlen;
cc =- writev(fd, iov, iovlen);
result int cc; int fd; struct iovec *iov; int iovlen;
Here iot)len is the count of elements in the iot) array.

8.2. Input/Output Control
Control operations on an object are performed by the ioctloperation:
ioctl(fd, request, buffer);
int fd, request; caddr_t buffer;
This oper~tion causes the specified requelt to be performed on the object /d. The requed
parameter specifies whether the argument buffer is to be read, written, read and written, or is
Revision E of 7 January

198~

21

Generic Operations

System Interface Overview

not needed, and also the size of the buffer, as well as the request. Different descriptor types and
subtypes within descriptor types may use distinct 'octl requests. For example, operations on
terminals control flushing of input and output queues and setting of terminal parameters; operations on disks cause formatting operations to occur; operations on tapes control tape positioning.
The names for basic control operations are defined in .

8.3. Non-Blocking and Asynchronous Operations
A process that wishes to do non-blocking operations on one of its descriptors sets the descriptor
in non-blocking mode as described in section 5.4. Thereafter the read call will return a specific
EWOULDBLOCK error indication if there is no data to be read. The process may ,elect the
associated descriptor to determine when a read is possible.
Output attempted when a descriptor can accept less than is requested'will either accept some of
the provided data, returning a shorter than normal length, or return an error indicating that
the operation would block. More output can be performed as soon as a ,elect call indicates the
object is writeable.
Operations other than data input or output may be performed on a descriptor in a non-blocking
fashion. These operations will return with a characteristic error indicating that they are in progress if they cannot return immediately. The descriptor may then be ,elected for write to find
out when the operation can be retried. When ,elect indicates the descriptor is writeable, a
respecification of the original operation will return the re~mlt of the operation.

22

Revision E of 7 January 1984

System Interlace Overview

File System

9. File System
The file system abstraction provides access to a hierarchical file system structure. The file system contains directories (each of which may contain other sub-directories) as well as files and
references to other objects such as devices and inter-process communications sockets.
Each file is organized as a linear array of bytes. No record boundaries or system related information is present in a file. Files may be read and written in a. random-access fashion. The user
may read the data in a directory as though it were an ordinary file to determine the names of
the contained files, but only the system may write into the directories. The file system stores
only a small amount of ownership, protection and usage information with a file.

9.1. l'faming
The file vstem calls take poth nome arguments. These consist of a zero or more component file
name. separated by "/" characters, where each file name is up to 255 ASCII characters excluding null ;fpd "/".
Each pro~ess always has two naming contexts: one for the root directory of the file system and
one for t4e current working directory. These are used by the system in the filename translation
process. If a path name begins with a "/", it is called a full path name and interpreted relative
to the root directory context. If the path name does not begin with a "/" it is called a relative
path name and interpreted relative to the current directory context.
The system limits the total length of a path name to 1024 characters.
The file name " .. " in each directory refers to the parent directory of that directory.
The calls
chdir{path);
char .path;
chfoot{path );
clift.!' .path;
change the current working directory and root directory context of a process. Only the superuser can change the root directory context of a process.

9.2. Creation and Removal
The file system allows directories, files and special devices, to be created and removed from the
file system.

9.2.1. Directory Creation and Removal
A directory is created with the mkdir system call:
mkdir(path, mode);
char .path; int mode;
and removed with the rmdir system call:

Revision E of 7 January 1984

23

System Interface Overview

File System

rmdir(path);
char *path;
A directory must be empty if it is to be deleted.

9.2.2. File Creation
Files are created with the open system call,
fd = open(path, oflag, mode);
rel5ult int fd; char *path; int 01lag, mode;
The pat~ parameter specifies the name of the file to be created. The oftafl parameter must
include Q,-CREAT from below to cause the file to be created. The protection for the new file is
specified In mode. Bits for oftafl are defined in :
:/Ihlefine
:/Idefine
#define
#define
#define
*define
#define
#define

O_RDONLY
O_WRONLY
O_RDWR
O_NDELAY
O_APPEND
O_CREAT
O_TRUNC
O_EXCL

000
001
002
004
010
01000
02000
04000

/*
/*
/*
/*
/*
/*
/*

1*

open for reading */
open for writing */
open for read & write */
non-blocking open */
append on each wri~e */
open with file create */
open with truncation */
error on create if file exists */

One of O_RDONLY, O_WRONLY and O_RDWR should be specified, indicating what types of
operations are desired to be performed on the open file. The operations will be checked against
the user's access rights to the file before allowing the open to succeed. Specifying O_APPEND
causes writes to automatically append to the file. The flag O_CREAT causes the file to be
created if it does not exist, with the specified mode, owned by the current user and the group of
the containing directory.
If the open specifies to create the file with O_EXCL and the file already exists, then the open
will fail without affecting the file in any way. This provides a simple exclusive access facility.

9.2.3. Creating References to Devices
The file system allows entries which reference peripheral devices. Peripherals are distinguished
as block or character devices according by their ability to support block-oriented operations.
Devices are identified by their "major" and "minor" device numbers. The major device number
determines the kind of peripheral it is, while the minor device number indicates one of possibly
many peripherals of that kind. Structured devices have all operations performed internally in
"block" quantities while unstructured devices often have a number of special ioetloperations,
and may have input and output performed in large units. The mknod call creates special
entries:
mknod(path, mode, dev);
char *path; int mode, dev;
where mode is formed from the object type and access permissions. The parameter tie., is a
configuration dependent parameter used to identify specific character or block i/o devices.

24

RevisionE of 7 January 1984

System Interface Overview

File System

9.2.4. File and Device Removal
A reference to a file or special device may be removed with the unlink call,
unlink(path );
char .path;
The caller must have write access to the directory in which the file is located for this call to be
successful.

9.3. Reading and Modifying File Attributes
Detailed information about the attributes of a file may be obta.ined with the calls:
*include 
stat(path, sth);
char *path; result struct stat *stb;
fstat(fd, stb);
int fd; result struct stat *stbj
The dtd structure includes the file type, protection, ownership, access times, size, and a count of
hard links. If the file is a symbolic link, then the status of the link itself (rather than the file
the link references) may be found using the I.tat call:
Istat(path, stb);
char *path; result struct stat *stb;
Newly created files are assigned the user id of the process that created it and the group id of the
directory JIi which it was created. The ownership of a file may be changed by either of the calls
c1u)wn(path, owner, group);
chpr *path; int owner, group;
fchown(fd, owner, ~up);
int fd, owner, group;
In addition to ownership, each file has three levels of access protection associated with it. These
levels are owner relaiive, group relative, and global (all users and groups). Each level of access
has separate indicators for read permission, write permission, and execute permission. The protection bits associated with a file may be set by either of the calls:
chmod(path, mode);
char *path; int mode;
fchmod{fd, mode);
int fd, mode;
where mode is a value indicating the new protection of the file. The file mode is a three digit
octal number. Each digit encodes read access as 4, write access as 2 and execute access as 1,
or'ed together. The 0700 bits describe owner access, the 070 hits describe the access rights for
processes in the same group as the file, and the 07 bits describe the access rights for other
processes.

Revision, of 7 January 1984

25

File System

System Interface Overview

Three additional bits exist: the 04000 "set-usel"-id" bit can be set on an executable file to eause
the effective user-id of a process which executes the file to be set to the owner of that file; the
02000 bit has a similar effect on the effective group-ide The 01000 bit causes an image 01 an
executable program to be saved longer than would otherwise be normal; this "stiekytt bit is a
hint to the system that a program is heavily used.
Finally, the access and modify times on a file may be set by the call:
utimes(path, tvp);
ehar *path; struct timeval *tvp[2];
This is particularly useful when moving files between media, to preserve relationships between
the times the file was modified.

9.4. Links and Renaming
Links allow multiple names lor a file to exist. Links exist independently 01 the file linked to.
Two types of links exist, Aartllinks and .gm6DI;c links. A hard link is a relerence counting
mechanism that allows a file to have multiple names within the same file system. Symbolic
links cause string substitution during the patbname interpretation process.
Hard links and symbolic links have different properties. A hard link insures the target file will
always be accessible, even after its original directory entry is removed; no such guarantee exists
lor a symbolic link. Symbolic links ean span file systems boundaries.
The following calls create a new link, named patAS, to patAl:
link(pathl, path2);
char *pathl, *path2;
symlink(pathl, path2);
char *pathl, *path2;
The unlink primitive may be used to remove either type of link.
II a file is a symbolic link, the "value" of the link may be read with the readl;n" eall,
le~ - readlink(path, buf, bufsize);
result int len; result char *path, *buf; int bufsize;

This call returns, in 6uJ, the null-terminated string substituted into pathnames passing through
palA.
Atomic renaming of file system resident objects is possible with the rename call:
rename( oidname, new name );
char *oldname, *newname;
where both DIJname and newname must be in the same file system. If newname exists and is a
directory, then it must be empty.

9.5. Extension and Truncation
Files are created with zero length and may be extended simply by writing or appending to
them. While a file is open the system maintains a pointer into the file indicating the current
location in the file associated with the descriptor. This pointer may be moved about in the file
in a random access fashion. To set the current offset into a file, the uee" call may be used,
26

Revision E 017 January 1084

System Interlace Overview

File System

oldotlset = lseek(fd, offset, type);
result off_t oldotlset; int fd; off_t offset; int type;
where

'we is given in

 as one of,

#define L_SET
#define L_INCR
#define L_XTND

0
1

2

1* set absolute file offset *1
1* set file offset relative to current position *I
1* set offset relative to end-of-file *1

The call "lseek(fd, 0, L_INCR)" returns the current offset into the file.
Files may have "holes" in them. Holes are void areas in the linear extent of the file where data
has never been written. These may be created by seeking to a location in a file past the current
end-of-file and writing. Holes are treated by the system as zero valued bytes.
A file may be truncated with either of the calls:
truncate(path, length);
char *path; int length;
ftruncate(fd, length);
int fd, length;
reducing the size of the specified file to length bytes.

9.0. Checking Accessibility
A process running with different real and effective user ids may interrogate the accessibility of a
file to the real user by using the acce" call:
accessible = access(path, how);
result int accessible; char *path; int how;
Here bow is constructed by or'ing the following bits, defined in :
#define
#define
#define
#define

F _OK
X_OK
W_OK
R_OK

0
1
2
4

1* file exists *I
1* file is executable *1
1* file is writable *1
1* file is readable *I

The presence or absence of advisory locks does not affect the result of acce".

9.7. Locking
The file system provides basic facilities that allow cooperating processes to synchronize their
access to shared files. A process may place an advisory read or write lock on a file, so that other
cooperating processes may avoid interfering with the process' access. This simple mechanism
provides locking with file granularity. More granular locking can be built using the IPC facilities to provide a lock manager. The system does not force processes to obey the locks; they are
of an advisory nature only.
Locking is performed after an open call by applying the flock primitive,
flock(fd, how);
int fd, how;
where the how parameter is formed from bits defined in :
Revision

~

of 7 January 1984

27

System Interface Overview

File System

#define
#define
#define
#define

LOCK_8H
LOCK_EX
L OCK_NB
LOCK_UN

1
2

4
8

/ * shared lock */
/* exclusive lock */
/ * don't block when locking */
/* unlock */

Successive lock calls may be used to increase or decrease the level of locking. If an object is
currently locked by another process when a floc' call is made, the caller will be blocked until the
current lock owner releases the lock; this may be avoided by including LOCK_NB in the AOfD
parameter. Specifying LOCK_UN removes all locks associated with the descriptor. Advisory
loeb held by a process are automatically deleted when the process terminates.

9.S. Disk Quotas
As an optional facility, each file system may be requested to impose limits on a user's disk
usage. Two quantities are limited: the total amount of disk space which a user may allocate in
a file system and the total number of files a user may create in a file system. Quotas are
expressed as Aard limits and .oft limits. A hard limit is always imposed; if a user would exceed
a hard limit, the operation which caused the resource request will fail. A soft limit results in the
user receiving a warning message, but with allocation succeeding. Facilities are provided to turn
soft limits into hard limits if a user has exceeded a soft limit for an unreasonable period of time.
To enable disk quotas on a file system the .dquota call is used:
15 etquot a( special,

file);
char *special, *file;

where .pecial refers
to a disk quota file
should be obtained.
To manipulate disk

to a structured device file w here a mounted file system exists, and file refers
(residing on the file system associated with .pec;al) from which user quotas
The format of the disk quota file is implementation dependent.
quotas the quota call is provided:

#include 
quota(cmd, uid, arg, addr);
int cmd, uid, arg; caddr_t addr;
The indicated cmd is applied to the user ID uitl. The parameters org and atltlr are command
specific. The file  contains definitions pertinent to the use of this call.

28

Revision E of 7 January 1984

Interprocess Communications

System Interlace Overview

10. Interprocess Communications
10.1. Interprocess Communication Primitives
10.1.1. Communication Domains
The system provides access to an extensible set of communication domain,. A communication
domain is identified by a manifest constant defined in the file . Important
standard domains supported by the system are the UNIX domain, AF _UNIX, for communication
within the system, and the "internet" domain for communication in the DARPA internet,
AF _INET. Other domains can be added to the system.

10.1.2. Socket Types and Protocols
Within a domain, communication takes place between communication endpoints known as ,ocket.. Each socket has the potential to exchange information with other sockets within the
domain.
Each socket has an associated abstract type, which describes the semantics of communication
using that socket. Properties such as reliability, ordering, and prevention of duplication of messages are determined by the type. The basic set of socket types is defined in :

/ * Standard socket types */
#define
#define
#define
#define
#define

SOCK_DGRAM
1
SOCK_STREAM
2
SOCK_RAW
3
SOCK_RDM
4
SOCK_SEQPACKET 5

/ * datagram */
/ * virtual circuit */
/ * raw socket */
/ * reliably-delivered message */

/ * sequenced packets */

The SOCK_DGRAM type models the semantics of datagrams in network communication: messages may be lost or duplicated and may arrive out-of-order. The SOCK_RDM type models the
semantics of reliable datagrams: messages arrive unduplicated and in-order, the sender is
notified if messages are lost. The ,end and receive operations (described below) generate
reliable/unreliable datagrams. The SOCK_STREAM type models connection-based virtual circuits: two-way byte streams with no record boundaries. The SOCK_SEQP ACKET type models
a connection-based, full-duplex, reliable, sequenced packet exchange; the sender is notified if
messages are lost, and messages are never duplicated or presented out-of-order. Users of the
last two abstractions may use the facilities for out-of-band transmission to send out-of-band
data.
SOCK_RAW is used for unprocessed access to internal network layers and interfaces; it has no
specific semantics.
Other socket types can be defined. t
Each socket may have a concrete protocol associated with it. This protocol is used within the
domain to provide the semantics required by the socket type. For example, within the

t This release does not support the

SOCK~DM

Revision E of 7 January 1984

and SOCK_SEQPACKET types.

29

System Interlace Overview

Interprocess Communications

"internet" domain, the SOCK_DGRAM type may be implemented by the UDP user datagram
protocol, and the SOCK_STREAM type may he implemented by the TCP transmission control
protocol, while no standard protocols to provide SOCK_RDM or SOCK_SEQPACKET sockets
exist.

10.1.3. Socket Creation, Naming, and Service Establishment
Sockets may he connected or unconnected. An unconnected socket descriptor is obtained by the
locket call:
s =- socket(domain, type, protocol);
result int s; int domain, type, protocol;
An unconnected socket descriptor may yield a connected socket descriptor in one of two ways:
either by actively connecting to another socket, or by becoming associated with a name in the
communications domain and accepting a connection from another socket.
To accept connections, a socket must first have a binding to a name within the communications
domain. Such a binding is established by a bind call:
bind(s, name, namelen);
int s; char *name; int namelen;
A socket's bound name may be retrieved with a getlockname call:
getsockname(s, name, namelen);
int s; result caddr_t name; result int tnamelen;
while the peer's name can be retrieved with getpeername:
getpeername(s, name, namelen);
int s; result caddr_t name; result int *namelen;
Domains may support sockets with several names.

10.1.4. Accepting Connections
Once a binding is made, it is possible to Iilten lor connections:
listen(s, backlog);
int s, backlog;
The backlog specifies the maximum count 01 connections that can be simultaneously queued
awaiting acceptance.
An accept calf:
t == accept(s, name, anamelen);
result int t; int s; result caddr_t name; result int *anamelen;
!

returns a descriptor for a new, connected, socket from the queue of pending connections on

30

I.

Revision E 017 January lQ84

System Interface Overview

Interprocess Communications

10.1.5. Making Connections
An active connection to a named socket is made by the connect call:
connect(s, name, namelen);
int s; caddr_t name; int namelen;
It is also possible to create connected pail"8 of sockets without using the domain's name space to
rendezvous; this is done with the ,ockdpa;r calif:

socketpair(d, type, protocol, sv};
int d, type, protocol; result int sv[2];
Here the returned
The call

'f}

descriptors correspond to those obtained with accept and connect.

pipe(pv);
result int pV[2];
creates a pair of SOCK_STREAM sockets in the UNIX domain, with pV[O] only writeable and
pV[l] only readable.

10.1.6. Sending and Receiving Data
Messages may be sent from a socket by:
cc = sendto(s, but, len, flags, to, tolen);
result int cc; int s; caddr_t buf; int len, flags; caddr_t to; int tolen;
if the socket is not connected or:
cc = send(s, buf, len, flags);
result int cc; int s; caddr_t but; int len, flags;
if the socket

i~

connected. The corresponding receive primitives are:

msglen - recvfrom(s, buf, len, flags, from, fromlenaddr);
result int msglen; int Sj result caddr_t buf; int len, flags;
result caddr_t from; result int .fromlenaddr;
and
msglen - recv(s, buf, len, flags);
result int msglen; int s; result caddr_t bur; int len, flags;
In the unconnected case, the parameters to and tolen specify the destination or source of the
message, while the from parameter stores the source of the message, and ~from/en(Jddr initially
gives the size of the from buffer.and is updated to reflect the true length of the from address.
All calls cause the message to be received in or sent from the message buffer of length len bytes,
starting at address buf. The flafJ, specify peeking at a message without reading it or sending or
receiving high-priority out-of-band messages, as follows:

t This release supports IDdetptlir creation only in the "unix" communication domain.

Revision E of 7 January 1984

31

System Interfaee Overview

Interprocess Communications

*define MSG_PEEK
*define MSG_OOB

Oxl
Ox2

/* peek at incoming message */
/* process out-of-band data */

10.1.7. Scatter/Gather and Exchanging Access Rights
It is possible to scatter and gather data and to exchange access rights with messages. When
either of these operations is involved, the number of parameters to the call becomes large. Thus
the system defines a me8sage header 8tructure, in <8ys/socket.h>, which is used to contain the
parameters to the calls:
struct msghdr {
caddr_t
int
struct
int
caddr_t
int

msg_name;
msg_namelen;
iov *msLiov;
msg_iovlen;
msg_accrights;
msg_accrightslen;

/* optional address */
/ * size of address */
/* scatter/ gather array */
/* * elements in mSLiov */
/* access rights sent/received
/* size of mSLaccrights */

*/

};
Here m'l-nome and ml,_nomelen specify the 80urce or destination address if the socket is
unconnected; m,,_nome may be given as a null pointer if no names are desired or required. The
m,,_iotJ and m,g_iotJ/en describe the scatter/gather locations, as described in section 8.3. Access
rights to be ·sent along with the message are specified in m'l-occr;,ht" which has length
m,g_occrightllen. In the "unix" domain these are an array of integer descriptors, taken from
the 8ending process and duplicated in the receiver.
This structure is used in the operations ,endm'lI and recvm,v.
sendmsg( s, msg, flags);
int S; struct msghdr *msg; int flags;
msglen = recvm8g(s, msg, flag8);
result int msglen; int S; result struct msghdr *msg; int flags;

10.1.S. Using Read and Write with Sockets
The normal UNIX reod and write calls may be applied to connected sockets and translated into
.end and receitJe calls from or to a 8ingle area of memory and discarding any rights received. A
process may operate on a virtual circuit socket, a terminal or a file with blocking or nonblocking input/output operations without distinguishing the descriptor type.

10.1.9. Shutting Down Halves or Full-Duplex Connections
A process that has a full-duplex socket such as a virtual circuit and no longer wishes to read
from or write to this socket can give the call:
shutdown(s, direction);
int s, direction;
w here direction is 0 to not read further, 1 to not write further, or 2 to completely shut the

32

Revision E of 7 January 1984

System Interface Overview

Interprocess Communications

connection down.

10.1.10. Socket and Protocol Options
Sockets, and their underlying communication protocols, may support option.. These options
may be used to manipulate implementation specific or non-standard facilities. The get.ockopt

and ,et,ockopt calls are used to control options:
getsockopt(s, level, optname, optval, optlen);
int s, level, optname; result caddr_t optval; result int *optlen;
setsockopt(s, level, optname, optval, optlen);
int s, level, optnamej caddr_t optval; int optlen;
The option optntJme is interpreted at the indicated protocol letJel for socket •. If a value is
specified with opttJtJl and optlen, it is interpreted by the software operating at the specified letJel.
The level SOL_SOCKET is reserved to indicate options maintained by the socket facilities.
Other letJeI values indicate a particular protocol which is to act on the option request; these
values are normally interpreted as a "protocol number".

10.2. UNIX Domain
This section describes briefly the properties of the UNIX communications domain.

10.2.1. Types or Sockets
In the UNIX domain, the SOCK_STREAM abstraction provides pipe-like facilities, while
SOCK_DGRAM provides datagrams - unreliable message-style communications.

10.2.2. Naming
Socket nameS are strings and may appear in the UNIX file system name space through portalst.

10.2.3. Access Rights Transmission
The ability to pass UNIX descriptors with messages in this domain allows migration of service
within the system and allows user processes to be used in building system facilities.

10.3. INTERNET Domain
This section describes briefly how the INTERNET domain is mapped to the model described in
this section. More information will be found in the Networking Implementation Note. in the
System Internals Manual.

t

The current implementation 01 the UNIX domain embeds bound sockets in the UNIX file system
name space; this is a side effect 01 the implementation.

Revision E of 7 January 1984

33

Interprocess Communications

System Interlace Overview

10.3.1. Socket Types and Protocols
SOCK_STREAM is supported by the INTERNET TCP protocol; SOCK_DGRAM by the UDP
protocol. The SOCK_SEQPACKET has no direct INTERNET lamily analogue; a protocol
based on one from the XEROX NS family and layered on top of IP could be implemented to fill
this gap.

10.3.2. Socket Naming
Sockets in the INTERNET domain have names composed of the 32 bit internet address, and a
16 bit port number. Options may be used to provide source routing for the address, security
options, or additional addresses for subnets of INTERNET for which the basic 32 bit addresses
are insufficient.

10.3.3. Access Rights Transmission
No access rights transmission facilities are provided in the INTERNET domain.

10.3.4. Raw Access
The INTERNET domain allows the super-U5er access to the raw facilities of the various network interfaces and the various internal layel'8 of the protocol implementation. This allows
administrative and debugging functions to occur. These interfaces are modeled as SOCK_RAW
sockets.

34

Revision E of 7 January 1984

System Interrace Overview

Devices

11. Devices
The system uses a collection of device-drivers to access attached peripherals. Such devices are
grouped into two classes: structured devices on which block-oriented input/output operations
occur, and unstructured devices (the rest).

11.1. Structured Devices
Structured devices include disk and tape drives, and are accessed through a system buffercaching mechanism, which permits them to be accessed as ordinary files are, performing reads
and writes as necessary to allow random-access.
The mount command in the system allows a structured device containing a file system volume
to be accessed through the UNIX file system calls.
Tape drives also typically provide a structured interface, although this is rarely used.

11.2. Unstructured Devices
Unstructured devices are those devices which do not support a randomly accessed block structure.
Communications lines, raster plotters, normal magnetic tape access (in large or variable size
blocks), and access to disk drives permitting large block transfers and special operations like
disk formatting and labelling all use unstructured device interfaces.
The writing of devices for unstructured devices other than communications lines is described in
the Device Driver Manual in the System Internals Manual.

Revision E

ot 7 January 1984

3S

Debugging Support

System Interfaee Overview

12. Debugging Support
The ptrace facility of version 7 UNIX is provided in this release. Planned enhancements which
would allow a descriptor-based process control facility have not been implemented.

36

Revision E of 7 January 1984

System Interface Overview

Part m

Summary of Facilities

-

Summary of Facilities

Appendix A. Summary of Facilities

A.I. Kernel Primitives
A.l.I. Process Naming and Protection
sethostid
gethostid
sethostname
gethostname
getpid
fork
exit
execve
getuid
geteuid
setreuid
getgid
getegid
getgroups
setregid
setgroups
getpgrp
setpgrp

set UNIX host id
get UNIX host id
set UNIX host name
get UNIX host name
get process id
create new process
terminate a process
execute a dHferent process
get user id
get effective user id
set real and effective user id's
get accounting group id
get effective accounting group id
get access group set
set real and effective group id's
set access group set
get process group
set process group

A.l.2. Memory Management

sbrk
sstkt

memory management definitions
change data section size
change stack section size

t Not supported in the 1.1 Sun release.

Revision E of 7 January 1984

37

System Interface Overview

Summary of Facilities
get pagesize
mmapt
mremapt
munmapt
mprotectt
madviset
mincoret

get memory page size
map pages of memory
remap pages in memory
unmap memory
change protection of pages
give memory management advice
determine core residency of pages

A.I.3. Signals

< sign al.h>
sigvec
kill
killpgrp
sigblock
sigsetmask
sigpause
sigstack

signal definitions
set handler for signal
send signal to process
send signal to process group
block set of signals
restore set of blocked signals
wait for signals
set software stack for signals

A.l.4. Timing and Statistics

gettimeofday
settimeofday
getitimer
setitimer
profil

time-related definitions
get current time Itond timezone
set current time and timezone
read an interval timer
get and set an interval timer
profile process

A.I.S. Descriptors
getdtablesize
dup
dup2
close
select
fcntl

descriptor reference table size
duplicate descriptor
duplicate to specified index
close descriptor
multiplex input/output
control descriptor options

t Not supported in the 1.1 Sun release.

38

Revision E of 7 January 1984

System Interlace Overview

Summary or Facilities

A.I.O. Resource Controls

get priority
set priority
getrusage
getrlimit
setrlimit

resource-related definitions
get process priority
set process priority
get resource usage
get resource limitations
set resource limitations

A.I.7. System Operation Support
mount
swapon
umount
sync
reboot
acct

mount a device file system
add a swap device
umount a file system
flush system caches
reboot a machine
speciry accounting file

A.2. System Facilities
A.2.1. Generic Operations
read
write

readv
writev

ioctl

read data
write data
scatter-gather related definitions
scattered data input
gathered data output
standard control operations
device control operation

A.2.2. File System
OperatioDs marked with a • exist in two rorms: as shown, operating on a file name, and operating on a file descriptor, when the name is preceded with a "f".
< sys/file.h >
chdir
cmoot
mkdir
rmdir
open
mknod
unlink
stat·

Revision E

ot 7 January 1984

file system definitions
change directory
change root directory
make a directory
remove a directory
open a new or existing file
make a special file
remove a link
return status for a file

39

System Interlace Overview

Summary of Facilities
1st at
chown·
chmod·
utimes
link
symlink
readlink
rename
Iseek
truncate·
access
flock

returned status of link
change owner
change mode
change access/modify times
make a hard link
make a symbolic link
read contents of symbolic link
change name of file
reposition within file
truncate file
determine accessibility
lock a file

A.2.3. Interprocess Communications

socket
bind
getsockname
listen
accept
connect
socketpair
sendto
send
recvfrom
recv
sendmsg
recvmsg
shutdown
getsockopt
setsockopt

standard definitioDs
create socket
bind socket to name
get socket name
allow queueing of connections
accept a connection
connect to peer socket
create pair of connected sockets
send data to named socket
send data to connected socket
receive data on unconnected socket
receive data on connected socket
send gathered data and/or rights
receive scattered data and/or rights
partially close full-duplex connection
get socket option
set socket option

A.2.4. Devices

A.2.5. Debugging Support

40

Revision E of 7 January 1984

SYSTEM CALLS

INTRO(2)

INTRO (2)

NAME
intro - introduction to system calls and error numbers
SYNOPSIS

#lnclude 
DESCRIPTION
~his section describes alrof the system calls. Most of these calls have one or more error returns.
An error condition is indicated by an otherwise impossible return value. This it] almost always -1;
tbe individual descriptions specify the details.

t

with normal arguments, all return codes and values from functions are of type integer unless
O..therwise noted. An error number is also made available in the external variable errno, which is
Dot cleared on successful calls. Thus errno should be tested only after an error has occurred.
~he

following is a complete list of the errors and their names as given in .

OJ

Error 0
Unused.

1 EPERM Not owner
Typically this error indicates an attempt to modify a file in some way forbidden except to
its owner or super-user. It is also returned for attempts by ordinary users to do things
allowed only to the super-user.
2 ENOENT No such file or directory
This error occurs when a file name is specified and the file should exist but doesn't, or
when one of the directories in a path name does not exist.
3 ESRCH No such process
The process whose number was given to kill and ptrace does not exist, or is already dead.
4 EINTR Interrupt~d system call
An asynchronous signal (such as interrupt or quit), which the user has ejected to catch,
occurred during a system call. If execution is resumed after processing the signal, it will
appear as if the interrupted system call returned this error condition.
S EIO I/O error
Some physical I/O error occurred during a read or write. This error may in some cases
occur on a caU following the one to which it actually applies.
6 ENXIO No such device or address
I/O on a special file refers to a subdevice which does not exist, or beyond the limits of the
device. It may also occur when, for example, an illegal tape drive unit number is selected
or a disk pack is not loaded on a drive.
7 E2BIG Arg list too long
An argument list longer than 10240 bytes is presented to ezecve.
8 ENOEXEC Exec format ~rror
A request is made to execute a file which, although it has the appropriate permissions,
does not start with a valid magic number, see a.out(5).
9 EBADF Bad file number
Either a file descriptor refers to
open file, or a read (resp. write) request is made to a
file which is ope.n only for writing (resp. reading).

no

10 ECHILD No children
Wait and the process has no living or unwaited-for children.
11 EAGAIN No more processes
In a lork, the system's process table is full or the user is not allowed to create any more
processes.

Sun Release 1.1

Last change: 15 March 1984

1

INTRO(2)

INTRO(2)

SYSTEM CALLS

12 ENOMEM Not enough core
During an ezecve or brealc, a program asks for more core or swap space than the system is
able to supply. A lack of swap space is normally a temporary condition, however a lack
of core is not a temporary condition; the maximum size ot the text, data, and stack segments is a system parameter.
13 EACCES Permission denied
An attempt was made to access a file in a way forbidden by the protection system.
14 EFAULT Bad address
The system encountered a hardware fault in attempting to access the arguments of a system call.
15 ENOTBLK Block device required
A plain file was mentioned where a block device was required, e.g. in moun'.
16 EBUSY Mount device busy
An attempt to mount a device that was already mounted or an attempt was made to
dismount a device on which there is an active flle directory . (open file, current directory,
mounted-on file, active text segment).
17 EEXIST File exists
An existing ftl~ was mentioned in an inappropriate context, e.g. link.
18 EXDEV CroM-device link
A hard link to a file on another device was attempted.

19 ENODEV No such device
An attempt was made to apply an inappropriate system call to a device; e.g. read a
.write-only device.
20 ENOTDm Not a directory
A non-directory was specified where a directory is required, for example in a path name
or as an argument to ehdir.
21 EISDm Is a directory
An attempt to write on a directory.
22 EINVAL Invalid argument
Some invalid argument: dismounting a non-mounted device, mentioning an unknown signal in 6ignal,reading or writing a file for which 6eek has generated a negative pointer.
Also set by math functions, see intro(3).
23 ENFILE File table overflo~
The system's table or open files is full, and temporarily no more open8 can be accepted.
24 E~ILE Too many open fiie~
Customary configuration limit is 20 per process.
25 ENOTTY Not a typewriter
The file mentioned in an ioeel is not a terminal or one or the other devices to which these
calls apply.
26 ETXTBSY Text ftle busy
An attempt to execute a pure-procedure program which is currently open for writing (or
reading!). Also an attempt to opeD for writing a pure-procedure program that is being
executed.

27 EFBIG File too large
The size of a file exceeded the maximum (about 10D bytes).
28 ENOSPC No space left on device
During a write to an ordinary file, there is no tree space left on the device.

2

Last change: 15 March 1984

Sun Release 1.1

SYSTEM CALLS

INTRO(2)

INTRO(2)

29 ESPIPE Illegal seek
An '8eek was issued to a pipe. This error may also be issued for other non-seekable devices.
30 EROFS Read-only file system
An attempt to modify a file or directory was made on a device mounted read-only.
31 EIviLINK Too many links
An attempt to make more than 32767 hard links to a file.
32 EPIPE Broken pipe
A write on a pipe or socket for which there is no process to read the data. This condition
normally generates a signal; the error is returned if the signal is ignored.
33 EDOM Math argument
The argument of a function in the math library (as described in section 3M) is out of the
domain of the function.
34 ERANGE Result too large
The value
a function in the math library (as described in section 3M) is unrepresentable within ~achine precision.

ot.

35 EWOULDBLOCK Operation would block
An operation which would cause a process to block was attempted on a object in nonblocking mode (see ioctl(2)).
36 EINPROGRESS Operation now in progress
An operation which takes a long time to complete (such as a connect(2)) was attempted
on a non-blocking object (see ioctl(2)).
37 EALREADY Operation already in progress
An operation was attempted on a non-blocking object which already had an operation in
progress.
38 ENOTSOck SocJcet operation on non-socket
Self-explanatory .
39 EDESTADDRR:EQ Destination address required
A requited address was omitted from an operation on a socket.
40 EMSGSIZE Message too long
A message sent on a socket was larger than the internal message buffer.
41 EPROTOTYPE Protocol wrong type for socket
A protocol was specified which does not support the semantics of the socket type
requested. For example you cannot use the ARPA Internet UDP protocol with type
SOCK_STREAM.
42 ENOPROTOOPT Bad protocol option
A bad option was specified in a gd8ockopt(2) or 8etl1ockopt(2) call.
43 EPROTONoSUPPORT Protocol not supported
The protocol lias not been configured into the system or no implementation for it exists.
44 ESOCKTNOSUPPORT Socket type not supported
The support for the socket type has not been configured into the system or no implementation for it exi6ts.
45 EOPNOTSUPP Operation not supported on socket
For example, trying to accept a connection on a datagram socket.
46 EPFNOSUPPORT "Protocol family not supported
The protocol family has not been configured into the system or no implementation for it
exists.

SUD

Release 1.1

Last change: 15 March 1984

3

INTRO(2)

SYSTEM CALLS

INTRO(2)

47 EAFNOSUPPORT Address family not supported by protocol family
An address incompatible with the requested protocol was used. For example, you
shouldn't 'necessarily expect to be able to use PUP Internet addresses with ARPA Internet protocol!.
48 EADDRlNUSE Address already in use
Only one usage of each address is normally permitted.
49 EADDRNOTAVAIL Can't assign requested address
Normally results from an attempt to create a socket with an address not on this machine.
50 ENETDOWN Network is down
A socket operation encountered a dead network.
51 ENETUNREACH Network is unreachable
A socket operation was attempted to an unreachable network.
52 ENETRESET Network dropped connection on reset
The host you were connected to crashed and rebooted.
53 ECONNABORTED Software caused connection abort
A connection abort was caused internal to your hoet machine.
54 ECONNRESET Connection reset by peer
A connection was forcibly closed by a peer .. This normally results from the peer
ing a 8hutdown(2) call.

execu~

55 ENOBUFS No buffer space available
An operation on a socket or pipe was not performed because the system lacked sufficient
buffer space.
66 EISCONN Socket is already connected
A connect request was made on an already connected socket; or, a 8endeo or 8endm8g
request on a connected socket specified a destination othe!' th:m the~,o!!.nected party.
57 ENOTCONN Socket is not connected
An request to send or receive data was disallowed because the socket is not connected.
58 ESlRJTDOWN Can 't send after socket shutdown
A request to send data was disallowed because the socket had already been shut down
with a previous Bhutdown(2) call.
59 unuaed
60 ETlMEDUUT Connection timed out
A connect request failed because the connected party did not properly respond after a
period of time. (The timeout period is dependent on the communication protocol.)
61 ECONNREFUSED Connection refused
No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service which is inactive on the foreign host.
62 ELOOP Too many levels of symbolic links
A path name lookup involved more than 8 symbolic links.
63 ENAMETOOLONO File name too long
A component ot a path name exceeded 265 characters, or an entire path name exceeded
1023 characters~
64 ENOTEMPTY Directory not empty
A directory with en tries other than "." and " .. " was supplied to a remove directory or
rename call.

4

Last change: 15 March 1984

Sun Release 1.1

SYSTEM CALLS

INTRO(2)

INTRO( 2)

DEFINITIONS

Descriptor
An integer assigned by the system when a file is rererenced by open(2), dup(2), or pipe(2) or
a socket is referenced by 8ocket(2) or 8ocketpair(2) which uniquely identifies an access path
to that file or socket from a given process or any oC its children.
Directory
A directory is a special type of file which contains entries which are references to other files.
Directory entries are called links. By convention, a directory contains at least two links, .
and .. , referred to as dot and dot-dot respectively. Dot refers to the directory itself and do~
dot refers to its parent directory.
Effective User Id, Effective Group Id, and Access Groups
Access to system resources is governed by three values: the effective user ID, the effective
group ID, and the group access list.
The effective user ID and effective group ID are initially the process's real user ID and real
group ID respectively. Either may be modified through execution oC a se~user-ID or se~
group-ID file (possibly by one its ancestors); see ezecve(2).
The group access list is an additional set of group lD's used only in determining resource
accessibility. Access checks are performed as described below in "File Access Permissions".
File Access Permissions
Every file in the file system has a set oC access permissions. These permissions are used in
determining whether a process may perCorm a requested operation on the file (such as opening a file for writing). Access permissions are established at the time a file is created. They
may be changed at some later time through the chmod(2) call.
File access is broken down according to whether a file may be: read, written, or executed.
Directory files use the execute permission to control ir the directory may be searched.
File access permissions are interpreted by the system as they apply to three different classes
of users: the owner of the file, those users in the file's group, anyone else. Every file has an
independent !Set of access permissions Cor each oC these classes. When an access check is
made, the system decides if permission should be granted by checking the access information applicable to the caller.
Read, write, and execute/search permissions on a file are granted to a process if:
The process's effective user ID is that of the !Super-user.
The process's effective user ID matches the user ID of the owner oC the file and the owner
permissions allow the access.
The process's effective ul5t!r ID does not match the user ID oC the owner of the file, and
either the proce!!'s effective group ID matches the group ID of the file, or the group ID of
the flle is in the process's group access list, and the group permissions allow the access.
Neither the effective user ID nor effective group ID and group access list oC the process
match ,the correepondiDI user ID and group ID oC the file, but the permissions Cor "other
users" allow access.
Otherwise, permission is denied.
File Name
Names consisting of up to 255 characters may be used to name an ordinary file, special file,
or directory.
These characters may be selected Crom the set or all ASCII character excluding 0 (nUll) and
the ASCU code tor I (slash). (The parity bit, bit 8, must be 0.)
Note that it is generally unwise to use *, 7, ( or I as part of file names because of the special

SUD

Release 1.1

Last change: 15 March 1984

5

INTRO(2)

SYSTEM CALLS

INTRO(2)

meaning attached to these characters by the shell.
Parent Process ID
A new process is created by a currently active process; see /ork(2). The parent process ID ot
a process is the process ID of its creator.
Path Name
A path name is a null-terminated character string starting with an optional slash (I), followed by zero or more directory names separated by slashes, optionally followed by a file
name. The total length of a path name must be less than {PATHNAME_MAX} characters.
It a path name begins with a slash, the path search begins at the root directory. Otherwise,
the search begins from the current working directory. A slash by itself names the root
directory. A null path name refers to the current directory.
Process Group ID
Each active process is a member of a process group that is identified by a positive integer
called the process group ID. This is the process ID of the group leader. This grouping permits the signalling of related processes (see killpg(2)) and the job control mechanisms ot
c8h(I).
Process ID
Each active process in the system is uniquely identified by a positive integer called a process
ID. The range of this ID is from 0 to 30000.
Real User ID and Real Group ID
Each user on the system is identified by a positive integer termed the real user ID.
Each user is also a member of one or more groups. One of these groups is distinguished from
others and used in implementing accounting facilities. The positive integer corresponding to
this distinguished group is termed the real group ID.
All processes have a real user ID and real group ID. These are initialized from the
equivalent attributes of the process which created it.
Root Directory and Current Working Directory
Eachproces8 has associated with it a concept of a root directory and a current working
directory for the purpose of resolving path name searches. A process's root directory need
not be the root directory of the root flle system.
Sockets and Address Families
A socket is an endpoint for communication between processes. Each socket h88 queues for
sending and receiving data.
Sockets are typed according to their communications properties. These properties include
whether messages sent and received at a socket require the name of the partner, whether
communication is reliable, the format used in naming message recipients, etc.
Each instance of the system supports some collection of socket types; consult 8ocket(2) for
more information about the types available and their properties.
Each instance of the system supports some number of sets of communications protocols.
Each protocol eet supports addresses of a certain format. An Address Family is the set of
addresses for a specific group of protocols. Each socket has an address ChOseD trom the
address family in which the socket was created.
Special Processes
The processes with a process ID's of 0, 1, and 2 are special. Process 0 is the scheduler. Process 1 is the initialization process inil, and is the ancestor of every other process in the system. It is used to control the process structure. Process 2 is the paging daemon.
Super-user
A process is recognized as a 8uper·U8er process and is granted special privileges if its

6

Last change: 15 March 1984

Sun Release 1.1

SYSTEM CALLS

INTRO(2)

effective user ID is

INTRO(2)

o.

Tty Group ID
Each active process can be a member of a terminal group that is identified by a positive
integer called the tty group ID. This grouping is used to arbitrate between multiple jobs
contending for the same terminal; see c8h(1), and ttll(4).
SEE ALSO
intro(3), perror(3)

Sun Release 1.1

Last change: 15 March 1984

7

SYSTEM CALLS

ACCEPT(2) /

ACCEPT(2)

NAME
accept - accept a connection on a socket
SYNOPSIS
#lnelude <.y./type••h>
#lnelude <.Y./lIOcket.h>

==

a..
aeeept(., addr, addrlen)
lnt n., ••
• truct .oekaddr *addr.
lnt *addrlen.
DESCRIPTION

The argument I is a socket which has been created with locket(2), bound to an address with
hind(2), and is listening for connections after a listen(2). Accept extracts the first connection on
the queue of pending connections, creates a new socket with the same properties of I and allocates
a new file descriptor, nl, for the socket. If no pending connections are present on the queue, and
the socket is not marked as non-blocking, tJccept blocks the caller until a connection is present. If
the socket is marked non-blocking and no pending connections are present on the queue, tJccept
returns an error as described below. The accepted socket, n8, is used to read and write data to
and rrom the socket which connected to this one; it is not used to accept more connections. The
original socket 8 remains open for accepting further connections.
Tpe argument addr is- a result parameter which is filled in with the address or the connecting
e~tity, aa known to the communications layer. The exact format of the tJddr parameter is deterD,tned by the domain in which the communication is occurring. The tJddrlen is a value-result
parameter; it should initially contain the amount of space pointed to by tJddr; on return it will
contain the actual length (in bytes) of the address returned. This call is used with connectionbaaed socket types, currently with SOCK_STREAM.
It is possible to lelect(2) a socket for the purposes or doing an tJccr.p! by selecting it for read.
RETURN VALUE!

The call returns -1 o~ error. If it succeeds it returns a non-negative integer which is a descriptor
for the actt:t~ted socket.
ERRORS

The tJccept will fail if:
(EBADFJ
[ENOTSOCK)

The descriptor is invalid.

(EOPNOTSUPP]

The referenced socket is Dot of type SOCK_STREAM.

[EFAULT)

The addr parameter is not in a writable part of the user address space.

[EWOULDBLOCK)

The socket is marked non-blocking and no connections are present to be
accepted.

The descriptor references a file, not a socket.

SEE ALSO

bind(2), connect{2}, Iisten(2), select(2), socket(2)

8

Last change: 29 August 1983

Sun Release 1.1

SYSTEM CALLS

ACCESS(2)

ACCESS ( 2)

NAME
access - determine accessibility or file
SYNOPSJS

*lnclude 
#define R_OK
4
#define W _OK
2
#define X_OK
1
#define F _OK
0

,.
,.
,.
,.

test
test
test
test

Cor read permission .,
Cor write permission .,
Cor execute (search) permission .,
Cor presence ot file .,

accessible = access(path, mode)
int accessible;
char *path;
int mode;
DESCRIPTION
Acce88 checks the given file ptJth tor accessibility according to mode, which is an inclusive or or
the bits R_OK, W_OK and X_OK. Specitying mode as F _OK (i.e. 0) tests whether the directories leading to the file can be searched and the file exists.

The real user ID and the group access list (including the real group ID) are used in veritying permission, so this call is usetul to set-UID programs.
Notice that only acceSff bits are checked. A directory may be indicated as writable by tJccess, but
an attempt to open it tor writing will tail (although files may be created there); a file may look
executable, but ezecve will tail unless it is in proper format.
RETURN VALUE
It ptJth cannot be found or if any of the desired access modes would not be granted, then a -1
value is returned; otherwise a 0 value is returned.
ERRORS
Access to the file is denied if one or more of the Collowing are true:

(ENOTDm)

A component of the path prefix is not a directory.

IENOENT)

The argument path name was too long.

(ENOENT)

Read, write, or execute (search) permission is requested tor a null path name or
the named file does not exist.

(EPERM)

The argument contains a byte with the high-order bit set.

(ELOOP)

Too many symbolic links were encountered in translating the pathname.

(EROFS)

Write access is requested tor a file on a read-only file system.

(ETXTBSY)

Write access is requested tor a pure procedure (shared text) file that is being executed.

(EACCES)

Permi88ion bits or the file mode do not permit the requested access; or search
permission is denied on a component of the path prefix. The owner or a file has
permission checked with respect to the !lowner" read, write, and execute mode
bits, members of the file's group other than the owner have permission checked
with respect to the !lgroup" mode bits, and all others have permissions checked
with respect to the "other" mode bits.

(EFAULTJ

PtJth points outside the process's allocated address space.

SEE ALSO
chmod(2), stat(2)

Sun Release 1.1

Last change: 2 July 1983

9

SYSTEM CALLS

ACCT(2)

ACCT(2)

NAME

acct - turn accounting on or off
SYNOPSIS

aeet(flle)
ehar *flleJ
DESCRIPTION

The system is prepared to write a record in an accounting JUe tor each process as it terminates.
This call, with a null-terminated string naming an existing file as argument, turns on accounting;
records tor each terminating process are appended to file. An argument ot 0 causes accounting to
be turned off.
The accounting flle tormat is given in accl{S).
This call is permitted only to the super-user.
NOTES

Accounting is automatically disabled wbeD the flle system the accounting file resides on runs out
ot space; it is enabled when space once again becomes available.
RETURN VALUE
On error -1 is returned. The file must exist and the call may be exercised only by the super-user.

It is erroneous to try to turn on accounting when it is already on.
ERRORS
Acct will fail if one of the following is true:

(EPERM]

The caller is not the super-user.

lEPERM]
lENOTDm]

The pathname contains a character with the high-order bit set.
A component ot the path prefix is not a directory.

(ENOENT]

The named file does not exist.

lEISDIR)
(EROFS]

The named file is a directory.

lEFAULT]
(ELOOP]

File points outside the process's allocated address space.
Too many symbolic links were encountered in translating the pathname.
The file is a character or block special file.

The named file resides on a read-only file system.

(EACCES]
SEE ALSO

1

acct(5), sa(8)

BUGS
No accounting is produced for programs running when a crash occurs. In particular nonterminating programs are never accounted for.

10

Last change: 13 February 1983

Sun Release 1.1

BIND(2)

SYSTEM CALLS

BIND ( 2)

NAME
bind - bind a name to a socket

SYNOPSIS

:fflnclude 
1¥lnclude 
bJnd(a, name, namelen)

lfft
-.
_,ruct _ockaddr *name.
"tt namelen.
DESCRlftTION
Bind assigns a name to an unnamed socket. When a socket is created with 8ocket(2) it exists in a
name space (address family) but has no name assigned. Bind requests the name, be assigned to
the socket.
NOTES
Bindinl a name in the UNIX domain creates a socket in the file system which must be deleted by
the caller when it is no longer needed (using unlink(2».
The rules used in na.me binding vary between communication domains. Consult the manual
entries in section 4 for detailed inrormation.

RETURN VALUE
It the bind is successful, a 0 value is returned. A return value of -1 indicates an error, which is
rurther specified in the global errnD.
ERRORS
The bind call will fail if:
(EBADF)

S is not a valid descriptor.

(ENOTSOCK)

Sis not a socket.

(EADDRNOTAVAIL) The specified address is not available from the local machine.
(EADDRINUSE)

The specified addre88 is already in use.

(EINVAL)

The socket is already bound to an address.

(EACCES)

The requested address is protected, and the current user has inadequate
permission to access it.

(EFAUL T)

The ntlme parameter is not in a valid part of the user address space.

SEE ALSO
connect(2), listen(2), socket(2), getsockname(2)

BUGS
The file created is a side-elect of the current implementation and will not be created in future
versions of the UNIX ipc domain.

SUD

Releas9 1.1
ill
.1

~

I'

Last change: 4 January 1984

11

BRK(2)

SYSTEM CALLS

BRK(2)

NAME

brk, sbrk - change data segment size
SYNOPSIS

eaddr_t brk(addr)
eaddr_t addr,
eaddr_t 8brk(mer)

mt mer,

DESCRIPTION
nrk sets the system's idea of the lowest data segment location not used by the program (called the

break) to addr (rounded up to the next multiple of the system's page size). Locations greater
than addr and below the stack pointer are not in the address space and will thu8 cause a memory
violation if accf'.esed.
In the alternate function sbrk, irter more bytes are added to the program'e data space and a
pointer to the start of the new area is returned.
When a program begins execution via ezecve the break ie set at the highest location defined by
the program and data storage areas. Ordinarily, therefore, only programs with growing data
areas need to use sbr1c.
The getrlimit(2) system call may be used to determine the maximum permissible size of the data
segment; it will not be possible to set the break beyond the rlim_maz value returned from a call
to getrlimit, e.g. "etext + rlp-+rlim_max." (See end(3) for the definition of etezt.)
RETURN VALUE
Zero is returned if the 6r1c could be set; -1 if the program requests more memory than the system
limit. Sbrk returns -1 if the break could not be set.
ERRORS
Sbrk will fail and no additional memory will be allocated it one 01 the following are true:

(ENO:MEM)

The limit, as set by setrlimit(2), was exceeded.

[ENO:MEM)

The maximum possible size of a data segment (compiled into the system) was
exceeded.

(ENO:MEM)

Insu1ficient space existed ill the swap area to support the expansion.

SEE ALSO

execve(2), getrlimit(2), malloc(3), end(3)
BUGS

Setting the break may fail due to a temporary lack ot swap space. It is not possible to distinguish
this from a failure caused by exceeding the maximum size of the data segment without consulting

getrlimit.

12

Last change: 29 August 1983

Sun Release 1.1

· CHDm(2)

SYSTEM CALLS

CHDm(2)

NAME

chdir - change current working directory
SYNOPSIS
chdJr(path)
char *pathJ
DESCRIPTION
Path is the pathname of a directory. CAdir causes this directory to become the current working
directory, the starting point for path names not beginning with "/".

In order for a directory to become the current directory, a process must have execute (search)
access to the directory.
RETUR~

VALUE
Upon 8uccessful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and
e~rnD is set to indicate the error.

ERRORS'
Chdir will fail and the current working directory will be unchanged if one or more of the following
are true:

(ENOTDIR)
[ENOENT)
(ENOENT)

A component of the pathname is not a directory.

(EPERM)

The argument contains a byte with the high-order bit set.

(EACCES)

Search permissioD is denied for any component of the path name.

The named directory does not exist.
The argument pa.th name was too long.

(FfAULT)

Paeh points outside the process's allocated address space.

(ELOOP)

Too many symbolic links were encountered in translating the pathname.

SEE ALSO
chroot(2)

SUD Release 1.1

Last change: 2 July 1983

13

SYSTEM CALLS

CHMOD(2)

CHMOD(2)

NAME

chmod,. fchmod - change mode of file
SYNOPSIS
cbmod(patb, mode)
char ·path;
tnt mode;

fcbmod(fd, mode)
tnt fd, mode;
DESCRIPTION
The file whose name is given by path or referenced by the descriptor Id has its mode changed to
mode. Modes are constructed by or'ing together some combination of the following:

04000 set user ID on execution
02000 set group ID on execution
01000 save text im~ge after execution
00400 read by owner
00200 write by owner
00100 execute (search on directory) by owner
00070 read, write, execute (search) by group
00007 read, write, execute (search) by others
If an executable file is set up for sharinl (this is the default) then mode 1000 prevents the system
from abandoning the swap-space image of the program-text portion of the file when its last user
terminates. Ability to set this bit is restricted to the super-user.

Only the owner of a file (or the super-user) may change the mode.
Writing or changing the owner of a file turns off the set-user-id and set-group-id bits. This makes
the system somewhat more secure by protecting set-user-id (set-group-id) files from remaining
set-user-id (set-group-id) if they are modified, at the expense of a degree of compatibility.
RETURN VALUE
Upon successful completiOll, a value of 0 is returned.. Otherwise, a value of -1 is returned and
errno is set to indicate the error.
ERRORS
Chmod will fail and the file mode will be unchanged if:

IEPERMj

The azgument contains a byte with the high-order bit set.

(ENOTDm)

A component of the path prefix is not a directory.

IENOENT)

The pathname was too lonl.

(ENOENT)

The named file does not exist.

(EACCES)

Search permission is denied on a component 01 the path prefix.

IEPERMj

The effective user ID does not match the owner 01 the file and the effective user
ID is not the super-user.

(EROFS)

The named file resides on a read-only file system.

(EFAUL T)

Path point, outside the process's allocated address space.

[ELOOP)

Too many symbolic links were encountered in translating the pathname.

Fchmod will fail if:

14

[EBADFJ

The descriptor is not valid.

(EINVAL)
(EROFS)

Fd refers to a socket, not to a file.

The file resides on a read-only file system.

Last change: 2 July 1983

SUD

Release 1.1

CHMOD(2)

.

SYSTEM CALLS

CHMOD(2)

SEE ALSO

open(2), chown(2)

Sun Release 1.1

Last change: 2 July 1983

15

SYSTEM CALLS

CHOWN(2)

CHOWN(2)

NAME

chown, fchown - change owner and group of a file
SYNOPSIS

ehown(path, ownel"p lP'oup)
ehal' *path;
tnt ownel', gl'oup;
tebown(td, ownel', group)
tnt td, ownel', gl'oup;
DESCRIPTION

The file which is named by path or referenced by Id has its owner and group changed as specified.
Only the super-user may execute this call, because if users were able to give tiles away, they could
defeat the file-space accounting procedures.
Chown clears the set-user-id and set-group-id bits on the file to prevent accidental creation of setuser-id and set-group-id programs owned by the super-user.
Fchown is particularly useful when used in conjunction with the file locking primitives (see
ftock(2)).
Only one of the owner and group id's may be set by specifying the other as -1.
RETURN VALUE

Zero is returned if the operation was successful; -1 Is returned if an error occurs, with a more
specific error code beiDg placed in the global variable errno.
ERRORS

Chown will fail and the file will be unchanged if:
(EINVALI
(ENOTDm)

The argument path does not refer to a file.
A component of the path prefix is not a directory.

(ENOENT)

The argument pathname is too long.

(EPERM)

The argument c~ntains a byte with the high-order bit set.

(ENOENT)

The named file does not exist.

(EACCES)

Search permission is denied on a component of the path prefix.

(EPERM)

The elective user ID does not match the owner of the file and the effective user
ID is not the super-user.

(EROFS)

The named file resides on a read-only file system.

(EFAUL T)

Path points outside the process's allocated address space.

(ELOOP)
Too many symbolic links were encountered in translating the pathname.
Fchown will faii if:
(EBADF)
(EINVAL)

Fd does not refer to a valid descriptor.
Fd refers to a socket, not a file.

SEE ALSO

chmod(2), ftock(2)

16

Last change: 29 August 1983

Sun Release 1.1

SYSTEM CALLS

CHROOT(2)

CHROOT(2)

NAME
chroot - change root directory
SYNOPSIS

cbroot(dlrname)
char *dlrnamel
DESCRIPTION

DirntJme is the address of the pathname of a directory, terminated by a null byte. Chroot causes
tbis directory to become the root directory, the starting point for path names beginning with "/".
This root directory setting is inherited across ezecve(2) and by all children of this process created
with lork(2) calls.
In order for a directory to become the root directory a process must have execute (search) access
to the directory.
This call is restricted to the super-user.
RETURN VALUE

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and
errno is set to indicate an error.
ERRORS

Chroot will fail and the root directory will be unchanged if one or more of the following are true:
(ENOTDffiJ

A component of the path name is not a directory.

(ENOENT)

The pathname was too long.

(EPERM)

The argument contains a byte with the high-order bit set.

(ENOENT)

The named directory does not exist.

(EACCES)

Sear~h

(EFAUL TJ

Path points outside the process's allocated address space.

(ELOOP)

Too many symbolic links were encountered in translating the pathname.

permission is denied for any component of the path name.

SEE ALSO
cbdir(2)

SUD

Release 1.1

Last change: 29 August 1983

17

SYSTEM CALLS

CLOSE(2)

CLOSE(2)

NAME

close - delete a descriptor
SYNOPSIS

close(d)
tnt d;
DESCRIPTION

The cl08e call deletes a descriptor from the per-process object reference table. It this is the last
reference to the underlying. object, then it will be deactivated. For example, on the last close of a
file the current Beek pointer associated with the file is lost; on the last close of a Bocket(2) associated naming information and queued data are discarded; on the last close of a file holding an
advisory lock the lock is released, see jlock(2) for further information.
A close of all of a process's descriptors is automatic on ent, but since there is a limit on the
number of active descriptors per process, cl08e is necessary for programs which deal with many
descriptors.
When a process forks (see /ork(2)), all descriptors for the new child process reference the same
objects as they did in the parent before the fork. It a new process is then to be run using
ezecve(2), the process would normally inherit these descriptors. Most of the descriptors can be
rearranged with dupe(2) or deleted with cl08e before the ezecve is attempted, but if some of these
descriptors will still be needed if the execve faila, it is necessary to arrange for them to be closed
if the execve succeeds. For this reason, the call "fcntt(d, F _SETFD, 1)" is provided which
arranges that a descriptor will be closed after a successful execve; the call "fcntt(d, F _SETFD, 0)"
restores the default, which is to not close the descriptor.

Cl08e unmaps pages mapped through this file descriptor.
RETURN VALUE

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the
global integer variable errno is set to indicate the error.
ERRORS.
O~.p8e

will fail if:

[EBADF)

D is not an active descriptor.

SEE ALSO

accept(2), ftock(2), open(2), pipe(2), socket(2), socketpair(2), execve(2), fcntl(2), mmap(2), munmap(2)

18

Last change: 20 March 1983

Sun Release 1.1

SYSTEM CALLS

CONNECT(2)

CONNECT(2)

NAME

connect - initiate a connection on a socket
SYNOPSIS
=ll=tnelude 
#lnelu.de 

eonneet(s, name, namelen)
lnt sa
.truet soekaddr *nameJ
tnt namelenJ
DESCRIPTION
The parameter 8 is a. socket. If it is of type SOCK_DGRAM, then this call permanently specifies
the peer to which datagrams are to be sent; it it is ot type SOCK_STREAM, then this call
attempts to make a connection to another socket. The other socket is specified by name which is
an address in the communications space of the socket. Each communications space interprets the
nome parameter in its own way.
RETURN VALUE
It the connection or binding succeeds, then 0 is retumed. Otherwise a -1 is returned, and a more
specific error code is stored in errno.
ERRORS
The call tails if:

(EBADFJ

S is not a valid descriptor.

(ENOTSOCKJ

S is a descriptor for a file, not a socket.

(EADDRNOTAVAIL J The specified address is not available on this machine.
[EAFNOSUPPOR TJ Addresses in the specified address tamily cannot be used with this socket.
[EISCO NNJ

The socket is already connected.

(ETIMEDOUT)

Connection establishment timed out without establishing a connection.

LECONNREFUSED) The attempt to connect was forcefully rejected.
[ENETUNREACH)

The network isn't reachable from this host.

[EADDRINUSE]

The address is already in use.

(EFAUL TJ
[EWOULDBLOCK)

The name parameter specifies an area outside the process address space.
The socket is non-blocking and the and the connection cannot be completed immediately. It is possible to select(2) the socket while it is connecting by selecting it tor writing.

SEE ALSO
accept(2), select(2), 8octet(2), get80ckname(2)

Sun Release 1.1

Last change: 7 July, 1983

19

CREAT(2)

SYSTEM CALLS

CREAT(2)

NAME

creat - create a new file
SYNOPSIS

creat(name, mode)
char *namel
DESCRIPTION

Thla Interface la obaoleted by open(Z).
Creat creates a new file or prepares to rewrite an existing file called n4me, given as the address of
a null-terminated string. If the file did not exist, it is given mode mode, as modified by the
process's mode mask (see um48k(2)). Also see chmod(2) ror the construction of the mode argument.
If the file did exist, its mode and owner remain unchanged but it is truncated to 0 length.
The file is also opened ror writing, and its file descriptor is returned.
NOTES

The mode given is arbitrary; it need not allow writing. This feature has been used in the past by
programs to construct a simple exclusive locking mechanism. It is replaced by the 0 _EXCL open
Dt9de, or jlock(2) racilitity.
RETURN VALUE
The value -1 is returned if an error occurs. Otherwise, the call returns a non-negative descriptor
which only permits writing.
ERRORS

Cre4t will fail and the file will not be created or truncated if one of the following occur:
[EPERM:)

The argument contains a byte with the high-order bit set.

(ENOTDm)

A component of the path prefix is not a directory.

(EACCES)

A needed directory does not have search permission.

(EACCES)

The file does not exist and the directory in which it is to be created is not writable.,

(EACCES)

The file exists, but it is unwritable.

(EISDIR)

The file is a directory.

(EMFILEJ

There are already too many files open.

[EROFS)

The named file resides on a read-only file system.

[ENXIO)

The file is a character special or block special file, and the associated device does
not exist.

(ETXTBSyl

The file is a pure procedure (shared text) file that is being executed.

(EF AUL T)

N4me points outside the process's allocated address space.

(ELOOP)

Too many symbolic links were encou~tered in translating thepathname.

[EOPNOTSUPP)
The file was a socket (not currently implemented).
SEE ALSO
open(2), write(2), close(2), chmod(2), umask(2)

20

Last change: 2 July 1983

Sun Release 1.1

DUP(2)

SYSTEM CALLS

DUP( 2)

NAME
dup, dup2 - duplicate a descriptor
SYNOPSIS
newd
dupeoldd)
tnt nawd, oldd.

==

dupl(oldd, newd)
Int oldd, newd.
DESCRIPTION
Dup duplicates an existing object descriptor. The argument oldd is a small non-negative integer
index in the per-process descriptor table. The value must be less than the size of the table, which
is returned by getdtable8ize(2). The new descriptor newd returned by the call is the lowest numbered descriptor which is not currently in use by the process.
The object referenced by the descriptor does not distinguish between references using oldd and
newd in any way. Thus if newd and oldd are duplicate references to an open file, read(2), write(2)
and 18eek(2) calls all move a single pointer into the file. If a separate pointer into the file is
desired, a different object reference to the file must be obtained by issuing an additional open(2)
call.
In the second form of the call, the value of newd desired is specified. If this descriptor is already
in use, the descriptor is first deallocated 38 if a clo8e(2) call had been done first.
RETURN VALUE
The value -1 is returned if an error occurs in either call. The external variable errno indicates
the cauee of the error.
ERRORS

Dup and dupe fail if:

(EBADFJ
IEMFILE)

Oldd or newd is not a valid active descriptor
Too many descriptors are active.

SEE ALSO
accept(2), open(2), close(2), pipe(2), socket(2), socketpair(2), getdtablesize(2)

SUD

Release 1.1

Last change: 12 February 1983

21

SYSTEM CALLS

EXECVE(2)

EXECVE(2)

NAME

execve - execute a file
SYNOPSIS

execve(name, argv, envp)
char *name, *uIVD, *envpDJ
DESCRIPTION

Execve transforms the calling process into a new process. The new process is constructed from an
ordinary file called the new procell jile. This file is either an executable object file, or a file of
data for an interpreter. An executable object file consists of an identifying header, followed by
pages of data representing the initial program (text) and initialized data pages. Additional pages
may be specified by the header to be initialize with zero data. See G.out(5).
An interpreter file begins with a line 01 the form H:f/:! interpreter"; When an interpreter file is
execve 'd, the system execve's the specified interpreter, giving it the name of the originally exec'd
file as an argument, shifting over the rest of the original arguments.
There can be no return from a successful ezecve because the calling core image is lost. This is the
mechanism whereby different process images become active.
The argumelil Grgv is an array of character pointers to null-terminated character strings. These
strings constitute the argument list to be made available to the new process. By convention, at
least one argument must be present in this array, and the first element of this array should be the
name of the executed program (i.e. the last component of nGme).
The argument envp is also an array of character pointers to null-terminated strings. These strings
pass information to the new process which are not directly arguments to the command, see
environ(5).
Descriptors open in the calling process remain open in the new process, except for those for which
the close-on-exec flag is set; see clo,e(2). Descriptors which remain open are unaffected by execve.
Ignored signals remain ignored across an ezecve, but signals that are caught are reset to their
default values. The signal stack is reset to be undefined; see .ngvec(2) for more information.
Each process has a real user ID and group ID and an effective user ID and group ID. The reGilD
identifies the person using the system; the effective ID determines his access privileges. Execve
changes the effective user and group ID to the owner of the executed file if the file has the "setuser-ID" or "set-group-ID" modes. The reGl user ID is not affected.
The new proc~ss also inherits the following attributes from the calling process:
proeerm ID
see getpid(2)
parent process ID
see getppid(2)
process group ID
see getpgrp(2)
access groups
see getgroup,(2)
working directory
see chdir(2)
root directory
see chroot(2)
control terminal
see ",(4)
resource usages
see getru8Gge(2)
interval timers
see getitimer(2)
resource limits
see getrlimit(2)
file mode mask
see umG8k(2)
signal mask
see 8ilvec(2)
When the executed program begins, it is called as lollows:
main(argc, argv, envp)
int argc;
char **argv, ·*envp;

22

Last change: 2 July 1983

Sun Release 1.1

SYSTEM CALLS

EXECVE(2)

EXECVE(2)

where arlc is the number of elements in arg" (the "arg count") and arg" is the array of character
pointers to the arguments themselves.
En", is a pointer to an array of strings that constitute the environment of the process. A pointer
to this array is also stored in the global variable "environ". Each string consists of a name, an
"==", and a null-terminated value. The array of pointers is terminated by a null pointer. The
shell Ih(l) passes an environment entry for each global shell variable defined when the program is
called. See environ(5) for some conventionally used names.
RETURN VALUE
It ezeclIe returns to the calling process an error has occurred; the return value will be -1 and the
global variable errno will contain an error code.
ERRORS

EzeclIe will fail
(ENOENT)
(ENOTDm)
(EACCES)

and return to the calling process if one or more of the following are true:
One or more components of the new process file's path name do not exist.
A component or the new process file is not a directory.
Search permission is denied for a directory listed in the new process file's path
prefix.

IEACCES)
(EACCES)

The new process file is not an ordinary file.

(ENOEXEC)

The new' process file has the appropriate access permission, but has an invalid
magic number in its header.

[ETXTBSY)

The new process file is a pure procedure (shared text) file that is currently open
for writing or reading by some process.

[ENOMEM)

The new process requires more virtual memory than is allowed by the imposed
maximum (getrlimit(2)).

[E2BIG)

The new process ,file mode denies execute permission.

The number or bytes in the new process's argument list is larger than the
limit of {ARG_MAX} bytes.

systelli~imposed

[EFAULTJ
[EFAULT)

The new process file is not as long as indicated by the size values in its header.

Pa'h, arlll, or en", point to an illegal address.

CAVEATS
It a program is letuid to , non-super-user, but is executed when the real uitl is "root", then the

program haa the powers of a super-user as well.
SEE ALSO

exit(2), fork(2), execl(3); environ(5)

SUD

Rele,. 1.1

Last change: 2 July 1983

23

EXIT (2)

SYSTEM CALLS

EXlT(2)

NAME

_exit - terminate a process
SYNOPSIS

_axlt(status)
tnt status,
DESCRIPTION
~fzit terminates a process with the followina conaequences:

All of the descriptors open in the callina prace. are elosed.
If the parent process of the callina process is executinl a wait or is interested in the SIGCHLD
sianai, then it is notified of the callina process's termination and the low-order eight bits of BtllluB
are made available to it; see wait(2). The low-order 8 bits of ,tatu, are available to the parent
process.

The parent proceM It> ot all of the callinl process's existinl child processes are also set to 1. This
means that the initialization process (see intro(2)) inherits each of these processes as well.
Most C programs will call the library routine ezit(3) which performs e1eanup actions in the standard i/o library before caUini _ezil.
RETURN VALUE
This call never returns.
SEE ALSO
fork(2), wait(2), exit(3)

24

Last change: 29 August 1983

Sun Release 1.1

SYSTEM CALLS

FCNTL(2)

FCNTL(2)

NAME
fcntl - file control
SYNOPSIS

#lnclude 
rell
fcntl(fd, cmd, ars)
Int res;
tnt I'd, cmc:l, ars;

==

DESCRIPTION
Fcntl provides for control over descriptors. The argument Id is a descriptor to be operated on by
cmd as follows:

Return a new descriptor as follows:
Lowest numbered available descriptor greater than or equal to argo
Same object references as the original descriptor.
New descriptor shares the same file pointer if the object was a file.
Same access mode (read, write or read/write).
Same flIe status fiags(i.e., both file descriptors share the same file status flags).
The close-on-exec flag associated with the new file descriptor is set to remain
open acrOS8 ezecve(2) system calls.
F_GETFD

Get the close-on-exec flag associated with the file descriptor Id. If the low-order
bit is 0, the file will remain open across exec, otherwise the file will be closed
upon execution of exec.

F_SETFD

Set the close-on-exec flag associated with Id to the low order bit of arg (0 or 1 as.
above).

F_GETFL

Get descriptor status flags, see lent/(S) for their definitions.

F_SETFL

Set descriptor status flags, see lent/(5) for their definitions.

F _GETOWN

Get the process ID or process group currently receiving SIGIO and SIGURG signals; process groups are returned as negative values.

F _SETOWN

Set the process Of process group to receive SIGIO and SIGURG signals; process
groups are specified by supplying arg as negative, otherwise arg is interpreted as
a process ID.

The SIOIO facilities are enabled by setting the FASYNC flag with F _SETFL.
RETURN VALUE
Upon successful completion, the value returned depends on cmd as follows:
F .J)UPFH
F _GETFD
F _GETFt
F _GETOWN
other

A new file descriptor.
Value 01 flag (only the low-order bit is defined).
Value of flap.
Value 01 file descriptor owner.
Value other than -l.

Otherwise, a value 01 -1 is returned and errnD is set to indicate the error.
ERRORS

Fcntl will fail if one or more of the following are true:
(EBADFJ

Filtlel is not a valid open file descriptor.

(EMF IL E)

Cmtl is F _DUPFD and the maximum allowed number of file descriptors are
currently open.

Sun Release 1.1

Last change: 29 August 1983

25

FCNTL{2)

(EINVALJ

SYSTEM CALLS

FCNTL(2)

Cmd is F _DUPFD and org is negative or greater the maximum allowable Dumber
(see getdtobleaize(2)).

SEE ALSO

close(2), execve(2), getdtablesize(2), open(2), sigvec(2)

26

Last change: 29 August 1983

Sun Release 1.1

FLOCK(2)

SYSTEM CALLS

FLOCK( 2)

NAME
flock - apply or remove an advisory lock on an open file
SYNOPSIS
#lnelude 

#deftne
#deftne
#deftne
#define

LOCK_SH
1
LOCK_EX
2
LOCK_NB"
LOCK_UN
8

gock(fd, operation)
fd, operation;

'''***
'*

*'*'

shared lock
exclusive lock
don't block when locking
unlock

*'

*'

.pte

DESCRIPTION
Flock applies or removes an advi8orlliock on the file associa.ted with the file descriptor Id. A lock
is applied by specifying an operation parameter which is the inclusive or of LOCK_SH or
LOCK_EX and, possibly, LOCK_NB. To unlock an existing lock operation should be
LOCK_UN.
Advisory locks allow cooperating processes to perform consistent operations on files, but do not
guarantee consistency (i.e. processes may still access files without using advisory locks possibly
resulting in inconsistencies).
The locking mechanism allows two types of locks: 8hared locks and ezclU8ive locks. At any time
multiple shared locks may be applied to a file, but at no time are multiple exclusive, or both
shared and exclusive, locks allowed simultaneously on a file.
A shared lock may be upgraded to an exclusive lock, and vice versa, simply by specirying the

appropriate lock type; this results in the previous lock being released and the new lock applied
(possibly after other processes have g,.ined and released the lock).

Requesting a lock on an object which is already locked normally causes the caller to blocked until
the lock may be acquired. If LOCK_NB is included in opera.tion, then this will not happen;
instead the call will (ail and the error EWOULDBLOCK will be returned.
NOTES
Locks a.re on files, not file descriptofSo That is, fite descriptors duplicated through dup(2) or
lork(2) do not result 'in multiple instances of a lock, but rather multiple references to a single
lock. If a process holding a lock on a file rorks and the child explicitly unlocks the file, the parent
will lose its lock.
Processes blocked awa.iting a lock may be awakened by signals.
RETURN.VALUE
Zero is returned ir the operation was successful; on an error a -1 is returned and an error code is
left in the global location errno.
ERRORS
The flock call rails if:
(EWOULDBLOCK)

The file is locked and the LOCK_NB option was specified.

(EBADFJ

,The argument Id is an invalid descriptor.

(EINVALj

The argument 14 refers to an object other than a. file.

SEE ALSO
open(2), close(2), dup(2~ execve(2), rork(2)

Sun Release 1.1

Last change: 27 July 1983

27

SYSTEM CALLS

FORK(2)

FORK(2)

NAME

fork - create a new process
SYNOPSIS

pld

== forkO

tnt pld.

DESCRIPTION

Fork causes creation of a new process. The new procesa (child process) is an exact copy or the
calling process except tor the following:
The child process has a unique process ID.
The child process has a different parent process ID (i.e., the process ID of the parent process).
The child process has its own copy of the parent's descriptors. These descriptors reference
the same underlying objects, so that, for instance, file pointers in file objects are shared
between the child and the parent, so that a 18eek(2) on a descriptor in the child process can
alrect a subsequent read or write by the parent. This descriptor copying is also used by the
shell to establish standard input and output ror newly created processes as well as to set up
pipes.
The child processes resource utilizations are set to 0; see 8etrlimit(2).
RETURN VALUE

Upon successrul completion, fork returns a value or 0 to the child process and returns the process
ID of the child process to the parent process. Otherwise, a value or -1 is returned to the parent
process, no child process is created, and the global variable errno is set to indicate the error.
ERRORS

Fork will fail and no child process will be created ir one or more or the rollowing are true:
[EAGAINJ

The system-imposed limit {PROC_MAX} on the total number or processes
under execution would be exceeded.

[EAGAINJ

The system-imposed limit {KID_MAX} on the total number of processes under
execution by a single user would be exceeded.

SEE ALSO

execve(2), wait(2)

28

Last change: 12 February 1983

Sun Release 1.1

FSYNC(2)

SYSTEM CALLS

FSYNC(2)

NAME

fsync - synchronize a file's in-core state with that on disk
SYNOPSIS

f.;yne(fd)
lnt fd;
DESCRIPTION

FeJjne causes all modified data and attributes of fd to be moved to a permanent storage device: all
in-core modified copies of buffers Cor the associated file have been written to a disk when the call
returns. (Note that this is different than BJjne(2) which schedules disk-io for all files (as though an
feJjne had been done on all files) but returns before the i/o completes.)
F'Jjne should be used by programs which require a file to be in a known state; for example in
buildinl a simple transaction facility.
RETURN VALUE
A 0 value is returned on success. A -1 value indicates an error.
ERRORS

The feJjne tails it:
J~aADF)
[~lNVAL)

Fd is not a valid descriptor.
Fd refers to a socket, not to a file.

SEE ALSO

sync(2), sync(8), cron(8)
BUGS

The current implementation

Sun Release 1.1

ot this call is expensive tor large files.

Last change: 29 August 1983

29

GETDTABLESIZE ( 2 )

SYSTEM CALLS

GETDTABLESIZE ( 2)

NAME

getdtablesize - get descriptor table size
SYNOPSIS

==

nd.
setdtableltse()
lnt ndl'
DESCRIPTION

Each process has a fixed size descriptor table which is guaranteed to have at least 20 slots. The
entries in the descriptor table are numbered with small integers starting at o. The call getdttJ,ble8ize returns the size or this table.
SEE ALSO

close(2), dup(2), open(2)

30

Last change: 12 February 1983

Sun Release 1.1

GETGID(2)

SYSTEM CALLS

GETGID(2}

NAME
getgid, getegid - get group identity
SYNOPSIS
Bid
setgldO
lnt gld.

==

egld == setes1d()
Int egld,
DESCRIPTION
Getgid returns the real group ID of the current process, getegid the efJective group ID.
The real group ID is specified at login time.
The effective group ID is more transient, and determines additional access permission during execution or a "set-gloup-ID" process, and it is for such processes that getgid is most useful.
SEE ALSO
getuid(2), setregid(2), setgid(3C)

SUD

Release 1.1

Last change: 12 February 1983

31

SYSTEM CALLS

GETGROUPS (2)

GETGROUPS(2)

NAME

getgroups - get group access list
SYNOPSIS

#lnclude 
ngroup. = getgroupB(n, &gldBet)
lnt ngroup.,
tnt n, *gld.et,
DESCRIPTION
Getgroup8 gets the current group access list of the user process and stores it in the array gid8et.
The parameter n indicates the number of entries which may be placed in gid8et and getgroup8
returns the actual number of entries placed in the gid8et array. No more than NGRPS, as defined
in < 81)8/ param.h >, will ever be returned.

RETURN VALUE

A return value or greater than zero indicates the number of entries placed in the gid8et array. A
return value or -1 indicates that an error occurred, and the error code is stored in the global variable errno.
ERRORS

The possible errors Cor getgroup are:
(EF AUL TJ

The arguments ngroup8 or gid8et specify invalid addresses.

SEEALSP

se\.groups(2), initgroups(3)

32

Last change: 13 March 1984

Sun Release 1.1

GETHOSTID ( 2)

SYSTEM CALLS

GETHOSTID ( 2 )

NAME
gethostid - get unique identifier of current host
SYNOPSIS

hostld

== sethostld()

tnt hoatld;

DESCRIPTION
GcthOBtid returns the 32-bit identifier for the current host, which is unique across all hosts.
SEE ALSO
hostid(l)

SUD

Release 1.1

Last change: 12 February 1983

33

SYSTEM CALLS

GETHOSTNAME ( 2 )

GETHOSTNAME ( 2 )

NAME

gethostname, sethostname - get/set name of current host
SYNOPSIS

gethoatname(name, namelen)
char *nameJ
lot namelenJ
aethoatname(name, namelen)
char *nameJ
lot nameleDI
DESCRIPTION

Getho8tname returns the standard host name tor the current processor, as previously set by
8etho8tname. The parameter namelen specifies the size of the name array. The returned name is
null-terminated unless insufficient space is provided.
,
Sethostname sets the name of the host machine to be name, which has length nameien. This call
is restricted to the super-user and is normally used only when the system is bootstrapped.
RETURN VALUE
If the call succeeds a value or 0 is returned. If the caD faits, then a value or -1 is returned and an
error code is placed int the global location errno.
ERRORS
The fonowing errors may be returned by these calls:

(EF AUL T)

The name or namelen parameter gave an invalid addreS8.

(EPERM)

The caller was not the super-user.

SEE ALSO
gethostid(2)
BUGS

Host names are limited to 255 characters.

34

Last change: 12 February 1983

Sun Release 1.1

SYSTEM CALLS

GETITIMER ( 2)

GETITlMER ( 2 )

NAME

getitimer, setitimer - get/set value or interval timer
SYNOPSIS

#lnelude 
#deftne ITIMER_REAL
0
#deftne ITIMER_VlRTUAL 1
#deftne ITIM:ER_PROF
2

'* real time Intervals *'
'* virtual time Intervals *'
'* uaer and system virtual time *'

Betltlmer(whlch, value)
Int which;
atruct'ltlmerval ·value.
setltlmer(whlch, value, ovalue)

tnt which,
atruc:t ltlmerval *value, *ovalue.
DESCRIPTION
The system provides each process with three interval timers, defined in . The getitimer call returns the current value for the timer specified in which, while the ectitimer call sets
the value of a timer (optionally returning the previous value of the timer).

A timer value is defined by the itimerval structure:
struct itimerval {
struct timeval it_interval;
struct timeval it_value;
};

/* timer interval */
/* current value */

If iCvalue is non-zero, it indicates the time to the next timer expiration. If iCinterval is non-zero,
it specifies a. value to be used in reloading iCvalue when the timer expires. Setting iCvalue to 0
disables a timer. Setting iCinterval to 0 causes a timer to be disabled after its next expiration
(assuming iCvalue is non-zero).
Time values smaller than the resolution 01 the system clock are rounded up to this resolution.
The ITIMER_REAL timer decrements in real time. A SIGALRM signal is delivered when this
timer expires.
The ITIMkR_vmTUAL timer decrements in process virtual time. It runs only when the process
is executing. A SIGVTALRM signal is delivered when it expires.
The ITIMER_PROF timer decrements both in process virtual time and when the system is running on behalf of the process. It is designed to be used by interpreters in statistically profiling the
execution 01 interpreted programs. Each time the ITIMER_PROF timer expires, the SIGPROF
signal is delivered. Because this signal may interrupt in-progress system calls, programs using this
timer must be prepared to restart interrupted system calls.
NOTES

Three macros for manipulating time values are defined in . Timerclear sets a time
value to zero, timerieset tests it a time value is non-zero, and timercmp compares two time values
(beware that >= and. <= do not work with this macro).
RETURN VALUE
II the calls succeed, a. value or 0 is returned. II an error occurs, the value -1 is returned, and a
more precise error code is placed in the global variable errno.
ERRORS'
The possible errors are:

IEFAULTJ

Sun Release 1.1

The value structure specified a bad address.

Last change: 29 August 1983

35

SYSTEM CALLS

GETITlMER( 2 )

[EINVAL)

GETITIMER ( 2 )

A value structure specified a time was too large to be handled.

SEE ALSO

sigvec(2), gettimeoCday(2)

36

Last change: 29 August 1983

Sun Release 1.1

SYSTEM CALLS

GETPAGESIZE ( 2)

GETPAGESIZE ( 2 )

NAME
getpagesize - get system page size
SYNOPSIS
pageslze == getpageslzeO
IDt paleDlze.
DESCRIPTION

Getpagesize returns the number of bytes in a page. Page granularity is the granularity or many or
the memory management calls.
The page size is a ,ystem page size and may not be the same as the underlying hardware page
size.
SEE ALSO
sbrk(2), pagesize(l)

SUD

Release 1.1

Last change: 29 August 1983

37

SYSTEM CALLS

GETPEERNAME ( 2 )

GETPEERNAME(2)

NAME

getpeername - get name of connected peer
SYNOPSIS

getpeername(s, name, name1en)
lnt s,
struet soekaddr *name,
lnt *name1en,
DESCRIPTION

Getpeername returns the name of the peer connected to socket I. The name/en parameter should
be initialized to indicate the amount of space pointed to by name. On return it contains the
actual size of the name returned (in bytes).
DIAGNOSTICS

A 0 is returned if the call succeeds, -1 if it fails.
ERRORS

The call succeeds unless:
(EBADF)

The argument

I

is not a valid descriptor.

[ENOTSOCK)

The argument

I

is a file, not a socket.

[ENOTCONN) The socket is not connected.
Insufficient resources were available in the system to perform the operation.
(ENOBUFS)
(EFAULT)

The name parameter points to memory not in a valid part of the process address
space.

SEE ALSO

bind(2), socket(2), getsockname(2)
BUGS

Names bound to sockets in the UNIX domain are inaccessible; getpeername returns a zero length
name.

38

Last change: 31 October 1983

Sun Release 1.1

GETPGRP(2)

SYSTEM CALLS

GETPGRP(2)

NAME
getpgrp - get process group
SYNOPSIS
PBI"P
letpBI"P(pld)
lnt prlP'
lnt pld.

==

DESCRIPTION

The proce88 group 01 the specified process is returned by getpgrp. If pid is zero, then the call
applies to the current process.
.
Process groups are used lor distribution or signals, and by terminals to arbitrate requests for their
input: processes which have the same process group as the terminal are loreground and may read,
while others will block with a signa.l il they attempt to read.
This ca.ll is thus used by programs such as cBh{l) to create process groups in implementing job
control. The TIOCGPGRP and TIOCSPGRP calls described in ttll(4) are used to get/set the
process group 01 the control termin al.
SEE ALSO

setpgrp(2), getuid(2), tty(4)

SUD

Releasp 1.1

Last change: 2 July 1983

39

SYSTEM CALLS

GETPID(2)

GETPID(2)

NAME

getpid, getppid - get process identification
SYNOPSIS
pld
getpld()
loog pld.

==

==

ppld
getppld()
1001 ppldl
DESCRIPTION

Getpid returns the process 10 or the current process. Most orten it is used with the host identifier
getho8tid(2) to generate uniquely-na.med tempora.ry files.
Getppid returns the proceea ID or the parent or the current process.
SEE ALSO

gethostid( 2)

40

Last change: 12 February 1983

Sun Release 1.1

SYSTEM CALLS

GETPRIORITY ( 2 )

GETPRIORITY (2)

NAME

getpriority, setpriority - get/set program scheduling priority
SYNOPSIS
#1nclude 

#deftne PRiO_PROCESS
#deftne PRIO_PGRP
#define PRIO_USER

0
1
2

/ .. proeess .. /

1* proeess group */
/* user Id */

==

prlo
getpl'lol'lty(whleh, who)
lnt prio, whleh, who.

setpl'iorlty(whleh, who, prlo)
mt which, who, prlo;
DESCRIPTION

The scheduling priority of the process, process group, or user, as indicated by which and who is
obtained with the getprioritll call and set with the 8etpriorit1l call. Which is one of
PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, and who is interpreted relative to which (a process identifier for PRIO_PROCESS, process group identifier Cor PRIO_PGRP, and a user ID Cor
PRIO_USER). Prio is a value in the range -20 to 20. The deCault priority is 0; lower priorities
cause more favorable scheduling.
The getprioritll call returns the highest priority (lowest numerical value) enjoyed by any of the
specified processes. The 8etpriorit1l call sets the priorities of all of the specified processes to the
specified ~aJue. Only the super-user may lower priorities.
RETURN V ALuxt

Since getpriority can legitimately return the value -1, it is necessary to clear the external variable
errno prior to the call, then check it afterward to determine if a -1 is an error or a legitimate
value. The setprioritll call returns 0 if there is no error, or -1 if there is.
ERRORS

Getprioritll and 8etpriority may return one of the fonowing errors:
[ESRCH)
No process(es) were located using the which and who values specified.
Which was not one of PRIO,YROCESS, PRIO_PGRP, or PRIO_USER.
(EINVALJ
In addition to the errors indicated above, 8etpriorit1l may fail with one of the following errors
returned:
A process was located, but neither its effective nor real user ID matched the
[EACCES)
effective user ID or the caller.
A nOD super-user attempted to change a process priority to a negative value.
[EACCES)
SEE ALSO

nice(I), fork(2), renice(8)

BUGS
. It is not possible for the process executing 8etprioritll ( ) to lower any other process down to its
current priority, without requiring superuser privileges.

SUD

Release 1.1

Last change: 20 March 1984

41

GETRLIMIT ( 2)

SYSTEM CALLS

GETRLIMIT ( 2 )

NAME

getrlimit, setrlimit - control maximum system resource consumption
SYNOPSIS

#lnclude 
#lnclude < s;ya/resource.h >
BetrDmlt(reaource, rip)
lnt resource;
atruct rUmlt*rlpl
aetrUmlt(reaource, rip)
tnt reaource;
structrUmlt *rlpJ
DESCRIPTION
Limits on the consumption of system resources by the current process and each process it creates
may be obtained with the getrlimit call, and set with the setrlimit call.

The resource parameter is one of the following:
RLIMIT_CPU

the maximum amount or cpu time (in milliseconds) to be used by each process.

RLIMIT_FSIZE

the largest size, in bytes, of any single file which may be creaied.

RLIMIT_DATA

the max.mum size, in bytes, of the data segment for a process; this defines
how far a program may extend its break with -the8brk(2) system call.

RLIMIT_STACK the maximum size, in bytes, of the stack segment for a process; this defines
how far a program's stack' segment may be extended automatically by the system.
RLIMIT_CORE

the largest size, in bytes, of a core file which may be created.

RLIMIT_RSS

the maximum size, in bytes, a process's resident set size may grow to. This
imposes a limit on the amount of physical memory to be given to a process; if
memory is tight, the system will prefer to take memory from processes which
are exceeding their declared resident set size.

A resource limit is specified as a soft limit and a hard limit. When a soft limit is exceeded a process may receive a signal (for example, if the cpu time is exceeded), but it will be allowed to continue execution until it reaches the hard limit (or modifies its resource limit). The rlimit structure
is used to speciry the hard and soft limits on a resource,
struct rlimit {
int
rlim_cur;
int
dim_max;
};

''**

*' *'

current (sort) limit
hard limit

Only the super-user may raise the maximum limits. Other users may only alter rlim_cur within
the range from 0 to rlim_maz or (irreversibly) lower rlim_maz.
An "infinite" v,alue for a limit is defined as RLIMIT_INFINITY (Ox7rCrrrrr).
Because this information is stored in the per-process information, this system call must be executed directly by the shell ir it is to affect all Cuture processes created by the shell; limit is thus a
built.-in command to csh( 1).
The system refuses to extend the data or stack space when the limits would be exceeded in the
normal way: a break call fails ir the data space limit is reached, or the process is killed when the
stack limit is reached (since the stack cannot be extended, there is no way to send a signal!).

42

Last change: 29 August 1983

SUD Release 1.1

SYSTEM CALLS

GETRLIMIT ( 2)

GETRLIMIT ( 2 )

A file i/o operation which would create a file which is too large will cause a signal SIGXFSZ to be
generated, this normally terminates the process" but may be caught. When the sort cpu time
limit is exceeded. a signal SIGXCPU is sent to the offending process.
RETURN VALUE
A 0 return value- indicates that the call succeeded, changing or returning. the resource limit. A
return value of -1 indicates· that an error occurred, and an error code is stored in the global loca-

tioll errnD.
ERRORS

Tile possible errors au!

lEFAUL TJ
(EPERMJ

The address specified for rip is invalid.
The limit specified- to sefrlimit would have
raised the maximum limit- yalu" and the caller is DO&- tire super-user.

SEE ALSO

cah(lt quota(2)
BUGS

There should be limifand "n(imit commands- in ,A(l)

Sun Release 1.1

38

well as in c,A.

Last change: 29 August 1983

43

GETRUSAGE(2)

SYSTEM CALLS

GETRUSAGE(2)

NAME

getrusage - get information about resource utilization
SYNOPSIS

:fI:lnelude 
:fI:lnelude 
:IIdefine RUSAGE_SELF
:fI:deflne RUSAGE_CHlLDREN

o
-1

'*

*'

call1Dl:proeeu
'* terminated' chUd procell. *'

setruaase(who, rusase)
lnt who,
Itruct rU8a•• *ru8.a',
DESCRIPT:ION
GdrU81tge returns information' about the resources utilized by' the current- process, or all its'terminated child processes~
The wlio parameter ia one of RUSAGE_SELF orRUSAGE_CHILDREN. If rU84ge is non-zero, the buffer it points to will be fi:Hed in with the foJ.;
lowing structure:
struct rusage: {
'* user time used'.' *'
struct timeval ru...utime;
'* system.time·used *'
stluct timeval rU;,;..stime;
iut
ru....maxns;
,*' mtegralshared; memory· size */
rU.;...UtrS8;
int
rU.;...idrss;
int
'*integral~unshared data,size
'* integral unshared stack size *'
in-t
ru:....isr88;
rUJDinllt;
int
'* page reclaims *'
in;t
,*'. page· faults *'
rUJDajftt;
rUJlswap;
int
swaps,*!
'*, block input operations *'
ru_inblock;
int
ru_oublock;
int
block output operations *'
ru;.;..mspndj
int
me88ages sent *t
int
ru_mSIlCV;
messages received *'
int
ru~nsign.als;
signals received *'
int;
ru:...nvcsw;
'* voluntary- context switches *'
ru_nivcsw;
int
'* involuntary context switches *'
};

*'

'*
''**
''**

The fields are interpreted as follows:
ru_utime
the total. amount of time spent executing in user mode. Time is given in
8econds:microsecond8~

the total amount of time. spent in the system executing on behalf of the
proc ess(es ). Time is given in seconds:microseconds.
the maximurn resident set size utilized. Size is given in pages (1 page =
2Kbytes)~

ru_ixrss

an "integral" valu.e indicating the amount of memory used which was also.
shared among other processes. This value is expressed in units of pages" clock
ticks (1 tick = 1'50 second). The value is calculated by summing the number of
shared memory pages in use eac~ time the internal system clock ticks, and then
averaging over 1 second intervals.
an integral value of the amount of unshared memory residing in the data segment of a process. The value is given in pages * clock ticks.

ru_isrss

44

an integral value of the amount of UDshared memory residing in the stack segment of a process. The value is given in pages * clock ticks.

Last change: 20 February 1984

Sun Release 1.1

SYSTEM CALLS

GETRUSAGE (2)

GETRUSAGE(2)

the number of page faults serviced without any i/o activity; here i/o activity is
avoided by "reclaiming" a page frame from the list of pages awaiting reallocation.
ru_majflt

the number of page faults serviced which required i/o activity.

ru_nswap

the number of times a process was "swapped" out of main memory.

ru_inblock

the number of times the file system had to perform input.

ru_outblock

the number of times the file system had to perform output.

ru_msg5nd

the number of ipc messages sent.

ru_msgrcv

the number of ipc messages received.

rU_Dsignals

the number of signals delivered.

ru_nvcsw

the number of times a context switch resulted due to a process voluntarily giving
up the processor before its time slice was completed (usually to await availability
of a resource).
the number of times a context switch resulted due to a higher priority process
becoming runnable or because the current process exceeded its time slice.

NOTES
The numbers ru_inblock and ru_outblock account only for real i/o; data supplied by the cacheing
mechanism is charged only to the first process to read or write the data.

SEE ALSO
gettimeofday(2), wait(2)
BUGS
There is no way to obtain information about a child process which has not yet terminated.

Sun Release 1.1

Last change: 20 February 1984

45

SYSTEM CALLS

GETSOCKNAME ( 2 )

GETSOCKNAME ( 2 )

NAME

getsockname - get socket name
SYNOPSIS

getsoekname(l, name, namelen)
lnt II
stl'uet soekaddl' *namel
lnt *namelenl
DESCRIPTION
GetBockname returns the current name for the specified socket. The namelen parameter should be
initialized to indicate the amount of space pointed to by name. On retuf)J it contains the actual

size of the name returned (in bytes).
DIAGNOSTICS

A 0 is returned if the ~all succeeds, -1 if it fails.
ERRORS

The call succeeds unless:
The argument , is not a valid descriptor.
(EBADF)
IENOTSOCK)

The argument' is a file, not a socket.

(ENOBUFS)

Insufficient resources were available in the system to perform the operation.

(EFAULT)

The name parameter points to memory not in a valid part of the process address
space.

SEE ALSO

bind(2), socket(2), getpeername(2)
BUGS

Names bound to sockets in the UNIX domain are inaece88ible; letlockname returns a zero length
name.

46

Last change: 24 October 1983

Sun Release 1.1

SYSTEM CALLS

GETSOCKOPT ( 2)

GETSOCKOPT ( 2 )

NAME
getsockopt, setsockopt - get and set options on sockets
SYNOPSIS

#meJude 
*~elude 
Betsoekopt(a, level, optname, optval, optlen)
Int II, level, optname;
char ·optval;
Int ·optlenl
8eteoekopt(s, level, optname, optval, optlen)
lnt I, level, optname;
char *optval.
Int optJeDI
DESCRIPTION

Getsockopt and 8et8oclcopt manipulate options associa.ted with a socket. Options may exist at
multiple protocol levels; they are always present at the uppermost "socket" level.
When manipulating socket options the level at which the option resides and the name or the
option must be specified. To manipulate options at the "socket" level, level is specified as
SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate
protocol controlling the option is supplied. For example, to indicate an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP; see

getprotoent(3N).
The ,parameters oplval and optlen are used to access option values ror BetBoclcopt. For getBoclcopt
they identify a buffer in which the value for the requested option(s) are to be returned. For get8oelcopt, opllen is a value-result parameter, initially containing the size of the buffer pointed to by
oplval, and modified on return to indicate the actual size of the value returned. If no option
va.lue is to be supplied or returned, oplval may be supplied as O.

Optnome and any specified options are passed uninterpreted to the appropriate protocol module
for interpretation, The include file < 81J8/8oelcet.h > contains definitions for "socket" level
options; see 8oclcet(2). Options at other protocol levels vary in format and name, consult the
appropria.te entries in (4P).
RETURN VALUE
A 0 is returned if the call succeeds, -1 it it tails.
ERRORS·
The caU succeeds unless:
[EBADFJ

The argument

8

is not a valid descriptor.

[ENOTSOCK)

The argument

B

is a file, not a socket.

(ENOPROTOOPT)

The option is unknown.

(EFAULT)

Tbe options are not in a valid part of the process address space.

SEE ALSO
socket(2), getprotoent(3N)

SUD

Release 1.1

Last change: 7 July 1983

47

GETTIMEOFDAY (2 )

SYSTEM CALLS

GETTlMEOFDAY ( 2 )

NJ\.ME

gettimeofday, settimeofday - get/set date and time
SYNOPSIS

#lnelude 
lettlmeofda,,(tp, tap)
.truet tlmeval *tpi
.truet tlmezone *tlPI
.ettlmeof'day(tp, tzp)
.truet tlmeval *tpi
.truet time lone *tzPI
DESCRIPTION

Gettimeofdo1/ returns the system's notion of the current Greenwich time and the current time
zone. Time returned is expressed in seconds and microseconds since midnight January 1, 1970.
The structures pointed to by tp and tzp are defined in  as:
struct timeval f
u_lon, tv _sec;
long
tv _usec;

/. seconds since Jan. 1, 1970.•/

/* and microseconds */

};

'*

*'

struct timezone {
of Greenwich
int
tz_minuteswest;
int
tZ_dsttime;
,. type of dst correction to apply

};

*'

The timezone structure indicates the local time zone (measured in minutes of time westward from
Greenwich), and a flag that, if nonzero, indicates that Daylight Saving time applies locally during
the appropriate pa.rt- of the year.
If ,p and' or tzp is a zero pointer, the corresponding information will not be returned or set.

Only the super-user may set the time of day.
RETURN

AO return value indica.tes that the call succeeded. A -1 return value indicates an error occurred,
and in this case an error code is stored into the global variable errno.
ERRORS

The following error codes may be set in errno:
[EFAULTJ

An argument address referenced invalid memory.

(EPERM)

A user other than the super-user attempted to set the time.

SEE ALSO

date(l), ctime(3)
BUGS

Time is never correct enough to believe the microsecond values. There should a mechanism by
which, at least, local clusters of systems might synchronize their clocks to millisecond granularity.

48

Last change: 20 March 1984

Sun Release 1.1

SYSTEM CALLS

GETUID(2)

GETUID(2)

NAME
getuid t geteuid - get user identity
SYNOPSIS

== setuld()
euld == seteuld()
uld

Int uldJ

Int euldJ

DESCRIf}TION

loctl(d, request, argp)
lnt d, request;
char *arIP;
DESCRIPTION
loetl perrorms a variety or runctions on open descriptors. In particular, many operating characteristics or character special files (e.g. terminals) may be controlled with ioetl requests. The writeups of various devices in section 4 discuss how ioetl applies to them.
An ioctl requelt has encoded in it whether the argument is an "in" parameter or "out" parameter, and the size of the argument Grgp in bytes. Macros and defines used in specifying an ioetl
requelt are located in the file .
RETURN VALUE
If an error has occurred, a value of -1 is returned and errno is set to indicate the error.
If no error has occurred (using a STANDARD device driver), a value or 0 is returned.
ERRORS

loetl will rail if one or more of the rollowing are true:
[EBADF)
D is not a valid descriptor.
(ENOTTY)
D is not associated with a character special device.
(ENOTTY]
The specified request does not apply to the kind of object which the descriptor d
references.
(EINVAL]
Request or argp is not valid.
SEE ALSO

execve(2), rcntl(2), mtio(4), tty(4)

50

Last change: 20 March 1984

SUD Release 1.1

SYSTEM CALLS

KILL (2)

KILL(2)

NAME
kill - send signal to a process
SYNOPSIS

kUl(pld, lis)
lilt pld,

81m

DESCRIPTION
Kill sends the signal 8ig to a process, specified by the process number pid. Sig may be one of the
signals specified in 8igvec(2), or it may be 0, in which case error checking is performed but no signal is actually sent. This can be used to check the validity of pid.

The sending and receiving processes must have the same effective user ID, otherwise this call is
restricted to the super-user. A single exception is the signal SIGCONT which may always be sent
to any child or grandchild of the current process.

II the process number is 0, the signal is sent to all other processes in the sender's process group;
this is a variant of killpg(2).
If the process number is -1, and the user is the super-user, the signal is broadcast universally
except to system processes and the process sending the signal.
Processes may send signals to themselves.
RETURN VALUE

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and
errno is set to indicate the error.
ERRORS
Kill will fail and no signal will be sent if any of the following occur:

(EINVALJ
IESRCH)
(EPERM)

Sig is not a valid signal number.

No process can be found corresponding to that specified by pid.
The sending process is not the super-user and its effective user id does not match
the effective user-id of the receiving process.

S-EEALSO

getpid(2), getpgrp(2), killpg(2), sigvec(2)

SUD

Release 1.1

Last change: 29 August 1983

51

SYSTEM CALLS

KILLPG(2)

KILLPG(2)

NAME

killpg - send signal to a process group
SYNOPSIS
kWpg(pP'p,alg)
tnt PP'P, alg;
DESCRIPTION
Killp, sends the signal 8i,to the process group p,rp. See 8i,vec(2) ror a list or signals.

The sending process and members or the process group must have the same effective user ID, otherwise this call is restricted to the super-user. AB a single special case the continue signal
~JGCONT may be sent to any process which is a descendant or the current process.
RETUR]~

VALUE
Upon successrul completion, a value or 0 is returned. Otherwise, a value or -1 is returned and the
global variable errno is set to indicate the error.

ERRORS

Killp, will fail and no signal will be sent ir any of the following occur:
(EINVAL)

Si, is not a valid signal number.

(ESRCH)
(EPERM)

No process were round in the specified process group.
The sending process is not the super-user and one or more or the target processes
has an effective user ID different rrom that or the sending process.

SEE ALSO
kn1(2),getpgrp(2), sigvec(2)

52

Last change: 16 February 1984

Sun Release 1.1

SYSTEM CALLS

LINK(2)

LINK(2)

NAME

link - make a hard link to a file
SYNOPSIS
Unk(namel, name!)
char *namel, *namell
DESCRIPTION

A hard link to name! is created; the link has the name name!. Name! must exist.
With hard links, both name! and name! must be in the same file system. Unless the caller is the
super-user, name1 must not be a directory. Both the old and the new link share equal access and
.
rights to the underlying object.
RETURN VALUE

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and
errno is set to indicate the error.
ERRORS
Link will fail and no link will be created if one or more of the following are true:

(EPERM)

Either pathname contains a byte with the high-order bit set.

(ENOENT)

Either pathname was too long.

(ENOTDIR)

A component of either path prefix is not a directory.

(ENOENT)

A component of either path prefix does not exist.

(EACCES)

A component of either path prefix denies search permission.

(ENOENT)

The file named by name! does not exist.

(EEXIST)

The link named by nameD does exist.

(EPERM)

The file named by name1is a directory and the effective user ID is not superuser.

[EXDEV)

The link named by name! and the file named by name1 are on different file systems.
The requested link requires writing in a directory with a mode that denies write
permission.

(EACCES}
(EROFS)

The requested link requires writing in a directory on a read-only file system.

(EFAULT)

One of the pathnames specified is outside the process's allocated address space.

[ELOOP)

Too many symbolic links were encountered in translating the pathname.

SEE ALSO

symlink(2), unlink(2)

Sun Release 1.1

Last change: 12 February 1983

53

LISTEN(2)

SYSTEM CALLS

LISTEN(2)

NAME
listen - listen ror connections on a socket
SYNOPSIS

u.ten(8, baeJdol)

tnt 8, backlolJ
DESCRIPTION

To accept connections, a socket is first created with .ocket(2), a backlog for incomin, connections
is specified with li,ten(2) and then the connections are accepted with accept(2). The listen caU
applies only to sockets or type SOCK_STREAM or SOCK_PKTSTREAM.
The backlog parameter defines the maximum length the queue of pending connections may ,row
to. If a connection request arrives with the queue full the client wiD receive an error with an indication of ECONNREFUSED.
RETURN VALUE
A 0 return value indicates success; -1 indicates an error.
ERRORS

The call fails if:
[EBADF)

The argument

8

is not a valid descriptor.

[ENOTSOCK)

The argument

8

is not a socket.

[EOPNOTSUPP)

The socket is not of a type that supports the operation listen.

SEE ALSO

accept(2), connect(2), socket(2)
BUGS

The backlog is currently limited (silently) to 5.

54

Last change: 12 February 1983

Sun Release 1.1

SYSTEM CALLS

LSEEK(2)

LSEEK(2)

NAME
Iseek, tell- move read/write pointer
SYNOPSIS

#deflne L_SET 0
#deflne L_INCR 1
#deflne L_XTND I

'''***

*' *'
*'

set the seek pointeI'
Increment the seek pointeI'
extend the flle size
poa
lseek(d, ofl'set, whence)
Int po••
lot d, ofl'.et, whence.

==

DESCRIPTION
The descriptor d rerers to a file or device open ror reading and/or writing. LBeek sets the file
pointer or d as rollows:
If whence is L_SET, the pointer is set to OJ/Bet bytes.
If whence is L_INCR, the pointer is set to its current location plus oJ/set.
If whence is L.JCTND, the pointer is set to the size or the file plus oJ/Bet.

Upon successrul completion, the resulting pointer location as measured in bytes rrom beginning or
the file is returned. Some devices are incapable or seeking. The value or the pointer associated
with such a device is undefined.
The obsolete runction··'ell(JUdeB) is identical to 'Beek(JUdeB} OL, L_INCR).
NOTES
Seeking rar beyond th~ end or a 61e, then writing, creates a gap or "hole", which occupies no physical space and reads as zeros.
RETURN VALUE
Upon successrul completion, a non-negative integer, the current 61e pointer value, is returned.
Otherwise, a value or -1 is returned and errno is set to indicate the error.
ERRORS

LBeek will rail and the file pointer will remain unchanged ir:
Fildei is not an open file descriptor.
[EBADF)
[ESPIPE)

IEINVAL)
IEINVAL)

Fildes is associated with a pipe or a socket.
Whence is not a proper value.
The resulting file pointer would be negative.

SEE ALSO
dup(2), open(2)

SUD

Releallf 1.1

Last change: 29 August 1983

55

SYSTEM CALLS

MKDffi(2}

MKDffi(2)

NAME
mkdir - make a directory file
SYNOPSIS

mkdlr(path, mode)
char *path;
lnt mode;
DESCRIPTION
Mkdir creates a new directory file with name PIJth. The mode 01 the new file is initialized Irom
mode. (The protection part 01 the mode is modified by the process's mode mask; see umuk(2».
The directory's owner ID is set to the process's elective user ID. The directory's goup ID is set
to that 01 the parent directory in which it is created.
The low-order 9 bits 01 mode are modified by the process's file mode creation mask: aU bits set in
the process's file mode creation mask are cleared. See umIJ8k(2).
RETURN VALUE
A 0 return value indicates success. A -1 return value indicates an error, and an error code is
stored in errno.
ERRORS

Mkdir will lail and no directory will be created if:
(EPERM)

The process's elective user ID is not super-user.

IEPERM)

The pIJth argument contains a byte with the high-order bit set.

(ENOTDffi)

A component 01 the path prefix is not a directory.

(ENOENT)

A component 01 the path prefix does not exist.

(EROFS)

The named file resides on a read-only file system.

(EEXIST)

The named file exists.

(EFAULTJ

PIJth points outside the process's allocated address space.

(ELOOP)

Too many symbolic links were encountered in translating the pathname.

An I/O error occured while writing to the file system.
IEIO)
SEE ALSO
chmod(2}, stat(2}, umask(2}

56

Last change: 29 August 1983

Sun Release 1.1

MKNOD(2)

SYSTEM CALLS

MKNOD(2)

NAME
mknod - make a special file
SYNOPSIS

mknod(path, mode, dev)
char *path;
tnt mode, deY;
DESCRIPTION
Mknod creates 3. new file whose name is path. The mode or the new file (including special file bits)
is~ initialized rrom mode. (The protection part or the mode is modified by the process's mode
mask; see umo8k(2)). The first block pointer or the i-node is initialized rrom dev and is used to
speciry which device the special file rerers to.

If mode indicates a block or character special file, dev is a configuration dependent specification or
a character or block I/O device. If mode does not indicate a block special or character special
device, dev is ignored.
Mknod may be invoked only by the super-user.
RETURN VALUE
Upon successrul completion a value or 0 is returned. Otherwise, a value or -1 is returned and
errno is set to indicate the error.

ERRORS
Mknod will fail a.nd the file mode will be unchanged it:
[EPER?\1)

The process's effective user ID is not super-user.

[t;PERM)

The pathname contains a character with the high-order bit set.

(ENOTDffiJ

A component or the path prefix is not a directory.

[ENOENT)

A component or the path prefix does not exist.

IEROFS)

The named file resides on a read-only file system.

(EEXIST)

The named file exists.

(EFAUL TJ

Path points outside the process's allocated address space.

[ELOOP)

Too many symbolic links were encountered in translating the pathname.

SEE ALSO
chmod(2), stat(2), umask(2)

SUD

Release 1.1

Last change: 2 July 1983

57

SYSTEM CALLS

MMAP(2)

MMAP(2)

NAME

mmap - map pages of memory
SYNOPSIS

#lne1ude 
#lnclude 
mmap(addr, len, prot, Ihare, rd, oft)
caddr_t addr; lnt len, prot, ahare, rd; o«_t 0«;
DESCRIPTION

N .B.I This caD Is not completely implemented In 4.1.
Mmop maps the pages starting at oddr and continuing for len bytes from the object represented
by the descriptor Id, at the current file position of offset off. The parameter shore specifies
whether modifications made to this mapped copy of the page are to be kept private or are to be
shored with other references. The parameter prot specifies the accessibility of the mapped pages.
The oddr and len parameters and the sum of the current position in Id and the off parameters
must be multiples of the page size (found using the getpogesize(2) call).
Pages are automatically unmapped at clost.
RETURN VALUE

The call returns 0 on success, -Ion failure.
ERRORS

The mmop call will fail if:
[EINVAL) The argument address or length is not a multiple of the page size as returned by
getpogesize(2),or the length is negative.
[EINVAL) The entire range of pages specified in the call is not part of data space.
[EINVAL) The specified Id does not refer to a character special device which supports mapping
(e.g. a frame buffer).
[EINVAL J The specified Id is not open for reading and read access is requested, or not open for
writing when write access is requested.
[EINVALJ The sharing mode was not specified as MAP_SHARED.
SEE ALSO

getpagesize(2), munmap(2), close(2)

58

Last change: 20 March 1984

Sun Release 1.1

SYSTEM CALLS

MOUNT(2)

MOUNT(2)

NAME
mount, umount - mount or remove file system
SYNOPSIS

mount(speelal, name, rwflal)
ehar *spec:laI, *namel
Int rrialD
umount(speelal)
ehar *speelall
DESCRIPTION
Mount announces to the system that a removable file system has been mounted on the blockstructured special file special; from now on, references to file nome will refer to the root file on the
newly mounted file system. Special and name are pointers to null-terminated strings containing
the appropriate path names~

Nome must exist already. Nome must be a directory. Its old contents are inaccessible while the
file system is mounted.
The rwjlag argument determines whether the file system can be written on; if it is 0 writing is
allowed, if non-zero no writing is done. Physically write-protected and magnetic tape file systems
must be mounted read-only or errors will occur when access times are updated, whether or not
any explicit write is attempted.

Umount announces to the system that the special file is no longer to contain a removable file system. The associated file reverts to its ordinary interpretation.
RETURN VALUE
Mount returns 0 if the action occuned, -1 if special is inaccessible or not an appropriate file; if
nome does not exist; if special is already mounted; if nome is in use; or if there are already too
many file systems mounted.

Umount returns 0 if the action occurred; -1 if if the special file is inaccessible or does not have a
mounted file system, or if there are active files in the mounted file system.
ERRORS
~(1unt

will fail when one of the following occurs:

(NODEV)

The caller is not the super-user.

(NODEV)

Special does not exist.

(ENOTBLK)

Special is not a block device.

[ENXIO)

The major device number of special is out of range (this indicates no device
driver exists for the associated hardware).

[EPERM]

The pathname contains a character with the high-order bit set.

[ENOTDffil

A component of the path prefix in nome is not a directory.

(EROFS)

Nome resides on a read-only file system.

[EBUSY)
(EBUSY)
(EBUSY)

Nome is not a directory, or another process currently holds a reference to it.
No space remains in the mount table.
The super block for the file system had a bad magic number or an out of range
block size.

(EBUSY)

Not enough memory was available to read the cylinder group information for the
file system.

(EBUSY)

An i/o error occurred while reading the super block or cylinder group informa-

tion.

SUD

Release 1.1

Last change: 29 August 1983

59

MOUNT(2)

SYSTEM CALLS

MOUNT(2)

Umount may fail with one of the followin, errors:
[NODEV)

The caller is not the super-user.

[NODEV)

SpecitJi does not exist.

(ENOTBLK)

Special is not a block device.

[ENXIO)

The major device n.umber of Bpecial is out of range (this indicates no device
driver exists for the associated hardware).

(EINVAL)

The requested device is not in the mount table.

[EBUSY]

A process is holdin, a reference to a file located on the file system.

SEE ALSO

mount(8), umount(8)

BUGS
The error codes are in a state of disarray; too many errors appear to the caller as one value.

60

Last change: 29 August 1983

SUD. Release

1.1

SYSTEM CALLS

MUNMAP(2)

:MUNMAP(2)

NAME

munmap - unmap pages or memory
SYNOPSIS

#lnelude 
munmap(addr, len)
eaddr_t addr,lnt len,
DESCRIPTION
N.D.I Th. eall. not eompleteJy Implemented In 4.2.

Munmop causes the pages starting at oddr and continuing for len bytes to refer to private pages
which will be initialized to zero on reference.
RETURN VALUE

The call returns -Ion error, 0 on success.
ERRORS

The call fails if any of the following:
(EINVALI The argument address or length is not a multiple of the page size as returned by
getpogerize(2),or the length is negative.
[EINVALI The entire range of pages specified in the call is not part of data space.
SEE ALSO

brk (2), mmap(2), close(2)

Sun Release 1.1

Last change: 20 March 1984

61

SYSTEM CALLS

OPEN(2)

OPEN(2)

NAME
open - open a file ror reading or writing, or create a new ·file
SYNOPSIS
#lnclude 

open(path, flap, mode)
char *path;
tnt flags, mode;
DESCRIPTION
Open opens the file path for reading and/or writing, as specified by the jUJgs argument and returns
a descriptor for that file. The jUJgs argument may indicate the file is to be created if it does not
already exist (by specifying the O_CREAT 8ag), in which case the file is created with mode mode
as described in chmod(2) and modified by the process' umask value (see umask(2».

Path is the address of a string of ASCn charactel'8 representing a path name, terminated by a null
character. The fiags specified are formed by or'ing the following values
O_RDONLY
O_WRONLY
O_RDWR
O_NDELAY
O_APPEND
O_CREAT
O_TRUNC
O_EXCL

open for reading only
open for writing only
open for reading and writing
do not block on open
append on each write
create file if it does not exist
truncate si~e to 0
error if create and file exists

Opening a file with O_APPEND set causes each write on the file to be appended to the end. It
O_TRUNC is specified and the file exists, the file is truncated to zero length. If O_EXCL is set
with O_CREAT, then if the file already exists, the open returns an error. This can be used to
implement a simple exclusive access locking mechanism. It the O_NDELAY flag is specified and
the open call would result in the process being blocked for some reason (e.g. waiting tor carrier on
a dialup line), the open returns immediately. The first time the process attempts to perform i/o
on the open file it will block (not currently implemented).
Upon successful completion a non-negative integer termed a file descriptor is returned. The file
pointer used to mark the current position within the file is set to the beginning of the file.
The new descriptor is set to remain open across ezecve system calls; see close(2).
There is a system enforced limit on the number of open file descriptors per process, whose value is
returned by the getdtablesize(2) call.
RETURN VALUE
The value -1 is returned if an error OCCUI'8, and external variable errno is set to indicate the cause
of the error. Otherwise a non-negative numbered file descriptor for the new open file is returned.
ERRORS
Open fails if:

62

[EPERM)

The pathname contains a character with the high-order bit set.

[ENOTDm)

A component of the path prefix is not a directory.

[ENOENT]

O_CREAT is not set and the named file does not exist.

[EACCES]

A component of the path prefix denies search permission.

[EACCES]

The required permissions (for reading and/or writing) are denied for the named
file.

[EISDIR]

The named file is a directory, and the arguments specify it is to be opened for
writing.

Last change: 17 February 1984

Sun Release 1.1

OPEN(2)

SYSTEM CALLS

OPEN(2)

[EROFS)

The named file resides on a read-only file system, and the file is to be modified.

(EMF IL E)
[ETXTBSY)

{OPEN_MAX} file descriptors are currently open.
The file is a pure procedure (shared text) file that is being executed and the open
call requests write access.

[EFAULT)

Path points outside the process's allocated address space.

(ELOOP)

Too many symbolic links were encountered in translating the pathname.

(EEXIST)

o_EXCL was specified and the file exists.

[ENXIOJ

The 0 _NDELAY flag is given, and the file is a communications device on which
there is no carrier present.

[EOPNOTSUPP)
An attempt was made to open a socket (not currently implemented).
SEE ALSO

chmod(2), close(2), dup(2), lseek(2), read(2), write(2), umask(2)

Sun

Rele~

1.1

Last change: 17 February 1984

63

PIPE(2)

SYSTEM CALLS

PIPE(2)

NAME

pipe- create an interprocess communication channel
SYNOPSIS
plpe(ftlde.)
lnt Blde.12b
DESCRIPTION

The pipe system call creates an 110 mechanism called a pipe. The file descriptors returned can be
used in read and write operations. WheD the pipe is written using the descriptor jiJdes[l). up to
4096 bytes of data are buffered before the writing process is suspended. A read using the descriptor jildes[O) will pick up the data.
It is assumed that after the pipe has been set up, two (or more) cooperating processes (created by
subsequent fork calls) will pass data through the pipe with read and write calis.
The shell has a syntax to set up a linear array of processes connected by pipes.
Read calls on an empty pipe (no buffered data) with only one end (all write file descriptors closed)
returns an end-of-file.
Pipes; are really a special case of the sockdpair(2) call and, in fact, are implemented as such in
the system.
A signal. is generated if a write on a pipe with only one end is

attempted~

RETURN VALUE

The· function value zero is· returned if the pipe was created; -1 if an error

occurred~

ER.RORS

The pipe call. will fail if:
(EMF ll:. E)

Too many descriptors are active.

[EFAULT)

The jildes buffer is in an invalid area of the process's address space.

SEE ALSO

sh(l), read(2), write(2), fork(2), socketpair(2)
BUGS

Should more than 4096 bytes be necessary in any pipe among a loop of processes, deadlock will
occur~

64

Last change: 12 February 1983

Sun Release 1.1

PROFIL(2)

SYSTEM CALLS

PROFIL(2)

NAME
profil - execution time profile
SYNOPSIS

profll(buff, butala, offaet, acale)
char *buff.
lnt butala, offaet, acale.
DESCRIPTION
BUffpoints to an area of core whose length (in bytes) is given by 6u/siz. After this call, the user's
program counter (pc) is examined each clock tick (20 milliseconds); offset is subtracted from it,
and the result multiplied by sCG/e. If the resulting number corresponds to a word inside 6uff, that
word is incremented.
The scale is interpreted as an unsigned, fixed-point fraction with binary point at the left: OxlOOOO
gives a 1-1 mapping of pc's to words in hu1T; OxSOOO maps each pair of instruction words together.
Ox2 maps aU instructions onto the beginning of 6uff(producing a non-interrupting core clock).
Profiling is turned 01 by giving a sCG/e of 0 or 1. It is rendered inelective by giving a 6u/siz of o.
Profiling is turned 01 when an ezecve is executed, but remains on in child and parent both after a
fork. Profiling is turned 01 if an update in 6uffwouId cause a memory fault.
RETURN VALUE
A 0,. indicating success, is always returned.
SEE ALSO
gprof( 1II- setitimer(2), monitor(3}

SUD

Release 1.1

Last change: 16 March 1984

65

SYSTEM CALLS

PTRACE(2)

PTRACE(2)

NAME

ptrace - process trace
SYNOPSIS
#lnelude <.lgnal.h>

ptraee(request, pld, addr, data)
lnt request, pld, *addr, data;
DESCRIPTION
PIrfJce provides a means by which a parent process may control the execution of a child process,
and examine and change its core image. Its primary use is for the implementation of breakpoint
debugging. There are four arguments whose interpretation depends on a reque8t argument. Generally, pid is the process ID of the traced process, which must be a child (no more distant descendant) of the tracing process. A process being traced behaves normally until it encounters some
signal whether internally generated like "illegal instruction" or externally generated like "interrupt". See 8igvec(2) for the list .. Then the traced process enters a stopped state and its parent is
notified via wfJit(2). When the child is in the stopped state, its core image can be examined and
modified using ptrfJce. If desired, another plrfJce request can then cause the child either to terminate or to continue, possibly ignoring the signal.

The value of the request argument determines the precise action of the call:

o

This request is the only one used by the child process; it declares that the process is to be
traced by its parent. All the other arguments are ignored. Peculiar results will ensue if the
parent does not expect to trace the child.

1,2 The word in the child process's address space at fJddr is returned. If I and D space are
separated (e.g. historically on a pdp-II), request 1 indicates I space, 2 Dspace. Addr must be
even. The child must be stopped. The input dfJtfJ is ignored.
3

The word of the system's per-process data area corresponding to fJddr is returned. Addr must
be even and less than 512. This space contains the registers and other information about the
process; its layout corresponds to the user structure in the system.

4,5 The given dfJtfJ is written at the word in the process's address space corresponding to fJddr,
which must be even. No useful value is returned~ If I and D space are separated, request 4
indicates I space,S D space. Attempts to write in pure procedure fail if another process is
executing the same file.
6

The process's system data is written, as it is read with request 3. Only a few locations can
be written in this way: the general registers, the floating point status and registers, and certain bits of the processor status word.

7

The dfJtfJ argument is taken as a signal number and the child's execution continues at location fJddr as if it had incurred that signal. Normally the signal number will be either 0 to
indicate that the signal that caused the stop should be ignored, or that value fetched out of
the process's image indicating which signal caused the stop. If fJddr is (int *)1 then execution
continues from where it stopped.

8

The traced process terminates.

9

Execution continues as in request 7; however, as soon as possible after execution of at least
one instruction, execution stops again. The signal number from the stop is SIGTRAP. (On
the Sun and VAX-II the T-bit is used and just one instruction is executed.) This is part of
the mechanism for implementing breakpoints.

As indicated, these calls (except for request 0) can be used only when the subject process has
stopped. The WfJil call is used to determine when a process stops; in such a case the "termination" status returned by wfJil has the value 0177 to indicate stoppage rather than genuine termination.

66

Last change: 15 March 1984

Sun Release 1.1

SYSTEM CALLS

PTRACE(2)

PTRACE(2)

To forestall possible ~raud, ptrtJce inhibits the set-user-id and set-group-id facilities on subsequent
ezectre(2) calls. It a traced process calls ezectre, it will stop before executing the first instruction
01 the new image showing signal SIGTRAP.
On the Sun and VAX-II, "word n also means a 32-bit integer, but the "even" restriction does not
apply.
RETURN VALUE

A 0 value is returned if the call succeeds. It the call fails then a -1 is returned and the global
variable errntl is set to indicate the error.

ERRORS

IEINVALI

The request code is invalid.
The specified process aoes not- exist.
The given signal number is inYalid.

IEFAULTJ

The specified address ii ou( 01 bounds.

fEPERM}

The specified process cannot be traced.

(EINVALJ
(EINVALJ

SEE ALSO
wait(2).- si,vec(2). adb(IS)-

BUGS
PtrtJce is unique and arcane; it should be replaced with a special file which can be opened and
read and written. The control functions could then be implemented with .ioctl(2) calls on this file.
This would be simpler to understand and have much higher performance.
The request 0 call should be able to specify signals which are to be treated normally and not
cause a stop. In this way, for example, programs with simulated floating point (which use "illegal
instruction" signals at a very high rate) could be efficiently debugged.
The error indication, -1, is a legitimate function value; errno, see inlro(2), can be used to disambiguate.

It should be possible to stop a process on occurrence or a system eal1; in this way a completely
controUed environment could be provided.

Sun Release 1.1

Last change: 15 March 1984

67

SYSTEM CALLS

QUOTA(2)

QUOTA(2)

NAME

quota - manipUlate disk quotas
SYNOPSIS

#tnelude<.ya/quota.h>
quota(emd, uld, ·UB, add!')
tnt emd, uld, UBI
eadd!'_t add!'1
DESCRIPTION

The quota call manipulates disk quotas (or file systems which have had quotas enabled with Betquota( 2). The cmd parameter indicates a command to be applied to the user ID vid. Arg is a
command specific argument and addr is the address or an optional, command specific, data structure which is copied in or out of the system. The interpretation of arg and addr is given with
each command below.
Q_SETDLIM
Set disc quota limits and current usage for the user with ID uid. Arg is a major-minor
device indicating a particular file system. Addr is a pointer to a struct dqblk structure
(defined in 
:fI:lnelude 
ee
readv(d, loY, lovent)
lnt ee, d,
atruet lovee ·lov,
lnt lovent,

==

DESCRIPTION
Read attempts to read n611te8 of data from the object referenced by the descriptor d into the
buffer pointed to by bu/. Readv perforll18 the same action, but scatters the input data into the
iovent buffers specified by the members of the iovee array: iov(O), iov(l), ... , iov(iovcnt-l).

For readv, the iovee structure is defined as
struct iovec {
caddr_t iov_base;
int
iov_len;
};
Each iovee entry specifies the base address and length or an area in memory where data should be
placed. R eadv will always fill an area completely before proceeding to the next.
On objects capable of seeking, the read starts at a position given by the pointer associated with d,
see 18eek(2). Upon return from read, the pointer is incremented by the number of bytes actually
read.
Objects that are not capable of seeking always read from the current position. The value of the
pointer associated with such a object is undefined.
Upon successful completion, read and readv return the number of bytes actually read and placed
in the buffer. The system guarantees to read the number of bytes requested if the descriptor
references a file which has that many bytes left before the end-of-file, but in no other cases.
If the returned value is 0, then end-of-file has been reached.
RETURN VALUE
If successful, the number or bytes actually read is returned. Othewise, a -1 is returned and the
global variable errno is set to indicate the error.

ERRORS
Read and read" will rail ir one or more of the following are true:

[EBADFJ

Fildes is not a valid file descriptor open for reading.

[EF AUL TJ

Bu/ points outside the allocated address space.

[EINTRJ

A read from a slow device was interrupted before any data arrived by the

delivery of a signal.
In addition, retJdv may return one or the rollowing errors:

70

(EINVAL)

lovent

[EINVAL)

One of the iov_lenvalues in the iovarray was negative.

[EINVALJ

The sum of the iov_len values in the iov array overflowed a 32-bit integer.

"'38

less than or equal to 0, or greater than 16.

Last change: 29 August 1983

Sun Release 1.1

READ(2)

SYSTEM CALLS

READ(2)

SEE ALSO
dup(2), open(2), pipe(2), socket(2), socketpair(2)

SUD

Release 1.1

Last change: 29 August 1983

71

SYSTEM CALLS

READLINK( 2 )

READLINK(2)

NAME
readlink - read value 01 a symbolic link

SYNOPSIS

==

ee
readUnk(path, but, butsla)
tnt eel
ehar *path, *but.
tnt butsls;
DESCRIPTION

RetJdlink places the contents 01 the symbolic link ntJme in the buffer 61.41 which has size 6ulBiz.
The contents of the link are not null terminated when returned.
RETURri VALUE
T'he call returns the count of characten placed in the buffer il it succeeds, or a -1 if an error
occurs, placing the error code in the global variable errno.
ERRORS

R etJdlink will fail and the file mode will be unchanged if:
[EPERM)
The ptJth argument contained a byte with the high-order bit set.
[ENOENT)

The pathname was too long.

(ENOTDm)

A component 01 the path prefix is not a directory.

(ENOENT)

The named file does not exist.

(ENXIOJ

The named file is not a symbolic link.

(EACCES)

Search permission is denied on a component 01 the path prefix.

(EPERM)

The effective user ID does not match the owner of the file and the effective user
ID is not the super-user.

(EINVAL)

The named file is not a symbolic link.

[EFAULT)

Bul extends outside the process's allocated address space.

(ELOOP)

Too many symbolic links were encountered in translating the pathname.

SEE ALSO
stat(2), lstat(2), symlink(2)

72

Last change: 2 July 1983

Sun Release 1.1

SYSTEM CALLS

REBOOT(2)

REBOOT(2)

NAME

reboot - reboot system or halt processor
SYNOPSIS
#lDelude <.y./reboot.h>
reboot(howto)
lnt howtol
DESCRIPTION
Rdool reboots the system, and is invoked automatically in the event of unrecoverable system
failures. Bowto is. a mask ot options passed to the bootstrap pro,ram. The system call interrace
permits only RB_HAL T or RB_AUTOBOOT to be passed to the reboot program; the other flags
are used in scripts stored on the console storage media, or· used in manual bootstrap procedures.
When none ot these options (e.g. RB...J\UTOBOOT) is given, the system is rebooted trom file
uvmunix" in the root file system ot unit 0 ot a disk chosen ia a processor specific way. An
automatic consistency check ot the disks is then normally performed.
The bits ot howto are:
RBJlA,LT
the- processor is simply halted; no rehoot takes place-.- RBJIAL T should be used with
caution.
RB_ASKNA:ME
Interpreted by the bootstrap program itselt, causing it to inquire as to what file should be
booted. Normally, the system is booted trom the file "vmunix" without asking.
RB_SINGLE
Normally, the reboot procedure involves an automatic disk consistency check and then
multi-user operations. RB_SINGLE prevents the consistency check, rather simply booting the system with a single-user shell on the console. RB_SINGLE is interpreted by the
init(8) program in the newly booted system. This switch is not available trom the system
call interface.
Only the super-user may rdoo' a machine.
RETURN VALUES
It successtul, this call never returns. Otherwise, a -1 is returned and an error is returned in the

global variable errno.
ERRORS

(EPERM)

The caller is not the super-user.

SEE ALSO

craah(8S), halt(8), init(8), reboot(S)

SUD Release

1~1

Last change: 12 February 1983

73

NAM~

RECV(2)

SYSTEM CALLS

RECV(21

recv, recvfrom, rec.vmsg - receive a mess~ge from a socket

SYNOPSIS

#lnelude 
#lnelude 
ee

== reev(a, bu.t, len, flap)

tnt ee, a;

ehar *but;
tnt len" ft ••,;
ee == reevfrom(a, but, len, fla.a, from, tromlen)
tnt ee, a;
ehar *but;
tnt len, fla.a;
atruet aoekaddr *trom;
tnt *tromlen;
ee == reevma.(a, mal, fla.a)

tnt ee, aJ
atr.uet ma.bd:r ~a.U;
lnt fla.a.
DESCRIPTION

Rec", rec,,/r()m, and rec"msg are used to receive messages {ro·m a socket.
The rec" call may be used only on a connected socket (see ctmnect(2).), while rec"from and
re~"m8g may be used to receive data on a socket whether it is in a connected state or not.

II from is non-zero, the sOUrce address or the message is fiUed in. Fromlen is a value-result
p.arameter, initiaJized, to the size of the buffer associated with from, and modified on return to
indicate the actual size of the address stored there. The length of the message is returned in cc.
If a message is too long to fit in the supplied buffer, exc~ bytes may be discarded d.epending on
the type of'so.cket the message is received frOID; see 8ocket(2).
If no messages are available at the socket, the receive call waits for a message to arrive, unless the

socket is nonblocking (see ioctl(2)) in which case a cc of -1 is retu:rned with the external variable
errno s,et to EWOULDBLOCK.
'
The 8elect(2) call may be used to determine when more data arrives.
The jlo.g8 argument to a send call is formed by or'ing one or more of the values,
I/:denn.e MSG_PEEK
#define MSG~OOB

Ox}

Ox2

'* peek at incoming message *'
'* process out-or-band data *'

The rec"m8g can uses a msghdr structure to minimize the number of directly supplied parameters.
This structure has the foitowing form, as defined in <8J18/8ocket.h>:
strqct I1lsghdr {
caddr_t mSA-name;
'* optional address *'
int
mSLnamelen;
'* size of address L
struct iovec *msLiov;
'* scatter/gather array *'
int
msgjovlen;
I/: elements in mSLiov
caddr..J mSLaccrights;
access rights 6entLreceived
int
mSLaccrightslen;

''**

*

*' *'

};
Here msg_nome and m8g_nome/en specify the destination address if the socket is unconnected;
m80_1t,Ome may be ghoen as a null pointer if no names are desired or required~ The m86_io" and
m8g_io"len describe the scatter gather locations, as described in reod(2). Access rights to be sent

74

Last change: 4 January 1984

Sun Release 1.1

RECV(2)

SYSTEM CALLS

along with the message are specified in

maU_(JccrightB,

RECV(2)

which has length

mBU_(Jccrightslen.

RETURN VALUE
These calls return the number of bytes received, or -1 if an error occurred.
ERRORS
The calIs fail if:
(EBADF)

The argument

B

is an invalid descriptor.

(ENOTSOCKt

The argument

B

is" not a socket.

(EWOULDBLOCK)

The socket is marked non-blocking and the receive operation would block.

(EINTRJ

The reeeive was interrupted by delivery of a signal before any data was
available for the receive.

(EFAULTJ

The data was specified to be received Into a non-exiStent or protected part
or the process address spaceo-

SEE ALSO
read(2), send(2), socket(!:}

Sun Release 1.1

Last change: 4 January 1984

75

SYSTEM CALLS

RENAME(2)

RENAME(2)

NAME

rename - change the name ot a file
SYNOPSIS

rename(from, to)
char *from, *tol
DESCRIPTION

Rename causes the link named from to be renamed as to. If to exists, then it is first removed.
Both from and to must be of the same type (that is, both directories or both non-directories), and
must reside on the same file system.
Rename guarantees that an instance of to will always exist, even if the system should crash in the
middle ot the opera.tion.
CAVEAT

The system can deadlock if a loop in the file system graph is present. This loop take. the lorm of
an entry in directory "a", say "a/loo", heinl a hard link to directory "b", and an entry in directory "b", say lib/bar", being a hard link to directory "a". When such a loop exists and two
separate processes attempt to perform "rename a/foo b/bar" and "rename b/bar a/foo", respectively, the system may deadlock attempting to lock both directories for modification. Hard links
to directories should be replaced by symbolic links by the system administrator.
RETURN VALUE
A 0 value is returned if the operation succeeds, otherwise rename returns -1 and the pobal vari-

able errno indicates tbe reason for the failure.
ERRORS

R ~mame will fail and neither of the argument files will be affected it any of the following are true:
(ENOTDIR)

A component of either path prefix is not a directory.

(ENOENT)

A component of either path prefix does not exist.

(EACCE5)

A component of either path prefix denies search permission.

(ENOENT)

The file named by from does not exist.

lEPERM)
(EXDEV)

The file named by from is a directory and the elrect:ve user ID is not super-user.

(EACCE5)

The requested link requires writing in a directory with a mode that denies write
permission.

lEROF5)

The requested link requires writing in a directory on a read-only file system.

lEFAULT)

Path points outside the process's allocated address space.
From is a parent directory of to.

(EINVAL)

The link named by to and the file named by from are on difterent logical devices
(file systems). Note that this error code will not be returned if the implementation permits cross-device links.

SEE ALSO
open(2)

76

Last change: 12 February 1083

Sun Release 1.1

RMDm(2)

SYSTEM CALLS

RMDffi(2)

NAME
rmdir - remove a directory file
SYNOPSIS

rmdlr(path)
char ·pathl
DESCRIPTION
Rmdir removes a directory file wh06e name is given by path. The directory must not have any
entries other than "." and " .. ".
RETURN VALUE
A 0 is returned if the remove succeeds; otherwise a -1 is returned and an error code is stored in
the global location errnD.
ERRORS
The named file is removed unless one or more of the following are true:

(ENOTEMPTY) The named directory contains files other than H." and H ..." in it.

lEPERM)

The pathname contains a- character with the high-order bit seC.

[ENOENT)

The pathname waa tOG-lOng.

(ENOTDmJ

A component of the patti prefix is not a directory.

[ENOENTT

The named file does DDt exist.

(EACCES)
(EACCES)
(EBUSY)
(EROFS)

A component 01 the path prefix denies search permission.

(EFAUL TJ

P atA points ou tside the process's alrocated address Ipace.

(ELOOP)

Too many symbolic links were encountered in tranllating the pathnameO-

Write permission is denied on the directory containing the nnt to be removed.
The directory to be removed is the mount point for a mounted file system.
The directory entry to be removed resides on a read-only file system.

SEE ALSO

mkdir(2),· unlink(2)

SUD

Release 1.1

Last change: 2 July 1983

77

SELECT(2)

SYSTEM CALLS

SELECT (2)

NAME

select - synchronous I/O multiplexing
SYNOPSIS

:f/:lnclude 
ntd. == select(width, readtd., wrltetd., execpttd., timeout)
lnt width, *readtds, *wrltetds, *execpttds.
struct tlmeval*tlmeout.
DESCRIPTION
Seleel examines the I/O descriptors specified by the bit masks read/dB, write/dB, and ezecpt/dB to
see il they are ready lor reading, writing, or have an exceptional condition pending, respectively.
Width is the number 01 significant bits in each bit mask that represent a file descriptor. Typically
width has the value returned by getdtableBize (e) for the maximum number 01 file descriptors or is
the constant 32 (number 01 bits in an int). File descriptor / is represented by the bit "1< 
#lnclude 
cc
aeDd(a, ma., leD, fta••)
lnt ee, a.
char
lpt len, ftagl,
~ ==.endto(., m.s, len, ftap, to, toleo)
cc,
{ttlar *mss;
~t lent ftaglJ.Itruct lockaddr *to.
~t toienf
Hndmas(., maSt- fta••)
tnt ee, at
Itruet- m1lhdr mllDf
lnt ftapl:.

==

*JIlI.'
trt I,

ce ..

DESORIPTION .
S IS a I50Cket created with Bocket(2). Send, Benifo, and Bentlmsg are used to transmit a message to
another-- socket. Senti may- be used only wlien the socket is in a cormected state, while Bentlto and
BendmB, may be used at any timeoThe addre88 or the target is given by to with tolen specifying its size. The length of the message
is .liven by len. It the message is too tong to- pass atomically. through the underlying protocol,
tILen the error EMSGSIZE is returned, and the message is not traMmi.tted ..
No indication or tailure to deliver is implicit in a Bend. Return values

ot -1 indicate some locally

detected errors.
It no messages space is available at the socket to hold the message to be transmitted, then Bend
normally blocks, unless the socket has been placed in non-blocking i/o mode. The Belect(2) call
may be used to determine when it is possible to send more data~
The ./ltJgB parameter lJIay be set to SOF_OOB to send "out-or-band" data on sockets which support this notIon (e.g. SOCK_STREAM)'
See ucv(21 fo~ , description

or the. nngAtlr structure.

RETURN VALUE
,
The call returns the number 01 characters sent, or

-1 it an error occarred.-

ERRORS

(EBADFJ

An invalid descriptor-waa specified.

~NOTSOGKI

The ar&ument , .. not a socket ..

(EFAULT}

(EMSGSIZE)

. ~n invalid uler space address was specified tor a parameter.
The socket requires that message be sent a.tomically, and the size of the
message to be sent made this impossible.

(EWOULDBLOCK) -The socket is marked noh-blocking and the requested operation would
block.
SEE ALSO
recv(2), 8lkket(~)

SUD

Release 1.1

Last change: 4 January 1984

79

SYSTEM CALLS

SETGROUPS ( 2 )

SETGROUPS ( 2)

NAME

setgroups - set group access list
SYNOPSIS

#lnelude 
setgl'oups(DIJI'oupa, gtdset)
lnt DIJI'OUp., *gldset,
DESCRIPTION
Setgroupa sets the group access list of the current user process according to the array gidael. The
parameter ngroupa indicates the number or entries in the array and must be no more than
NGRPS, as defined in .
Only the super-user may set new groups.

RETURN VALUE
A 0 value is returned on succel!l8, -Ion error, with a error code stored in errno.
ERRORS

The aetgfoup, call wiD fail if:
IEPERM]

The caller is not the super-user.

IEF AUL T)

The address specified for gidBeI is outside the process address space.

SEE ALSO
getgroups(2), initgroups(3)

80

Last change: 7 July 1983

Sun Release 1.1

SYSTEM CALLS

SETPGRP(2)

SETPGRP(2)

NAME
setpgrp - set process group
SYNOPSIS

aetplrp(pld, PBrP)
lnt pld, Plrp,
DESCRIPTION
Setp"p sets the process group or the specified process pid to the specified pgrp. If pid is zero, then
the call applies to the current process.

If the invoker is not the super-user, then the affected process must have the same- effective user-id
as the invoker or be a._descendant or the invoking process.
RETURN VALUE
Selpgr, returns when the operation W3.fL successful. It the request failed, -1 is returnea and the
global variable errnD indicates the reasoD.
ERRORS

Set"r, wiD fail and

~he

process group win not be altered it one or the following

occur~

(ESR CHI

The requested process does not exist.

(EPERM)

The- effective user ID of the requested process is di1ferent rrom that or the caller
and the process is not a-- descendent or the calling pto£ess.

SEBALSO

getpgrp(2)

SUD

Release 1.1

Last change: 12 February 1983

81

SYSTEM CALLS

SETQUOTA ( 2 )

SETQUOTA(2)

NAME

setquota - enable/disable quotas on a file system
SYNOPSIS

setquota(speclal, file)
char *speclal, *flle;
DESCRIPTION

Disc quotas are enabled or disabled with the .dquottJ call. SpecitJI indicates a block special device
on which a mounted file system exists. It JUe is nonzero, it specifies a file in that file system from
which to take the quotas. If JUe is 0, then quotas are disabled on the file system. The quota file
must exist; it is normally created with the quottJcheck(8) program.
Only the super-user may turn quotas on or 01.
SEE ALSO

quota(2), quotacheck(8), quotaon(8)
RETURN VALUE
A 0 return value indicates a successful call. A value of -1 is returned when an error occurs and

errno is set to indicate the reason for failure.
ERRORS

SelquottJ will fail when one of the following occurs:
(NODEV)

The caller is not the super-user.

(NODEV)

SpecitJI does not exist.

(ENOTBLK)

SpecitJl is not a block device.

(ENXIO)

The major device number of .pecitJl is out of range (this indicates no device
driver exists for the 38sociated hardware).

(EPERMi

The pathname contains a character with the high-order bit set.

(ENOTDffi)

A component of the path prefix in file is not a directory.

(EROFS)

File resides on a read-only Ille system.

(EACCES)

File resides on a file system dilerent trom .pecitJI.
File is not a plain file.

(EACCES)

BUGS
The error codes are in a state of disarray; too many errors appear to the caller as one value.

82

Last change: 29 August 1983

SUD

Release 1.1

SETREGID ( 2)

SYSTEM CALLS

SETREGID ( 2 )

NAME
setregid - set real and effective group ID
SYNOPSIS

aetreald(rsld, esld)
tnt "Sid, epd;
DESCRIPTION
The real and effective group ID's of the current process are set to the arguments. Only the
super-user may change the real group IDof a process. Unpriviledgecl users may change the
effective group ID to the real group ID, but to no other.

Supplying a value or -1 for either the real or effective group ID rorces the system to suhstitute the
current ID in place or the -1 parameter.
RETURN VALUE

Upon suecessrul completion, a value
errno is set to indicate the error.

or 0 is returned ..... Otherwise, a value of -1 is returned and

ERRORS

[EPERM)

The current process is not the super.user and a change other tDan changing the
effective group-id to the real group-id was specified.

SEE ALSOgetgid(2); setreuid{2}, setgrd{3C)

SUD

Release 1.1

Last change: 12 February 1983

83

SYSTEM CALLS

SETREUID ( 2 )

SETREUID ( 2 )

NAME

setreuid - set real and effective. user ID's
SYNOPSIS

aetreuld(ruld, euld)
.tnt ruld, euld.
DESCRIPTION

The real and effective user !D's 01 the current process are set according to the arguments. If ruid
or euid is -1, the current uid is filled in by the system. Only the super-user may modify the real
uid 01 a process. Users other than .the super-user. may change the effective uid 01 a process only to
the realuid.
RETURN VALUE

UpoD8uccessful completion, a value 01 0 is returned. Otherwise, a value 01 -lis returned and
errnoisset to. indicate the error.
ERRORS
[EPERM)

The current proce88 is not the super-user and a change other than changing the
effective' user-id to the real user-id was specified.

SEE ALSO

getuid(2), setregid(2), setuid(3)

84

Last change: 12 February 1983

Sun Release 1.1

SHUTDOWN ( 2)

SYSTEM CALLS

SHUTDOWN ( 2 )

NAME
shutdown - shut down part of a full-duplex connection

SYNOPSIS

ahutdown(a, how)
lnt a, hOWl
DESCRIPTION
The ,hutdown call causes all or part of a full-duplex connection on the socket associated with 8 to
be shut down. It how is 0, then further receives will be disallowed. If how is 1, then further sends
will be disallowed. If how is 2, then further sends and receives wiD be disallowed-.
DIAGNOSTICS
A 0 is returned if the call succeeds, -1 if it fails.
ERRORS
The call succeeds unless:

(EBADF)

Sis Dot a valid descriptor.

[ENOTSOCK}

S is a file, Dot a societ.

(ENOTCONN) Tlie specified socket- is not connected.
SEE ALSO
conDect(2},locket(2r
BUGS
The Aow values should be defined cOBstants.

SUD

Release 1.1

Last change: 29 August 1983

85

SYSTEM· CALLS

SIGBLOCK ( 2 )

SIGBLOCK ( 2 )

NAME

sigblock - block signals
SYNOPSIS

== slsbloek(mask),

oldmaak
tnt ma.k,

DESCRIPTION
Sigblock adds the signals specified in mca,k to the set ot signals currently beinl blocked trom
delivery. Signal i is blocked it the i-I'th bit in mca,k is a 1. The previous mask is returned, and
may be restored usinl ,ig,dmca,k(2).

It is not pOl58ible to block
by the system.

SIGK~L,

SIGSTOP, ()r SIGCONT; this restriction is silently imposed

RETURN·VALUE

The previous set of masked signals is

returned~

SEE ALSO

kill(2), sigvec(2), sigsetmask(2),

86

Last change: 4 January 1984

Sun Release 1.1

SIGPAUSE ( 2)

SYSTEM CALLS

SIGP AUSE ( 2 )

NAME

sigpaule - atomically release blocked signals and wait for interrupt
SYNOPSIS

Ilgpaule(llsmalk)
lDt Ilsmaakl
DESCRIPTION
SigplJu,e assigns ,igmlJ,i to the set ot masked signals and then waits for a signal to- arrive~ on
return the set ot masked signals is restored. SigmtJ8i is usually 0 to indicate that no signals are
now to- be blocked. SigptJu,e always terminates by being interrupted. returning EINTR.

In normal usage, a signal is blocked using 8ig6Iock(2), to begin a critical section, variables
modified on the occurance ot the signal are examined to determin ... that there is no work to be
done~ and the process- pauses awa.iting work by using 8igptJu,e with the maak returned by 8il1h1ock.
SEE ALSO
sigblock(2), sigvec(2)

SUD

Release 1.1

Last change: 7 July 1983

87

SYSTEM CALLS

SIGSETMASK ( 2 )

SIGSETMASK ( 2)

NAME

sigsetmask - set current signal mask
SYNOPSIS
algset mask ( mask),
tnt mask,
DESCRIPTION
Sig8etmo8k sets the current signal mask (those signals which are blocked from delivery). Signal i
is blocked if the i-1 'th bit in m08k is a 1.

The system quietly disallows SIGKILL, SIGSTOP, or SIGCONT to be blocked.
RETURN VALUE

The previous set or masked sign ala is returned.
SEE ALSO
kill(2), sigvec(2), sigblock(2), sigpause(2)

88

Last change: 4 January 1984

Sun Release 1.1

SYSTEM CALLS

SIGSTACK (2 )

SIGSTACK ( 2 )

NAME

siptack - set and/or get signal stack context
SYNOPSIS

*lDelude 
.truet .•llItaek {
eaddr_t .S_IPI
lDt
.._on.tack.

.

}

• taatack(aa, 0 ••)
.truet .I..taek ...,

·0•• ,

DESCRIPTION

Bi,lltJc" allows users to define an alternate stack on which signals are to be processed. If 88 is
non-zero, it specifies a .',ntJI
on which to deliver signals and tells the system if the process is
currently executing on that stack. When a signalls action indicates ita:-handler should execute on
the signal stack (specified with a ai,uc(2) call),. the system clecks to see if the process is
currently executing 'on that stack. If the process is not currently executing on thtt signal stack,
the system arranges a switch to the signal stack for the duration of the signal handler's execution.
If "" is non-zero, the cunent signal stack state is returned.

"4C"

NOTES
,:~,
Signal stacks are not "grown" automatically, Ii is done tor tie normal stack. II the stack
overflow. unpredictable results may occur.
RETURN VALUE
Upon successful completion, a value of 0 is returned. Otherwise. a value of -1 is returned and
err,., is eet to indicate the error.
"
ERRORS

Si"'tJci will fail and the li,nal Itack context will remain 1111c)aiIged if one of the following
occurl.
I~AULTJ

Either II or "" point. to memory which is not a valid part of the process
addre. space.

SEE ALSO
8i,"c(2), setjmp(3) ,

Sun Release 1.1

Last change: 29 August 1983

89

SYSTEM CALLS

SIGVEC(2)

SIGVEC(2)

NAME

sigvec - software signal facilities
SYNOPSIS

:fI:lnelude < 11snalctb >
Itruet Iisvee {
lnt
(·IV_handler)(),

Int
Int

lv_malt,
IV_onltack,

}J
Ilsvee(ll., vee, ovee)
Int
Itruet Iisvee ·vee, ·OV8C,

II.,

DESCRIPTION

The system defines a set of signals that may be delivered to a procell. Signal delivery resembles
the occurence of a hardware interrupt: the silnal il blocked from further occurrence, the current
process context il saved, and a new one is built. A procesl may specify a handler to which a signal is delivered, or specify that a signal is to be blocked or ignored. A procesl may also specify
that a default action is to be taken by the system when· ,.a signal occurs. Normally, signal
handlers execute on the current stack of the procesl. This may be chanled, on a per-handler
baais, so that lilnals are taken on a lpecial lignal flack.
All signals have the same priorit,. Signal routines execute with tbe signal that ~aused their invocation blocked, but other signals may yet occur. A global ,igna' ma,k definel the set of signals
currently blocked from delivery to a process. The signal muk for a process is initilized from that
of its parent (normally 0). It may be chanled with a ,igblock(2) or ,ig,etma,k(2) call, or when a
silnal ia delivered to the procell.
When a silbal condition arisel for a procell, the signal is added to a set of signatl pending for the
procesl. If the signal is not currently blocked by the process then it is delivered to the procesl.
When a silnal is delivered, the current Itate of the procell il saved, a new signal mask is calculated (aa deecribed below), and the signal handler il invoked. The call to the handler is arranged
10 that if the lignalhandlinl routine returnl normally the procesl will resume execution in the
context from before the silnal's delivery. If the procell wishel to resume in a dilerent context,
then it must arraDI~ to restore the previoul context itself.
When a signal is deliverea to a process a new signal muk is installed for the duratioD of the process' signal handler (or until a ,ig610ck or ,ig,elma,k call is made). This mask is formed by takinl
the current signal mask, adding the signal to be delivered, and or'ing in the signal muk auociated with the handler to be invoked.

Sigvec assigns a bandler lor a specific signal. If vec is non-zero, it specifies a handler routine and
muk to be used."when deliverinl the specified silnal. Further, if ,v_on"ack is 1, the system will
deliver the silnal to the process on a 'ignal ,tack, specified with ,ig,tack(2). If ovec is non-zero,
the previous handlinS· information for the signal is returned to the user.
The following is a
SIGHUP
1
SIGINT2
SIGQUIT
3·
SIGILL
4·
SIGTRAP
o·
SIGIOT
6*
SIGEMT
7·
SIGFPE
8·
SIGKILL
9

90

list of all silnals with names as in the include file <,igntJI.h>:
hangup
interrupt
quit
illegal instruction
trace trap
lOT instruction
EMT instruction
fioating point exception
kill (cannot 'be caught, blocked, or ignored)

Last cbange: 7 July 1983

Sun Release 1.1

SYSTEM CALLS

SIGVEC(2)

SIGBUS
SIGSEGV
SIGSYS
SIGPIPE
SIGALRM
SIGTERM
SIGURG
SIGSTOP
SIGTSTP

10*
11*
12*
13
14
15
16
17t
1St
~IGCONT
19.
AIGCHLD
20.
~IGTTIN
21 t
SIGTTOU
22t
SIGIO
23
SIGXCPU
24
SrGXFSZ
25
SIGVTALRM 2G
SIGPROF
'n
SIGWINCH 28

SIGVEC( 2)

bus error
segmentation violation
bad argument to system call
write on a pipe with no one to read it
alarm clock
software termination signal
urgent condition present on socket
stop (cannot be caught, blocked, or ignored)
stop signal generated trom keyboard
continue after stop (cannot be blocked)
child status has changed
background read attempted trom.- control terminal
background write attempted to control terminal
i/o is possible on a descriptor (see fcntl(2))
cpu time limit exceeded (see 8etrlimit(2))
file size limit exceeded (see 8etrlimit(2))
virtual time alarm (see lelitimer(2})
profiling timer alarm (see letitimer(2})
window changed (see win (4S))

The starred sign'ls in the list above cause a core image if not caught or ignored.
Once a signal handler is installed, it remains instaHed until another ligvec call is made, or an
ezecve(2) is performeci. The default action for a signal may be reinstated by setting Iv_hondler to
SIG.J)FL; this default is termination (with a core image for starred signals) except for signals
marked with. or t. Signala marked with·. are discarded if the action is SIG_DFL; signals
marked with t cause the procesl to stop. It Iv_hondler is SIG_IGN the signal is subsequently
ilnored, and pendin, instances of the signal are discarded.
It a caught signal occurs during certain system calls, causing the call to terminate prematurely,
the call is automatically restarted. In particular this can occur during a reod or write(2) on a slow
device (such I I a terminal; but not a file) and during a woit(2).

After a /Dri(2) or v/ork(2) the child inherits all signals, the signal mask, and the signal stack.
The ezeclle(2) call resets all ca~.ht signals to default action; ignored signals remain ignored; the
sipal milk rema.ins the same; the signal stack state is reset.
kOTES '.
The mask specified in lIee is not allowed to block SIGKILL, SIGSTOP, or SIGCONT. This is
done silently by the system.
RETURN VALUE
A 0 value indicated that the call succeeded. A -1 return value indicates an error occured and
errno i. let to indicated the reason.
ERRORS

Sigllee will fail and no new signal handler will be installed if one ot the following occurs:
(EFAULTJ
1

Either lIec or .Dllec points to memory which is not a valid part of the process
addre. space.

(~ALI

Si, is Dot a valid signal number.

(EINvALJ

An attempt is made to ignore or supply a handler for SIGKILL or SIGSTOP.

An attempt is made to ignore SIGCONT (by default SIGCONT is ignored).
[EINVALJ
SEE ALSO
.
kill(I), ptracet~), kill (2), sigblock(2), sigsetmask(2), sigpause(2) sigstack(2), tdgvec(2), setjmp(3),
tty(4)

Sun Release 1.1

Last change: 7 July 1983

91

SIGVEC(2)

SYSTEM CALLS

SIGVEC(2)

NOTES (VAX-II)

The handler routine can be declared:
handler(sig, code, scp)
int sig, code;
struct sigcontext ·scp;
Here ,ig is the signa1 number, into which the hardware faults and traps are mapped aa defined
below. Co de is a parameter which is either a constant as given below or, for compatibility mode
faults, the code provided by the hardware (Compatibility mode faults are distinguished from the
other SIGILL traps by having PSL_CM set in the psi). Scp is a pointer to the ,igconle:d structure (d~fined in < BigJltll.h », used to restore the context from before the signal.
The following defines· the mappinl of hardware traps to signals and codes. All of these symbols
are deflned in < ,ignGI. h > :
Code
Hardware condition
Signal
Arithmetic traps:
Integer overflow
SIGFPE
Integer division by ~ero
SIGFPE
Floating overflow trap
SIGFPE
Floating/decimal division by zero SIGFPE
Floating underflow trap
SIGFPE
Decimal overflow trap
SIGFPE
Subscript-range
SIGFPE
Floating overflow fault
SIGFPE
Floatinl divide by zero rault
SIGFPE
Floating underllow rault
SIGFPE
Length access control
SIGSEGV
Protection violation
SIGBUS
Reserved instruction
SIGILL
Customer-reserved instr.
SIGEMT
Reserved operand
SIGILL
Reserved addressing
SIGILL
Trace pending
SIGTRAP
Bpt instruction
SIGTRAP
Compatibility-mode
SIGILL
Cbme
SIGSEGV
Chms
SIGSEGV
Chmu
SIGSEGV

FPE_INTOVF_TRAP
FPE_INTDIV_TRAP
FPE'yLTOVF_TRAP
FPEYLTDIV_TRAP
FPE_FL TUND_TRAP
FPE_DECOVF_TRAP
FPE_SUBRNG_TRAP
FPE_FLTOVF_FAULT
FPE.YLTDIV_FAULT
FPE_FLTUNDj'AULT
ILLJtESAD_FAULT
ILL_PRIVIN_F AUL T
ILL..RESOP_FAUL T
hardware supplied code

BUGS
This manual page is confusing.

92

Last change: 7 July 1983

Sun Release 1.1

SYSTEM CALLS

SOCKET(2)

SOCKET(2)

NAME
socket ::- create an endpoint for communication
SYNOPSIS

#lnc:1ude 
#Include 
a
aocket(af, type, protocol}
Int a, ai, type, protocol,

==

DESCRIPTION
Socket creates an endpoint for communication and returns a descriptor.
Tbe 0/ parameter specifies an address format with which addresses specified in later operations
uainl the 80Cket should be interpreted. These formats are defined in the include file
< 81/s/l-Ocket.h>. The currently understood formats are
AF _UNIX
AF JNET
AFYUP

AFJMPLINK

(UNIX path names},
(ARPA InCernet addressest,
(Xerox PUP-I Internet addresses), ana
(IMP "hOISt at IMP" addresses).

The socket has the indicated type which specifies the semantics of communication. CUrrently
defined types are~
SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_SEQPACKET
SOCK_RDM
A SOCK_STREAM type provides sequenced, reliable, two-way connection based byte streams
with an out-ot-band data transmission mechanism. A SOCK_DGRAM socket supports datagrams
(conneetionle88, unreliable messages ot a fixed (typically small) maximum length}. SOCK_RAW
sockets provide access to internal network interfaces. The types SOCK_RAW, which is available
only to the'luper-uset, and SOCK_SEQPACKET and SOCK_RDM,which are planned, but not
yet implemented, are D,ot described here.
The protocol specifieil. particular protocol to be used with the socket. Normally only a single
protocol exist; to support a particular socket type using a given address format. However, it is
possible that many protocols may exist in which case a particular protocol must be specified in
this manner. The protocol number to use is particular to the "communication domain" in which
communication is to take place; see ,er.nce,(3N) and protocol,(3N}.
Sockets 01 type SOCK_STREAM are tull-duplex byte streams, similar to pipes. A stream socket
must be in a connected state betore any data may be sent or received on it. A connection to
another soc-ket is created with a connect(2} call. Once connected l data may be transferred using
reGd(2) and write(2} calls or some variant ot the ,end(2) and recv{2} calls. When a session has
been completed a clo,c(2) may be performed. Out-ot·band data may also be transmitted as
described in ,end,t2) and received as described in recu(2}.
The communic~tions protocols used to implement a SOCK_STREAM insure that data is not lost
or duplicated. It ~ piece of data tor which the peer protocol has buffer space cannot be succes&lully transmit~d witllbf a reasonable length or time, then the connection is considered broken and
calla will indicate an error with -1 returns and with ETIMEDOUT as the specific code in the global variable errno. The protocols optionally keep sockets "warm" by forcing transmissions
roughly every minute hl the absence of other activity. An error is then indicated if no response
can be elicited on an'~o·therwise idle connection tor a extended period (e.g. 5 minutes). A SIGPIPE signal is raised it a process sends on a broken stream; this causes naive processes, which do
not handle the signal, ,to exit.

Sun Release 1.1

Last change: 29 August 1983

93

SYSTEM CALLS

SOCKET (2)

SOCKET(2)

SOCK_DGRAM &.nd SOCKJtAW sockets allow sending of datagrams to correspondents named
in Bend(2) calls. It is also possible to receive datagrams at such a socket with recv(2).
An !cntl(2) call can be used to specify a process group to receive a SIGURG signal when the out,.
of-band data arrives.
The operation of flockets is controlled by socket level optionB., These options are defined in the
file  and explained below. Setsockopt and IdBockopt(2) are used to set and get
options, respectively.
SO_DEBUG
tum on recording ot debugging information
SO_REUSEADDR
allow local address reuse
SO_KEEPALIVE
keep connections alive
SOJ)ONTROUTE
do no apply routing on outgoing messages
SO_LINGER
linger on close if data present
SO.J)ONTLINGER
do not linger on close
't

SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR indicates
the rules used in validatingaddres8es supplied in a 6ind(2) call should allow reuse of local
addre88es. SO _KEEP ALIVE enables the periodic transmission of messages on a connected socket.
Should the connected party fail to respond to these messages, the connection is considered broken
and processes using the socket are notified via a SIGPIPE signal. SO_DONTROUTE indicates
that outgoing mes8~ges should bypass the standard routing facilities. Instead, messages are
directed to the appropriate network interface according to the network portion of the destination
addre88. SO_LINGER and SO.J)ONTLINGER control the actions taken when unsent messags
are queued on socket and a cl!,Ie(2) is performed. It the socket promises reliable delivery of data
and SO~INGER is set, the system will block the process on the clole attempt until it is able to
transmit the data or until it decides it is unable to deliver the information (a timeout period,
termed the linger interval, is specified in the letBociopt call when SO_LINGER is requested). If
SOJ)ONTLINGER is specified and a close is issued, the system will process the close in a
manner which allows the process to continue as quickly as possible.
RETURN VALUE
A -1 is retutned if an error occurs, otherwise the return vahle is a descriptor referencing the
socket~

ERRORS
The Bocket call fails if:
(EAFNOSUPPOR TJ

The specified addresa family is not supported in this version of the system.

(ESOCKTNOSUPPOR TJ
The specified socket type is Dot supported in this address family.
(EPROTONOSUPPORTI
_
The specified protocol is not supported.

(EMF IL EJ

The per-process descriptor table is full.

(ENOBUFS)

No buffer space is available. The socket cannot be created.

SEE ALSO
accept(2), bind(2), con·ned(2), getsockname(2), getsoetopt(2), ioctt(2), Iisten{2), recv(2), select(2),
send(2), shutdown(2), socketpair(2)
"A 4.2BSD Interprocess Communication Primer".
BUGS
The use of keepalives is a questionable feature for this layer.

94

Last change: 29 August 1983

Sun Release 1.1

SYSTEM CALLS

SOCKETPAIR ( 2)

SOCKETP AIR ( 2 )

NAME
80cketpair - create a pair or connected sockets
SYNOPSIS

*lDclude 
#lnclude 
aocketpall'(d, type, protocol,
...t d, type, protocol,
lnt .v(11,

BY)

DESCRIPTION
The 8tJcketptJfr system call creates an unnamed pair ot connected aockets in the specified domain
d, or tlie specified 'llpe and using the optionally specified protocol. The descriptors used in
referencing the new sockets are returned in IV[O) and IV[I). The two sockets are indistinguishable.

DIAGNOSTICS
A 0 is returned it the call succeeds, -1 if it rails.
ERRORS
The call suc_ceeds unless:.-

(EMFILEJ

Too many descriptors are in use by this- process.

(EAFNOSUPPOR TJ The specilled address tamBy is not supportect-on· thfs macliine.
(EPRO TO NO SUPPORT)
The specified protocol is not supported on this machine.
(EOPNOSUPPOR TJ The specified protocol does not support creation ot SocKet pairs.

[EFAUL TJ

The address IV does not specify a valid part or the process address space~

SEE ALSO
read(2), write(2), pipe(2)

BUGS
This call is currently implemented only tor the UNIX domain.

Sua Release 1.1

Last change: 29 August 1983

95

STAT(2)

SYSTEM CALLS

STAT(2)

NAME

stat, Istat, fstat - get file status
SYNOPSIS

#lnclude 
#lnclude 
.tat(path, bul)
chal' *path;
.tl'uct stat *buf.
latat(path, bul),
chal' *path;
.tl'uct .tat *buf.
f.tat(fd, bul)
lntfd,
.tl'uct .tat *buf,
DESCRIPTION
Stot obtains information about the file poth. Read, write or execute permission of the named file
is not required, but all directories listed in the path name leading to the file must be reachable.

L8to' IS like 8tOt except in the case where the named file is a symbolic link, in which case lstot
returns information about the link, while BtOt returns information about the file the link references.
F8tot obtains the same information about an open
as would be obtained by an open call.

81. referenced by the argument descriptor, such

Bul is a pointer toa BtOt structure into which information is placed concerning the file. The contents of the structure pointed to by 6ul
struct fStat

t

dev_t
ino_t
u..short
short
short
short
dev_t
off_t
time_t
int
time_t'
int
time
.......t
int
long

Ion.
long

*'
*'*'
*'
*'

st_dev;
'* device inode resides on *'
st_ino;
'* this inode's number
st_mode;
protection*,
st_nlink;
Dumber or hard links to the file
st_uidi
user-id or owner
st-lid;
group-id of owner
st_rdev;
the device type, for inode that is device
st_size;
total size ~f file~t
st_atime;
file last access time
st_spare1;
st_mtimej
file last modify time
st_spare2;
st_ctime;
'* file last status change time
st_spare3;
st_blksize;
optimal blocksize for file system i'o ops
st_blocks;
actual number of blocks allocated
st_spare4[2J;

'''***
''**
''**
'*
''**

*'

*'

*'

*' *'

};
Time when file data was last read or modified. Changed by the following system
calls: mknod(2), utime8(2), reod(2). write(2), and truncote(2).For reasons of
efficiency st_atime is not set when a directory is searched, although this would be
more logical.
9-'

Time when data was last modified. It is not set by changes 01 owner, group, link
count, or mode. Changed by the following system calls: mknod(2), utime8(2),

96

Last change: 6 March 1984

SUD Release 1.1

SYSTEM CALLS

STAT(2)

STAT(2)

write(2).
Time when file status was last changed. It is set both both by writing and changing
the i-node. Changed by the following system calls: chmod(2) chown(2), link(2),
mknDd(2), unlink(2), utime,(2), write(2), truncate(2).

''** *'*'
''**
*'
*'
''**
''** *' *'
''**
''**
'*

The status inrormation word ''-mode has bits:
#define S_IFMT
0170000
type of file
#define S_IFDffi
0040000
directory
#define S_IFCHR
0020000
character special
#define S_IFBLK
0060000
block special
#define S_IFREG
0100000
regular .,
#define S_IFLNK
0120000
symbolic link
*define S_IFSOCK
0140000
socket
*define S_ISUJD
0004000
set user id on execution
*define S_ISGJD
0002000
set group id on execution
*define S_ISVTX
0001000
save swa.pped text even after use
*define S_mEAD
0000400
read permission, owner
*define S_IWRITE
0000200
write permission, owner
*define S_IEXEC
0000100
execute/search permission, owner
The mode bits 0000070 and 0000007 encode group and others permissions (see chmod(2».

*'*'
*'*' *'
*'

When Id is associated with a pipe, Ista' reports an ordinary file with an i-node number, restricted
permissions, and a not necell8arily meaningful length.

RETURN VALUE
Upon luccessful completion a value of 0 is returned. Otherwise, a value of -1 is returned and
errno il set to indicate the error.

ERRORS

S'a' and "'0' wiD fail if one or more of the following are true:

(ENOTDm)

A component of the path prefix is not a directory.

IEPERM]

The pathname contains a character with the high-order bit set.

(ENOENT)

The pathname W81 too long.

(ENOENT)
(EACCESJ

The named file does not exist.
Search permission is denied for a compoDent of the path prefix.

(EFAULT)

Bulor name points to an invalid address.

F,'al will fail it one or both of the following are true: .
(EBADFJ

Filde~1s

(EFAUL TJ
IELOOP)

Bul Points to an invalid address.

not a valid open file descriptor.

roo many symbolic links were encountered in translating the pathname.

OAVEAT

I

The fields in the stat . structure currently marted ',-'porel, ',-'poree, and ''-,pare9 are present
in preparation for inode time stamps expanding to 64 bits. This, however, can break certain proIrams which depend on the time stamps being contiguous (in calls to utimes(2)).
SEE ALSO
'
chmod(2), c~own(2), utimes(2)

BUGS
Applyinl/,to'to a socket returns a zero'd buffer.

SUD

Release 1.1

Last change: 6 March 1984

97

SWAPON(2)

SYSTEM CALLS

SWAPON(2)

NAME

swapon - add a swap device for interleaved paging/swapping
SYNOPSIS

8wapon(speclal)
char *spec1al,
DESCRIPTION
SWGpon makes the block device speciGI available to the system for allocatioD for paging and swapping. The names of potentially available devices are known to the system and de&Ded at system
configuration time. The size of the swap area on eciGl is calculated at the time the device is
first made available for swapping.

I,

SEE ALSO

s"apon(8), config(8)

BUGS
There is no way to stop swapping on a disk

80

that the pack may be dismounted.

This call will be upgraded in future versions of the system.

98

Last change: 29 August 1983

Sun Release 1.1

SYMLINK(2)

SYSTEM CALLS

SYMLINK(2)

NAME
symlink - make symbolic link to a file
SYNOPSIS

8),mllnk(name-t, Dame!)"
char *namel, *nameJ.
DESCRIPTION
A symbolic link Dame! is created to Damel (Damet is the name or the file created, namel. is the
string used in creating the symbolic link). Either name may be an arbitrary path name; the files
need Dot be on the same file system.
RETURN VALUE

Upon successful completion, a zero value is returned. It an error occurs, the error code is stored
in errno and a -1 value is returnect.
ERRORS
The symbolie link is made unless on or more or the Collowiag are true:

[EPERM:}

Either Damel or namet conta.ins a character with the higb-order bit setr

[ENOENT)

One or the pathnames specified was too loogo-

(ENOTDm)

A component oC-the nameD prefix is not a directory.

IEEXISTl

Na~t already exists ..

(EACCES)

rEF AUL TJ

A component or the namet path prefix denies search permission.
The file namet would reside on a read-only file system.
Nome) or namet points outside the process's allocated address space.

IELOOP)

Too ma.y symbolic links were encountered in translating the pathname.

(EROFS)

SEE ALSO
link(2), In(l), unlink(2)

Sun Release 1.1

Last change: 29 August 1983

99

SYNC(2)

SYSTEM CALLS

SYNC(2)

NAME

sync - update

super~block

SYNOPSIS
8ync()
DESCRIPTION
Sync causes all information in core memory that should be on disk to be written out. This

includes modified super blocks, modified i-nodes, and delayed block I/O.
Sync should be used by programs which examine a file system, tor example Jsck, dJ, etc. Sync is
Illandatory before a boot.
SEEALSP

(81nc(2), sync(8), cron(8)

BUGS
The writing, although scheduled, is not necessarily complete upon return trom sync.

100

Last change: 12 February 199a

SUD

Release 1.1

SYSCALL(2)

SYSTEM CALLS

SYSCALL(2)

NAME

syseall- indireet system call ' .
SYNOPSIS·
8Y8eaU(number.........)
DESORIPTION
SIIBctJllperforms the- system eall whose assembly language interrace has t..e speciffed number, and
_rgwnenu arg •••.
The register dO- value or tbe system call is returned.
DIAGN~STICS

WheD the C.bit is set, 'IIBcaU returns -1 and sets the external variable ermtt (see intro(2))_

BUGS
':fUlere is-no way to simulate system calls such as p.ip~(2), which return values in register dl.

Sun Release 1.1

Last change: 29 August 1983

101

TRUNCATE(2)

SYSTEM CALLS

TRUNCATE(2)

NAME

truncate, rtruncate - truncate a file to a specified length
SYNOPSIS

truncate(path, length)
char ·path.
tnt lensth.
ttruncate(rd,lensth)
tnt rd, lensth.
DESCRIPTION

Truncate causes the file named by path or rererenced by /4 to be truncated to at most length bytes
in size. If the file previously was larger than this size, the extra data is lost. With /truncate, the
file must be open ror writing.
RETURN VALUES

A value or 0 is returned if the call succeeds. It the call tails a -1 is returned, and the global variable errno specifies the error.
ERRORS

Truncate succeeds unless:
The pathname contains a character with the high-order bit set.
(EPERM)
The pathna.me was too long.
(ENOENT)
A component of the path prefix of pot" is not a directory.
(ENOTDIR)
The named file does not exist.
[ENOENT)
A component of the path prefix denies search permission.
[EACCES)
(EISDIR)
The named file is a directory.
The Jla~ed file resides on a read-only file system.
(EROF.S)
[ETXTBSY)
The file is a pure procedure (shared text) file that is being executed.
[EFAULT)
Nome points outside the process's allocated address space.
Ftruncate succeeds unless:
The /4 is not a valid descriptor.
[EBADFJ
(EINVAL)
The /d references a socket, not a file.
SEE ALSO

open(2)
BUGS

Partial blocks discarded as the result of truncation are not zero filled; this can result in holes in
files which do not read as zero.
These calls should be generalized to allow ranges or bytes in a file to be discarded.

102

Last change: 7 July 1983

SUD

Release 1.1

UMASK(2)

SYSTEM CALLS

UMASK(2)

NAME

umaak - set file creation mode mask
SYNOPSIS

Gumuk

== umUk(Dumaak)

Int oUlDNk, Dumalk.

DESCRIPTION
UmtJ8~ sets the processt-lt file mode creation mask to numtJ8k and returns the previous value of the
mask..- The low-order ~ bits or n.mtJH are used whenever a file is created, clearing corresponding..
hlts.in the file mode· (see cflmtHl(2)). This clearing allows each user to restriet~ the default aecess
his, fllea.

t,

The
,., value is Initially 022-{write accesl for owner only). The mask is Inherited by child processes.
RETURN V ALugT~e previous value or the file mode mask ii returned by the calL

SEE ALSP

c~;p1ocl(2)~ mknod{2},open(2)

Sun Release 1.1

Last change: 12 February 1983

103

SYSTEM CALLS

UNLINK (2)

UNLINK(2)

NAME

unlink - remove directory entry
SYNOPSIS

unllnk(path)
char ·path,
DESCRIPTION
Unlink removes the entry for the file pal" from its directory. If this entry was the last link to the
file, and no process has the file open, then all resources associated with the file are reclaimed. If,

however, the file was open in any process, the actual resource reclamation is delayed until it is
closed, even though the directory entry has disappeared.
RETURN VALUE

Upon successful completion, a value of 0 is retumed. Otherwise, a value of -1 is returned and
errno is set to indicate the error.
ERRORS

The

unlin~

succeeds unless:

(EPERM}
(ENOENT)
(ENOTDm)
(ENOENT)
(EACCES)

The path contains a character with the high-order bit set.
The path name is too long.

(EACCES)

Write permission is denied on the directory containing the link to be removed.

(EPERM)

The named file is a directory and the effective user ID of the process is not the
super-user.

(EBUSY)

The entry to be unlinked is the mount point tor a mounted file system.

(EROFS)

The named file resides on a read-only file system.

(EFAUL T)

Pal" points outside the process's aliocated address space.

(ELOOP)

Too many symbolic links were encountered in translating the pathname.

A component of the path prefix is not a directory.
The named file does not exist.
Search permission is denied for a component 01 the path prefix.

SEEALSq
c1ose(2), link(2), rmdir(2)

104

Last change: 2 July 1983

Sun Release 1.1

UTIMES(2)

SYSTEM CALLS

'.

UTlMES(2)

. NAME

utimes - set file times
SYNOPSIS

#lDclude <.y./typea.h>
utlm_(flle, tvp)
char *fll••
IItruct tlmeval *tvp(Z);
DESCRIPTION
The "time. call uses the "accessed" and "updated" times in that order from the tvp vector to set
the correspondinl recorded times ror file.

The caller must be the owner or the file or the super-liser. The "inode-changed" time of the file is
let to the current time.
RETURN VALUE

UPOD successful completioD, a value of 0 is returned. Otherwise, a value of -1 is returned and
errno il let to indicate the error.
ERRORS

Utime will fail if one .!lr more of the followinl are true:
LEPERM)
The pathDame contained a character with the high-order bit set.
(ENOENT)

The pathname- was too lonl.

IENOENT)

The Darned file doel not exist.

(ENOTDIR)

A component otthe path prefix is not a directory.

IEAOOES)
(EPERM)

A componeJlt of the-path prefix denies search permissfou.

(EACCESJ

The elective user m is not super-usor and not the OWBer 01 the file and time" is
NULL and write accesl is denied.

[EROPS)

The file SYltem containin& the file is mounted read-onlr__

IEFAULTJ

Tv, pointl eutaide the process's allocated address space.
Too many symbolic tinks were encountered in translatia-& the pathname.

(ELOOPJ

The process is Det super-user and not.-the owner or the tlle.

SEE ALSO

atat(2}

SUD

Release 1.1

Last change: 2 July 1983

105

SYSTEM CALLS

VADVISE( 2)

VADVISE(2)

NAME

vadvise - give advice to paging system
SYNOPSIS

#lnelude <8y./vadvlae.h>
vadvlae(param)
tnt param,
DESCRIPTION

Vodvi8e is used to inform the system that process paging behavior merita special consideration.
Parameters to vodtJi,e are defined in the &le . Currently, two calla t vodvi8e are
implemented.
The call
vadvlae(VA~NOM)J

advises that the paging behavior is not likely to be well handled by the system's default algorithm, since reference information is collected over macroscopic intervals (e.g. 10-20 seconds) will
not serve to indicate future· page references. The system in this case will choose to replace pages
with little emphasis placed on recent usage, and more emphasis on referenceleu circular behavior.
It is eBBentitd that processes which have very random palin, behavior (such as LISP during garbage collection of very large address spaces) call vodviBeJ 81 otherwise the IYltem haa great
difricultr dealing with their page-consumptive demands.
The call
vadvlae(VA_NORM)I
restores default paling replacement behavior after a call to
vadvlae(VA~NOM)1

BUGS
Will go away soon, being replaced by a per-page modvi,e facility.

106

Last change: 29 August 1983

SUD Release 1.1

VFORK(2)

SYSTEM CALLS

VFORK(2)

NAME

vfork - spawn new process in a virtual memory efficient way
SYNOPSIS
pld

== vlol'k()

tnt pldJ

DESCRIPTION
VJork can be used to create new processes without fully copying the address space of the old process,which is horrendously inefi'icient in a paged environment. It is useful when the purpose of
lork(2) would have been to create a new system context ror an ezecve. Vlorl: differs from lorl: in
that the child borrows the parent's memory and thread of control until a call to ezecve(2) or an
exit (either by a call to ezit(2) or abnormally.) The parent process is suspended while the child is
usinl its resources.
Vlork returns 0 in the child's context and (later) the pid or the child in the parent's context.

Vlork can normally be used just like lork. It does not work, however, to return while running in
the childs context from the procedure which called v/ork sblce the eventual return from vlork
would then return to" a no longer existent stack frame. Be careful, also, to call _ezit rather than
ezit if you can't ezecve, since ezit will Dush and close standard I/O channels, and thereby mess up
the parent processes standard I/O data structures. (Even with lork it is wrong to call ent since
bulered data would then be Dushed twice.)
SEE ALSO
fork(2), execve(2), sigvec(2), wait(2),
DIAGNOSTIOS
Same as for lort.

BUGS
Thia system call will be eliminated when proper system sharing mechanisms are implemented_
Users should not depend on the memory sharing semantics of vlork as it will, in that case, be
made synonymous to lork.
To avoid a possible deadlock situation, processes which are children in the middle 01 a vlork are
never sent SIGTTOU or SIGTTIN signals; rather, output or loctls are allowed and input attempts
result in an end-of-Die indication.

Sun Release 1.1

Last change: 2 July 1983

107

VHANGUP(2)

SYSTEM CALLS

VHANGUP(2)

NAME

vhangup - virtually "hangup" the current control terminal
SYNOPSIS

vhansup()
DESCRIPTION
VhtJngup is used by the initialization process init(8) (among others) to arrange that users are given
"dean'" terminals at login, by revoking access or the previous users' processes to the terminal.
To effect this, vhtJngup searches the system tables for references to the control terminal ot the
invoking process, revoking accees permissions on each instance or the terminal which it finds.
Further attempts to access the terminal by the affected processes will yield i/o errors (EBADF).
Finally, a hangup signal (SIGHUP) is sent to the proceS8 group ot the control terminal.

SEE

AL~O

init (8)

BUGS
Access to the control terminal via /dev /tty is still possible.
This call should be replaced by an automatic mechanism which takes place on process exit.

108

Last change: 12 Febuary 1983

SUD

Release 1.1

SYSTEM CALLS

WAIT(2)

WAIT(2)

NAME
wait, wait3 - wait for process to terminate or stop
SYNOPSIS

:fIlnelude 
pld
walt(statue)
lnt pld;
unloD walt *status;
pld .. walt(O)
Int pld;
#lnelude 
*lnelude 
pld .. walt3(etatus,"optlons, ruease)
lnt pld;
union walt -statuI,
Int options,
struet rUllase *rusale;

==

DESCRIPTION
W Git causes its caller to delay until a signal is received or one of its child processes terminates or
stops due to tracing. If any child has died or stopped due to tracing and this has not been
reported via WGit, return is immediate, returning the process id and exit status of one of those
children. U that child had died, it is discarded. If there are no children, return is immediate with
the value -1 returned. If there are only running or stopped but reported children, the calling
processes is suspended.

On return from a successful wait call, 8tatul is nonzero, and the high byte of 8ftdUI contains the
low byte of the argument to ent supplied by the child process; the low byte of stGIUI contains the
termination status of the process. A more precise definition of the "GIUI word is given in
< 1111/ WGit.lH>.
WGitS is an alternate mtedace which allows both non-blocking status collection and the status of
children stopped by any means. The ,'tdUI parameter is defined as above. The optionl parameter is used to indicate the call should not block if there are no processes which have status to
report (WNOHANG), and/or that children of the current process which are stopped due to a
SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal are eligible to have their status reported as
well (WUNTRACED). A terminated child is discarded after it reports status, and a stopped process will not report iti statuI more than once. If rU'Gle is non-zero, a summary of the resources
used by the terminated procell and all itl children is returned. (This information is currently not
available lor stopped p,r9cessel.)
When the WNOHANG option iSl specified and no processes have status to report, waitS returns a
pill ot o. The WNOHANG and WUNTRACED options may be combined by or'ing the two
values.
NOTO
See rilvec(2) tor a fist of termination statuses (signals); 0 status indicates normal termination. A
special status (0177) is returned tor a stopped process which has not terminated and can be restarted; see ptrace(2) and lilvec(2). If the 0200 bit of the termination status is set, a core image of
the proceu was produced by the system.
If the parent process terminates without waiting on its children, the initialization process (process
ID == 1) inherits the children.
Wai' and waitS are automatically restarted when a process receives a signal while awaiting termination ot a child procesa.

Sun Release 1.1

Last change: 22 December 1983

109

WAIT ( 2)

SYSTEM CALLS

WAIT(2)

RETURN VALUE
If wait returns due to a stopped due to tracing or terminated child process, the process ID 01 the
child is returned to the calling process. Otherwise, a value 01 -1 is returned and errno is set to
indicate the error.
WaitS returns -1 if there are no children not previously waited lor; 0 is returned if WNOHANG
is specified and there are no stopped or exited children.

ERRORS
Wait will fail and return immediately it one or more ot the tollowinl are true:

,ECHILD)

The calling prace. has no existing unwaited-tor child processes.

J~F AUL T)

The Blah" or rUBale arguments point to an illegal address.

SEE ALSO
exit(2)

110

Last change: 22 December 1983

Sun Release 1.1

SYSTEM CALLS

WRITE(2)

WRITE(2)

NAME
write, writev - write on a file

SYNOPSIS

wrlte(d, but, nbytea)
tnt d,
char ·but,
tnt Db,.tea,
:fFtnclude 
*lnclude 
wrltev(d, loY, loveclen)
tnt d,
atruct lovec ·lov,
lnt loveclen,
DESORIPTION
Write attempts to write n6,1te, 01 data to the object referenced by the descriptor d from the buffer
pointed to by 6uf. Writel1 performs the same action, but gathers the output data Irom the iovlen
buffers specified by the members of the iOI1 array: iovlOJ, iovll), etc.
On objects capable 01 seeking, the write starts at a position given by the pointer associated with
d, see l,eek(2). Upon return Irom write, the pointeria incremented by the number of bytes actuaUy written.
Objects that are not capable of seeking always write Irom the current position. The value of the
pointer associated with such an object is undefined.

If the real user is not the super-user, then write clean the set-user-id bit on a file. This prevents
penetration or system security by a user who "captures" a writable set-user-id file owned by the
8uper-user.
RETURN VALUE
Upon successlul completion the number ot bytes actually writen is returned. Otherwise a -1 is
returned and errno I. set to Indicate the error.
ERRORS

Write will rail and the file pointer will remain unchanged il one or more 01 the rollowing are true:
(EBADFJ

D Is not a valid descriptor open lor writing.

(EPIPE)

An a~tempt is made to write to a pipe that is not open lor reading by any pro-

IEP IP E)

An attempt is made to write to a socket of type SOCK_STREAM which is not
connected to a peer ISOCket.

(EFBIGJ

An attempt w2M made to write a file that exceeds the process's file size limit or
th6 maximum fll. size.
Part Oli iov or data to be written to ~he file points outside the process's allocated
addresa'spaceo,

(EFAULTJ

j

SEE ALSO

Iseek(2), open(2), pipe(~}

Sun Release 1.1

Last change: 29 August 1983

111

SUBROUTINES

INTRO(3)

INTRO( 3)

NAME
intro - introduction to library functions
DESCRIPTION
Section 3 describes functions found in libraries.
This section describes subroutines found in the system libraries.
The main 0 library is /lib/libc.a, and contains all the system call entry points described in section 2 as well as functions described in several subsections here. The primary functions in the 0
library are described in the main section 3. Functions associated with the "standard I/O library"
used by many 0 programs are found in section 35. The libc library also includes the Internet network fUnctions described in section 3N and routines providing compatibility with other UNIX systems as described in section 30 as well as all the system entry points from section 2.
Other sections here are:
(3F)

The SF functions are all functions callable from FORTRAN. These functions perform
the same jobs as the straight "3" functions do for C programmers. There are in fact
three FORTRAN libraries, namely -lU'17 which contains the system interrace routines,
-U'17 which is the I/O interrace library, and -IF7'1 which is everything not contained in
the other two. These libraries are searched automatically by the loader when loading
FORTRAN programs.

(3M)

These functions constitute the math library" 0 declarations for the types of functions
may be obtained from the include file . To use these functions with C programs use a -1m option with cC(l). They are automatically loaded as needed by the Fortran and Pascal compilers /77(1) and pe(I).

(3X)

Various specialized libraries have not been given distinctive captions. Files in which such
libraries are found are named on appropriate pages if they don't appear in the libc library.

FILES
/lib/libc.a
/u8r /lib /libc"'p.a
/usr/lib/libm.a
/usr/lib/ libm...p. a
/usr /lib/libU77.a
/usr /lib/libI77.a
/ usr /lib /libF77. a
/usr /lib /libcurses.a
lusr llib/libdbm.a
lusr llib llibmp.a
lusr llib/libtermcap.a
lusr/lib/libtermcap"'p. a
lusr llib/libtermlib
IU8r llib/libtermlib-p.a
lusr llib llibplot.a
lusr/li b/lib300.a
lusr llib Ilib300s.a
I usr /lib Ilib4014.a
lusr llib Ilib450.a

o Library «2), (3), (3N) and (3C) routines)
'Profiling 0 library (tor gproJ(l))
Math Library -1m (see section 3M)
Profiling version of -1m
FORTRAN system interface (8ee section 3F)
FORTRAN 1/0 (see section 3F)
FORTRAN everything else (see section 3F)
8creen management routines (see cur8e8(3X)
data base management routines (see dbm(3X))
mUltiple precision math library (see mp(3X))
terminal handling routines (see termeap(3X))

plot routines (see plot(3X))

"
"
"
"

SEE ALSO
intro(30), intro(3S), intro(3F), intro(3M), intro(3N), nm(l), Id(I), cc(I), 177(1), intro(2)
DIAGNOSTICS
Functions in the matb library (section 3M) may return conventional values when the (unction is
undefined for the given arguments or when the value is not representable. In these cases the
external variable errno (see intro(2)) is set to the value EDOM (domain error) or ERANGE (range

Sun Release 1.1

Last change: 12 January 1984

1

INTRO(3)

INTRO(3)

SUBROUTINES

error). The values of EDOM and ERANGE are defined in the include file .
LIST OF FUNCTIONS
Name

abort
abs
alarm
alloca
alphasort
asctime
assert
atof
atoi
atol
bcmp
bcopy
bzero
calloe
cfree
clearerr
closedir
closelog
crypt
ctime
dysize
ecvt
edata
encrypt
end
endfsent
endgrent
endhostent
endnetent
endprotoent
endpwent
en dservent
environ
errno
etext
execl
execle
execlp
execv
execvp
exit
fclose
fcvt
(dopen
(eof
(error
fllush
fls
(getc
(gets

2

Appears on Page

abort.3
abs.3
alarm.3c
malloc.3
scandir.3
ctime.3
assert.3
atof.3
atof.3
atof.3
bstring.3
bstring.3
bstring.3
malloc.3
malloc.3
ferror.3s
directory .3
syslog.3
crypt.3
ctime.3
ctime.3
ecvt.3
end.3
crypt.3
end.3
getfsent.3
getgrent.3
gethosten t.3n
getnetent.3n
getprotoent.3n
getpwent.. 3
getserven t.3n
execl.3
penor.3
end.3
execl.3
execl.3
exec1.3
execl.3
execl.3
exit.3
fclose.Ss
ecvt.3
ropen.Ss
terror.3s
(error.3s
fclose.3s
bstring.3
getc.3s
gets.3s

Description

generate a fault
integer absolute value
schedule signal alter specified time
memory allocator
scan a directory
convert date and time to ASCII
program verification
convert ASCII to numbers
convert ASCII to numbers
convert ASCII to numbers
bit and byte string operations
bit and byte string operations
bit and byte string operations
memory allocator
memory allocator
stream status inquiries
directory operations
control system log
DES encryption
convert date and time to ASCII
convert date and time to ASCII
output conversion
last locations in program
DES encryption
last locations in program
get file system descriptor file entry
get group file entry
get network host entry
get network entry
get protocol entry
get password file entry
get service entry
execu te a file
system error messages
last locations in program
execute a file
execu te a file
execute a file
execute a file
execu te a file
terminate a process alter flushing any pending output
close or flush a stream
output conversion
open a stream
stream status inquiries
stream status inquiries
close or flush a stream
bit and byte string operations
get character or integer (rom stream
get a string from a stream

Last change: 12 January 1984

Sun Release 1.1

INTRO(S)

fileno
ropen
Iprintl
rputc
Iputs
tread
free

'reopen
(rexp
tscant
rRek
ftell
fiime
fwrite
gcv'
getc
getchar
getenv
getfsent
getfsfile
getrsspec
. getlstype.
getgrent
getgrgid
get-gmam
gethosthyaddr
gethostbyname
gethostent
getlogin
getnetbyaddr
getnetbyname
getnetent
getopt
getpus
getprotobyname
getprotobynumber
getprotoent
getpw
getpwent
getpwnam
getpwuid
gets
getservbyname
getservbyport
getservent
getw
getwd
gmtime
gtty
htonl
htons
index
inet_addr

Sun Release 1.1

SUBROUTINES

ferror.Ss
lopen.Ss
printf..3s
putc.3s
puts.&
freacL3s
malloc.3
lopen.3iS:
frexp.3
Kanl..38rseek.3sIseek.3s
time.$c
Iread.&:
ecvt.3
getc.Sa
getc.3s
getenv.3.
getfsent.3
getfeent.3
getfsent.3
getfsent.3
get-grent.3
getgrent.3
getgrent.3
gethostent.3n
gethostent.3n
gethostent.3n
getlogin.3
getnetent.3n
getnetent.3n
getnetent.3n
getopt.3c
getpus.3
getprotoent.3n
getprotoent.3n
getprotoent.3n
getpw.3
getpwent.3
get-pwent.3
getpwent.3
gets.3s
getserven t.3n
getserven t.3n
getservent.3n
getc.3s
getwd.3
ctime.3
stty.3c
byteorder .3n
byteorder .3n
string.3
inet.3n

INTRO(3)

stream status inquiries
open a stream
formatted output c-oDversion
put character or word on a stream
put a strin&. on a stream
bulered binary inputLoutpuC
memory alfocator
open a-streamsplit into man(1SSa and exponeal-formatted Input coaversion
reposition a"stream
reposition a·stream
get"Gate- and:til1ie
bulerecf bmary- input/output
outpur cOD-version
get: character or in'ege~ from stream
get. character or integer from stream
valu-e lor environment name
get- file system descriptor file entry
get file system descrfptor file entry
get file system descriptor file entry
get file system descriptor file entry
get group file entry
get group file entry
get group file entry
get network hoet entry
get network hoet entry
get network host entry
get login name
get network entry
get network entry
get network entry
get option letter from argv
read a password
get protocol entry
get protocol entry
get protocol entry
get name from uid
get password file entry
get password file entry
get password file entry
get a string from a stream
get service entry
get service entry
get service entry
get character or integer from stream
get current working directory pathname
convert date and time to ASCII
set and get terminal state
convert values between host and network byte order
convert values between host and network byte order
string operations
Internet address manipUlation

. Last cbange: 12 January 1984

3

SUBROUTINES

INTRO(3)

inet_lnaof
inet_makeaddr
inet_netof
inet_network
inet_ntoa
initgroups
initstate
insque
isalnum
isalpha
iS38Cii
isatty
iscntrl
isdigit
isgraph
isinf
islower
isnan
isprint
ispunct
isspace
isupper
ldexp
localti·me
longjmp
malloc
mktemp
modI
moncontrol
monitor
monstartup
nice
nlist
ntohl
ntohs
opendir
open log
optarg
optind
pause
pclose
perror
popen
print!
psignal
putc
putchar
puts
putw
qsort
rand
random
rcmd

4

inet.3n
inet.3n
inet.3n
inet.3n
inet.3n
initgroups.3
random.3
insque.3
. ctype.3
ctype.3
ctype.3
ttyname.3
ctype.3
ctype.3
ctype.3
isinf.3
ctype.3
isinf.3
cty.pe.3
ctype.3
cty.pe.3
ctype.3
frexp.3
ctime.3
setjmp.3
malloc.3
mktemp.3
Irexp.3
monitor.3
monitor.3
monitor.3
nice.3c
nlist.3
byteorder .3n
byteorder .3n
directory .3
syslog.3
getopt.3c
getopt.3c
pause.3c
popen.as
perror.3
popen.3s
printf.3s
psignal.3
putc.3s
putc.3s
puts.3s
putc.3s
qsort.3
rand.3c
random.3
remd.3n

INTRO(3)

Internet address manipulation
Internet address manipulation
Internet address manipulation
Internet address manipulation
Internet address manipulation
initialize group access list
better random number generator; routines for changing generato1'8
insert/remove element from a queue
character classi8cationmatros
character classi8cation macros
character classification macros
find name of a terminal
character classification macros
character classification macros
character classification macros
test for indeterminate Boating point values
character classification macros
test for indeterminate Boating point values
character classification matros
ch"aracter classification macros
ch"aracter classific ationhlacros
character classificationlllacr08
split into mantissa and 'ex'ponent
·convert date and time to ASCII
non-localgoto
memory allocator
make a unique filename
split into mantissa and exponent
prepare· execu tionprofile
prepare execution profile
prepareexecu tionprofile
set program priority
get entries from name list
convert values between host and network byte order
convert values between host and network byte order
directory operations
control system log
get option letter from argv
get option letter from argv
stop until signal
initiate I/O to/from a process
system error messages
initiate I/O to/from a process
formatted output conversion
system signal messages
pu t ch aracter or word on a stream
put character or word on a stream
put a string on a stream
put character or word on a stream
quicker sort
random number generator
better random number generator; routines lor changing generato1'8
routines for returning a stream to a remote command

Last change: 12 January 1984

Sun Release 1.1

SUBROUTINES

re_comp
re_exec
readdir
reaUoc
remque
rewind
rewinddir
teXeC

riDdex
rresvport
ruserok
scandir
scant
seetdir

set.bur
aetbuler
setegid
seteuid
setfsentsetpd
setgrent
sethostent
setjmp

setkey
aetlinebul
s-etnetent
setprotoent
setpwent
letrgid
setruid
aetservent
setstate
aetuid
signal
sleep
sprintt
srand
arandom
sscant
atdio
streat
atremp
strepy
strlen
strncat
strncmp
strncpy
stty
swab
sys_errJist
sys_nerr
sys_siglist
syslog

Sun Release 1.1

INTRO( 3)

regular expression handler
regular expression handler
directory operations
memory- allocator
insert/remove element trom a ' l - reposition a stream
directory-operationsreturn stream to a remote com....ct
atring operations
routines ror retumillg a stream tcJ-a remote command
routinearor retuming a stream to:. a. remota command
SCaD a directory
fOrmatted input cOBversioll
directory operations
assign 6afrering to a stream
.... ~setbuf.3s
assfgn buffering to &- stream
setbuf.3s
set user: and group ID
setuid.3
set user- and group ID
setuid.3
get fIl~ system descriptor file entry
getrsen~.3
setllid.S
set user and group JD
get group file entry
getgrent.S
gethosten t.3n get network host en'ry
setjmp.a
non-local goto
crypt.3
DES encryption
assign bufl'ering to a stream
setbut.as
getnetent.3n
get network entry
getprotoent.3n get protocol entry
getpwent.3
get paasword file entry
letuid.3
set user and group ID
setuid.3
set user and group ID
getservent.3n get service en try
better random number generator; routines for changing generators
random.S
set user and group ID
setuid.3
simplified software signal facilities
signal.S
suspend execution (or interval
sleep.S
printt.&
formatted output conversion
random number generator
rand.3c
random.3
better random number generator; routines for changing generators
formatted input conversioll
scant.&
intro.3s
standard buffered input/output package
string.3
string operations
string operations
string.3
string operations
string.3
string: 3
string operations
string- operations
string.3
string.3
string operations
string.S
string operations
stty.3c;
set and get terminal state
·swab.3
swap bytes
system error messages
perror.3
perror.S
system error messages
psignal.S
system signal messages
8yslog.3
control system log
regex.3
regex.3
directory .3
malloc.3
insque.3
fseek.3s
direct.ory .3
rexec.3n
string.3
remd.3n
rcmd.3n
sc:andir.3
scant.&
directory .3

Last change: 12 January 1984

5

system
telldir
time
times
timezone
tmpnam
ttyname
ttyslot
ulimit
ungetc
utime
valloc
varargs
vlimit
vtimes

6

INTRO(3)

SUBROUTINES

INTRO(3)

system.3
directory .3
time.3c
times.3c
ctime.3
tmpnam.3c
ttyname.3
ttyname.3
ulimit.3c
ungetc.3s
utime.3c
valloc.3
varargs.3
vlimit.3c
vtimes.3c

issue a shell command
directory operations
get date and time
get process times
convert date and time to ASCII
create a name ror a temporary file
find name or a terminal
find name or a term'inal
get and set user limits
push character back into input stream
set file times
aligned memory allocator
variable argument list
control maximum system resource consumption
get inrormation about resource utilization

Last change: 12 January 1984

Sun Release 1.1

ABORT(3)

SUBROUTINES

ABORT{3}

NAME
abort -- ,enerate a fault
DESORIPTION
Abor' executes all instruction which is illegal hi user mode. This causes a- _is-nal that normally
termiDatea tie- proc:eu- with a core dump, which may be used ror debuggia..SEE ALSO
adb(IS~ liPaI($}t-exit{2}-

DIAGNOSTICS
UsuallJ 'IQ-T trap - core damped'

rfOUL the

she1t.--

BVOS

The 46orC.-tVDctioa does- not flu_ sr-aJldird I/O 6uft'en.. Use J1ftJ,lt--as described iIL/elo.e(3S)__

Sun Release 1.1

Last change: 26 August 1983

7

ABS(3)

SUBROUTINES

ABS(3)

NAME

aba - integer absolute value
SYNOPSIS

aba(l)
lnt I,
DESCRIPTION
Ab, returns the absolute value or its integer operand.
SEE ALSO
floor(3M} tor lab,

BUGS
Applying the ab,function to the most negative integer gen,erates a result which is the most negative integer. That is, aba(Ox80000000} returns Ox80000000 as a result.

8

Last change: 27 August 1983

SUD

Release 1.1

ASSERT(3)

SUBROUTINES

ASSERT(3)

NAME
assert - program verification
SYNOPSIS-:

*lndude <....t.h>
. . .rt(exPI'_IOD)

DESCRIPTION
A,.erl is- a macro tiat indicate. ezprel16ion is expected to be true at ~hia _Roint ill the program. It
causes-- aD ezif(2) with a diagnostic comment on the standard output wheD eqre6rion i&-Ialse (0).
CompiliBg with the cc(l) option -DNDEBUG effectively deletes tlllllert trona the-program.
DlAGNOS-TrCS

'"AaertioD failed: lIe I hue n.' F is the source file and

rt the

soatee line namber 01 tlie

_.~rtstate­

meet-_

SUD

Release 1.1

Last change: 23 August 1983

9

SUBROUTINES

ATOF(3)

ATOF(3)

NAME
atof, atoi, atol - convert ASCD to numbers
SYNOPSIS

double atof(nptr)
char *nptrJ
atol(nptr)
char *optrJ
Ion. atol(nptr)
char *nptrJ
DESCRIPTION
These lunctions convert a string pointed to by nplr to Boating, integer, and lonl integer representation respectively. The first unrecognized character ends the string.

ot digits optionally containing a decimal point, then an optional 'e' or 'E' lollowed by an optionally signed
integer.

AID! recognizes an optional string 01 spaces, then an optional sign, then a strinl

Aloi and Idol recognize an optional string of spaces, then an optional sign, then a string 01 digits.

SEE ALSO
scanf(3S)

BUGS
There are no provisions tor overBow.
Curre,ntly, tdo! performs highly inaccurate cOllversionsol very large or very small numbers - on
the order ot 10**32 or its reciprocal.

10

Last change: 19 March 1984

Sun Release 1.1

BSTRING(3)

SUBROUTINES

BSTRING(3)

NAME
beopy, hemp, bzero, Is - bit and byte string operations
SYNOPSIS

beoP7(bl, bl, length)
char ·bl, ·bl,
tnt length,
bcmp(bl, bl, lenath)
char ·bl, ·bl,
lnt length,
bzero(b,lensth)
char
tnt lenath.

·b,

1'1(1)
lnt I,

DESCRIPTION
The functions bcoPl1. bcmp, and bzero operate on variable length striqs of bytes. They do not
check tor DuD bytes as the routines in Btring(3) do.

Bco'l/ copies length bytestrom string 61 to the string 6e.
Bcm, compares byte strin, bl against byte strin, be, returnin, zero it they are identical, non-zero
otherwise. Both strings are assumed to be length bytes long.
Bzero places lengtb 0 bytes in the string b.
FIB Inds the first bit aet in the argument passed it and returns the index or that bit. Bits are
numbered starting at 1 trom the right. A return value or -1 indicates the value passed is zero.
BUGS

The bcm, and 6coPlI routines take parameters backwards rrom Btrcmp and Btrepy.

Sun Release 1.1

Last change: 4 March 1983

11

OR'YPT(3)

SUBROUTINES

ORVPT(3)

NAME

crypt, setkey ,encrypt - DES encryption
SYNOPSIS

char *crypt(key, salt)
char *key, *s.lt;
setkey(key)
char *keYI
encrypt(bloek, edftall)
char *blockl
DESCRIPTION

Crl/p' is the password encryption routine. It is based on the NBS Data Encryption Standard, with
variations intended (among other thinp) to frustrate·use 01 hardware implementations 01 the DES
lor key search.
The first argument to crypt is normally a user's typed password. The second is a 2-character
string chosen from the set (a-zA-Z0-9./J. The 8tJl'string is used to perturb the DES algorithm in
one of 4006 different ways, after which the password is u8ed as the key to encrypt repeatedly a
constant string. The returned value points to the encrypted password, in the same alphabet as
the salt. The first two characters are the salt itself.
The other entries provide (rather primitive) access to the actual DES algorithm. The argument of
8etkel/ is a character array of length 64 containing only the characters with numerical value 0 and
1. If this string is divided into groups of 8, the low-order bit in each group is igll'ored, leading to
a 56-bit key which is set into the machine.
The argument to the encrllP' entry is likewise a character array 01 length 64 containing 0'8 and
1'15. The argument array is modified in place to a similar array representing the bits of the argument after having been SUbjected to the DES algorithm using the key set by Betkel/. If edftag is 0,
the argument is encrypted; if non-zero, it is decrypted.
SEE ALSO

passwd(l), passwd(5), 10gin(I), getpass(3)

BUGS
The return value points to static data whose content is overwritten by each call.

12

Last change: 25 February 1983

Sun Release 1.1

SUBROUTINES

CTIME(3)

CTIME(3)

NAME
ctime, localtime, gmtime, asctime, timezone, dysize - convert da.te and time to ASCII
SYNOPSIS

char *ctlme(eloek}
Ion. *eioc:kl
#lnelude 
.truct tm *loealtlme(elock}
Ions *cloekt
Itruet.. tm *.mtlme(dcac:i.}
Ion. *eloekl
char *alCtlme(tm)
.truct tm *tma
char *tlmelone(sone, dlt)
lot drlbelY)
IDt~,

DESORIPTION
Clime converts a time pointed to by clock such as returned by gettimeoJdtJ1J(2) Into ASClIand
returns a pointer to a 26-character string in the following form. All the fields have constant
width.
SUD

Sep 16 01:03:52 1973\n\0

LoctJilime and gmtime return pointers to structures containing the broken-down time. LoclJUime
eorrects lor the time zone and possible daylight savings time; gmtime converts directly to GMT,
which il the time UNIX uses. ABctime CORverts a broken-down lime to ASCII and returns a
pointer to a 26-character string.
The structUl'e declaration rrom the include file is:Itruct tm {
int
int
int
int
int
int
int
int

1;

in,

tm_sec;
tm_min;
tm.Jlour;
tmJDday;
tmJDon;
. tm..,rear;
tm_wday;.
tmJday;
tm_isdst;

These- qaanCities give the time on a 24-110ur clocl.rday of month (t--Il), month of year f();.ll}, day
01 week (Saaday .. 0), year - 1900, day of yeu. (Q.365), and a flag that is nonzero if da,ligbt saving time is In,effect.

.

When local tldte is caBed for, the program consults the system to determine the. time zone and
whether the U.S.A., Australian, Eastern European, Middle European, or Western European daylight saving time adjustment is appropriate. The program knows about various peculiarities in
time conversibD ov~rthe i>ast 10-20 yean •.

Timezone returns the name of the time zone associated with its first argument, which is measured
in minutes westward Crom Greenwich. If the second argument is 0, the standard name is used,
otherwise the Daylight Saving version. If the required name does not appear in a ta.ble built into
the routine, the difference from GMT is produced; e.g. in Mghanistan timezone{-{60* 4+ 90), 0) is
appropriate because it is 4:30 ahead of GMT and the string GMT+4:30 is produced.

SUD Release l.l

Last change: 23 August 1983

13

CTUdE(3)

SUBROUTINES

CTIME(3)

D1I8ize retums the Dumber of days in the argument year ,either 365 or 366.
SEE ALSO

gettimeofday(2), time(3C)

BUGS
The retum values point to static data whose content is overwritten byeaehcaU.

14

Last change: 23 August 1983

Sun Release 1.1

CTYPE(3)

SUBROUTINES

CTYPE(3)

NAME
isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, iscntrl r isascii, isgraph,
toupper, tolower, toucH - character classification and conversion mac.os
SYNOPSIS

*lnclude 
laalpha(c)

•••
OHARACTER CLASSIFICATION MACROS
These macros classify ASCII-coded integer values by table lookup. Each- is a predicate retarning
nonzero tor true~ zero for false. [BaBcii is defined on all integer values; the rest are defined only
where isascii( c) is true and on the single non-ASCII value EOF (see Btdio(3S».
iealpha( c) t is a letter
isupper( c) c is an upper case letter
i81ow~r( c)

c is a rower cue letter

isdigit( c)

C'il- a

digit

isxdigit( c) c is a hexadecimal digit
isalnum( c) c ie an alphanumeric character
isspace( c) c is a space, tab, carriage return, newline, or formfeed
ispunct( c) c is a punctuation character (neither control nor alphanumeric)
isprint( c)- c is a printinl character, code 040(8) (space) through 0176 (tilde)
iscntrl(c)

c is a delete character (0177) or ordinary control character (Iesathan 040).

isascii( c)

c is an ASCII character, code less than 0200
isgraph( c) c is a visible graphic character, code 041 (exclamation m-ark) tbrough 0176 (tilde).
CHARACTER CONVERSION MACROS
These macroe perform- simple conversions on single characters-.
toupper( c)

converts c to ita upper-case equivalent. Note that this only works where c is
known to be a lower-case character to start witl (presumably checked via
'Blower).

tolower(c)

eonverts c to its lower-case equivalent. Note that this ITnly works where c isknown to be a upper-case character t~ start with (presumably checked" via

iBupper) ..

toaacii(c)

masks c with the correct value
in the range 0 thru Ox7f..

80

that c is guaranteed to be an

AScn character

SEE ALSO
aacii{7}

SUD Rele~

1.1

Last change: 9 March 1984

15

,·SUBROUTINES

DIRECTORY(3)

DIRECT6RY( 3 )

NAME

opendir, readdir ,telldir, seekdir, rewinddir,' closedir - directory operations
SYNOPSIS

:fI:lnelude 
DIR *«>pendlr(fllename)
eha;r*fllename;
,truet dlreet*r_ddlr(dlrp)
~IR *dlrp;
lon.·telldlr(dlrp)
DIR'''dlrp;
.eekdlr(dlrp, :Ioe)
'DIR*dlrp;
-Ion.loe.
re·wlnddlr.{dlrp)
DIR*dlrp.
elo.edlr(dlrp)
DIR *dlrp.
DESCRIPTION

Opendiropens the directorynamedbyjiJentJmeand 88sociatesa diredo'rll.tretJmwith it. Opendir
returns a pointer to be used to identify the directorll'81retJm insubseqnentoperations. The
pointer NULL is returned if jilen4me callnotbe accessed oris nota directory,arit it cannot fntJIloc(3) enough memory to hold the whole thing.

R ttJddirreturnsapointer to the next directory entry . It returns NULL 'upon 'I'eae-hingthe end of
the directory or detecting an invalid seeidiroperation.
Telldirreturns the current location associated with the named 'd'rector1l stream.
Seeidir sets the position of the next retJddir operatioD ontheilirectorlJ 8trelJm. The new position
reverts to the oneusociated withthedirector1l,'retJm whell thelelldiroperatioil was performed.
Values returnedbylelldir are goOOoBlY torthelitetimeof the DIR pointer from which they are
derived. It the directory is closed and then reopened, 'the telliUr value may be invalidated due to
undetected directory compaction. It is sare to use a previous telldir value immediately after a call
to opendir and before any calls 'to retJddir.

Rewinddir resets the position of thenameddirector1l ,tretJmto thebeginilingof the directory.
Closedir closes theu.meddirector,l stretJ"' and trees the structure associated with,theDIR
pointel'~

Sample code whichsearchs adirectoryror entry U name" is:
len == strlen(name );
dirp==opendir(" .");
for(dp ==readdir(dirp); dp!==NULL; dp==readdit(dirp))
j'f(dp. >d_namlen==== lenll8t!strcmp(dp->d_name, n:a.me}) {
C'loseciir(dirp};
,retufnFOUND;

}
closedir(dirp,);
ret'ur,nNOT_FOUND;
S:EEALSO

open(2), elose(2), read(2), lseek(2), dir(5)

16

Last change: 25 February 1983

DmECTORY (3-)

SUBROUTINES

DIRECTORY(3)

BUGS

Old UNIX programs which examine directories should be converted 10 use this package, as the
new directory format il non-obvious.

SUD Rele~
~: ~

1.1

Last change: 25 February 1983

17

SUBROUTINES

ECVT(3)

ECVT(3)

NAME

ecvt, fcvt, gcvt - output conversion
SYNOP~IS

~har ·eevt(value, ndlslt, deept, algn)
double value;
','
llpt ndlglt, ·decpt, ·_lln;
char ·tcvt(value, ndlglt, deept, _lin)
double value;
lnt ndlslt, ·decpt, ·_lgn;

char ·.evt(value, ndlalt, but)
double value,
char ·but,
DESCRIPTION

Eevt converts the value to a null-terminated string or ndigit ASCD digits and returns a pointer
thereto. The position or the decimal point relative to the beginning or the string is stored
indirectly through deept (negative means to the left of the returned digits). It the sign 01 the
result is negative, the word pointed to by sign is non-zero, otherwise it is zero. The low-order
digit is rounded.
Fevt is identical to ecvt, except that the correct digit has been rounded for Fortran F-format output 01 the number of digits specified by ndigit,.
Gevt converts the value to a null-terminated ASCD string in 6uJ and returns a pointer to 6uJ. It
attempts to produce ndigit significant digits in Fortran F format if possible, otherwise E format,
, ready for printing. Trailing zeros may be suppressed.
SEE ALSO
isinf(3), printf(3S)

BUGS
The return values point to static data whose content is overwritten by each call.

18

Last change: 23 August 1983

Sun Release 1.1

END(S)

SUBROUTINES

END(3)

NAME
end, etext, edata - last locations in program
SYNOPSIS

extero end,
. extero etext,
extero edata,
DESCRIPTION
These names refer neither to routines nor to locations with interestin. eOittents. The address of
etezt is the first address above the program text, ediJttJ above the initialized data region, a!ld end
above the uninitialized data region.
When execution begins, the program break coincides with end, but k itt-reset by the routmes
brk(2), malloc(3)~ standard input/output (atdio(SS}), the profile (-p) option or cc(I), etc. The
current value of the program break is reliably returned by 'sbrk(O)', see hrA:(2).
SEE ALSO
brk(Z), malloc(S)

Sun Release 1.1

Last change: 19 January 1983

19

SUBROUTINES

EXECL:(3)

EXECL(3)

NAME
exec1, execv, execle, exec1p, execvp, environ - execute a file
SYNOPSIS

,xeel(name, ar.o, "'SI, •••, arsn, 0)
char *name, *ar.o, *ar.l, •••, ·arpI
exec:v(name, argyl
char *name, *arsv [ b
exeele(name, arsO, arsl, •••, arp, 0, envp)
char ·name, ·arll, *arsl, •••, ·arp, ·envp[ II
exeelp(name, arll, ara1, •••, aran, 0, envp)
char *name, *arlO, *ara1, •••, *arp, *envp[ b
exeevp(name, argy, envp)
char *name, *arl"[], ·envp[]a
extern char ·*envlron.
DESCRIPTION
These routines provide various interfaces to the ezecve system call. Refer to ezecve(2) for a
description of their properties; only brief descriptions are provided here.

Ezec in all its forms overlays· the calling process with the named file, then transfers to the entry
point of the core image of the file. There can be no return from a successful exec; the calling core
image is lost.
The nGme argumen~ is a pointer to the name of the file to be executed. The pointers Gr,(O),
org[l) ... address null-terminated strings. Conventionally or,(O) is the name of the file.
Two interfaces are available. eze.cl is useful when a known file with known arguments is being
called; the arguments to ezecl are the character strings constituting the file and the arguments;
the first argument is conventionally the same as the file name (or its last component). A 0 argument must end the argument list.
The ezecv version is useful when the number of arguments is unknown in advance; the arguments
to ezeevare the name of the file to be executed and a vector of strings containing the arguments.
The last argument string must be followed by a 0 pointer.
When a C program is executed, it is called as follows:
main(argc, argv, envp)
int argc;
char **argv, **envp;
where Grle is the argument count and Grgv is an array of character pointers to the arguments
themselves. As indicated, Grgc is conventionally at least one and the first member of the array
points to a string containing the name of the file.

Arlv is directly usable in another ezeev because Grlvl Grle) is o.
Envp is a point~r to an array br strings that cohstitute the environment or the process. Each

string consists of a name, an "=", and a null-terminated value. The array of pointers is terminated by a null pointer. The shell sA(I) passes an environment entry for each global shell variable defined when the program is called. See environ(5) for some conventionally used names.
The C run-time start-oft' routine places a copy of envp in the global cell environ, which is used by
ezeev and ezecl to pass the environment to any subprograms executed by· the current program.

Ezeclp and ezecvp are called with the same arguments asezeel and ezecv, but duplicate the shell's
actiQns in searching for an executable file in a list of directories. The directory list is obtained
from the environment.

20

Last change: 20 March 1984

SUIl ReleasW! 1.1

EXECL(3)

SUBROUTINES

EXECL(3)

FILES
/bin/sh shell~ invoked it command file found by ezeclp or ezectlp
SEE ALSO

execve(2), fork(2), environ(5), c8b(I), sb(l)
"UNIX Programming" in Programming Tools for the SUN Workstatio,.; ppw 1-3.
DIAGNOSTICS
If the file cannot be found, if it is not executable, if it does not stal't with a valid magic Bamber
(see a.out(5)), it maximum memory is exceeded, or if the argument.. require too much space, a
r"turn CDnstitutes the diagnostic.; the return value is -1. Even for the super-user, at least ODe of
the execute-permiuion bits must be set for a file to be executed.

BUGS
If

e~cc", is eaIIecl.&o execute a flle th~ turas out to be a shell command file, and if it is impossible to execute the sheU, the values- of argu/O} and arguf-l}will be modiled before return-

SUD Release 1.1

Last change: 20 March 1984

21

EXIT(3.)

SUBROUTINES

EXIT(3)

NAME

exit - terminate aproceu after flushing any pending output
SYNOPSIS

exlt(status)
tnt status,
DESCRIPTION

Ezi, terminates a process by calling ezi'(2) alter calling the Standard I/O library function
_cletJnupto flush any buffered output. Ezi, never returns.
SEE ALSO

exit(2), intro(3S)

22

Last change: 23 August 1983

Sun Release 1.1

FREXP(3)

SUBROUTINES

FREXP(3)

NAME

lrexp, Idexp, modI - split into mantissa and exponent
SYNOPSIS

double fJ'exp(value, eptr)
double value.
lDt ·eptrl
doubleldexp(value, exp)
double value.
double modl(value, lptr)
double value, *lptrl
DESORIPTION
Frezp returns the mantissa of a double value as a double quantity, z, of magnitude less than 1 and
stores an integer n such that value == z· 2 n indirectly through eptr.

Ltfezp returns the quantity value. eezp.

Mod! retUrDS the positive
iplr.

fracti~nal

part of VtJlue and stores the integer part indirectly through

SEE ALSO
isinf(3)

BUGS
The identity claimed for the results of Irezp cannot hold when the value argument is an IEEE
indefinite quantity - infinity or not-a-number.

Sun Release 1.1

Last change: 23 August 1983

23

SUBROUTINES

GETDATE(3)

GETDATE ( 3')

NAME
getdate - convert.time and date lromASCn
SYNOPSIS
#lnelude<'.Y·ltypea~h.>
#lnclude 

tlme_t getdate(but, now,
char *bul.
struct timeb *now;
DESORIPTION

Getdate converts most common time specifications to standard UNIX lormat. The first argument
is the character string containing the time. and date; the second is the assumed current time (used
lor relative specifications); it NULL is passed, Itime(2) is used to obtain the current time and
timezone.
The character string consists 01 0 or more specifications 01 the lollowing lorm:
tod

A tod is a time of day, which is of the form hla:mm(:88) (orhhmm) (meridian) (zone). If
no meridian - .morpm - is specified, a 24-hour clock is used. A tod may be specifiedu
jUlt hhfollowed bya meridian.

date

A date is a specific month and day, andpoesibly a year. Acceptable formats are
mm/ddl/IIII) and monthname tId(,IIJI) It omitted, the year delaultsto the current year; il a
year is specified as a number leu than 100, 1900 is added. If a number not followed by a
day or relative time· unit occun, it will be interpreted as a year il a totl, monlhname,and
dd have already been specified; otherwise, it will be treated as a tod. This rule allows the
output Irom date(l) or ctime(3) to be passed as input to ,etdate.

day

A dall 01 the week may be specified; the current day will be used if appropriate. A da.1I
maybe preceededby a number, indicating which instance 01 that day is desired; the
default is 1. Negative numbers indicate times past. Some symbolic numbers are
accepted: I.at, next, and the ordinals flrat through twelfth (.eeond is ambiguous, and
is not accepted as an ordinal number). The symbolic number next is equivalent to I;
thus, ne~' montlall refers not to the immediately coming Monday, but to the one a week
later.

relative time
Specifications relative to the current time are also accepted. The lormat is (number) unit;
acceptable units are year, month, tortnlsht, w_k, day, hour,mlnute,and HCOnd.
The actual date istormed as lollows: first, any absolute date and/or time is processed and converted. Using that time as the .base, day-ol-week speciBcations are added; last, relative
specificationa ar.e used. If a date or day is speciBed, and no absolute or relative time is given,
midnight is used. Finally, a correction is applied so that the correct hour of the day is produced
after allow in I lor daylight savings time differences.

Getdtdt acceptsmoet common abbreviations for days, months, etc.; in particular, it ,recognizes
them with upper or lowercase fint letter, andrecognize8 three-letter abbreviations lor any of
them, with or without a trailing periOd. Units, such as weeks, may be specified in the singular 01'
plural. Timezone and meridian values may be in upper or lower case, and with O'r without
periods.
FILES
lusr/lib /libu.a
SEEALS()
ctime(3),time( 2)

24

Last change: 6 JanuarylD84

Sun Release 1.1

GETDATE(3)

SUBROUTINES

GETDATE(3)

BUGS

Because "tJcc(l) is used to parse the date, getdtJte cannot be used a subroutine to any program
that also needs "tJcc.
The grammar and scanner are rather primitive; certain desirable and unambiguous constructions
are not accepted. Worse yet, the meaning of some legal phrases is not what is expected; nezt
week is identical to e weeks.
The daylight savings time correction is not perfect, and can get confused if handed times between
midnight and 2:00 am on the days that the reckoning changes.
Because loctJltime(2) accepts an old-style time format without zone information, attempting to
pus getdtJte a current time containing a different zone will probably fail.

Su Release 1.1

Last change: 6 January 1984

25

GETENV(3)

SUBROUTINES

GETENV(3)

. NAME

getenv - value for environment name
SYNOPSIS

char *.etenv(name)
char *name.
DESCRIPTION

Getenv searches the environment list (see envirDn(5)) for a string of the form nsme-=va/ue and
returns a pointer to the string value if such a string is present, otherwise ,etenv returns the value
o (NULL).
SEE ALSO

environ(5), execve(2)

26

Last change: 19 January 1983

Sun Release 1.1

SUBROUTINES

GETFSENT ( 3 )

GETFSENT ( 3 )

NAME
getrsent, getrsspec, getrsfile, getrstype, setfsent, endfsent - get file system descriptor file entry

SYNOPSIS

#lnelude 
atruet latab ·settaentO
.truet I.tab *setl..pee(.pee)
ehar ·.peea
.truet I.tab ·setlafUe(ftle)
ehar ·~Iea
.truet I.tab ·setl.t),pe(t)'pe)
ehar ·t)'pea
lnt .etl.entO
lnt endlsentO
DESCRIPTION

Get/sen I, get/sspec, get/sl1lpe, and gd/sfiJe each return a pointer to an object with the following
structure containinl the broken-out fields of a line in the file system description file, < fstab.h>.
struct fstab {
char
char
char
int
int

·Cs_spec;
·ts_file;
·fs_type;
tsJreq;
tS..,PU8no;

};
The fields- have meanings described in 1814(,(5).
Get/senl reads the next Iina ot the file, opening the file it necessvy.

Set/sent opens and rewinds the file.
End/senl c10ees the file.
GetJ"pec and lelj8fiJe sequentially search from the- beginninl of tile file until a matching special
file Dame or file system file name is foand, or until EOF is encountered. Get/st1lpe does likewise,
matchiDI on the file system type field.
FILES
/etc/fstab

SEE ALSO
fstab(i~

DIAGNOSTICS

Nulrpointer- (p):--retufDed ·OD EOF or eJrOJ.

BUGS
The retara vat.a points to statk iDfoJmaUoa whleh is ovenmUen ia eae" eall.

Suo Relealff 1.1
;-

Las' change: 23 August 1983

27

SUBROUTINES

GETGRENT (3 )

GETGRENT(3)

NAME

getgrent, getgrgid"; getgrnam, setgrent, endgrent - get group file entry
SYNOPSIS

#lne1ude 
.truct group *setgrentO
atruct group *setgrald(ald)
lnt slda
.truct group *setpnam(name)
char *namea
aetsrentO
endsrentO
DESCRIPTION
Getgrent, getgrgidand getgrnam each return pointers to an object with the following structure
co,ntaining the broken-out fields 01 a line in the group file:

I!Itruct grGUp {
char
*gr_name;
~har
*gr"passwd;
int
gr-lid;
char
**,r_mem;

};
The members of this structure are:
gr_name
gr.J)asswd
gr...lid
gr_mem

The name or the group.
The encrypted password of the group.
The numerical group-IDe
Null-terminated vector of pointers to the individual member namel!l.

Gd,rent simply reads the next line while ,et,r,id and ,et,rntlm search until a matching ,id or
name il!l found (or until EOF is encountered). Each routine picks up where the others leave 08' 80
l!Iuccel!l8ive calls may be used to search the entire file.
A call to letgrent has the effect of reWinding the group file to allow repeated searches. Endgrent
may" be called to dose the group file when procel!ll!ling il!l complete.

FILES

/etc/group
SEE ALSO
getlogin(3),getpwent(3), group(S)
DIAGNOSTICS
A null pointer (0) is returned on EOF or enor.
BUGS

The return value points to static information which is overwrittenoDeachcal1.

28

Last change: 23 August 1983

SUD Release 1.1

GETLOGIN ( 3 )

SUBROUTINES

GETLOGIN(3)

NAME

getlogin - get login name
SYNOPSIS
cbu

·.etloslnO

DESCRIPTION
Getlolin returns a pointer to the login name as lound in / etc/utmp. It may be used in conjunction with letpwnam to locate the correct password file entry when the same userid is shared by
several login names.
If letlolin is called within a process that is not attached to a typewriter, it returns NULL. The
correct procedure lor determining the login name is to first call ,et/o,in and il it lails, to call
,etpwuid(,etuidO)·

FILES

/etc/utmp
SEE ALSO
getpwent(3), getgrent(3), utmp(S)
DIAGNOSTICS
Returns NULL (0) il Dame not found.
BUGS

The return values point to static data whose content is overwritten by each call .
. Gdlogin does not work ror processes running under a ptV (lor example, emacs shell buffers, or shell
tools) unless the program "lakes" the login name in the / etc/ utmp 61e.

SUD

Release 1.1

Last change: 20 March 1984

29

GETPASS(3)

SUBROUTINES

GETPASS(3)

NAME

getpass - read a password
SYNOPSIS

char *getpass(prompt)
char *prompt.
DESCRIPTION

GetptJBB reads a password (rom the file I devl tty, or 'if that cannot be opened, (rom the standard
input, alter prompting with the null-terminated string prompt and disabling echoing. A pointer is
returned to a null-terminated string ot at most 8 characters.

FILES

Idevltty
SEE ALSO

crypt(3)
BUGS

The return value points to static data whose content is overwritten by each call.

30

Last change: 19 January 1983

Sun Release 1.1

GETPW(3)

SUBROUTINES

GETPW(3)

NAME
getpw - get name from uid
SYNOPSIS

setpw(uld, but)
char *bufl
DESCRIPTION

Getpw .. ob.oleted by setpwent(3).
Gelpw searches the password file for the (numerical) uid, and fills in 6u/ with the corresponding
line; it returns non-zero if uid could not be found. The line is null-terminated.
FILES

/etc/passwd
SEE ALSO

getpwent(3), passwd(5)
DIAGNOSTICS

Non-zero ·return on error.

Sun Release 1.1

Last change: 26 August 1983

31

GETWD(3)

SUBROUTINES

GETWD(3)

NAME

getwd - get current working directory pathname
SYNOPSIS

#lnc:lude 
char *Ietwd(patbname)
c:har pathname(MAXPATIILENb
DESCRIPTION

Getwd copies the absolute pathname of the current workinl directory to potlanome and returns a
pointer to the result.
DIAGNOSTICS

Getwd returns zero and places a IDeas ale in potlanome if an error

OCCUI'8.

BUGS

Getwd may faU to return to the current directory it an error OCCUI'8.

32

Last change: 25 February 1983

Sun Release 1.1

INITGROUPS ( 3 )

SUBROUTINES

INITGROUPS( 3)

NAME
initgfoups - initialize group access list
SYNOPSIS
lnltsroupa(name, baa.ld)
cha.. *name,
lnt bailelld,
DESORIPTION

InilgroupI reads through the group file and sets up, using the 8elgroup8(2) call, the group access
list for the user specified in name. The ba8egid is automatically included in the groups list. Typically this value is given as the group number from the password file.
FILES
fete/group
SEE ALSO
setgroups(2)

DIAG NOS TIOS

Inil,roupI returns -1 if it was not invoked by

the_super-user~

BUGS
Initgroup8 usea the routines based on getgrent(3). If the iiivoldng prog.ram uses any of these routines, the group structure will be overwritten in the call to initgro-up8.
Noone seems to keep letc/group up to date.

Sua Release 1.1

fiast cit all Ie: 23 August 19-83

33

SUBROUTINES

INSQUE(3)

NAME

insque, remque.,.,.

iIlsertlre~oye ~Iement

from a

que1J~

SYNOPSIS
.tI'U~t

qeleql {
a.tr1lct qt;tlem *qj'o...,,,,.
atr1lct qelem *CL.backl
char ~dat.DI

}I
lnlque(elem, pred)
.truct qelem ·ele~, *prech
remque(elem)
atr1lct qelem *e1eJll;I
DESORIPTION
In'lJue ~ (0) if there is no available memory or if the &ren>a
has been detectably ~orrupted by storing outside the bounds of a block.

36

Last change: 21 March 1984

Sun Release 1.1

MALLOC(3)

SUBROUTINES

MALLOC(3)

BUGS
When reGlloc returns 0, the block pointed to by ptr may be destroyed.

AlloctJ is machine dependent; it's use is discouraged.

S.a-Rele8S4' l.f

Last chaage: 21 March 1984

37

SUBROUTINES

MKTEMP(3)

MKTEMP(3)

NAME

mktemp - make a unique file name
SYNOPSIS

char ·mktemp(tempiate)
char ·templatel
DESCRIPTION
Mldemp replaces template by a unique file name, and returns the address 01 the template. The

template should look like a file name with six trailinl X's, which will be replaced with the current
process id and a unique letter.

Note.:
• Mitemp actually change. the template strinl which you pus, this means that you cannot use

the same template strinl more than once - you need a fresh template for every unique Ole you
want to open .
• When mitemp is creatiDI a new unique filename it ehecksfor the prior existellce 01 a file with
that name. This means that if you are creating more than one unique filename, it is bad practice to use the same root template for mUltiple invocatioDsof ~mJ:temp.
SEE ALSO

letpid(2)

38

Last change: 6 January 1984

Sun Release 1.1

SUBROUTINES

MONITOR (3)

MONITOR (3)

NAME
monitor, monstartup, moncontrol- prepare execution profile
SYNOPSIS

monltor(lowpe, hl,hpe, buffer, but.lze, nfunc)
lnt (·lowpe)(), (·hlchpc)()1
Ihort buffer 01
mODltutup(lowpe, h1ahpe)
lnt (·lowpc)(), (·hlshpe)().
mODcontrol(mode)
DESORIPTION
There are two different forma of monitorinl available: An executable program created by:
cc -p •.•
automatically includes calls for the pro.l(l) monitor and includes an initial call to its start-up routine mon,'ar'up with default parameters; monilor need not be called explicitly except to gain fine
control over proll buffer allocation. An executable program created by:
. cc -PI ...
automatically includes calls for the gpro.l(l) monitor.

Mon,'ar'up is a high level interface to profil(2). Lowpe and higlape specify the address range that
il to be sampled; the lowelt address sampled is that of lowpe and the highest is just below laiglape.
Mon"ar'up allocatel'space usin, B6rk(2) and puses it to monilor (see below) to record a histo,ram or periodically iampled values or the program counter, and of counts of calls of certain functionl, in the buffer. Only callI of functionl compiled with the profiling option -p of cc(l) are
recorded.
To prolle the entire program, it is sufficient to use
extern et~xt();
monltartup(oXSOOO, etext);

Elez' lies jult above all the pro,ram text, see end(3).
To atop execution monitorinl and write the resultlon the file mon.lflll use
monitor(O);
theD pro/(l) caD be uled to examine the resultl.

Moncontrol il used to lelectively control prollmg within a proaram.- This works with either
,p,ol(l) type prollinl. WheD the program star-tl, profiling beginl. To stop the collectloa 01 histOiraID tiekl and call eounta use moneoRlrol(O); to resulDe tlie collectiolt of histogram
tic,kl and caU countl use moneont,o(l). Thil allows the cost of particular operations to be meas.,.,0J(1~ or

ured. Note that aD output file will be produced UpOD program exit irregardless-- of the state of

moneonl,ol.
Moni'o, is a low level interface to profil(2~ Lowpc and higlape are the addresses of two (unctions;
buffer is the addre. o~ ,a (user supplied) array ot IV/8ize short integers. At most nJune caU counts
can be kept. For the results to be significant, especially where there are small, heavily used routinea, it il sugelted that- the buler be no more tlian &- few times amaller than the range of IocatioDI sampled. Monitor divides the buffer into space to record the histogram of program counter
samples over the range 'owpe to Aigbpe,and space to record call COUDts- of fUDctions compiled with
the -p option to ee(l}.
To profile the entire program,.it is su.licient to use

Sun Release 1.1

Last change: 19 January 1983

39

.MONl'rOR (3)

MONITOR (:3<)

extem :etext();

mODif,or(0x8000, . etext,· bul,

bufsi~e,· .'UDC);

mOD.out

. SEE ALSO
cc(l), prol(l), Iprol(1),protll(2), sbrk(2)

40

Las.t che.nge: 19 JaDuary"1983

NLIST(3)

SUBROUTINES

NLIST( 3)

NAME
nlist - get entries from name list
SYNOPSIS

#lnelude < nllst.h >
nlUt(fllename, nl)
ehar *fllenameJ
.tl'uet nllat nl[];

DESCRIPTION
Mi" examines the name list in the given executable output file and selectively extracts a list of
values. The name list consists of an array of structures containing names, types and values. The
list is terminated with a null name. Each name is looked up in the name list of the file. It the
name is found, the type and value of the name are inserted in the next two fields. If the name is
not found, both entries are set to o. See 0.ouI(5) for the etructure declaration.
This subroutine is useful for examining the system name list kept in the file /vmunb.. In this
way prolrams can obtain system addresses that are up to date.
SEE ALSO
a.out(5)
DIAGNOSTICS
All type entriel are let to 0 it the file cannot be found or if it is not a valid namelist.

Sun Reiease 1.1

Last change: 19 January 1983

41

SUBROUTINES

PERROR'(3)

PERROR(3)

NAME

perror, sys_errlist, ays_nerr, errno - system error messages
SYNOPSIS

perror(.)
char ••,
lot .y._nerr,
char ·.y._erru.t[].
lot errno,
DESCRIPTION

Perror produces a short error meuage on the standard error file describing the last error encountered during a call to the system from a C program. First the argument string 8 is printed, then
a colon, then the message and a new-line. Most usefully, the argument string is the name of the
program which incurred the error. The error number is taken from the external variable errno
(see intro(2)), which is set when errors occur but not cleared when non-erroneous calla are made.
To simplifY variant formatting of meuages, the vector of message strings '1I,_errli" is provided;
errno can be used as an index in this table to get the meuage string without the newline.
SII,_nerr is the number of messages provided lor in the table; itahould be checked because new
error codes may be added to the system before they are added to the table.
SEE ALSO
in~ro(2),

42

psilnal(3)

Last change: 19 January 1983

Sun Release 1.1

PSIGNAL(3)

SUBROUTINES

PSIGNAL(3)

NAME
pslgnal, &ys_siglist - system signal messages
SYNOPSIS

pslpal(sts, s)
unsigned
char
char *sy-_slsUatlb

*_.

-ls.

DESCRIPTION
PBignal produces a short message on the standard error file describing the indicated signal. First
the argument string B is printed, then a colon, then the name of the signal and a new-line. Most
usefully, the argument string is the name of the program which incurred the signal. The signal
Dumber should be from among those found in <,ignal.A>.

To simplify variant formatting of signal names, the vector of message strings B1IB_BigliBt is provided; the signal number can be used as an index in this table to get the signal name without the
newline. The define NSIG defined in < Bignal.A> is the number of messages provided tor in the
table; it should be checked because new signals may be added to the system before they are added
to the table.
SEE ALSO
perror(3), signal(3)

SUD

Release 1.1

Last change: 26 August 1983

43

SUBROUTINES

QSORT(3)

QSORT(3)

NAME

qsort - quicker sort
SYNOPSIS

qlort(baae, nel, width, eompar)
ehar *bale.
lnt (*eompar )0.
DESCRIPTION
Qaorl is an implementation of the quicker-80rt algorithm. The first argument is a pointer to the
base of the data; the second is the number of elements; the third is the width of an element in

bytes; the laat is the name of the comparison routine to be called with two argumentawhich are
pointers to the elements being compared. The routine must return an integer less than, equal to,
or greater than 0 according as the first argument is to be considered less than, equal to, or greater
than the second.
SEE ALSO

sort(l)

44

Last change: 19 January 1983

Sun Release 1.1

SUBROUTINES

RANDOM(3)

RANDOM(3)

NAME
random, srandom, initstate, setstate - better random number generator; routines ror changing
generatorl

SYNOPSIS

Ions randomO
srandom(leed)
Int seed.
Ions *lnltstate(seed, Itate, n)
unllsned seeel.
Ions *.tat..
Int

n.

Ions *setltate(ltate)
Ions *statel
DESCRIPTION

Random ules a non-linear additive feedback random number generator employing a default table
of size 31 long integers to return successive pseud~random numbers in the ranme from 0 to 2~u_1.
The period of this random number generator is very large, approximately 16*(2 1_1).
Random/lrandom have (almost) the same calling sequence and initialization properties as
rand/srand. The difference is that rand(3C) produces a much less random sequence - in fact, the
low dozen bits generated by rand go through a cyclic pattern. All the bits generated by random
are usable. For example, "randomO&Ol" will produce a random binary value.
Unlike ,rand, Brandom does not return the old seed; the reason for this is that the amount of state
information used is much more than a single word. (Two other routines are provided to deal with
restarting/changing random number generators). Like rand(3C), however, random will by default
produce a lequence of numben that can be duplicated by calling ,random with 1 as the seed.
The initltate routine allows a state array, passed in as an argument, to be initialized for future
use. The size of the state array (in bytes) is used byinilltale to decide how sophisticated a random number generator it should use - the more state, the better the random numbers will be.
(Current "optimal" valuel for the amount of Itate information are 8, 32, 64, 128, and 256 bytes;
other amounts will be rounded down to the nearest known amount. Using less than 8 bytes will
cause an error). The seed for the initialization (which specifies a starting point for the random
number sequence, and provides for restarting at the same point) is also an argument. Ini','a'e
returns a poi~ter to the previous state information array.
Once a stat@ has been initialized, the sdslale routine provides for rapid switching between states.
Sd,'ate returns a pointer to the previQus state array; its a.rgument state array is used for further
random number generation until the ~~xtcall to initsttite or setltate.

ti

Once a state array hat been initializ~tt!
may be testaried at a different point either by calling
initltGle,(with the de~ired seed, the state array, and its size) or by calling both setstate (with the
state arr2tY) and sra,adom (with the desired seed). The advantage of calling both setstate and
IrGndorra iii that the aile of ~he state arr~y does not have to be remembered after it is initialized.
a

With 2ql bytes of 8f~'llliformation" ~he period of the random number generator is greater than
208, whiclshould be ~JUn~feht for m06t j)'..arp08es.

hlAaNosTICS
lr fnilsta'e is called witJa tess than 8 bytes of state information, or il ,el,Iate detects that the state
information has been garbled, error messages are printed on the standard error output.
SEE ALSO
rand (3C)

Sun Release 1.1

Last change: 9 March 1984

45

RANDOM(3)

SUBROUTINES

RANDOM(3)

BUGS

About 2/3 the speed or fGnd(3C).

46

Last change: 9 March 1984

Sun Release 1.1

REGEX(3)

SUBROUTINES

REGEX(3)

NAME
re_comp, re_exec - regular expression handler
SYNOPSIS

char *re_comp(.)
char *••
re_exee(a)
char *••
DESCRIPTION

Re_comp compiles a string into an internal form suitable for pattern matching. Re_ezec checks
the argument string against the last string passed to re_comp.
Re_comp returns 0 if the string B was compiled successfully; otherwise a string containing an error
message is returned. It re_comp is passed 0 or a null string, it returns without changing the
currently compiled regular expression.
R e_ezec returns 1 if the string 8 matches the last compiled regular expression, 0 if the string 8
failed to match the last compiled regular expression, and ·1 if the compiled regular expression was
invalid (indicatinl an internal error).
The strings passed to both re_comp and re_ezec may have trailing or embedded newline characters; they are terminated by nulls. The regular expressions recognized are described in the
manual entry for ed(l), given the above difference.
SEE ALSO
ed(l), eX(l), egrep(I), fsrep(I), grep(l)
DIAGNOSTICS

Re_ezec returns -1 for an internal error.
R e_comp returns one ot the tollowinl strings it an error occurs:
No premo"8 re,ular ezprel8ion
Re,ular ezpre88ion too Ion,
unmatched \(
mi"in, J
too manu \(\) pairl
unmatched \)

Sun Rele~ 1.1
,i

Last change: 4 March 1983

47

SUBROUTINES

SCANDffi(3)

SCANDm(3)

NAME

scandir, alphasort - scan a directory
SYNOPSIS

:f/:lnc1ude 
*lnclude 
Icandlr(dlrname, nameltat, lelect, compar)
char *dlrnamel
Itruct direct *(*namellatD).
Int (*lelect)OI
Int (*compar)01
alphalort(dl, dl)
.truct direct **dl, *·dll
DESCRIPTION

SctJndir reads the directory dirntJme and builds an array of pointers to directory entries using mtJlloc(3). The third parameter. is a pointer toa routine which .is called with a pointer to a directory
entry and should return a non zero value if the directory entry should be included in the array.· If
this pointer is null, then all the directory entries will be included. The last argument is a pointer
to a routine which is passed to "ort(3) to !Ort the completed array . II this pointer is null, the
array is not sorted. AlphtJ,orl is a routine which will 80rt the array alphabetically.
SctJndir returns the number of entries in the array aDd a pointer to the array throu&h the parameter namelist.
SEE ALSO

directorY(3),malloc(3'), q80rt(3)
DIAGNOSTICS

.aeturns -1 if the directory cannot be opened for reading or if molloc(3) cannot allocate enough
memory to hold. all the data ~tructures.

48

Last change: 19 January 1983

SunR.lease .1.1

SETJMP(3)

SUBROUTINES

SETJMP( 3)

NAME
setjmp, longjmp - non-local goto
SYNOPSIS

*lnelud. 
val .. aetjmp(env)
Jmp_buf anv,
lonl.lmp(env, val)
Jmp_buf mv,
val - _aetjmp(env)
Jmp_buf anv,
_lon&Jmp(env" val)
Jmp_buf anv,
DESCRIPTION
Seljmp and longjmp are useful for dealing with errors and interrupts encountered in a low-level
subroutine of a programa
Seljmp saves its stack environment in env for later use by longjm). Seljmp also saves the register
environment. Seljmp returns the value O. If a longJmp call will be made, the routine which called
'djmp should not return until after the longjmp has returned control (see below).
L ongjmp restores the environment saved by the last call of ,etjmp, and then returns in such a
way that execution continues as if the call of 'djmp had just returned the value val to the function that invoked ,eljmp. The calling function must not itself have returned in the interim, otherwise longjmp Will be returning control to a possibly non-existent environment. All memorybound data have values as of the time longjmp was called. The machine registers are restored to
the values they had at the time that ,djmp was called. But, because the resblter storage class is
only a hint to the C compiler, variables declared as repter varia.bles may not necessarily be
assigned to machine registers, so their values are unpredictable after a longjmp. This is especially
a problem for programmers trying to write machine-independent C routines.

The following code fragment indicates the low of control of the ,dimp and longjmp combination:
.. . /unclion'4eclaralion
jmp_bur
my_environment;

... code ...

11'( setjmp (my_environmen.t J)

{

Ihi.. i, the code after the return from longjmp
... more code
rapt.r variable, hG.ve. unpredictable vtflue,
more code
o

•

0

0

o· 0

•

0

0'

0'

0

le", {
Ihi, i, Ihe rdurn from .etimp.
more code:
Do not mcotlifg resletel' variable,
in Ihi, Ie, oJ Ihe codt
o • • more cod.e
o •••
o

<

•

0

O.

•

•

}
Seljmp and longjmp save and restore the signal mask. ,igBetma,k(2), while _,djmp and; _Iongjmp
manipulate only the C stack and registers.

SUD

Release 1.1

Last change: 26 August 1983

49

SUBROUTINES

SETJMP (3)

SETJMP(3)

SEE ALSO

sigsetmask(2), sigvec(2), signal(3)

BUGS
Setjmp does not save current notion or whether the process is executing on the signal stack. The
result is that a longjmp to some place on the signal stack leaves the signal stack state incorrect.

Last change: 26 August 1983

Sun Release 1.1

SETUlD(3)

SUBROUTINES

SETUID(3)

NAME
setuid, seteuid, setruid, setgid, setegid, setrgid - set user and group ID

SYNOPSIS

setuld(uld)
seteuld(euld)
setruld(ruld)
letlld(lld)
setesld(epd)
aetrpd(,.&ld)
DESORIPTION
Sduid (·,dgid) sets both the real and effective userlD-(gl'oup ID)ot the current process to as
specified.

Sdeuitl (,etegitl) sets the effediveuser ID (group ID) -of the current process.
Sdruitl (,druid) seta 'the real user ID (groupID) ofthecUfrentproce&s.
These callsareon:lypermitted tothesuper-userorirthe argument is the real or ellectiveID.

SEE ALSO
setreuid( 2),aetregid(2),getuid( 2), getgid( 2)
DIAGNOSTICS
Zero isretumed if the user(group)ID is set; -1 is returned otherwise, with the global variable
errnoset aa 101 setreuid Olsetregid.

Su.Release 1.1

Last cbange: 1 April 1983

51

SUBROUTINES

SIGNAL (3)

SIGNAL (3)

NAME

signal - simplified software signal facilities
SYNOPSIS

#lnclude <.Ignal.h>

(*sJanal(sis, tune»O
void (*tunc)O.
DESCRIPTION

Signal is a simplified interface to the more leneral ,igvee(2) lacility.
A signal is generated by some abnormal event, initiated by a user at a terminal (quit, interrupt,
stop), by a program error (bus error, etc.), by request ot another program (kill), or when a process
is stopped because it wishes to access its control terminal while in the background (see tty(4)).
Signals are optionally generated when a process resumes after being stopped, when the status ot
child processes changes, or when input is ready at the control terminal. Most signals cause termination of the receiving proceaa if no action is taken; some silnals instead cause the process receiving them to be stopped, or are simply discarded il the proceaa has not requested otherwise.
Except for the SIGKILL and SIGSTOP signals, the lignal call allows signals either to be ignored
or to cause an interrupt to a specified location. The tollowin, is a list 01 all sipal. with names as
in the include file < ,ignal." > :
SIGHUP
SIGINT
SIGQUIT
SIGILL
SIGTRAP
SIGIOT
SIGEMT
SIGFPE
SIGKILL
SIGBUS
SIGSEGV
SIGSYS
SIGPIPE
SIGALRM
SIGTERM
SIGURG
SIGSTOP
SIGTSTP
SIGCONT
SIGCHLD
SIGTTIN
SIGTTOlJ
SIGIO t
SIGXCPO
SIGXFSZ
SIGVTALRM
SIGPROF
SIGWINCH

1
2
3*
4*
5*
6*
7*
8*
0
10*
11*
12*
13
14
15
16
17t
18t

hangup
interrupt
quit
illegal instruction
trace trap
lOT instruction
EMT instruction
floating point exception
kill (cannot be caught or ignored)
bU8 error
segmentation violation
bad argument to system call
write on a pipe with no one to read it
alarm clock
software termination signal
urgent condition present on socket
stop (cannot be caught or ignored)
stop signal generated from keyboard
19, continue alter stop
20. child status has changed
21 t background read attempted trom control terminal
22t background write attempted to control terminal
23 i/o is possible on a descriptor (see Jentl(2)}
24 cpu time limit exceeded (see ,eerlimit(2)}
25 file size limit exceeded (see ,eerlimit(2)}
26 virtual time alarm (see ,ditimer(2»
27 profiling, timer alarm (see ,eeitimer(2))
28 window changed

The starred signals in the list above cause a core image if not caught or ignored.
If June is SIG_DFL, the default action lor signal Big is reinstated; this default is termination (with

a core image tor starred signals) except tor signals marked with. or t. Signals marked with. are
discarded il the action is SIG_DFL; signals marked with t cause the process to stop. If June is
SIG_IGN the signal is subsequently ignored and pending instances of the signal are discarded.

52

Last change: 15 June 1083

Sun Release 1.1

SUBROUTINES

SIGNAL (3)

SIGNAL (3)

Otherwise, when the signal occurs further occurences of the signal are automatically blocked and

June is called.
A return from the function unblocks the handled signal and continues the process at the point it
was interrupted. Unlike prevlou••lanal faclUtls, the handler June remain. Installed after
• sign,.! ha. been deUvered.
It a caught signal occurs during certain system calls, causing the call to terminate prematurely,
the call is automatically restarted. In particular this can occur during a read or write(2) on a slow
device (such as a terminal; but not a file) and during a wait(2).
The value of ,ignal is the previous (or initial) value of June for the particular signal.
Mter a Jork(2) or vJork(2) the child inherits all signals. An ezeeve(2) resets all caught signals to
the default action; ignored signals remain ignored.
RETURN VALUE
The previous action is returned on a succe68ful call. Otherwise, -1 is returned and errno is set to
indicate the error.
ERRORS

Sunal wiD fail and no action will take place if one of the following occur:
IEINVALJ
Si, isnC)t a valid signal number.
IEINVALJ

An attempt is made to. ignore or sup.ply a handler for SIGKaL or SIGSTOP.

(EINVALJ

An attempt is made toignore SIGCONT (by defaultSIGCONT is i&nored).

SEE ALSO
kill(l), ptrace(2), kill(2), sllVec(2), sigblock(2), slgsetmask(2), sigpause(2), sigstaek(2), setjmp(3),
tty(4)
NOTES' (VAX-II)
The handler routine can be declared:

, handler(eil, code, scp)
Here ,ig is the signal number, into which the hardware faults and traps are mapped as defined
below. Code isa p,arameter which is either a constant as given below or, for compatibility mode
faults, the code provided by the hardware. Scp is a pointer to the ,truet ,igeontezt. used / by the
system to restore the process context from before the signal. Compatibility mod.e faults are dis.tinguished from the other SIGaL traps by havinl PSL_CM setin the psI.
The followinl defines. the mappinl' of hardware traps to signals and codes. All of, these symbols
are defined i. < lignal.. h>:
Hardwa,e condition
Signal
Code
Arithmetic traps:
Integer overfiC)w
SIGFPE
SIGFPE
Inteler .divieiQn by zero.
Floatinl·.overftow, trap
SIGFPE
FloatiDI/decimaldivision. by zero SIGFPE
SIGFPE
Floatin&.underJiow trap
SIGFPE
Decimal. Qverfiow· trap
SlGFPE
Subacript-raQ"
SIGFPE
Floatinloverfiow falJlt
Floating divide by zero fault
SIGFPE
SIGFPE
Floating underfiow fault
Length. accees (ontrol
SIGSEGV
ProtectioD .violatiQn
SIGBUS·
SIGaL
Reae"ed inetru.;tioQ,

FPE_INTOVF_TRAP
FPE_INTDIV_TRAP
FPEYLTOVF_TRAP
FPE__FLTDIV_TRAP
FPE_FLTlJND_TRAP
FPE....DECOVF__TRAP
FPE_SUBRNG_TRAP
FPE_FLTOVF_FAUL T
FPE_FLTDIV~FAULT

FPE_FLTUND_FAULT

Last change: 15 June 1983

53

SIGNAL (3)

Customer-reserved instr.
Reserved operand
Reserved addressing
Trace pending
Bpt instruction
Compatibility-mode
Chme
Chll18
Chmu

54

SUBROUTINES

SIGEMT
SIGILL
SIGILL
SIGTRAP
SIGTRAP
SIGILL
SIGSEGV
SIGSEGV
SIGSEGV

SIGNAL (3)

ILL_PRIVIN_FAUL T
ILL_RESOP_F AUL T

hardware supplied code

Last change: 15 June 1983

Sun Release 1.1

SLEEP (3)

SUBROUTINES

SLEEP(3)

NAME

lleep - lu.peDd executioD tor iDtervai
SYNOPSIS
aleep(aeeond.)
uulped .ecoDde,
DESCRIPTION

Slee, suspeDds the current process trom execution tor the number ot seconds specified by the
argument. The actual suspension time may be up to 1 second less than that requested, because
schedulecl wakeups occur at fixed I-second intervals, and may be an arbitrary amount longer
because ot other activity in the system.
Slee, il implemented by setting an interval timer and pausing until it expires. The previous state
ot this timer is saved aDd restored. It the sleep time exceeds the time to the expiration or the
previous value ot the timer, the procel!ll sleeps only until the timer would have expired, and the
signal which occurs with the expiration ot the timer is sent one second later.
SEE ALSO

setitimer(2), silpause(2)

BUGS
AD interface with flner resolution is needed.

Sua Release 1.1

Last change: 13 June 1983

55

STRING (3)

NAME

SUBROUTINES

STRING(3)

strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, index, rindex - string operations

SYNOPSIS

#lnclude 
char *streat(sl, II)
char *11, *11.
char *ltrncat(ll, II, n)
char *11, *11,
stremp(ll, II)
char *11, *.1,
Itrnemp(ll, II, a)
char *11, *11.
char *ltrepY(ll, II)
char *11, *11,
char *ltrncpY(ll, II, D)
char *11, *11,
Itrlen(l)
char *1'
cha.. *lndex(I, e)
cha.. *1, e,
cha.. *.. lndex(I, c)
cha.. *1, CJ
DESORIPTION

These functions operate on null-terminated strinls. They do not check for overftow of any receivinl strinl.
SIret" appends a copy of string " to the end of string 11. Strnet" copies at most ncharacters.
Both return a pointer to the null-terminated result.
Stremp compares its arguments and returns an integer greater than, equal to, or less than 0,
accordinl as 11 is lexicographically greater than, equal to, or less than ". Strnemp makes the
same comparison but looks at at moat n characters.
Strep1I copies strinl " to 11, stoppin& after the null character has been moved. SIrnep1I copies
exactly n characters, truncating or null-paddinl "; the tarlet may not be Dull-terminated if the
length of " is n or more. Both return 11.
Slrlen returns the number of non-null characters in ,.
Indez (rindez) returns a pointer to the first (last) occurrence of character e in strinl I, or zero if c
does not occur in the string.

BUGS
Stremp uses native character comparisoD, which is sigDed OD the SUD.

On the Sun processor (and OD some other machines), you caD NOT use a zero poiDter to iDdicate
a Dull striDg. A zero pointer is an error aDd results iD aD abort of the program. If you wish to
indicate a Dull string, you must have a pointer that points to an explicit Dull striDg. OD PDP-II's
and VAXten, a source pointer of zero (0) caD generally be used to indicate a Dull string. Programmers using NULL to represent an empty string should be aware of this portability issue.

56

Last change: 19 January 1983

Sun Release 1.1

SWAB (3)

SUBROUTINES

SWAB(3)

NAME
swab - swap bytes
SYNOPSIS

.wab(lrom, to,nbytea)
char *lrom, *to,
DESCRIPTION
SwtJb copies nbyte, bytes pointed to by from to the position pointed to by to, exchanging adjacent
even and odd bytes. It is useful for carrying binary data between high-ender machines (mM
3M's, MC68000's, etc) and low-ender machines (PDP-II's and VAX'es).

Nbule, should be

even~

The from and to addresaes should not overlap in portable programs.

Last ('hange: 20 :March 1984

57

SYSLOG(3)

SYSLOG(3)

SUBROUTINES

NAME
syslog, open log, close log - control system 10,
SYNOPSIS

#lnclude 
openlog(ldent,loptat)
char *ldentl
ayalo,(prlorlty, meaaa,e, parametera ... )
char *muaase,
cloaelo,()
DESCRIPTION
S1/,IOI arranges to write the mello-Ie onto the system log maintained by '1/,'o,(8). The message is
tagged with priorit1/. The me!Sage looks like a print/{3S) string except that %m is replaced by
the current error message (collected from errno). A trailing newline is added if needed. This
message will be read by '1/"°1(8) and output to the system console or files as appropriate.
IIspedal processing is needed, openlol can be called to initialize the log file. Parameters are ident
which is prepended to every message, and 10l,tat which is a bit field indicating special status;
current values are:
L OG_PID

log the process id with each message: useful for identifying instantiations or daemons.

Openlol returns zero on success. If 8118101 cannot send datagrams to 8118Iol(8), then it writes on
/ dev/ console instead. If / dev/ con,o/e cannot be written, standard error is used. In either case, it
returns -1.
Olole/Ol can be used to close the log file. It is automatically -closed
call (see ezecve(2)).

OD

a successful exec system

EXAMPLES
syslog(LOG_SALERT, "who: internal error 23");
openlog{"servedtp", LOG_PID);
syslog(LOG_INFO, "Connection (rom host %d", CallingHost);
SEE ALSO
syslog(8)

58

Last change: 15 March 1984

Sun Release 1.1

SUBROUTINES

SYSTEM(3)

SYSTEM(3)

NAME

system - iuue a sheD command
SYNOPSIS

ayatem(atl'lns)
ehal' *atrlnlJ
DESCRIPTION

Sll,tem causes the "~ring to be given to ,1a(1) 88 input as ir the string had been typed as a commaDd at a terminal. The current process waits until the sheD has completed, then returns the
exit statuI of the sheD.
SEE ALSO

popen(3S), execve(2), wait(2}
DIAGNOSTICS

Exit status 127 indicates the shell couldn't be executed.

SUD

Release 1.1

Last change: 19 January 1983

59

TTYNAME(3)

SUBROUTINES

TIYNAME(3)

NAME

ttyname, isatty, ttyslot - find name of a terminal
SYNOPSIS
char *ttyname(flledea)

laatty(flledea)
tty_lotO
DESCRIPTION
Ttl/ntJme returns a pointer to the null-terminated path name ot the terminal device associated
with file descriptor ftledel.
l'tJttl/ returns 1 if pedel is associated with a terminal device, 0 otherwise.

Ttl/Ilot returns the number of the entry in the 111/1(5) file for the control terminal of the current
process.
FILES

/dev/·
/etc/ttys
SEE ALSO

ioctl(2), ttys(5)
DIAGNOSTICS

Ttl/ntJme returns a null pointer (0) it /Uedel does not- describe a terminal device in directory
'/dev'.
Ttl/Ilot returns 0 if I/etc/ttys' is inaccessible or if it cannot determine the control terminal.
BUGS

The return value points to static data whose content is overwritten by each caD.

60

Last change:- »JaD1IaJ'1 1983

Sa Release 1.1

VALL'OC(3)

SUBROUTINES

VALLOC(3)

NAME
vaUoc - aligned memory allocator
SYNOPSIS
char *vaUoc(8Iae)

uDllsned al&el
DESCRIPTION
Valloc allocates Bizebytea aligned on a page boundary. It is implemented by callingmalloc(3)
with a slightly larger request, saving the true beginning of the block allocated, and returning a
properly8ligned 'pointer.
DIAGNOSTIOS
Valloc returns a nuH pointer (0) if there is no available memory or if the arena has been detectably corrupted by storingouteide the bounds ofabloek .
.BUGS

V/rec itD't implemented.

SUD ~Relea.ae

1.1

Last change: 19 January 1983

61

VARARGS(3)

SUBROUTINES

VARARGS(3)

NAME

varargs - variable argument list
SYNOPSIS
#lnelude 

/unction(va_alllt)
va_del
va_lilt pvtJr;
va_Itart(pvtJr);
, - va_&I's(pvtJr, 'lIpe);
va_end(pvtJr );
DESORIPTION
This set of macros provides a means of writing portable procedures that accept variable argument
lists. Routines having variable argument lists (such as printJ{3S)) that do not use varargs are
inherently nonportable, since different machines use different argument p888ing conventions.

va_allat is used in a function header to declare a \rariable argumenl Hst.
va_del is a declaration ror va_aDat. Note that there ia no semicolon alter va_deL
va_lilt is a type- which can- be used for the variable 'Nr, which is used to traverse the list. One
such variable must always be declared.
va__tart(pvar) is called to initialize pvtJr to the beginning 01- tfae list.
V&_a...(pwr, 'lIPe) will retum the Dext argument in the list pointed to by pvsr. T,Ipe is the- type
the argument is expected to- be. Dilerent typea CaD be mixed, but It is up to the routine to tuo",
what- type of UJument it- expected, ame. it eaDDor-be determined at rUDtime.
va_end(p-uM) Ii uaedto BniR up.
Multiple trannall, each- braekett91 by va__. . . •••

.._eDcI, are peuibie.

EXAMPbE

-llae1ucle 
exec!(.ya_allat)
'¥a_del-

t

va_Ita" ap;
eiar:~:­

dru- ·arptlOO~
lnl- arpo - U;-

}
BtrG8-

It • ap to the calia, JOutine. to 
Itty(fd, but)
tnt fd,
(Itl'uet Iptyb *buf.
stty(fd, but)
Int fda
atl'uet Ipty b *buf.
DESCRIPTION

Tbt. Intel'face t. obloleted by loetl(I}.
Stt1lsets the state 01 the terminal associated with Ide Gtt1l retrieves the state 01 the terminal associated with Ide To set the state of a terminal the call must have write permission.
The 8tt1l call is actually Uioctl(fd, TIOCSETP, buf)", while the ,tty call is "ioetl(fd, TIOCGETP,
but)". See ioctl(2) and tI1l(4) for an explanation.
DIAGNOSTICS

II the call is successf'd 0 is returned, otherwise -1 is returned and the global variable errno contains the reason lor the failure.
SEE ALSO

ioetl(2}, tty(4}

8

Last change: 26 August 1083

SUD

Release 1.1

TIME (3C)

COMPATIDILITY ROUTINES

TIME(3C)

NAME
time, ftime - get date and time
SYNOPSIS

tlmeotda7 =- tlme(O)
tlmeotda7 =- tlme(tloe)
Ion. *tloel
*lDelude <171/t7pel.h>
#lDelude <171/tlmeb.h>
ftlme(tp)
Itruet tlmeb *tPI
DESCRIPTION

Thele lDtertae.. are obloleted by lettlmeotd&7(Z).
Time r~turns the time since 00:00:00 GMT, Jan. 1, 1970, measured in seconds.
If "De is nonnull, the return value is also stored in the place to which Iloe points.
The Ilime entry 8l1s in a structure pointed to by its argument, as de8ned by <8118/time1J.A>:
strud timeb

{
time_t
uDsigned
short
short

time;
short millitm;
timezone;
dstflal;

};
The structure contains the time since the epoch in seconds, up to 1000 milliseconds of moreprecise interval, the local time ZODe (measured in minutes of time westward from Greenwich), and
a f1aa that, if nonzero, indicatel that Daylight Saving time applies locally during the appropriate
part of the year.
SEE ALSO
date(I), gettimeofday(2), settimeofday(2), ctime(3)

SUn Rele., 1.1
i

"

Last change: 1 April 1983

9

TIMES (3C)

COMPATmILITY ROUTINES

TIMES(3C)

NAME

times - get process"times
SYNOPSIS

:#1nelude 
:#1nelude 
tlmea(bufrer)
atruet tma ·bufrer.
DESCRIPTION

Tbla Interface Is obloleted by setrua. .e(I).
Time, returns time-accounting information for the current process and for the terminated child
processes of the current proce88. All times are in I/HZ seconds, where HZ is 60.
This is the structure returned by time,:
struct tms {
time_t
time_t
time_t
time_t

};

tms_utime;
tmsJtime;
tms_cutime;
tms_cstime;

,. user time .,
,. system time .,

'*

user time, children

*'

'* system time, chUdren */

The children times are the sum of the children 'a process times and their chUdren-'. times.
SEE ALSO
time(I), letrusage(2), wait3(2), time(3C)

10

Last change: 3 November 1983

SUIl

Release 1.1

TMPNAM(3C)

COMPArrmILITY ROUTINES

TMPNAM(3C)

NAME
tmpnaJD - create a na.me for a temporary file
SYNOPSIS

#lnc:lude 
cha.. *tmpnam(.)
cha.. *••
DESCRIPTION

Th" ..outlne "Included to .. •7.tem-m compatlbUlt7.
Tmpnam lenerates a file name that can safely be used for a temprary file. If (int)a is zero,
Impnam leaves its result in an internal static area and returns a pointer to that area. The next
call to Impnam will destroy the contents 01 the area. II (int)a is nonzero, a is assumed to be the
address 01 an array 01 at least L_tllipnam bytes; Impnam places its result in that array and

returns , as its' value.
Tmpnam lenerates a ditJerent lile name each time it is called~

Files created usinl tmpnr.m and either !open or creat are only temporary in the sense that they
reside in a directory intended for temporary use, and their names are unique~ It is the user's
relponsibility to use unlink(2) to remove the flle when its use is ended.
SEE ALSO
creat(2), unlink(2), mktemp(3), fopen(3S)

BUGS
II called more than 17,576 times in a sinale process, tmpnam will start recyclinl previously used
namel.

Between the time a lile name is created and the lie is opened~ it is possible for some other process
to create a file with. the lame name. This can never happen if that other process il usinl tmpnam
or mktemp, and the lile names are cholen 10 as to render duplication by other means unlikely.

SUD

Release 1.1

Last

change~

26 August 1983

11

COMPATmILITY ROUTINES

ULIMIT(3C)

ULIMlT(3C)

NAME

ulimit - get and set user limits
SYNOPSIS
10DI uUmlt(cmd, aewUmlt)

tnt cmda
DESCRIPTION

Tht. function t.lncluded for ayatem-m compatlblUty, and" obaoletecl by ,elr/imil(2).
This function provides for control over process limits. The cmd values available are:
1
Get the process's file size limit. The limit is iD uDits 01 512-byte blocks and is inherited
by child processes. Files of any size can be read.
S

Set the process's file size limit to the value 01 newlimil. Any process may decrease this
limit, but only a process with an elective user ID of super-user may increase the limit.
Ulimit will rail and the limit will be unchanged if a process with aD effective uler ID other
than the super-user attempts to increase its file size limit.

a

Get the maximum possible break value. See 6rk(2).

RETURN VALUE
UpOD successful completioD. a nOD-Degative value ia returned. Otherwise a value 01-1 is returned
and errno is set to indicate the error.
SEE ALSO
brk(2), setrlimit(2), write(2}

12

Last change: 27 August 1983

SUD Release 1.1

UTIME(3C)

COMPATmILITY ROUTINES

UTlME(3C)

NAME
u time - set file times
SYNOPSIS

*lDelude 
utlme(ftle, tlmep)
ehar *flleJ
tlme_t tlmep[lb
DESCRIPTION

This Interface" obsoleted b7 utlmea(J).
The ,dime ca.1l uses the 'accel!lSed' and 'updated' times in that order from the timep vector to set
the corresponding recorded times tor file.
The caller must be the owner
let to the current time.

ot the file or the super-user. The

'inode-cbang~d'

time of the file is

SEE ALSO
utimes(2), atat(2)

Sun Rele, 1.1

Last change: 1 April 1983

13

VLIMIT(3C)

COMPATmILITY ROUTINES

VLIMIT(3C)

NAME
vlimit - control maximum system resource consumptioD
SYNOPSIS

:fI:lnclude 
vUmlt(l'eaoul'ce, value)
DESCRIPTION

Tbla taclUty Ia lupel'leded by letrUmlt(I).
Limits the consumption by the current process and each process it creates to not individually
exceed value on the specified re,ource. It value is specified as -1, then the current limit is returned
and the limit is unchanged. The-resources which are currently controllable are:

LIM_NO RAISE
A paeudo-limit; it set Bon-zero thea tile limits may Dot be raised. Only the
super.user may remove the rtlrfJire restrictioa.

bJ each process

LIM_CPU

the maximum number-of cplMecoads to be used

LIM_FSIZ.E-

the larl.-est- single ~le which can be ereaW-

~JM..J)ATA

tile muimaa growth or the clata+ stack ngiOlJ yia.. ,b,k(2) beyond the end of
the

p,ogra~

LIM_STACK the JIluinnnn sme or- the automaUcaJ(,eextended Itack region
LIM_CORE-

the Mze orthe largest eore dump that, wUl 6e creMed~

LIM_MAXRSS--

a sort limit tor- the amount or pliyaical memory (in bytea}-to be given to the program •. II memory is tight, the system: will prefer to take memol7 rrom proeeaaea
wllich are exceeding their declared LIM_MAXRSS.

Because this inrormation is stored in the per--procell intormatioll this system call must be executed directly by tile shell if it is to alect all tu&ure proceuel created by the ehen; limi' is thul a
built-ill command to c'h~l).

The Iystem reruse. to extend the data or stack space wheD the limits. would be exceeded in the
normal- way; a
call tails if the data apace I1mft. is reached, or the process is kUled when the
stack limit is reached (since the stack ean-n.ot be extended, there is no way to seDd a. signaH).

bre,"

A ftle i/o operation which. would create a file which. too larle wiD cau,-e a signal SIGXFSZ to be
generated, this normally terminates the process, but lDay be caught. When the cpu time limit il
exceede"'~ a lignal sroxcpu is sent to the olendiag proc~tn aBow it time to procesl the signal
it is- given 6 seconds grace by raising the cpu time limit.
SEE ALSO
cah(lt

BUGS
If LIM_NORAISE is set, then no grace .hoald be liVe. -bca the cpa tilDe liiDit is exceeded ..

TlieJe should be limi' and ",&limi' commands in ''fl.) • well .. ill

14

Last change: 13 June 1983

Cllt.

SUD

Release 1.1

VTIMES(3C)

COMPATmILITY ROUTINES

VTlrviES ( 3C )

NAME
vtimes - get information about resource utilization

SYNOPSIS

vtlmea(par_vm, ch_vm)
Itruet vtlm•• ·par_vm, ·eh_vmJ
DESCRIPTION
Thla f.eUlty Ia luperleded by setruI.se(2).

Vlime8 returns accounting information for the current process and for the terminated child
processes of the current process. Either pa,_vm or clLvm or both may be 0, in which case only
the information for the pointers which are non-zero is returned.
After the call, each buffer contains information as. defined by the contents of the include file'

< 8118Ivtime8.1a>:

struct vtimes {
int
vm_utime;
,. tiser time (·HZ) .,
int
vm_stime;
,. system time (*HZ) *'
,. divide next two by utime+ stime to get averages .,
unsigDedvm_idsf8s;
,. integral of d+ s flS . ,
unsigned vm;,jxr88;
,. integral of text rss .,
int
vm_maxrsl;
,. m!JXimum rSI
iot
vmJDajflt;
,·major page faults .,
lnt
vm_minftt;
,. minor page raults·'
int
vmJl6Wap;
,. number 01 swapl.·'
hat
vmJnblk;
,. block reads .,
int
vm_oublk;
,. block writes .,
};

*'

The. vm_ulime and vm_Blime fields give the user and system time respectively in 60ths of a second
(or 60th. if that Ii the frequency 01 wall current in your locality.) The vm_id,,, and vm_iz,,,
measure memory usale. They are computed by integrating the number or memory pages in use
each over cpu time. They are reported as though computed discretely, adding the current
memory usage (in 612 byte pages) each time the clock ticks. It a process used 5 core pages over 1
cpu-second for its data and stack, then vm_id"" would have the value 5·60, where
vm_ulime+ vm_"ime would be the 60. Vm_id"" integrates data and stack segment usage, while
vm_izrs, integrates text segment usage. Vm_maz,,, reports the maximum instantaneous sum or
thetext+ data+ stackeore-resident pale count.
The vm_majjU field gives the number or page raults which resulted in disk activity; the vm_minJU
field gives the number of page faults incurred in simulation of reference bits; vm_n'wtJP is the
Dumber 01 swaps which occurred. The number of file system input'output events are reported in
vm_in61k and vnLoubli These numbers account only. for real i'o; data supplied by the caching
mechanism iacbar,ed only to the first prace", to re~ or write the data.
SEE ALSO
setrusage(2), wait3(2)

Sun Releasr 1.1

Last change: 13 June.1983

15

INTRO(3M)

-MATHEMATICAL FUNCTIONS

INTRO(3M)

NAME

intro - introduction to mathematical library functions
DESCRIPTION
These functions constitute the math library, libm. They are automatically loaded as needed by
the Fortran compiler 177(1). The link editor searches this library under the "-1m" option.
Declarations for these functions may be obtained from the include file .
LIST OF FUNCTIONS

Name Appears on Page
acos
sin .3m
uin
sin .3m
atan
sin.3m
atan2
sin.3m
cabs
hypot.3m
ceil
floor.3m
cos
sin ~3m
cosh
sinh. 3m
exp
exp.3m
tabs
floor.3m
floor
f1oor;3m
gamma gamma.3m
hypot
hypot.3m
jO
jO.3m
jt
jO.3m
jn
jO.3m
log
exp.3m
log10
exp.3m
pow
exp.3m
sin
sin.3m
sinh
sinh.3m
exp.3m
sqrt
tan
sin.3m
tanh
sinh~3m
yO
jO.3m
y1
jO.3m
yn
jO.3m

DeBcription
trigonometric functions
trigonometric functions
trigonometric functions
trigonometric functions
Euclidean distance
absolute value, floor, ceiling functions
trigonometric functions
hyperbolic functions
exponential, logarithm, power, square root
absolute value, floor, ceilingfunc.tions
absolu te value,. floor, ceiling functions
log gamma function
Euclidean distance
bessel functions
bessel functions
bessel functions
exponential, logarithm, power, square root
exponential, logarithm, p.ower, square root
exponential" logarithm, power, square root
trigonometric' functions'
hyperbolic functions
exponential, logarithm:; power, square root
trigonometric functions
hyperbolic functions
bessel functions
bessel functions
bessel function8

Last change: 12 January 1984

1

MATHEMATICAL FUNCTIONS

EXP(3M)

EXP(3M)

NAME

exp, log, log10, pow, sqrt - exponential, logarithm, power, square root
SYNOPSIS
#lnelude 

double exp(x)
double

x,

double loS (x)
doublaxJ
double loSlO(x)
double XI
double pow(x, 7)
double x, ;¥J
double aqrt(x)
doublexJDESCRIPTION
Ezp retHns the expollential function of z.
L~, returna

pDfIJ returns

the natural logarithm of z; lo,tUreturns the bale lOloiarithm.

11'.

S9" returns the square root 01 a.

SEE ALSO
hypot(3M), sinh(3M), intro(2)DIAGNOSTICS
Ezp and pow return a huge value when the ~orrect value would over80w; errrao is set to
ERANGE. Pow returns 0 and sets errno to EDOM when the- second argument is negative and
non-integral and when both arguments are O.

Log returns 0 when z is zero or negative; errno is set to EDOM.

S"r' returns 0 when z is negative; errrao is set to EDOM.

2

Last change: 19 January 1983

Sun Release 1.1

FLOOR (3M)

MATHEMATICAL FUNCTIONS

FLOOR(3M)

NAME
tabs, floor, ceil - absolute value, floor, ceiling (unctions
SYNOPSIS

f:lnclude 
double flool'(x)
double XI
double edl(x) .
double XI
double tab.(x)
double XJ
DESCRIPTION

.

Fob returns the absolute value I z I.
Floor returns thela~gest integer not greater than z.
Ceil returns the smallest integer not less than .z.

S-EE ALSO
abs(3)
BUGS

The Jab function is actually in the standard Clibrary ,and should be moved to the math library.

SUQ

Release 1.1

Last change: 26 August 1983

3

MATHEMATICAL FUNCTIONS

GAMMA (3M)

GAMMA{3M)

NAME

gamma - log gamma function
SYNOPSIS

#lnelude 
double gamma(x)
double XJ
DESCRIPTION
Gamma returns In tr{ I z I )I. The sign 01 r( z-~ ~ is returned in tile external inteler ri,ngam.
The roUowilr1 C program might be used to calculate r:

t

Y :III gamma(x);
:fjfdetvax
it (y- > 88-.0)
#endil
#ircref SUD
it (y > 706.0)
#endit
error();
y =- exp(Yl;if(signgam}
y -

-y;-

DIAGNOSTICS

A huge value is returned for negative integer arguments.
BUGS

There should be a positive indication of error.

4

Last change: 23 August 1983

Sun Release 1.1

trrPOT(3M)

MATHEMATICAL FUNCTIONS

HYPOT(3M)

NAME
hypot, cab. - EuclideaD distance
SYNOPSIS

flnclude 
double hypot(x, y)
double x, y.
double caba(_)
.truct { double x, 7.} -.
DESCRIPTION
HIJ'o' aDd ctJb retur..
sqrt(x·x + y.,),
takiDI precautio•• a,aiD.t uDwarraDted overflows.
SEE ALSO
exp(3M) for 'fr'

SUD. Release

1.1

Last change: 19 January 1983

5

JO(3M)

MATHEMATICAL FUNCTIONS

JO(3M)

NAME
jOt jl, jn, yO, yl, yn - bessel functions

SYNOPSIS

#lnelude < math.h>
doable JO(x)
double XI
tlbubleJl(x)
double XI
double In(o, x)
double XI
double yO(x)
double XI
double )pl(x)
double XI
double 70[0,- x)
double XI
DESORIPTION

These functions calculate Bessel lunctions 01 the tint and second kinds lor real arluments and
inteaer orders.
DIAGNOSTIOS

Nelative arlumenta cause I/O, 1/1, and I/n to return a hUle nelative value and set errno to EDOM.

6

Last change: 19 January 1983

SUD

Release 1.1

SIN(3M)

MATHEMATICAL FUNCTIONS

SIN( 3M)

NAME

sin, cos, tan, UiD, acOI, atan, atan2 - trigonometric functions
SYNOPSIS
*mclude 
double IIm(x)
double x,

double co.(x)
double

x,
x,

double asm(x)
double
double &eOBeX)
double XJ
double at.D(x)
double XI
double ataDI(x, y)
double x" J"
DESCRIPTION
Sin, COB and tan return trigonometric functions of radian arguments. The magnitude of the argument should be checked by the caller to make sure the result is meaningful.

Alin returns the arc sin in the range -1r/2 to 1r/2.
Aco, returns the arc cosine in the range 0 to 1r.
Atlln returns the arc tanlent of z in the range -1r/2 to 1r/2.
Atllne returns the arc tanlent or sill in the range -1rto 11'.
DIAGNOSTICS
Arguments of magnitude greater than 1 cause asin and aCOB to return value 0; errno is set to
EDOM. The value ot tan at ita singular points is a huge number, and errno is set to ERANGE.
BUGS

The value

SUD

Release 1.1

ot tan tor arluments greater than about 2··31 is garbage.

Last change: 19 January 1983

7

MATHEMATICAL FUNCTIONS

SINH ( 3M)

SINH(3M)

NAME

sinh, cosh, tanh - hyperbolic functioDs
SYNOPSIS

*lnelude 
double Blnh(x)
double eOBh(x)
double x,
double tanh{x)
double xt
DESCRIPTION
These (unctions compute the designated hyperbolic functions for real arguments.
DIAGNOSTICS
Sinh and

8

COBIt

return a iluge value or appropriate sign when the correct value would overflow.

Last change: 19 January 1983

Sun Release 1.1

INTRO(SN)

NETWORK FUNCTIONS

INTRO(3N)

NAME

intro - introduction to network library functions
DESCRIPTION
This section describes functions that ar.e applicable to the DARPA Internet network, which are
part of the standard C library.
LIST OF FUNCTIONS

Name·
endhostent
endnetent
endprotoent
endse"ent
lethostbyaddr
lethostbyname
lethostent
letnetbyaddr
letnetbyname
letnetent
letprotobyname
letprotobynumber
letprotoent
letse"byname
letae"byport
letse"ent
htonl
htons
inet_addr
inetJnaof
inet_makeaddr
inet_netof
inet..network
inet..nt()a
ntohl
ntoha
rcmd
rexee
rresvport
ruserok
aetholtent
letnetent
letprotoent
aetle"ent

SUDRele~

l.1

Appea" on Page
lethosten t.3n
letnetent.3n
letprotoent.3n
letse"en t.3n
lethosten t.3n
lethoatent.3n
lethoaten t.3n
letnetent.3n
letnetent.3n
letnetent.3n
letprotoent~3n

ietprotoeDt.3n
letprotoeDt.3n
letae"ent.3n
letae"ent.3n
letse"en t.3n
byteorder .3n
by,teorder .3n
inet.3n
inet.3D
inet.3n
inet.3n
inet.3n
inet.3n
byteorder .3n
byteorder.3n
rcmd.3n
rexec'3n .
rcmd.3n
rcmd.3n
lethostent.Sn
letnetent.3n
letprotoent.3n
letaervent.3n

De8cription
get network host entry
get network entry
get protocol en try
let se"ice entry
get network host en try
get network host en try
let network host entry
get network entry
let network entry
let network entry
let protocol en try
let protocol en try
let protocol en try
let se"ice entry
let ae"ice entry
let ae"ice entry
convert values between host and network byte order
convert values between hoat and network byte order
Internet addrey manipulation
Internet addrey manipulation
Internet addrey manipulation
Internet addrey manipulation
Internet addrey manipulation
Internet addrey manipulation
convert values between hoat and' network byte order
convert values between hoat and network byte order
routines for returninl a stream to a remote command
return stream to a remote command
routines for returninl a stream to a remote command
routines for returning a stream to a remote command
get network host entry
get. network entry
let protocol en try
get se"ice entry

Last change: 12 January 1984'

1

,BYTEORDER(3N)

NETWORK FUNCTIONS

BYTEORDER ( 3N )

'NAME

htonl,l;ltons, utohl, ntohs - convert values between host and network byte order
SYNOPSIS

:-

*lDclude <8ya/typea.h>
#lDelude  •
Theee routiDea- are most otteD ueecl Dr conjuDctioD witl IDtenet addrellee and pons as returDed
by ",Aollen'(3N) and,e""."n'(3N).

SEE-ALSO
,e'loNDt(3N); Ictaerveat(3N)
BUGS

The-VAX handles bytes backwards trom meet everyone else iD the world., This i...llot- expected to
be fixed in the near future.

2

Last change: 4 March 1983

SUD

Release 1.1

GETHOSTENT ( 3N )

NETWORK FUNCTIONS

GETHOSTENT ( 3N )

NAME
letho.tent, lethostbyaddr, geth06tbyname, sethostent, endhostent - get network host entry
SYNOPSIS

,Include 
.truct ho.teat ·.etho.tentO
.truct ho.tent ·.etho.tbyname(name)
char ·namel
.truet ho.teat ·.etho.tbyaddr(addr, len, type)
char ·addrl Int len, type,
.etho.teat(.tayopen)
IDt .tayopeD
endho.teDtO
DESCRIPTION

:

Getho,'en', ,etho"b,ln.me, and ,dho,,6,1.dd, each return a pointer to an object with the followinl.tructure containinlthe broke>~-out I.elds of a line in the network host data bue, 'de/Aolt,.
atruct

hoeteat
chAt
char
iot
int
char

{
·h_name;
··h...;aliases;
h_addrtype;
hJength;
·h~addr;

};

'*
'*

offieial name of host ./
,. alias list .,
,. address type .,
,. length 01 addre811 .,
addres.·'

The members 01 thi' Itructure are:
th~,

hJlame

Official Dame 01

h_aliuea
h...;addrtype

A zero terminated array 01 alternate Dames tor the host.
The type 01 address beiD, returned; currently always AF_INET.

hJeDIth

The leDlth, iD bytes,

hOlt.

ot the addre•.

A poiDter to the network address lor the host. Hoet addreaaes are returned in network byte order.

Getho,'en' reads the next line 01 the lie, openinl the lie if necesaary.
Setho,',nl OpeDS aDdreMnds the' lie. II the "''1open fla, is non-zero, the hOlt data base will not
be closed alter each call to ,e,AOIlenl (either directly, or indirectly through one of the other
"Ietholt" calla).

Endho,'en' eto... the lie.
Getho,,6,1nome and ,dholl6,1tJddr sequentially search Irom the beginning of the lie until a matchial hOlt name or hOlt addrel. ill IOUDd, or until EOF is encountered. Host addresses are supplied
iD Detwork order.
FILES
/ete/hoats
SEE ALSO
hoats(S)
DIAGNOSTICS
Nun pointer (0) returned OD EOF or error.

SUD Release 1.1

Last change: 9 February 1983

3

..

GETHOSTENT ( 3N )

NETWORK FUNCTIONS

GETHOSTENT(3N)

BUGS
mU8.~

All information is ·contained in a static area 110 it
Internet address format is currently undentood.

;

4

be copied it it is to be saved. Only the

~.

Last change: 9 February 1983

SUD

Release 1.1

GETNETENT ( aN)

NETWORK FUNCTIONS

GETNETENT ( 3N )

NAME

getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent - get network entry
SYNOPSIS

'Include 
Itract netent *setnetentO
_tract netent *setnetbyname(name)
char *namea
_truet netent *setnetbyacldr(net,.type)
I~D. netl
lIetnetent(atayopen)
Int stayopen
endnetent(l
DESCRIPTION

Getnetenl, getnetb"nGme, and ,etnetb1lGddr each return a pointer to an object with the following
structure containing the broken-out fields ot aline in the network database, 'ete'networkl,.
Itruct

Qetent
char
char
int

lonl

{'
*n_name;
**n.;..a1iases;
n_addrtype;
nJieti

''**

official name or net
alias list *'
'* net number type *'
'* net number *'

*'

}j
The members of tbis.8tructure are:
DJlame

The official narne of the network.

D_alia&ea

A zero terminated list of aiternateQames ror the network.

D_addrtype The type or the network number returned; curreQtly· only AF_INET.
II_net

The network number. Network numbers are returned in machine byte order.

Gdndent read. the Ilext line of the file, opeldng the flle ifneceeary.
Setneten' opens and rewinds the. file. It the· BtG1Iopen flag is non-zero, the net data base will not be
closed· after each call to ,etndenl (either directly or indirectly· through one ot the other "getnet"
J

calls).

Endnelenl cleses the file.
Gdnet6yname and gdnelblladdr sequentially search from the beginning ot the file until a matching
net name or net address is found, or until EOF is
hoat order.

encountered~

Network numbers. are supplied in

FILES

,etc ,networks
SEE ALSO
networks(5)
DIAGNOSTICS
Nun pointer (0) returned on EOF or error.
BUGS

Allinlormation is contained in a static area so it must be copied if it is to be saved.
Only Internet network numbers are currently understood.

SUII Release 1.1

Last change: 9 March 1984

5

GETPROTOENT(3N)

NETWORK FUNCTIONS

GETPROTOENT (3N)

NAME

getprotoent, getprotobynumber, getprotobyname, setprotoent,endprotoent -let protocol entry
SYNOPSIS

*lnclud. 
atl'uet pl'otoent *getprotoentO.tl'uct protoent *setprotob7name(nameJ
ch.... ·Damet
.tract pl'otoent '-setpl'Otob7nwnber(proto)
lilt protol
aetpl'otoent~tayopen}

lntatqopen
endpl'otoent(J
DESCRIPTION

Udpr4tuent, getp,.",tob,ume, and gdprotHgnum6e,. each return a pointer to an object with the
foltowing structur«t containiD, the brokellPout Befcls or a line in the network protocol data bas~
I dcfprQto ctJU_
struct

protoent {
char
·p_name:
char
·'-p_aliases~
1011-&
P"'proto;

''**
/*

official name of protocol
alias rut .-t
protoeol munber *'

*'

};
The members of this structure are:
p_name- The official name of the protocol.
p_aliaees A zero terminated list of alternate names lor the protocol.
p"proto The protocol number.
Gdprotoent reads the next line of the flle, openinl the file if necessary.
Setprotoent opens and rewinds the 61e. If the ,ttJlIopen Bag is non-zero, the net data base will not
be closed after each call to gdprotoent (either directly, or indirectly through one 01 the other
"getproto" calls).
Endprotoent cl08es the file.
GetprotobllntJme and getprotobllnumber sequentially search from the beginning of the file until a
matching protocol name or protocol number is found,-or until EOF is encountered.
FILES

/ etc /protocols
SEE ALSO

protocols(S)
DIAGNOSTICS

Null pointer (0) returned on EOF or error.
BUGS

All information is contained in a static area
Internet protocols are currently understood.

6

80

it must be copied if it is to be saved. Only the

Last change: 9 February 1983

SUD Release 1.1

NETWORK FUNCTIONS

GETSERVENT ( aN )

GETSER VENT ( 3N)

NAME
getse"ent, getservbyport, getservbyname, setservent, endservent - get service entry
SYNOPSIS

#lnclude 
.truct .el"Vent ·setlerventO
.truct e.l"Vent ·seteervbyname(name, proto)
char ·oame,. ·proto,
etruet; lel"Vent ·setlervbyport(port, proto)
lnt port,char ·protol
8etsel"Vent(atayopen)
lntet~opeD

endlerventO
DESCRIPTION

Get8ervent, getBervbllntJme, and get8ervbllPort each return a pointer to an object with thefoUowing
structure containing the broken-out fields' or A line in the network services data base,
/ etc/Bervice,.
struct

servent
char
char
lonl
char

{
·s_name;
··s;...aliases;
s"'port;
·s-proto;

*'

/. olicia} name of service .,
/. alias list
,. port service resides at .,
,. protocol to use

};

*'

The membe... of this structure are:
SJl8.m8

The olicial name or the service.

s_aliaaea A zero terminated list of alternate names for the service.
8..J)ort

The port number at which the service resides. Port numbers are returned in network
byte order.

s"proto

The name of the protocol to use when contacting the service.

Get,erven' reads the next line or the file, openinl; the file if necessary .
Set,erven' opens and' rewinds the file. If the ,t(JIJopen flag is non-zero, the net data base will not
be closed aCter each call to get,erven' (either directly, or indirectly through one oC the other "getserv" calla).

End,erven' closes the 61e.
Get,ervblln(Jme and gd,ervbllPor' sequentially search from the beginning of the file until a matchinl protocol name or port number is Cound, or until EOF is encountered. If a protocol name is
allO .supplied (non-NULL), searches must also match the protocol.
FILES
/etc/services
SEE ALSO
getprotoent(3N), services(5)
DIAGNOSTICS
Null pointer (0) returned on EOF or error.

BUGS
All inCormation is contained in a static area so it must be copied ir it is to be saved. Expecting
port numbers to fit in a 32 bit quantity is probably naive.

Sun, Release 1.1

Last cbange: 9 February 1983

7

INET( 3N)

NETWORK FUNCTIONS

INET(3N)

NAME

inet_addr, inet_network, inet_mueaddr, inetJnaol, inet_netol, iaet_ntoa - Internet address
manipulation
SYNOPSIS

#lnclude <.,../aoeket.h>
..,lnclude <-neUnet/ln.h>#lDc:lude 
.truct In_add..
lDel__addr(cp}
ch.... -epl-

Intm.~etworl(ep)-

char ·CPf
at.uet-In_addr
Inet..makeaadl{net, IDa)
lnt net, mar

tnt
lnet_maof(In)
atruct In__ddr In.
Int
lnet_Detot(ln)
atruet In_add.. In.

char •
lnetJltoa(In)
atruct In_addr In.
DESCRIPTION
The routines ineCtJddr and ineCndwori each interpret character strings representing numbers
expressed in the Internet standard II." notation, returning numbers suitable lor use as Internet
addre!8es and Internet network numbers, respectively. The routine ind_maieaddr takes an internet network number and a local network address and constructs an Internet addresa from it. The
routines ineCndoj and ineC'ntJo! break apart Internet host addresses, returninl the network
number and local network address part, respectively.

The routine ineCntotJ returns a pointer to a string in the hase 256 notation "d.d.d.d" described
below.
All Internet address are returned in network order (bytes ordered trom left to right). All network

numbers and local address parts are returned as machine format integer values.
INTERNET ADDRESSES
Values specified using the "." notation take one of the following forms:
a.b.c.d
a.h.c
a.b

a
When four parts are specified, each is interpreted as a byte 01 data and assigned, from left to
right, to the four bytes of an Internet address. Note that when an Internet address is viewed as a
32-bit integer quantity on the VAX the bytes referred to above appear as IId.c.b.a". That is,
VAX bytes are ordered from right to left.
When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed
in the right most two bytes ot the network address. This makes the three part address format
convenient tor specifying Class B network addresses as "128.net.host".

8

Last change: 29 August 1983

Sun Release 1.1

lNET(3N)

NETWORK FUNCTIONS

INET( 3N)

When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed
in the right most three bytes or the network address. This makes the two part address format
convenient tor specirying Class A network addresses as "net.host".
When only one part is given, the value is stored directly in the network address without any byte
rearrangement.
All numbers supplied as "parts" in a "." notation may be decimal, octal, or hexadecimal, as
specified in the C language (i.e. a leading Ox or OX implies hexadecimal; otherwise, a leading 0
implies octal; otherwise, the number is interpreted as decimal).
SEE ALSO

gethostent(3N), getnetent(3N), hosts(S), networks(S),
DIAGNOSTICS

The value -1 is returned by inet_tJddr and ineCnetwork for malformed requests.
BUGS

The problem of host byte ordering versus network byte ordering is confusing. A simple way to
specify Clul C network addreues in a manner similar to that tor Class Band Clau A is needed.
The return value tram ineCntotJPoints. to static information which is overwritten in each call.

SUD

Release 1.1

Last change: 29 August 1983

9

NETWORK FUNCTIONS

RCMD(3N)

RCMD(3N}

NAME

rcmd, rresvport, ruserok - routines (or returning a stream to a remote command
SYNOPSIS
rem
rcmd(ahost, tnport, locusel', remuser, cmd, tdlp);
char **ahost.
u_short lnport;
char *Ioculel', *l'emUler, *cmd;
tnt *fd2p,

==

I - rrelvpol't(port);
tnt *port;
rusel'ok(rholt, superUler, rUler, Iuser);
char *rholt,
tnt Iuperuler;
char *I'Uler, *Iuser;
DESCRIPTION
Rcmd is a routine used by the super-user to execute a command on a remote machine using an
authentication scheme based on reserved port numbers. Rrelvport is a routine which returns a
descriptor to a socket with an address in the privileged port space. RUlero/c is a routine used by
servers to authenticate clients requesting service with rcmd. All three functions are present in the
same file and are used by the rBhd(8C) server (among others).

Rcmd looks up the host *ahoet using gethoBtbllname(3N), returning -1 it the host does not exist.
Otherwise *ahoet is set to the standard name of the host and a connection is established to a
server residing at the well-known Internet port inport.
If the call succeeds, a socket ot type SOCK_STREAM is returned to the caller, and given to the
remote command as stdtn and stdout. It Idep is non-zero, then an auxiliary channel to a control
process will be set up, and a descriptor for it will be placed i~ "ld£.p. The control process will
return diagnostic output (rom the command (unit 2) on this channel, and will also accept bytes on
this channel as being UNIX signal numbers, to be forwarded to the process group of the command. If Idep is 0, then the Itderr (unit 2 o( the remote command) will be made the same as the
ltd out and no provision is made (or sending arbitrary signals to the remote process, although you
may b~ able to get its attention by using out-of-band data.

The protocol is described in detail in rehd(8C).
The rresvport routine is used to obtain a socket with a privileged address bound to it. This
socket is suitable ror use by rcmd and several other routines. Privileged addresses consist o( a
port in the range 0 to 1023. Only the super-user is allowed to bind an address or this sort to a
socket.

Ruetrok takes a remote host's name, as returned by a gethoBtent(3N) routine, two user names and
a flag indicating if the local user's name is the super-user. It then checks the files I etcl h08t8. equiv
and, possibly, .rhoat8 in the current working directory (normally the local user's home directory)
to see i( the request (or service is allowed. A 1 is returned if the machine name is listed in the
"hosts.equiv" file, or the host and remote user name are (ound in the ".rhosts" file; otherwise
rUBero/c returns O. It the BuperUBer flag is 1, the checking of the "host.equiv" file is bypassed.
SEE ALSO
rlogin(IC), rsh(IC), rexec(3N), rexecd(8C), rlogind(8C), rshd(8C)

BUGS
There is no way to specify options to the BO eket call which rcmd makes.

10

Last change: 17 March 1982

Sun Release 1.1

REXEC(3N)

NETWORK FUNCTIONS

REXEC(3N)

NAME

rexec - return stream to a remote command
SYNOPSIS
rem l1:li re.xec(ahoat, mport, uaer, p ..awd, cmd, fdlp).
char ··ahoatl
u..lhort lnportl
char ·uler, ·pallwd, ·cmdl
lnt *fdipi
DESORIPTION
Rezec looks up the host ·oho,' using Ielho't6vnome(3N), returning -1 it the host does not exist.
Otherwise ·oho,' is set to the standard name of the host. It a usernameandpassword are both
specified, then these are used to authenticate to the roreign host; otherwise the environment and
then the user's .nelrc file in his home directory are searched ror appropriate information. It all
this fails, the user is prompted for the information.
The port inporl specifies which well-known DARPA Internet port to use for the connection; it will
normally be the value returned from the call "getservbyname("exec", "tcp")U (see
leI,ervent(3N)). The protocol for connection is described in detail in rezecd(8C).
It the call succeeds, a socket of type SOCK_STREAM is returned to the caller, and given to the
remote command as atdln and atdout. If Idep is non-zero, then a auxiliary channel to a control
procell will be setup, and a descriptor for it will be placed in ·Idep. The control process will
return dialnoetic output from the command (unit 2) on this channel, and will also accept bytes on
this channel as beinl UNIX signal numbers, to be forwarded to the process group ot the command. If Idep is 0, then the atderr (unit 20r the remote command) will be made the same as the
atdout and no provision is made ror sendinl arbitrary signals to the remote process, although you
may be able to let it. attention by usinl out-of-band data.
SEE ALSO
rcmd(3N), rexecd{8C)

BUGS
There is no way to specify options to the ,ocket call which rezec'makes.

SUD

Release 1.1

Last change: 17 March 1982

11

STANDARD I/O LffiRARY

INTRO(3S)

INTRO(3S)

NAME
stdio - standard buffered input/output package
SYNOPSIS
#lnelude <.tdlo.b>
FILE ·stdlnl
FILE *.tdout.
FILE ·stderr.
DESORIPTION
The functions described in section 3S constitute a user-level bufFering scheme. The in-line macros
,etc and putc(3S) handle characters quickly. The higher level routines get8, !geta, 8can!, !8can!,
fread, put" !put" print!, !print!, !write all use ,etc and pute; they can be freely intermixed.
A file with associated buffering is called a 'tream, and is declared to be a pointer to a defined type
FILE. A !open(3S) creates certain descriptive data for a stream and returns a pointer to designate the stream in all further transactions. There are three normally open streams with constant
pointers declared in the include file and associated with the standard open files:

.tdln

standard input file
atdout
standard output file
stde....
standard error file
A constant 'pointer'NULL (0) designates no stream at all.
An integer constant EOF (-1) is returned upon end or flle or error by integer functions that deal
with streams.
Any routine that uses the standard input/output package must include the header file <8tdio.h>
of pertinent maero definitions. The functions and constants mentioned in sections labeled 3S are
declared in the include file and need no further declaration. The constants, and the following
'fundiona' are implemented as macros; redeclaration of these Dames is perilous: getc, getchar,
pute, putchar, !eol, lerror, jUeno, elrerr.
SEE ALSO
.
open(2), close(2), read(2), write(2), fread(3S), fseek(3S)
DIAGNOSTIOS
The value EOF is returned uniformly to indicate that a FILE pointer has not been initialized
with lopen, input (output) has been attempted on an output (input) stream, or a FILE pointer
designates corrupt or otherwise unintelligible FILE data.
For purposes of efficiency, this implementation of the standard library has been changed to line
bufFer output to a terminal by default and attempts to do this transparently by flushing the output whenever a read(2) from the standard input is nece88ary. This is almost always transparent,
but may cause confusion or malfunctioning of programs which use standard i/o routines but use
read(2) themselves to read from the standard input.
In eases where a large amount o.f computation is done after printing part of a line on an output
terminal, it is necessary to JIIu8h (see !clo,e(3S)) the standard output before going off and computing so that the output will appear.
BUGS
The standard buffered' functions do not interact weD with certain other library and system functions, especially vlor~ and a60rt.
LIST OF FUNOTIONS

Name
clearerr
fclose
fdopen

SUD Release 1.1

Appellr. on Page
ferror.3s
felose.3s
fopen.3a

De8cription

stream status inquiries
close or flush a stream
open a stream

Last change: 12 January 1984

1

STANDARD I/O LmRARY

INTRO(3S)

feof
(error
Blush
(getc
fgets
fileno
top en
fprintl
fputc
tputs
fread
freopen
fscanf
fseek
ttell
fwrite
getc
getchar
gets
getw
pclose
popen
printf
putc
putchar
puts
put\\'
rewind
scanr
setbur
setbuffer
setlinebur
sprintl
sscanf
stdio
ungetc

2

ferror.3s
(error.3s
(close.as
getc.as
gets.3s
(error.3s
topen.3s
printt.as
putc.&
puts.as
fread.as
fopen.&
scant.3s
(seek.3s
fseek.3s
fread.as
getc.&
getc.&
gets.3s
getc.a.
popen.3s
popen.3s
printr.as
putc.3s
putc.&
puts.as
putc.3s
fseek.3s
scant.3s
setbur.3s
setbur.3s
setbuf.as
printf.3s
scanf.3s
intro.as
ungetc.3s

INTRO(3S)

stream status inquiries
stream status inquiries
close or Bush a stream
get character or integer from stream
get a string from a stream
stream status inquiries
open a stream
tormatted output conversion
put character or word on a stream
put a string on a stream
buffered binary input/output
open a stream
formatted input conversion
reposition a stream
reposition a stream
buffered binary input/output
get character or integer trom stream
get character or integer rrom stream
get a string from a stream
get character or integer from stream
initiate I/O to/from a process
initiate I/O to/from a proceu
formatted output conversion
put character or word on a stream
put character or word on a stream
put a string on a stream
put character or word on a stream
reposition a stream
formatted input conversion
assign buffering to a stream
assign buffering to a stream
assign buffering to a stream
formatted output conversion
tormatted input conversion
standard buffered input/output package
push character back into input stream

Last change: 12 January 1984

SUD

Release 1.1

FCLOSE(3S)

STANDARD I/O LIDRARY

FCLOSE(3S)

NAME
fclose, mush - close or flush a stream
SYNOPSIS
*lnelude 
feloflile(atl'eam)
FILE *stl'eam,
fDuah(stream)
FILE *.tl'eam.
DESCRIPTION
Fclo8e causes any buffers for the named stream to be emptied, and the file to be closed. Buffers
allocated by the standard input/output system are freed.

Fclo,e is performed automatically upon calling ezit(3).
Fftu,h causes any buffered data for the named output ,tream to be written to that file. The
stream remains open.

SEE ALSO

c!ose(2), topen(3S), setbuf(3S)
DIAGNOSTICS
These routines return EOF if ,tream is not associated with an output file, or if buffered data cannot be transferred to that file.

SUD Releas~

1.1

Last change: 19 January 1983

3

FERROR(3S)

STANDARD I/O LmRARY

FERROR(3S)

NAME
ferror, feof, clearerr, fileno - stream status inquiries

SYNOPSIS
#lnelude <.tdlo.h>
feof(stream)
FILE *.tream,
fel'l'ol'(stl'eam)
FILE *.tl'eam
elearel'r(.tream)
FILE *.tl'eam
flleno(.tl'eam)
FILE *.tream,
DESCRIPTION
Feo! returns non-zero when end of file is read on the named input ,tretJm, otherwise zero.
Ferror returns non-zero when an error has occurred reading or writing the named "ream, otherwise zero. Unless cleared by cletJrerr, the error indication lasts until the stream is closed.
elrerr resets the error indication on the named ,tretJm.

Fileno returns the integer Ole descriptor asaociated with the ,tretJm, see open(2).
These functions are implemented as macros; they cannot be redeclared.

SEE ALSO
fopen(3S), open(2)

4

Last change: 19 January 1983

SUD Release 1.1

STANDARD I/O

FOPEN(3S)

L~RARY

FOPEN(3S)

NAME

fopen, freopen, fdopeD - open a stream
SYNOPSIS
*lnclude <.tdlo.h>
FILE *topen(fllen.m., typ.)
cha.. ·fll.name,·typ••

FILE *lreopen(fllen.me, typ., .t..eam)
cha.. ·ftl.name, ·typ••
FILE
FILE *fdopen(ftld_, typ.)
cha.. ·typeJ
DESCRIPTION
Fopen opens the file named by filename and associates a stream with it. Fopen returns a pointer
to be used to identily the stream in subsequent operations.
Tllpe is a character strina havina one 01 the lollowina values:
"r" open for reading
"w" create lor writing
"a" append: open for writing at end of file, or create for writing
In addition, each 'ype may be lollowed by a '+' to have the file opened lor reading and writing.
"r+" positions the stream at the begin nina of the file, "w+" creates or truncates it, and "a+"
positions it at the end. Both reads and writes may be used on read/write streams, with the limitation that an I,eell, rewind, or readinl an end-of-file must be used between a read and a write or
vice-vena.
Freopen substitutes the named file in place 01 the open ,'ream. It returns the original value of
,'ream. The orilinalstream is closed.
Freopen is typically used to attach the preopened constant names, .tdln, .tdout, .tde...., to
specified files.
Fdopen associates a st'ream with a file descriptor obtained rrom open, dup, creat, or pipe(2). The
'llpe or the stream must agree with the mode of the open file.

·.t....m.

SEE ALSO
open(2), fclose(3S)
DIAGNOSTICS
Fopen and Ireopen return the pointer NULL ir jUename cannot be accessed.

BUGS
Fdopen is not portable to systems other than UNIX.
The read/write type, do not exist on all systems. Those systems without read/write modes will
probably treat the 'llpe as ir the '+' was not present. These are unreliable in any event.

Sun Release 1.1

Last change: 9 June 1981

5

FREAD(3S)

STANDARD I/O LmRARY

FREAD(3S)

NAME

fread, (write - buffered binary input/output
SYNOPSIS

#lDclude 
tread(ptr, slzeof(*ptr), nltems, stream)
FILE *strealD;
twrlte(ptr, slzeol(*ptr), nltema, stream)
FILE *stream;
DESCRIPTION

Fread reads, into a block beginning at ,Ir, nilem, ot data ot the type ot *plr trom the named
input dream. It returns the number ot items actually react.
If dream is stdln and the standard output is line buffered, then any partial output line will be
Bushed betore any call to read(2) to satisty the fread.
Fwrile appends at most ni'em, ot data ot the type or *plr beginning at ptr to the named output
,'ream. It returns the number ot items actually written~
SEE ALSO

read(2), write(2}, fopen(3S), getc(3S), putc(3S), gets(3S), puts(3S). printr(3S), acanl(3S)
DIAGNOSTICS

Fread and fwrile return 0 upon end ot lie or enor.

6

Last change: 19 January 1983

SUD

Release 1.1

FSEEK(3S)

STANDARD I/O LffiRARY

FSEEK(3S)

NAME
fseek J !tell, rewind - reposition a stream
SYNOPSIS

,Include 
tseek(atream, offset, ptrname)
FILE *.tream,
Ion. offset,
Ions fteU(stream)
FILE *stream,
I'ewlnd(stream)
DESCRIPTION
F,ed: sets the position of the next input or output operation on the stream. The new position is
at the signed distance offset bytes from the beginning, the current position, or the end or the file,
according as ptrname haa the value 0, 1, or 2.

F,eek undoes any elects of ungetc(3S).
Fte" returns the current value or the olset relative to the beginning or the file associated with the
named ,tream. It is measured in bytes on UNIX; on some other systems it is a magic cookie, and
the only foolproof way to obtain an offset for /seek.
Rewind(,tream) is equivalent to /,eek(,tream, OL, 0).
SEE ALSO
Iseek(2), fopen(3S)

DIAGNOSTICS
Fleek returns -1 for improper seeks.

SUD

Release 1.1

Last change: 19 January 1983

7

NAME
getc, getchar, fgetc,

GETC(3S)

STANDARD I/O LmRARY

GETC(3S)

get~

SYNOPSIS -

- get character or integer fro", stream
.
~{-

:f/:lnclude 

Int setc(atream)
FILE ·stream,

lilt ~etc:b&l'O
Int tsete(stream)
FILE ·stream,

tnt setw(stream)
FILE ·stream,
DES.CRIPTION

Getc retttrDs the next character from the named input ,'ream.
GdeharO is identical to- Idc( "din).
Fg:dc behaves like- ,ek,. but is a genuine IUDction, -not a macro; it ml.!- be used to save ob~ct.
text<>Gefw returns the next C tnt- (word) Irom the- named input "ream. It returns the cOIlItant EOF
upcmend of file or errorrhut since that is a good integer value, JeoJ and /errorf3S) shoulel be used
to: cheek th.e sUcc.e&s of
Gdwassumea no special alignmen-t in the file.

,,,'w.

SEE ALSO-

lopen(3S), putc(3S), getl(3S}, -lcant(3S), freacl(as), ungetc(S8-)
DIAGNOSTICS

Tilese- functions return tbe- integer constant EOF at end

or file or upon read error.

A stop with message, 'Reading bad file', means an attempt-has been made to read trom a stream
th-at has not been opened lo~reading by IOlen.
BUGS

The end-ol-file return from ,,,tellor is incompatible with that ia- UNIX editions 1-6.
Because it is implemellted as a macro, ,et~ treats a ,'ream arpment with side eledlt incorrectly.
In particular, 'getc(·r+ + );' doesn't work sensibly.
Data files written. and read with putw and gdw are not portable; the size of aa lnt and the order
in. whica data bytes are stored within an lot varies bet-WeeD- macliinelf.

8

Last change: 23 August 1983

SUD

Release 1.1

GETS (3S)

STANDARD I/O LmRARY

GETS (3S)

NAME
gets, fgets - get a string from a stream
SYNOPSIS

,Include 
char *Betl(S)
char *s;
char *',eta(s, D, stream)
char *s,
FILE *stream;
DESORIPTION
Get, reads a string into 8 from the standard input stream .tdlo. The string. is terminated by a
newline character, which is replaced in , by a null character. Get' returns its argument.

F,et, reads n-l characters, or up to a newline character, whichever comes first, from the ,tream
into the string'. The last character read into, is followed by a null character. Fget, returns its
first argument.
SEE ALSO
puts(3S), getc(3S), scanf(3S), fread(3S), ferror{3S}
DIAGNOSTICS
Gd, and I,d, return the CODstant pointer NULL upon end of file or error.

BUGS
Gd, deletes a newline,

Sua Release 1.1

Jget, keeps it, all in·. the name or backward compatibility.

Last change: 19 January 1983

9

STANDARD I/O LffiRARY

POPEN(3S)

POPEN(3S)

NAME

popen, pelose - initiate I/O to{trom a process
SYNOPSIS
*lnclude 
FILE ·popen(eommand, type)
char ·eommand, ••ype,
peloae(lItream)
FILE

·.tream,

DESORIPTION
The arguments to popen are pointers to null-terminated strings- containing respectively a shell
command line and an I/O mode, either "r" tor readml or "w" for writinl. It creates a pipe
between the ca1linl proceu and thtt eonrmand to he executed. The value returned is a stream
DOinter that can be used (as appropri-ate) to write to the standard input of the command or read
trom its standard output.

A stream opened by pop-en shouIa be closed by pelo,e, which waits tor the 88sociated process to
terminate and returns the exit status- orthe command.
Because open &tes are shared, a type "r" command DtaJ· be used to filter Btdfn, ad a type "1'1" taDer Btlout.
SEE ALSO

pfpe(2), topen(3S), fcl08e(3S), 8Ystem(3-),. wait(Z), sh(l}DIAGNOSTICS
Popen returns a null pointer if files or processes eannot be created, or the sheD cannot be
accessed
0-

PctOBI: retumll -1 it Btream is not associated with a 'pepened' command.

BUGS

Buffered reading before opening an input filter may lea~e-tl,e standard input ot that filter mispositioned. Similar problems with an output filter may be 10testaUed by caretul buffer flushing, for
instance, with ffiU8h, see /elqle(3S).

P'I-en always calla Bh, never calls e,/r.

10

Last change: 19 January 1983

Sun Release 1.1

PRINTF(3S)

PRINTF(3S)

STANDARD I/O LmRARY

NAME

printl, tJ:rintl, sprint' - formatted output conversion
SYNOPSIS

,Include 
prlntf(format (, argJ ... )
chap *format,
fprlDtf(8tl'eam, format (, arg J •• ~ )
FILE *ztreama
eh..r *fol'mat,
apl'mtt(e, format (, arg J ••. )
char *., format,
flnclude <"&I"UI8.h>
_dOPI'Dt(tormat, arp, stream}
char ·'ormat,
va_&t *arp,
FILE "'streama
DESORIPTION
Printl places output. on the standard output stream .td.out. Fprintf places output on the named
output stream. Sprin" places 'output' in the string 8, followed by tliecharacter '\0'. All of these
routines work by cailinS· the implementation-dependent routine _doprnti using the variable-length
argument facilities of vGrarg8(3).
Each 01 these functions CODverts, formats, and prints its arguments after the first under control of
the 8rat argument. The first argument is a character string which contains two types of objects:
plaiD characters, which are simply copied to the output stream, and conversion specifications,
each of which cauees: c.oDversioD and printing· 01 the next 8ucce88ivearg

Each conversion specification is introduced by the character
•

an optional ~minu8 sign
indicated fleld;

•

an optional digit strinl specifyinl a field width,. if the converted value has fewer characters thaD the fleld width it will be blank-padded on the left (or right, if the leftadjustment indicator has been given) to make up the field width; if the field width begins
with a zero, zere>opaddinl will be done instead of blank-padding;

..

an optional period '.' which serves to separate the field width· from the next digit string;

..

an optional· digit string specifying a preci8ion which specifies the number of digits to
appear after the decimal point, for e- and f-conversion, o.r the maximum number of characten to be printed from a string;

•

an optional 'fl.' character specifying that the value should be converted to an "alternate
form". For c, d, ., and u, conversions, this. option has no elect. For 0 conversions, the
precision 01 the number is increased to force the first character of the output string to· a
zero. For x(X) conversion, a non-zero result has the string Ox(OX) prepended to it. For
e, E, I, 8, and G, conversions,. the result will always contain a decimal point, even if no
digits follow tbe point (normally, a decimal point only appears in the results of those
conversions if . ~ digit follows the decimal point). For. and. G conversions, trailing zeros
are not removed from the result as they would otherwise be.

•

the character 1 specifying that a following d,

•

SUD. Release

,~,

%. Following the %, there. may be

which apeciflea lef' adju,tment of the converted value in the

0,

x, or u corresponds to a long integer argo

. a character which indicates the type of conversion to be applied.

1.1

Last change: 1 April 1981

11

STANDARD I/O LmRARY

PRINTF(3S)

PRINTF(3S)

A field width or precision may be '.' instead of a digit string. In. this case an integer or, supplies
the field width or precision.
The conversion characters and their meanings are
~

clox

The integer ar,

t

The float or double org is converted to decimal notation- in the style 'l-Jddd.ddd' where
the number of- d's after. the decimal point is equal to the precision specification for the.
argument. It the precision is missing, 6 digits are given; if the precision is explicitly 0, DO
digits and no decimal point are printed.

•

The float or double arg is cODverted in the style '[-Jd.ddde:t dd' where there is one digit
before the decimal point and the number after is equal to the precision specification Corthe argument; when the precision is missmg, 6--digits are produced.

•

The float or double tUg is printed in style d, in style I, or in style ep- whichever grves-full
precision in minimum- spa.ce.

converted to decimal, octal, or hexadecimal notation respectively.

The %e, %f, and %8 formats print IEEE indeterminate values fmfinity or Dot-a-number) as
ItInfinity" or "Nan" respectively.
c

The character tJrg is printed.

•

Arg is taken to be a string (character pointer) and characters from the string are printed

until a DlIlI character or until the number of characters indicated by the precision
specification is reached; however if the precision is 0 or missing all characters up to a null
are printed.

u

The unsigned integer arg is converted to decimal and printed (the result will be in the
range 0 through MAXUINT, where MAXUlNT equals 4294967295 on a VAX-II or Sun
and 65935 on a PDP-II).

%

Print a

,% ..; no argument is converted.

In no case does a non-existent or small field width cause truncation of a field; padding takes place
only if the specified field width exceeds the actual. width. Characters generated by print! are
printed by putc(3S).

Example.
To print a date and time in the form 'Sunday, July- 3, 10:02', where weeida,l and month are
pointers to null-terminated strings:
printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min);
To print 1r ~v ~. decimals:
printf("pi

= %.5(", 4·atan(I.0));

SEE ALSO

plltc(3S), scanf(3S), ecvt(3)
BUGS

Very wide fields (>128 characterslfail.
The v-alues UlnfinityH and

12

'~n'"

cannot be read by 8canjf3S).

Last change: 1 April 1981

Sun Release 1.1

PUTC(3S}

STANDARD I/O LffiRARY

PUTC(3S)

NAME
pate, putchar, fputc, putw - put character or word on a stream
SYNOPSIS

*lDclude <8tdlo.h>
tnt pute(c, 8tream)
char CI
FILE *.treaml
putchar(e)
lpute(e,8tream)
FILE *.treaml
putw(w, .tream)
. FILE *.treaml
DESCRIPTION
Pule appends the character e to the named output "ream. It returns the character written.

PUleAar(e) is deflned as ,ule(e, .tdout).
F,ule behaves like pule, but is a senuine function rather than a macro.
Pulw appends C tnt (word) w to the output ,tream. It returns the integer written. Pulw neither
assumes nor caulesspecial alisnment in the flle.
SEE ALSO
fopen(3S), fclose(3S), getc(3S), puts(3S), printf(3S), fread(3S)
DIAGNOSTICS
These functions return the constant EOF upon error. Since thi8 is a good integer, Jerror(3S)
should be used to detect pulw errors.
BUGS

Beeause it is implemented as a macro, pule treats a "reo.m argument with side eleds improperly.
In partieular "pute(e, *t+ + }". doesn't work sensibly.
Errors can oceur lonl after the call to pule.
Data flies written and read with pulw and ,elware not portable; the size of an tnt and the order
in whieh data bytes are stored within an tnt varies between mae hines.

Sun Release 1.1

Last change: 23 August 1983

13

PUTS(3S)

STANDARD I/O LmRARY

PUTS (3S)

NAME
puts, ,puts - put a string on a Itream
SYNOPSIS

*lnclude <.tdlo.h>
put·CI)
char

*••

tput.C., .tream)
char *••
FILE *.treamJ
DESCRIPTION
Put, copies the null-terminated string • to the Itandard output Itream aWout aDd appends a
newline character.

Fput, copies the null-terminated string' to the named output ,'ream.
Neither routine copies the terminal nun character.
SEE ALSO
lopen(3S), gets(3S), putc(3S), printl(3S), lerror(3S)
Iread(3S) tor Iwrite

BUGS

Put, appends a newline, Ipu', doe. not, an in the name 01 backward eompatibUity.

14

Last change: 19 January 1983

Sun Release 1.1

SCANF(3S)

STANDARD I/O LffiRARY

SCANF(3S)

NAME
scant, rseuf, sBeanf - formatted input conversion
SYNOPSIS
*lnclude 
Icanf(format ( , pointer) ... )

char *format,
flcanf(.tream, format [ , pointer J ... )
FILE *.tream,
ehar *format,
IIC&OI(I, format ( pointer) ... )
char *" *format,
J

DESCRIPTION
Scan/ reads from the standard input stream .tdln. FBcan/ reads from the named input Btream.
SBcan/ reads from the character string B. Each function reads characters, interprets them according to a format, and stores the results in its arguments. Each expects as arguments a control
string format, described below, and a set of pointer arguments indicating where the converted input should be stored.
The control string usually contains conversion specifications, which are used to direct interpretation of input sequences. The control string may contain:
1.

Blanks, tabs or newlines, which match optional white space in the input.

2.

An ordinary character (not %) which must match the next character of the input stream.

S.

Conversion specifications, consisting of the character ~, an optional assignment suppressing
character *, an optional numerical maximum field width, and a conversion character.

A conversion specification directs the conversion or the next input field; the result is placed in the
variable pointed to by the corresponding argument, unless assignment suppression was indicated
by *. An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted.
The conversion character indicates the interpretation or the input field; the corresponding pointer
arlument must usually be of a restricted type. The f~lIowing conversion characters are legal:

% a single '%' is expected in the input at this point; no assignment is done.
d
o
x

an octal integer is expected; the corresponding argument should be a integer pointer.
a hexadecimal integer is expected; the corresponding argument should be an integer pointer.

I

a character string is expected; the corresponding argument should be a character pointer
pointing to an array or characters large enough to accept the string and a terminating '\0',
which will be added. The input field is terminated by a space character or a newline.

e

a character is expected; the corresponding argument should be a character pointer. The normal skip over space characters is suppressed in this case; to read the next non-space character, try '%h'. If a field width is given, the corresponding argument should refer to a character array, and the indicated number of characters is read.

e

a floating point number is expected; the next field is converted accordingly and stored
through the corresponding argument, which should be a pointer to a float. The input format
lor floating point numbers is an optionally signed string of digits possibly containing a de-cimal point, followed by an optional exponent field consisting or an E or e followed by 3n optionally signed integer.

(

indicates a string not to be delimited by space cliaracters. The lett bracket is followed by a

t

SUD

a decimal integer is expected; the corresponding argument should be an integer pointer.

Release 1.1

Last change: 15 March 1984

15

SCANF(3S)

STANDARD I/O LmRARY

SCANF(3S)

set of characten and a right bracket; the characters between the brackets define a set of
characters making up the string. It the first character is not circumflex ( .. ), the input field is
all characten until the first character not in the set between the brackets; it the first character alter the lelt bracket is A, the input field is all characten until the fint character which is
in the remaining set 01 characters between the brackets. The correspondinl argument must
point to a character array.

The conversion characters d,.. 0 and
pointer to Ion. rather than to lnt is
or t may be capitalized or preceded
The conversion characters d,--o aDd x
than to lnt.

x may be capitalized or preceded by I to indicate that a
in the argument list. Similarly, the conversion characters.
by 1 to indicate a pointer to double rather than to Boat.
mar be preceded by h to indicate a pointer to .hort rather

The BCGn! functions return the number 01 successfully matched and assigned input items. This
calL be used to dedde how many input items were lou ad. The constant EOF is returned upon
end 01 input; note that this is different from OJ which means that no conversion was done; if
conversion was intended 1 it was frustrated by an inappropriate character in the inputOFor example,.. the eaH
int i; float x;-char namelSDl;
8li, 8lx, name):

scanr("o/"qd%t%s·~

with the input line
25

54.32&-1 thompson

will assign to ithe value 25,

% the

value 5.432, and nome will contain 'tAomp,on\O'. Or,

int i; float x; char namel50J;
scanf("%2d%t%·d%[1234567800)", .ti, .tx, name~
with input
56789012356a72
will assiln 56 to i, 789.0 to
gelchor will return 'a'.

%,

skip '0123', and place the strinl '56\0' in nome. The next call to

SEE ALSO
ator(3), getc(3S), printt(3S)
DIAGNOSTIOS
The BCGnj functions return EOF on end ot input, and a short count tor mesinl or illegal data
items.

BUGS
The success or literal matches and suppressed assignments is not directly determinable.
Scan! cannot read the strings which printj(3S) generates tor IEEE indeterminate Boating point
values.
SCGn! provides no way to convert a number in any arbitrary base (decimal, hex or octal) based on
the traditional C conventions (leading 0 or Ox).

16

Last change: 15 March 1984

SUB

Release 1.1

SETBUF(3S)

STANDARD I/O LffiRARY

SETBUF(3S)

NAME
letbuf, aetbuler, letlinebuf - assign bulering to a stream

SYNOPSIS

*lDclude 
letbuf(stream, but)
FILE *.tl'eam,
char -bul,
letbuffer(stream, but, 11&e)
FILE *.tl'eam,
char *buf'1
mt 81__

setllnebuf'(stream)
FILE *streaml
DESCRIPTION
The three types of buffering available are unbuffered, block buffered, and line buffered. When an
output stream is unbuffered, inrormation appears on the destination file or terminal as soon as
written; when it is block buffered many characters are saved up and written as a block; when it is
line buffered characters are saved up until a newline is encountered or input is read from stdin.
Ffl,U8h (see !clo,e(3S)) may be used to force the block out early. Normally all files are block
buflered. A buffer is obtained from malloc(3) upon the firet getc or putc(3S) on the flle. If the
standard stream Itdout refen to a terminal it is line buffered. If the standard stream .tderr
refer. to a terminal it is line buffered.

Sethu! is used after a stream has been opened but before it is read or written. The character array bu! is used instead of an automatically allocated buffer. If bu! is the constant pointer NULL,
input/output will be completely unbuffered. A manifest constant BUFSIZ tells how big an array
i8 needed:
chap buf[BUFSIZ};
Se#bu//er, an alterna.te form of ,etbu!, is used after a stream has been opened but berore it is read
or written. The character array 6uJwhose size is determined by the size argument is used instead
or an automatically allocated buffer. II bu! is the constant pointer NULL, input/output will be
completely unbuffered.

Setlinebu/ is used to change 8tdou' or dderr (only) from block buffered or unbuffered to line
bulered. Unlike ,etbu! and ,etbuJTer it can be used at any time that the file descriptor is active.

A file can be changed trom unbuffered or line buffered to block buffered by using !reop en (see
/open(3S)). A file can be changed from block bulered or line bulered to unbulered by using !reopen followed by Betbu/with a buler argument or NULL.
SEE ALSO
(open(3S), getc(3S), putc(3S), malloc(3), rclose(3S), puts(3S), printf(3S), rread(3S)
«

Sun Rele~, 1.1

Last change: 23 August 1983

17

UNGETC(3S)

STANDARD I/O LffiRARY

UNGETC(3S)

NAME

ungete - push character back into input stream
S-YNOPSIS

#lnclude 
uDsetc(c, stream)
FILE *.tream.
DESCRIPTION
Un,de pushelJ the character c back on aD mput, stream. That character will be returned by the
next ,de call on that stream. Unldc returns c..

One character of pushback is guaranteed provided something has been read from the stream and
the stream is actuallybufrered. Attempts to push EOF are rejected.
AD /Buk(3S) eruel all memory of pushed back characters.
SEE ALSO

get.cf3S), se.tbef{3S), tseekfSS)
DIAGNOSTICS
fJn,dc returns EOF if it can't push a character back.

18

Last change: 19 January 1983

Sun Release 1.1

INTRO(3X)

MISCELLANEOUS FUNCTIONS

INTRO(3X)

NAME
intro - introduction to other libraries
DESORIPTION
This section contains manual pages describing other libraries,' which are available only rrom C.
The list below includes libraries which provide device independent plotting runctions, terminal
independent screen management routines ror two dimensional non-bitmap display terminals, and
functions for managing data bases with inverted indexes. All functions' are located. in separate
libraries indicated in each manual entry.
FILES
lusr llib/libcurses.a
lusr/lib/libdbm.a
lusr/lib/libmp.a
lusr llib llibplot.a
lusr/lib/lib300.a
lun llib Ilib300s.a
lusr Ilib/lib-i50.a
lusr Ilib/lib4014.a
lusr llib Ilibtermcap. a
lusr/lib/libtermcap-p.a
lusr/lib/libtermlib.a '
lusr/lib/libtermlib-p.a

SUII

Release 1.1

screen management routines (see cur8e8(3x))
data base management routines (see dbm(3x))
multiple precision math library (see mp(3x))
plot routines (see plot(3x))

"
"

"

"

terminal handling routines (see termcap(3x))

Last change: 12 January 1984

1

CURSES (3X)

MISCELLANEOUS FUNCTIONS

CURSES (3X)

NAME

curses - screen runctions with "optimal" cursor motion
SYNOPSIS

cc ( flags J files -Icur_ -ltermcap ( libraries J
DESCRIPTION
These rou tines give the user a method or updating screens with reasonable optimization. They
keep an image or the current screen, and the user sets up an image or a new one. Then the
re/re8h() tells the routines to make the current screen look like the new one. In order to initialize
the routines, the routine initBcr(j must be called belore any 01 the other routines that deal with
windows and screens are used. The routine endwin() should be called berore exiting.
SEE ALSO
ioctl(2J, getenY(3), tty(4), termcap(5)
FUNCTIONS
addch(ch)
addstr(&tr)
box (win ,vert,hor)
crmodeO
dearO
clearok(scr,boolt}
clrtobotO
clrtoeolO
delchO
deletelnO
delwin(win)
echo()
endwinO
eraseO
getchO
getcap(name)
getstr(str)
gettmodeO
getyx(win,y,x)
inchO
initscrO
insch(c)
insertlnO
leaveok(win, boolf)
longname( termbur,name)
move(y',x)
mvcur(lasty ,Iastx,newy ,newx)
newwin(lines,cols,beginJ, begin~)
nlO
;
nocrmodeO
noecho()
nonlO
norawO
overlay(winl,win2)
overwrite(winl,win2)
printw(fmt,argl,arg2, ... )
rawO
retreshO
resettyO

2

add a character to .td.cr
add a string to std.cr
draw a box around a window
aet cbreak mode
clear .td.er
let clear ftag for .cr
clear to bottom on .,d.cr
clear to end of line on Btd.cr
delete a character
delete a line
delete win
set echo mode
end window modes
erase .,dBcr
get a char through BtdBcr
get terminal capability nome
get a string through BldBcr
get tty modes
get (y ,x) co-ordinates
get char at current (y,x) co-ordinates
initialize screens
insert a char
insert a line
set leave ftag for win
get long name from term",,!
move to (y,x) on .tdBcr
actually move cursor
create a new window
set newline mapping
unset cbreak mode
unset echo mode
unset newline mapping
unset raw mode
overlay winl on win2
overwrite winl on top of win2
printf on 8tdBcr
set raw mode
make current screen look like Bld8cr
reset tty flags to stored value

Last change: 16 February 1984

Sun Release 1.1

CURSES (3X)

MISCELLANEOUS FUNCTIONS

lavettyO
Icanw(fmt,ar&l,ar&2, ... )
ICroll(win)
ICrollok(win,boolf)
setterm(name)
ItandendO
etandoutO
lubwin(win,lines,cola,belin-y,beliD.J[)
touchwin(win)
unctrl(ch)
waddch(win ,ch)
waddstr(win ,str)
wclear(win)
wclrtobot(win)
wclrtoeol(win)
wdelch(win,c)
wdeleteln(win)
werue(win)
wletch(win)
wletstr(win,str)
winch(win)
winsch(win,c)
winlertln(win)
wmove(win,y,x)
wprintw(win ,fmt,arll ,ar&2, ... )
wrefresh(win)
wlcanw(win,fmt,arll,uI2, ... )
wltandend(win)
watandout(win)

SUD

Release 1.1

CURSES (3X)

8tored current tty Hags
scanf through eldecr
scroll win one line
set scroll fl ag
set term variables ror name
end standout mode
start standout mode
create a subwindow
"change" all or win
printable version or ch
add char to win
add string to win
clear win
clear to bottom of win
clear to end of line on win
delete char from win
delete line from win
erase win
let a char through win
let a string through win
get char at current (y,x) in win
insert char into win
insert line in to win
set current (y,x) co-ordinates on win
print( on win
make screen look like win
scanf through win
end standout mooe on win
start standout mode on win

Last change: 16 February 1984

3

DBM(3X)

MISCELLANEOUS FUNCTIONS

DBM(3X)

NAME

dbminit, fetch, store, delete, flrstkey, nextkey - data base subroutines
SYNOPSIS

typedet atruct {
char *dptr;
tnt daise,
} datum;
dbmlnlt(flle)
char *flle,
datum tetcb(key)
datum ken
atore(ke~, content}
datum key. contentJ
delete(key)
datum key,
datum flratkeyQ
datum nextkenkex)
datum key,
DESCRIPTION
These functions maintain key/content pairs in a data base. The lundions will handle very large
(a billion blocks) databases and will access a keyed item in one or two file system acceues. The
functions are obtained with the loader option -ldbm.

Kevs and contents are described by the dGtum typedet. A datum specifies a string of d,ize bytes
pointed to by dptr. Arbitrary binary data, as well as normal ASCII strings, are allowed. The data
base is stored in two files. One file is a directory containing a bit map and has '.dir' as its SUfrlX..The second file contains all data and has '.pag' as its sulix.
Before a database can be accessed, it must be opened by dbminit. At the time or this call, the flies
file.dlr and file.pas must exist. (An empty database is created by creating zero-length '.dir' and
, .pag' files,)
Once open, the data stored under a key is accessed by letch and data is placed under a key by
,tore. A key (and its associated contents) is deleted by deleteO- A linear pass through aU keys in a
database may be made~ in an (apparently) random order~ by use or jir,tkey and neztkev. Fi"tkev
will return the lirst key in the database. With any key neztkell will return the next key in the
database. This code will traverse the data base:
for (key - flrstkey(J; key.dptr t- NULL~ key - nextkey(key))
DIAGNOSTIOS
All functions that; return an int indicate errors with negative values. A zero return indieates ok.
Routines that return a datum indicate errors with a nuU (0) dpt,.
BUGS-

The '.pag'- file will contain holes 80 that its apparent size is about rour times its actual content.
Older UNIX systems may create real file blocks tor these holes when touched. These files cannot
be copied by normal means (cp, cat, tp, tar, ar) without filling in the holes.

Dptr pointers returned by these
quent calls.

subr~utines

point into static storage that is changed by subse-

The sum ot the sizes of a key/content pair must not exceed the internal block size (currently 1024
bytes). Moreover all key/content pairs that hash together must fit on a single block. Store will
return an error in the event that a disk block filla with inseparable data.

4

Last change: 20 March 1984

SUD

Release 1.1

DBM(3X)

MISCELLANEOUS FUNCTIONS

DBM(3X)

Delde does Dot physically reclaim file space, although it does make it available for reuse.

The order 01 keys presented by firBtkey and neztkey depends on a hashing function, not on anything interesting.

There are no interlocks and no provisionunreliable cache flushing; thus concurrent updating and
reading is risky.

SUD

Release 1.1

Last change: 20 March 1984

5

NAME

MP(3X)

MISCELLANEOUS FUNCTIONS

MP(3X)

.
...
.h
.
itom, madd, msub, mult, mdiv, min, mout, pow, gcd, rpow - multiple preCISion IDtegerarlt metlc

SYNOPSIS

#lnclude 
madd(a, b, c)

-a, -b, -CI

MINT

maub(a, b, c)

MINT -.,

-b, *CI

mult(a, b; e)

-a. -b, -c,

MINT

mdlv(a, b~ q, 1")
MINT -a, -b .. -q, -l"J
mln(a}

M1NT*aFmout(a)

MINT *&1
pow(at- b, e, cI)
MINT -a" -b, -c,
Icd(a, b, e)

MINT *a, -b,

-d,

·c,

rpow(a, D, b)
MINT -a,

-b,

ahort DJ

maqrt(a, b, r)
-a, -b, -"

MINT

adlv(a,

D,

q, r)

MINT -a, *cu
ahort

0,

-r.

MINT *ltom(D)
ahort DJ
DESCRIPTION

These routines perform arithmetic on integen of arbitrary length. The integers are stored using
the defined type MINT. Pointers to a MINT should be initialized using the function ilom, which
sets the initial value to n. After that space is managed automatically by the routines.
Madd, mBub and mutt assign to their third arguments the sum, difference, and product, respectively, or their first two arguments. Mdiv assigns the quotient and remainder, respectively, to its
third and fourth arguments. Sdiv is like mdiv except that the divisor is an ordinary integer.
M8grt produces the square root and remainder of its first argument. Rpow calculates a raised to
the power h, while pow calculates this reduced modulo m. Min and mou' do decimal input and

6

Last change: 15 March 1984

SUIl

Release 1.1

MP(3X)

MISCELLANEOUS FUNCTIONS

MP(3X)

output.
Use the -Imp loader option to obtain access to these functions. -Imp.
DIAGNOSTICS
Illegal operations and running out of memory produce messages and core images.
FILES
!ulr!lib!libmp.a

Sun Release 1.1

Last change: 15 March 1984

7

PLOT(3X)

MISCELLANEOUS FUNCTIONS

PLOT( 3X)

NAME
openpl, erase, label, line, circle, are, move, cont, point, linemod, space, closepl- graphics interrace
SYNOPSIS

opeopl()
eraseO

label(l)
char 10.
Une(xl, yl, xl, yl)
clrcle(x, y, r)
arc(x, y, xO, yO, xl, yl)
move(x, y)
eoot~tY)
polDt~,n

llDemod(l)

char·Ot
.pae.e(xO, yO, xl, ,,1)
eloaepl()
DESORlPncm-These subro1ttines generate graphic output ia a reiativery device-independent manner. See ,loI(6-}
lor a description of their effect. Openpl moat be used berore any of the othen to open the device
lor writing. Ololepl flushes the output.
String arguments toltJbel and fmemod are nulI-terminated~ and do-not contain newlfnes.Various 8avora or theae functions exiat. for clilereat output devices. They are obtained by the lollowing Id(l) options:-

-Iplot
-1300
-1300.
-1460
-14014

device-independent graphics stream- en standard output for plol(lG) fllten
GSI 300 terminal
GSI aoos- terminalDASI 450 terminal
Tektronix 4014 terminal

SEE ALSO
plot(5), plot(lG), graph(lG)
FILES-

lusr/lib/Ubplot.a
lusr/lib/lib300.a
lusr /lib Ilib300s.a
lusrIlib/lib400.a
IUSf Ilib/lib4014.a

8

Last change: 19 January 1983

Sun Release 1.1

TERMCAP(3X)

MISCELLANEOUS FUNCTIONS

TERMCAP(3X)

NAME
tgetent, tgetnum, tgetftag, tgetstr, tgoto, tputs - terminal independent operation routines
SYNOPSIS

char PC,
chal' -BC,
char -UP,
ahort oapeed,
tletcmt(bp, Dame)
char -bp, -Dame,
tsetoum(ld)
char -Id,

tletft&s(ld)
char -Id,
char tletatr(ld, area)
char -Id, -*area,
char •
tloto(e:m, deateol, deatUne)
char ·cm,
tputs(e:p, atrcnt, outc)
repter ehar *epi
tnt affent,
lDt (*oute)0.
DESORIPTION
These functions extract and use capabilities from the terminal capability data base termcap(5).
These are low level routines; see curse,(3X) for a higher level package.

Tgetent extracts the entry for terminal name into the buffer at hp. Bp should be a character buffer
of size 1024 and must be retained through all subsequent calls to tgetnum, tgetjlag, and tgetBtr.
Tgetent returns -1 if it cannot open the termcap file, 0 if the terminal name given does not have
an entry, and 1 if all goes well. It will look in the environment for a TERMCAP variable. If
found, and the value does not begin with a slash, and the terminal type name is the same as the
environment string TERM, the TERMCAP string is used instead of reading the termcap file. If
it does begin with a slash, the string is used as a path name rather than / etc/termcap. This can
speed up entry into programs that call tgetent, as well as to help debug new terminal descriptions
or to make one for your terminal if you can't write the file / etc/termcap.
Tgetnum gets the numeric value of capability id, returning -1 if is not given for the terminal.
Tgetjfag returns 1 if the specified capability is present in the terminal's entry, 0 if it is not.
Tgd", gets the string value of capability id, placing it in ·the buffer at area, advancing the area
pointer. It decodes the abbreviations for this field described in termcap(5), except for cursor
addreuing and padding information.
Tgoeo returns a cttrSC)f addressing string decoded from cm to go to column deBlcol in line deBt/ine.
It usee the external variables UP (from the up capability) and BC (if be: is given rather than ba)
if necessary to avoid placing \0, AD or AQ in the returned string. (Programs which call tgoto
should be sure to turn off the XTABS bit{s), since tgoto may now output a tab. Note that programa using termcap should in general turn off XTABS anyway since some terminals use control I
for other functions, such as nondestructive space.) If a % sequence is given which is not understood, then tgolo returns "OOPS".

SUD

Release

1~1

Last change: 9 February 1983

9

TERMCAP (3X)

:MISCELLANEOUS FUNCTIONS

TERMCAP(3X)

Tputl decodes the leadins paddinl intormation ot the strins ep; offent gives the number ot lines
affected by the operation, or 1 it this is not applicable, oule is a routine which is called with each
character in turn. The external variable olpeed should contain the encoded output speed ot the
terminal as described in "11(4). The external variable PC should contain a pad character to be
used (trom the pc capability) it a null fa) is inappropriate.
FILES

/usr/lib/libtermcap.a -Itermcap library
data base
/etc/termeap
SEE ALSO

eX(l), curses(3X), tty(4), termcap(5)

10

Last change: 9 February 1983

Sun Release 1.1

INTRO(4)

SPECIAL Fll..ES

INTRO( 4)

NAME
intro - introduction to special files and hardware support
DESORIPTION
This section describes device interfaces to the operating system for disks, tapes, serial communications, high-speed network communications, and other devices such as mice, frame buffers and windows.
The operating system can be built with or without many of the devices listed here; we show for
most devices the syntax in a description to config(8) to cause the device to be included in a sy~
tem. For mose devices we also give a DIAGNOSTICS section which lists the error messages
which the device may produce to appear on the system console, and in the. system error log file
/usr/aAim/messages.
Section 4 has been broken up according to machine independent device interfaces, "4" entries,
Sun sp~cific devices "4S", Vax specific devices "4V", manual pages for protocol families "4F",
and manual pages for protocols and raw interfaces "4P".
Most devices on the Sun workstation exist on the Multibus, whose common properties are
described in m6( 4S).
Devices which are present in every kernel include a driver for the paging drum drum(4), drivers
for accessing physical, virtual and i/o memory mem(4S) and the drivers for the data sink
/dev /null, nUII(4).
Communications lines are most often used with the terminal driver described in ttll(4). The terminal driver runs on communications lines provided either by a communications driver such as
oct(4S) or zs(4S) or on a more virtual terminal, either provided by the Sun console monitor
cona(4S) or a true pseudo-terminal ptll(4) used in applications such as windowing or remote networking.
Magnetic tapes all provide the interface described in mtio(4). Tape devices for the Sun include
Gr(4S) and tm(4S).
Disk controllers provide standard block and raw interfaces, as well as a set of ioctl's defined in
tlkio(4S) supporting disk formatting and bad block handling. Drivers available for the Sun
include .7:1I(4S) and ip(4S).
The operating system supports one or more protocol/amilies supporting local network communications. The only complete protocol family in this version of the system is the Internet protocol
family inet(4F). Each protocol family provides basic services to each protocol implementation
such as packet fragmentation and reassembly, routing, aAidressing and basic transport. A protocol
family is normally composed of a number of protocols, one per 80cket(2) type. It is not required
that a protocol family support all socket types.
The primary network support is for the Internet protocol family described in inet(4F). Major protocols in this family include the Internet Protocol ip(4P) describing the universal datagram format, the stream Transport Control Protocol tcp(4P), the User Datagram Protocol udp(4P), the
Address Resolution Protocol Grp(4P), and the Internet Control Message Protocol icmp(4P). The
primary network interface is for the 10 Megabit Ethernet ec(4S); a software loopback interface
10(4) also exists. General properties of these (and all) network interfaces are described in i/(4N).
The general support in the system for local network routing is described in routing(4N); these
facilities apply to aU protocol families.
Miscellaneous devices include color frame buffers cg*(4S), monochrome frame buffers bUJ*(4S), the
console frame buffer, fb(4S), the console mouse mou8e(4S) and the window devices win(4S).

Sun Release 1.1

Last change: 21 March 1984

1

SPECIAL FILES

AR (4S)

AR(4S)

NAME
ar - Archive 1/4 inch Streaming Tape Drive
SYNOPSIS

device arO at mbO car Ox2OD priority 3
DESCRIPTION

The Archive tape controller is a Sun 'QIC-II' interface to an Archive streaming tape drive. It
provides a standard. tape interlace to the device, see mlio(4}J- with some deficiencies listed under
BUGS below.
The maximum blocksize for the raw device is limited only by available memory.
FILES

/dev/rarO
Idev /nram

non-rewind in&.-

SEE ALSO
mtio(4}, tm(4S)
Archive IntelligeDt Tape Drive Theory of Operation, Archive Corporation (Sun 8000-1058-01J
Arcliive Product Manual (Sfdewinder 1/4" Streaming Cartridge Tape Drive) (Sun 800-0628-01)
Sun 1/4ft- Tape Interfaee - User Manual (Sun 80.0-0415-(1)
DIAGNOSTICS-

ar%da. would not lnltIaU&e.
ar%dl already open. The tape can be open by only one process-at a time.
ar~odl no .uch cfrlve.
ar%dl no cartridge In drive.
ar%dl cartridge t. write

protected~

arllnterrupt from unltlaDzed controller %x.
al'%dl many retries, consider retlrlnl tht. tape.
ar%da %b error at block

*
*

%d punted.

ar%dl %b error at block %d.
al'l sivlnl up on Rdy, try agaln.
BUGS

The tape cannot reverse direction so BSF, BSR and FSR are not available.
The system will hang if the tape is removed while running.
When using the raw device, the number of by tea. in any- given transfer must be a multiple of 512
bytes. If it is not, the device driver returns an erLor.

2

Last change; 20 March 1984

SUD Release 1.1

ARP(4P)

SPECIAL FILES

ARP( 4P)

NAME
arp - Address Resolution Protocol
SYNOPSIS

pseudo-devlee ether
DESCRIPTION

ARP is a protocol used to dynamically map between DARPA Internet and 10Mbls Ethernet
addresSes. It is used by all the 10Mb Is Etherg,et interface drivers.
ARP caches Internet-Ethernet address mappings. When an interface requests a mapping for an
address not in the cache, ARP queues the message which requires the mapping and broadcasts a
message on the associated network requesting the address mapping. If a response is provided, the
new mapping is cached and any pending messages are transmitted. ARP will queue at most one
packet while waiting for a mapping request to be responded to; only the most recently "transmitted" packet is kept.
To enable communications with systems which do not use ARP, ioctls are provided to enter and
delete entries in-the Intemet-to-Ethemet tables. Usage:
*lnelude 
#lnelude 
*lnelude 
.truet arpreq arprecu
loetl(s, SIOCSARP, (eaddr_t)&arpreq).
loetl(s, SIOCGARP, (eaddr_t)cb.rpreq),
loetl(s,SIOCDARp,(eaddr_t)&arpreq).
Each ioctl takes the same structure as an argument. SIOCSARP sets an ARP entry, SIOCGARP
gets an ARP entry, and SIOCDARP deletes an ARP entry. These ioctls maybe applied to any
socket descriptor " but only by the super-user. The orpreq structure conta~Ds:

/*

* ARP ioctl request

*/

struct arpreq {
struct sockaddr arp-pa;
struct sockaddr arp_ha;
int
arpjlags;

1* protocol address */
/* hardware address */
/* flags */

};

/* arp_flags f!eld vaiues */
*define ATF _COM
2
/* completed entry (arp_havalid) *'
;ll:define ATF_PERM 4
/* permanent entry
*define ATFYUBL
8
/* publish (respond for other host)
The address family for the orp-po sockaddr must be AF _INET; for the orp_ho sockaddr it must
be AF_UNSPEC. The only flag bits which may be written are ATF _PERM and ATF_PUBL.
ATFYERM causes the entry to be permanent if the ioctl call succeeds. The peculiar nature of
the ARP tables may cause the ioctl to fail if more than 4 (permanent) Internet host addresses
huh to the same slot. ATF_PUBL specifies that the ARP code should respond to ARp· requests
for the indicated· host coming from other machines. This allows a Sun to act as an "ARPserver"
which may be useful in convincing an ARP-only machine to talk to a non-ARP machine.

*'

*'

ARPwatches passively for hosts impersonating the local host (i.e. a host which responds to an
ARP mapping request'for the local host's address).
DIAGNOSTICS

dupUeate IP addre..!! sent from ether net address: %x:%x:%x:%x:%x:%x. ARP has
discovered another host on the local network which responds to mapping requests for its own

SUD

Release 1.1

Last change: 11 January 1984

3

ARP( 4P)

SPECIAL Fll..ES

ARP( 4P)

Internet address.
SEE ALSO

ec(4S), ie(4S), inet(4F), arp(8C), ifconfig(8C)
An Ethernet Address Resolution Protocol, RFC826, Dave Plummer, MIT (Sun 8()()"10Sg..ol)
BUGS

ARP p'ackets on the Ethernet use only 42 bytes or data, however, the smallest legal Ethernet
packet is 60 bytes (not including CRC). Some systems may not enforce the minimum packet size,
others will.

4

Last change: 11 January 1984

Sun Release 1.1

BK(4)

SPECIAL FILES

BK{ 4)

NAME
bk - line discipline for machine-machine communication
SYNOPSIS

pseudo-device bk
DESCRIPTION
This line discipline provides a replacement for the tty driver tty(4) when high speed output to and
especially input from another machine is to be transmitted over an asynchronous communications
line. The discipline was designed for use by a (now obsolete) store-and-forward local network running over serial lines. It may be suitable for uploading of data from microprocessors into the system. If you are going to send data over asynchronous communications lines at high speed into
the system, you must use this discipline, as the system otherwise may detect high input data rates
on terminal lines and disable the lines; in any case the processing of such data when normal terminal mechanisms are involved saturates the system.
The line discipline is enabled by a sequence:

:f/:lnelude 
tnt Idlse
NETLDISC, fUdes; •••
loetl(flldes, TIOCSETD, &ldlse);

==

A typical application program then reads a sequence of lines from the terminal port, checking
header and sequencing information on each line and acknowledging receipt of each line to the
sender, who then transmits another line of data. Typically several hundred bytes of data and a
smaller amount of control information will be received on each handshake.
The old standard teletype discipline can be restored by doing:

==

Idlse
OTTYDISC.
loetl(flldes, TIOCSETD, &Idlse);
While in networked mode, normal teletype output functions take place. Thus, if an 8 bit output
data path is desired, it is necessary to prepare the output line by putting it into RAW mode using
ioctl(2). This must be done before changing the discipline with TIOCSETD, as most ioctl(2)
calla are disabled while in network line-discipline mode.

When in network mode, input processing is very limited to reduce overhead. Currently the input
path is only 7 bits wide, with newline the only character terminating an input record. Each input
record must be read and acknowledged before the next input is read as the system refuses to
accept any new data when there is a record in the buffer. The buffer is limited in length, but the
system guarantees to always be willing to accept input resulting in 512 data characters and then
the terminating newline.
User level programs should provide sequencing and checksums on the information to guarantee
accur-ate data transfer.
SEE ALSO
tty(4)
DIAGNOSTICS
None.

Sun Release 1.1

Last change: 17 August 1983

5

BWONE(4S)

SPECIAL FILES

BWONE(4S)

NAME

bwone - Sun one black and white frame buffer
SYNOPSIS
device bwoneO at mbO cal' OxcOOOO prlorlt-y 3
DESCRIPTION
The 6wont interrace provides access to Sun-1 black-and-white graphics controller boards. It sup-

ports the FBIOGTYPE ioctl which a program can use to inquire as to the characteristics of the
display device; see foio(4S)
It supports the FBIOGPIXRECT ioctl which aUows Sun Windows to be run on it; see flio( 4S)
Reading or wr-iting to the frame buffer is not allowed - you must use the mmap(2) system call to
map the board into your address space-.
FILES

Idev /bwone(Q.9f
SEE ALSO

mmap(2), fb(4S), fbio{4S}
S1rn 1024 Video-Board - User Manual (Sun

800-042(}~

DIAGNOSTICS

None.

BUGS
Use of vertica~retrace interrupts fa Dol--Illpporled.

6

Last change: 21 March 1984

SUD

Release 1.1

BWTWO(4S)

SPECIAL FILES

BWTWO( 4S)

NAME
bwtwo - Sun two black and white frame buffer
SYNOPSIS
device bwtwoO at mbO ear Ox700000 priority 3
DESCRIPTION
The bwtwo interface provides access to Sun-2 Monochrome Video Controller boards. It supports
the FBIOGTYPE ioctl which a program can use to inquire as to the characteristics of the display
device; see fbio(4S)
It supports the FBIOGPIXRECT ioctl which

~llows

SunWindows to be run on it; see fbio(4S)

Reading or writing to the frame buffer is not allowed - you must use the mmap(2) system call to
map the board into your addrel5S space.
FILES
/ dev /bwtwo(0-9J
SEE ALSO
mmap(2), fb(4S), fbio(4S)
DIAGNOSTICS
None.
BUGS
Use ot vertical-retrace interrupts is not supported.

SUD

Release 1.1

Last change: 21 March 1984

7

CGONE(4S)

CGONE(4S)

SPECIAL FILES

NAME

egone - Sun-l eolQ.r graphics interface
SYNOPSIS
device cgoneO at mbO car OxeBOOG priority 3
DESCRIP-TION

The cgone interface provides access to the 800-1 color graphics controller board, which is normally supplied with a 13" or 19" RS170 color- monitor. It provides the standard frame buffer
interface as defined in J6io(4S).
It supports the FBIOGPIXRECT ioetl which allows SunWindows to be run on it; see J6io(4S)
The hardwal'e consumes 16 kilobytes of Multibus memory space. The board starts at standard
addresaea OxESOOO or OxECOOO. The board must be configured for interrupt level 3.
FILES

/dev legonett-ot
SEE ALSO
mmap(2}, fhio(-4S)
Sun Color Video Board USer's Manual (Sun 8000-0398, Rev BJ
Barco GDM-Color Display 120VAC Operation Instruetfona (13") (Sun 800-1002-(1)
Barco Color Display CD 252 120[220VAGOperation Guide (19") (Sun 8()()..1003..01}
DIAGNOSTICS

None.
BUGS

Use of color board vertical-retrace interrupts is not supported.

8

Last change: 21 March 1984

SUD

Release 1.1

SPECIAL FILES

CONS( 4S)

CONS (4S)

NAME

cons -driver for Sun console
SYNOPSIS
None; included in standard system.
DESCRIPTION
Cons is an indirect driver for the Sun workstation console, which implements a standard UNIX
terminal. Cons is implemented by calling the PROM resident monitor to perform I/O to and
from the current system console, which is either a Sun frame buffer or an R S232 port.

When the SUD window system win(4S) is active, console input is directed through the window system rather than being read from /dev/console.
An ioctl TIOCCONS may be applied to serial devices other than the console to cause output
which would normally appear on the console to instead be routed to the other devices. This is
used by the window system which does a TIOCCONS on a pseudo-terminal to cause console output to be routed there rather than to the screen through the PR(OM monitor, since routing output
througb the PROMd~5troysthe integrity of the screen.
FILES

/ devl consol'e
/dev /ttya

alternate console (serial port)

SEE ALSO

oct(4S),ttY(4), zS(4S)
BUGS
TIOCCONS should be restricted to the owner of /devlconsole.

Sun Release 1.1

Last change: 21 March 1984

DKIO( 4S)

SPECIAL FILES

DKIO( 4S)

NAME
dkio - generic disk control operations _
DESCRIPTION
All Sun disk drivers support a set of ioctl's for disk formattting and labelling operations. Basic to
these ioctl's are the definitions in :

'**
'**'

Structures and definitions for disk io control commands

Disk identification .,
struct elk_info {
intdkCctlr;
short dki_unit;
short dki_ctype;:
short dki_f1ags;

''**
'* *'

,. 8ap

};

/* eontroller types .,
:f/:define DKC_UNKNOWN
I=define DKC_SMD2180
#define DKC_XY 440
I=define DKC_DSD5215
I=deflne DKC_XY450
#define DKC_SCSI

'* *'

flags DKI_BAD144 01
#define
#define DKI_MAPTRK 02
#define DKI_FMTTRK 04
#deflne DKI_F~ITVOL OxOS

'*

Definition of a disk's
struct dk...,geom {
unsigned short
unsigned short
unsigned short
. unsigned short
unsigned short
unsigned short
unsigned short
unsigned short
unsigned short
unsigned short

o
1
4

5
6

7

'''***
'*

geometry

*' *' *'
*'

use DEC std 144 bad sector fwding
controller does track mapping
formats only full track at a time
tormats only full volume at a time

*'

*'

};

''**
''**
''** *
''r**
'*

Disk format request *i
struct dk_lmt {
daddr_t dkf_blkno;
daddr _t dkl_nblk;
u_char dkf_fill;
};

'''***

*'
*'
*'

dkLncyl;
dkg_acyl;
dkLbcyI;
dkLnhead;
dkLbhead;
dkLnsectj
dkgJntrlv;
dkLlapl;
dkLlap-2;
dkLextra(10};

'*

'*
10

*'*'
*'

controller addre81
unit (slave) address
controller. type

Disk re-map request

*'

=I of data cylinders

*'

1= of alternate cylinders .,

*'

cyl offset (for fixed head area)
# of heads
head offset (for Larks, etc.)
of sectors per track
interleave factor */
gap 1 si:&e .,
gap 2 size
for compatible expansion

*' *'
*'

*'

starting block
:#= of blocks
fill data

Last change: 20 March 19S4

Sun Release 1.1

DKIO( 48)

SPECIAL Fn.ES

struct dk~mapr {
daddr_t dkm_fblk;
daddr_t dkm_thlk;
daddr_tdkm_nblk;
u_char dkm_fill;

/*
/*
/*
/*

DKIO( 4S)

trom block */
to block * /
:#= blocks */
fill data */

};
/* disk io control commands
:#=define DKIOCHDR
#defineDKIOCGGEOM
#define DKIOCSGEOM
*defineDKIOCGPART
#defineDKIOC8PART
#define DKIOCFMT
#define DKIOCMAP
#defineDKIOCINFO

*/

_IO(d, 1)
/* next
_IOR(d, 2, struct dk-leom)
_IOW(d, 3, struct dk-leom)
_IOR(d, 4, struct dk_map)
_IOW(d, 5,struct dk_map)
_IOW(d, 6, struct dk_tmt)
_IOW(d, 7, struct dk_mapr)
_IOR(d, 8, struct dk_into)
I

I/O will read/write header * /
/* Get geometry */
/* Set geometry */
/* Get partition into */
/* Set partition into */
/* Format * /
/* Map * /
/* Get info*/

The DKIOCGINFO ioctl returns a dk_info structure which tells the kind ot the controller and
attributes about how bad-block processing is done on the controller. Bad sectors can then be pr~
cesled using either the DKIOCMAP request, which causes a sector to be re-mapped on the disk,
or the DKIOCFMT request which causes a sector to be re-rormatted.Toread or write the header
on a disk sector the DKIOClIDR ioctl can be used, it causes the next read or write request to also
read or write the (drive-type-specific) header data.
The DKIOCGPART and DKIOCSPART get and set the controller's current notion of the partition table for the disk (without changing the partition table on the disk itself), while the
DKIOCGGEOM and DKIOCSGEOM ioctl's do similar things for the per-drive geometry intormation. These can be used to format a drive, where the label does not exist betore the drive is tormatted.
SEE ALSO
ip(4S), xy(4S)
BUGS

The DKlOCMAP and DKlOCFMT request are incompletely implemented.

Sun Releastt 1.1

Last change: 20 March 1984

11

DRUM ( 4)

DRUM(4)

. SPECIAL FILES

NAME

drum - paging device
SYNOPSIS
None; included with standard system.
DESCRIPTION
This file refers to the paging device in use by the system. This may actually be a 8ubdevice of
one or the disk drivers, but in a system with paging interleaved across multiple disk drives it provides an indirect driver for the multiple drives.
FILES

/dev/drum

BUGS
Reads from the drum are not allowed across the interleaving boundaries. Since these only occur
every .5Mbytes or so, and since the system never allocates blocks across the boundary, this is usually not a problem.

12

Last change: 17 August 1983

SUD

Release 1.1

EC( 4S)

NAME

SPECIAL FILES

EC (4S)

ec - 300m 10 Mb Is Ethernet interface

SYNOPSIS

device eeO at mbO ear OxeOOOO priority 3
DESCRIPTION

The ec'interrace provides access to a 10 Mb/s Ethernet network through a 3COM controller. For
a general description of network interfaces see if( 4N).
The hardware consumes 8 kilobytes of Multibus memory space. This memory is used for internal
bulering by the board. The board starts at standard addresses OxEOOOOor OxE2000. The board
must be configured for interrupt level 3.
The interrace software implements an exponential backol algorithm when notified of a collision
on the cable.
The interrace handles the Internet protocol family, with the interrace address maintained in Internet format. The Address Resolution Protocol arp(4P) is used to map 32-bit Internet addresses
used in inel(4F) to the 48-bit addresses used on the Ethernet.
DIAGNOSTICS

ee%dl Ethernet Jammed. Arter 16 failed transmissions and backols using the exponential
backol algorithm, the packet was dropped.
ee%dl can't handle at%d. The interface was handed a message with addresses formatted in an
unsuitable address family; the packet was dropped.
SEE ALSO

arp(4N), if(4N), inet(4F)
3COM 3C4oo Multibus Ethernet Controller Reference Manual (Sun 800-0398)
BUGS

The interrace hardware is not capable of talking to itself, making diagnosis more dilicult.

Sun Rele~ 1.1

Last change: 12 January 1984

13

EN( 4S)

EN(4S)

SPECIAL FILES

NAME

en - Sun 3 Mb/s experimental Ethernet interface
SYNOPSIS
device enO at mbO cal' OxlOO priority 3
DESCRIPTION
The en interface provides' access to a 3 Mb/s Ethernet network. The host's address- is discovered
at boot time by probing the Ethernet address register. For a general description or network interfaces, see i/{4N}.

The board consumes 256 bytes of Multibus I/O space startin, at standard address Oxl00.
The interface handles both Internet and PUP protocol families, with the interrace address maintained in Internet format. PUP addresses are converted to Internet addresses by subsituting PUP
network and host values for Internet network and imp values, and setting the Internet host
number to zero.
DIAGNOSTICS:
en%dl output error. The hardware indicated an error on the previous transmission..-

en%dl sener error. After 16 retransmissions tile pac(et was dropped.
en%dlmput error. The hardware indicated an error in reading a packet-off the cable.
en%da can't handle at%d. The interface was handed a message with addresses formatted in
an unsuitable address family; the packet was dropped.
SEE-ALSO

if (4N), inet(4F)
Sun 3Mbit Ethernet Board, User's.. Manuaf (Sun 8(»'0392)
BUGS

This hardware and driver are not suppor&ed.

14

Last change: 11 August 1983

Sun Release 1.1

SPECIAL FILES

FB( 4S)

FB(4S)

NAME
fb - driver for Sun console frame buffer
SYNOPSIS
None; included in standard system.
DESCRIPTION
The Jb driver provides indirect access to a Sun graphics controller board. It is an indirect driver
for the Sun workstation console's frame buffer. At boot time, the workstation's frame buffer device is determined from information from the Monitor ProIDs and set to be the one that Jb will
indirect to. The device driver for the console's frame buffer must be configured into the kernel so
that this indirect driv,er can access it.
The idea behind this driver is that user programs can open a known device, query its characteristics and access it in a device dependent way, depending on the type. Fb redirects open(2),
clo8e(2), ioctl{2}, and mmop(2) calls to the real frame buffer. All of the Sun frame buffers support
the same general interface; see fbio(4S)

FILES
/dev/fb
SEE,ALSO
fbio(4S), bwone(4S), bwtwo(4S)

Sun Release 1.1

Last change: 21 March 1984

15

SPECIAL FILES

FBIO (4&)

FBIO( 4SJ

NAME
fbio - general properties of frame bulen
DESCRIPTION
All of the Sun frame bulers support the same general interface. Each responds to a FBIOGTYPE
ioctl(2) which returns information in a structure defined in :

struct

tbtype (
int
fb_type;
int.
fb_height;
iiat
fb_width;
int
rb_depth~
iDt
fb_cmaize;
int
fb_size;

/* as defined below *'

*'

1* In pixels *l

'r*

in pbela
bite per. pixel- ./
1* size 01 color map (entries) */
/* total aile in by-tea • f

#deAne FBTYPE_SUNIBW
f:deflne FBTYPE_SUNICOLOR
*deflne FBTYPE_SUN2BW

a
1

z-

Each device has a FBTYPE which is used by higher-level software to determine how to perform
raster-op and other functions. Each device is used by opening it, doing a FBIOGTYPE ioetl to
see which frame buler type is present,. and thereby selecting the appropriate device management
routines.
Full fledged frame bulers, i.e., those that expect to run SunWindows, implement an FBIOGPIXRECT ioetl(2), which returns a pixrect. This call is made only from inside the kernel. The
returned pixrect is used by win(4S) for cursor tracking and colormap loading.
SEE ALSO
mmap(2), fb(4S), bwone(4S), bwtwo(4S}, clone(4S), win(4S)

16

Last change: 21 March 1984

SUD Release 1.1

ICMP( 4P)

SPECIAL FILES

ICMP( 4P)

NAME
icmp - Internet Control Message Protocol
SYNOPSIS
None; included automatically with inet(4F).
DESCRIPTION
The Internet Control Message Protocol ICMP is used by gateways and destination hosts which
process datagrams to communicate errors iii datagram processing to source hosts. (The datagram
level of Internet is discussed in ip(4P).) ICMP uses the basic support .of IP 38 if it were a higher
level protocol, however ICMP is actually an integral part of IP.
ICMP messages are sent in several situations: for example when a datagram, cannot reach its destination, when the gateway does not have the buffering capacity to forward a datagram, and when
the gateway can direct the host to send traffic on a shorter route.
The Internet protocol is not designed to be absolutely reliable. The purpose of these control messages is to prov'ide feedback about problems in the communication environment, not to make IP
reliable. There are still no guarantees that a datagram will be delivered or a control message will
be returned. Some datagrams may still be undelivered without any report of their loss. The
higher level protocols which use IP must implement their own reliability procedures if reliable
communication is required.
The ICMP messages typically report errors in the processing of datagrams. To avoid the infinite
regress of messages about messages etc., no IClvIP messages are sent about ICMP messages. Also
ICMP messages are only sent about errors in handling fragment 0 of fragmented datagrams.
There are i1 types of ICMP packets which can be received by the system. They are defined in
this excerpt from < netinet/ip_icmp.h> , which also defines the values of some additional codes
further specifying the cause of certain errors.

/*

* Definition of type and code field values

*/
#define ICMP _ECHOREPL Y
0
#define IC:MP_UNREACH
3
#deflne
IClvIP_UNREACH_NET
*deflne
ICMP _UNREACHJIOST
*deflne
ICMP _UNREACH_PROTOCOL
*define
ICMP_UNREACHYORT
*deflne
ICMP _UNREACH_NEEDFRAG
*define
ICMP_UNREACH_SRCF AIL
*deflne ICMP_SOURCEQUENCH
4
*deflne ICMPJtEDffiECT
5
*define
ICMP _REDmECT_NET
0
*deflne
ICMP...REDmECT_HOST
1
*deflne
ICMP_REDffiECT_TOSNET 2
:jI:deflne
ICMP_REDmECT_TOSHOST 3
#deflnelCMP_ECHO
8
*define ICMP_TIMXCEED
11
#define
ICMP_TIMXCEED _INTRANS 0
*define
ICMP _TIMXCEED_REASS
1
#deflne ICMP _P ARAMPROB
12
#define ICMP_TSTAMP
13
#define ICMP_TSTAMPREPLY
14
#define ICMP _mEQ
15
#deflne ICMP_mEQREPL Y
16

Sun Release 1.1

/* echo reply */
/* dest unreachable, codes: */
o
1
2
3
4
5

/*

/*

/*
/*

'*
/*
/*

/*

/*

Last change: 17 August 1983

/*
/*
/*

bad net */
bad host */
bad protocol */
/* bad port */
/* IP_DF caused drop */
/* src route failed */
packet lost, slow down */
shorter route, codes: */
/* for network */
/* for host */
/* for tos and net */
/* (or to8 and host */
echo service */
time exceeded, code: */
/* tt1==O in transit */
/* ttl==O in reass */
ip header bad */
timestamp request */
timestamp reply */
information request */
information reply */

17

ICMP(4P)

SPECIAL Fll.,ES

ICMP( 4P)

Arriving ECHO and TSTAMP packets cause the system to generate ECHOREPL Y and
TSTAMPREPL Y packets. ffiEQ packets are not yet processed by the system, and are discarded.
UNREACH, SOURCEQUENCH, TIMXCEED and P ARAMPROB packets are processed internally by the protocols implemented in the system, or reflected to the user if a raw socket is being
used; see ip(4P). REDffiECT, ECHOREPLY, TSTAMPREPLY and ffiEQREPLY are also
reflected to users of raw sockets. In addition, REDffiECT messages cause the kernel routing
tables to be updated; see routing(4N).
SEE ALSO

inet(4F), ip(4P)
Internet Control Message Protocol, RFC792, J. Postel, USC-lSI (Sun 800-1064-01)
BUGS

IREQ messages are not processed properly: the address flelds are not set.
Messages which are source routed are not sent back using inverted source routes, but rather go
back through the normal routing mechanisms.

18

Last change: 17 August 1983

Sun Release 1.1

IF( 4N)

IF (4N)

SPECIAL FILES

NAME
if - general properties of network interfaces
DESCRIPTION
Each network interface in a system corresponds to a path through which messages may be sent
and received. A network interface usually has a hardware device associated with it, though certain interfaces such as the loopback interface, 10(4), do not.
At boot time each interface which has underlying hardware support makes itselC known to the
system during the autoconfiguration process. Once the interface has acquired its address it is
expected to inst.all a routing table entry so that messages may be routed through it. Most interfaces require some part of their address specified with an SIOCSIF ADDR ioctl before they will
allow traffic to flow through them. On interfaces where the network-link layer address mapping is
static, only the network number is taken from the ioctl; the remainder is found in a hardware
specific manner. On interfaces which provide dynamic network-link layer address mapping facilities (e.g. 10Mb's Ethernet! using orp(4P),), the entire address specified in the ioctl is used.
The following ioctl calls may be used to manipulate network interfaces. Unless specified otherwise, the request takes an ifreq structure as its parameter. This structure has the form
struct

'*

*'

ifreq {
char
itr_name(16J;
name of in,terrace (e.g. "ecO")
union {
struct sockaddr ifru:.....addr;
struct sockaddr itru_dstaddr;
short itru_flap;
} ifr_itru;
ifr_ifru.ifru_addr
'define ifl_addr
address
ifr_ifru.irru_dstadrlr
*define ifr_dstaddr
other end of p-to-p link
ifr_ifru.ifrujlags
=f/:define ifrJlag.
flags
};

'''*** *' *'

*'

SIOCSIF' ADDR
Set interface address. Following the address assignment, the "initialization" routine for
the interface is called.
SIOCGIFADDR
Get interface address.
SIOCSIFDSTADDR
Set point to point address for interface.
SIOCGIFDSTADDR
Get point to point address for interface.
SIOCSIFli'LAGS
Set interface flags field. If the in.terface is marked down, any processes currently routing
packets through the interrace are notified.
SIOCGIFFLAGS
Get interface flags.
SIOCGIFCONF
Get interface configuration list. This request takes an ifconf structure (see below) as a
value-result parameter. The ifc_Ien field should be initially set to the size of the buffer
pointed to by ifc_buf. On return it will contain the length, in bytes, of the configuration
. list.

'*

• Structure used in SIOUGIFCONF request.
• Used to retrieve interface configuration

SUD Release 1.1

Last change: 15 August 1983

19

SPECIAL FILES

IF (4N)

IF( 4N)

* for machine (useful for programs which
* must know all networks accessible).

*'

struct

ifconf {
int
ifc_Ien;
'* size of associated buffer *'
union {
caddr_t ifcu_buf;
struct ifreq *ifcu_req;
} ifc_Hcu;
#define ifc_bur ifc_ifcu.ifcu_buf '* buffer address *'
#deflne ifc_req ifcjfcu.ifcu_req '* array of structures returned *'
};

SEE ALSO

arp(4P), ec(4S), en(4S), 10(4)

20

Last change: 15 August 1983

Sun Release 1.1

SPECIAL FILES

INET( 4F)

INET( 4F)

NAME
inet - Internet protocol family
SYNOPSIS

option. INET
p.eudo-devlee lnet
DESCRIPTION
The Internet protocol family is a collection of protocols layered atop the Internet Protocol (IP)
transport layer, and qtilizing the Internet address format. The Internet family provides protocol
support for the SOCK_STREAM, SOCK.J)GRAM, and SOCK_RAW socket types; the
SOCK_RAW interfaee~.provides access to the IP protocol.
ADDRESSING
Internet addresses are four byte quantities, stored in network standard format (on the VAX these
are word and byte reversed). The include file  defines this address as a discriminated union.

Sockets in the Internet protocol family utilize the following addressing structure,
strud sockaddr_in{
short sin_family;
u_short sin-port;
struct in_addr sin_addr;
char
siD_zeroIS);

};
(Library routines to return and manipulate structures of this form are in section 3N of the
manual; see intro(aN) and the other section 3 entries mentioned under SEE ALSO below.) Each
socket has a local addr~ss specifiable in this form, which can be established with bind(2); the getBocknGme(2) call returns this address. Each socket also may be bound to a peer socket with an
address specified in this :form; this peer address can be specified in a connect(2) call, or transiently
with a single message in a 8endto or 8endm81 call; see 8end(2). The peer address of a socket is
returned by the geepeernGme(2) call.
The sin_addr field of the socket address specifies the Internet address of the machine on which the
socket is located. .A special value may be specified or returned for this field,
l!Iin_addr.I!Laddr===INADDR~NY. This address is a "wildcard" and matches any of the legal
internet addresses on the local machine. This address is useful when a process neither knows (nor
cares) what the local Internet address is, but even more useful (or server processes with which to
service aU requests to. the current machine. Since a machine can have several addresses (one per
hardware network interface), specifying a single address would restrict acceSs to the service to
those clients which spei!ified the address of that interface. By specifying INADDR_ANY, the
server can arrange to service clients from all interfaces.'
When a socket address is bound, the networking system checks that there is an interface with the
address specified available on the current machine (unless) of course, a wildcard address is
specified), and retumsan error EADDRNOTAVAll., if no such intedaceisCound.
The local port address specified in a bind(2)· ·call is restricted to be greater than
IPPORT_RESERVED (=1024, in . The
ICMP, TCP, UDP and ND protocols are processed internally by the system; others may be
accessed through a raw socket by doing:

==

8
8ocket(AF_INET, SOCK_RAW, IPPROTO_xxx);
Datagrams sent from this socket will have the current host's address and the specified protocol
number; the raw IP driver will construct an appropriate header. When IP datagrams are received
for this protocol they are queued on the raw socket where they may be read with recvfrom; the
source IP address is reflected in the received address.
SEE ALSO

send(2), recv(2), inet(4F}
Internet Protocol, RFC791, USC-lSI {Sun 800-1063-01)·
BUGS

One should be able to send and receive IP options.
Raw sockets should receive ICMPerror packets relating to the protocol; currently 8uch packets
are simply discarded.

SUD

Release 1.1

Last change: 17 August 1983

25

SPECIAL FILES

IP (4S)

IP (4S)

NAME

ip - Disk driver for Interphase 2180 S:MD Disk Controller
SYNOPSIS

controller lpeO at mbO ear Ox40 priority Z
disk IpO at IpeO drive 0
disk Ipl at IpeG drive I
DESCRIPTION

Files with minor device numbers 0 through 7 refer to various portions of drive 0; minor devices 8
through 15 refer to drive 1, and 80 on. The standard device names begin with "ip" followed by
the drive number and then a letter a-h for partitions 0-7 respectively. The character ? stands
here for a drive number in the range 0-7.
The block file's access the disk via the system's normal buffering mechanism and may be read and
written without regard to physical disk records. There is also a 'raw' interface which provides for
direct transmission between the disk and the user's read or write buffer. A single read or write
call results in exactly one I/O operation and therefore raw I/O is considerably more effflcient
when many words are transmitted. The names of the raw files conventionally begin with an extra

'r.'
In raw I/O counts should be a multiple of 512 bytes (a disk sector). Likewise Beek calls should
specify a multiple of 512 bytes.
DISK SUPPORT

This driver handles all SMD drives, by reading a label from sector 0 of the drive which describes
the disk geometry and partitioning.
The ip?a partition is normally used for the root file system on a disk, the ip?b partition as a paging area, and the ip?c partition for pack-pack copying (it normally maps the entire disk). The
rest of the disk is normally the ip?h partition.
FILES

/dev /ip(0-7](a-hJ
/dev /rip[0-7](a-h)

block flies
raw flies

SEE ALSO

dkio(4S), xy(4S)
"Interphase SMD2180 Storage Module Controller/Formatter - User's Guide" (Sun 800-0274)
DIAGNOSTICS
Ip%d: SMD-2180. When booting tells the controller type.

Ip%d: Inltlallzatlon failed. Because the controller didn't respond; perhaps another device is at
the address the system expected an Interphase controller at.
lp%d: errol' %x readlns label
information.

OD

head %d. Error reading drive geometry/partition table

Ip%d: Corrupt label on head %d. The geometry/partition label checksum was incorrect.
Ip%d: Miaplaeed label on head %d. A disk label was copied to the wrong head on the disk;
shoudn't happen.
Ip%d: Un8upported phy8 partition
Ip%d: unit not onHne.

=1/=

%d. This indicates a bad label.

Ip%d%e: cmd how (meg) blk %d. A command such as read, write, or format encountered a
error condition (bow): either it failed, the unit was restored, or an operation was rdrlled. The
msg is derived from the error number given by the controller, indicating a condition such as
"drive not ready", "sector not found" or "disk write protected".

26

Last change: 20 March 1984

Sun Release 1.1

IF( 4S)

SPECIAL FILES

IP (4S)

BUGS
In raw I/O read and write(2) truncate file offsets to 512-byte block boundaries, and write scribbles
on the tail or incomplete blocks. Thus, in programs that are likely to access raw devices, read,
write and Iseek(2) should always deal in 512-byte multiples.
The driver no longer supports versions or the 2181.

Sun Release 1.1

Last change: 20 March 1984

27

KB(4S)

SPECIAL FILES

KB( 4S)

NAME

kb - Sun keyboard
SYNOPSIS
pseudo-device kb3
DESCRIPTION

Kb provides access to the Sun workstation keyboard translation. Definitions lor a1terring keyboard translation are in  and .
The call KIOCTRANS controls the presence of keyboard translation:

int x;
err == ioct1(fd, KIOCTRANS, &x);
where if z is 0 the keyboard tranlation is turned off and up/down key codes are reported. Specifying z as 1 restores normal keyboard translations.
.
The call KIOCSETKEY changes a keyboard translation table entry:
/

-~

struct

kiockey {
int
kio_tablemask;
u_char kio_station;
u_char kio_entry;
char
kio_string(10);

/* Translation table (one of: 0,

CAPSMASK,
SHIFTMASK, CTRLMASK, UPMASK) */
/* Physical keyboard key station (0-127) */
/* Translation table station'8 entry */
/* Value for STRING entries (null terminated)

*/

};
struct kiockey key;
err == ioctl(fd, KIOCSETKEY, &key);
Set 1cio_tablema8k table's kio_station to kio_entru. Copy kio_string to string table if kio_entru is
between STRING and STRING+ 15. This call may return EINVAL il there are invalid arguments.
The call KIOCGETKEY determines the current value 01 a keyboard translation table entry:
struct kiockey key;
err == ioct1( fd, KIOCGETKEY, Ilkey);
Get kio_tablema8k table's kio_Blation to kio_entru. Get kio_Blring from string table if no_entry is
between STRING and STRING+ 15. This call may return EINVAL il there are invalid arguments.
FILES

/dev/kbd
SEE ALSO

kbd(5)

28

Last change: 21 March 1984

SUD

Release 1.1

LO( 4N)

SPECIAL FILES

LO(4N)

NAME

10 - software loopback network interface
SYNOPSIS
paeudo-devlce loop
DESCRIPTION
The loop device is a software loopback network interface; see iJ(4N) for a general description of
networ~ interfaces.
The loop interface is used for performance analysis and software testing, and to provide
luaranteed acce811 to Internet protocols on machines with no local network interfaces. A typical
application is the comlot(8C). server which accepts notification of mail delivery through a particular port on the loopback interface.
By derault, the loopback interrace is accessible at Internet address 127.0.0.1 (non-standard); this
addre811 may be changed with the SIOCSIF'ADDR ioctl.
DIAGNOSTICS
lo"dl can't bandle ~d. The intedace was handed a message with addresses formatted in an
unsuitable address ramily; the packet was dropped.
SEE ALSO
it(4N), inet(4F)
BUGS
It should handle all addresl and protocol ramilies. An approved network address should be
reserved tor this interface.

Sun Release 1.1

Last change: 17 August 1983

29

SPECIAL FILES

MB( 4S)

M8(4S)

NAME

mb - Multibus
SYNOPSIS

controller mbO at neXU8

r

DESCRIPTION
The mb device is the driver for the Intel Multibus(R), which provides support functions to the

various devices which can reside there. It vectors interrupts to the Multibus devices according to
the priority level of the interrupt received and queues requests for dma when there are insufficient
resources to service the request or to allow certain dma's to proceed exclusively. It also implements byte swapping to/from deficient devices.
DIAGNOSTICS

None.
SEE ALSO

ar(4S), cg(4S), ip(4S), ms(4S), oct(4S), tm(4S), vp(4S), xy(4S), zS(4S)
Intel Multibus(R) Specification, Order Number 9800683-04 (Sun 800-1057-01)

30

Last change: 11 August 1983

Sun Release 1.1

MEM(4S)

SPECIAL FILES

MEM(4S)

NAME
mem, kmem, mbmem, mbio - main memory and I/O space
SYNOPSIS
None; included with standard system.
DESCRIPTION
These devices are special files that map memory and bus i/o space. They may be read, written,
seek'ed and (except for kmem) mmap(2)ed.
Mem is a special file that is an image of the physical memory of the computer. It may be used,
tor example, to examine (and even to patch) the system.
Kmem is a special file that is an image of the kernel virtual memory of the

~ystem.

Mbmem is a special file that is an image of the Multibusmemory of the system.
memory is in the range from 0 to 1 Megabyte.
Mbio is a special file that is an image
trom 0 to 64K.

ot

Multibus

the Multibu8 I/O space. Multibus I/O space extends

When reading and writing mbmem and mbio odd counts or offsets cause byte accesses and even
counts and offsets cause word accesses.
DIAGNOSTICS
None.
FILES
/dev/mem
/dev/kmem
/devlmbmem
/dev/mbio

Sun Release 1.1

Last change: 11 August 1983

31

MOUSE(4S)

SPECIAL FILES

MOUSE(4S)

NAME

mouse - Sun mouse
SYNOPSIS
pseudo-device ms3
DESCRIPTION

The 'mouse interface provides access to the Sun Workstation mouse.
The mouse incorporates a microproceasor which generates a byte-stream protocol encoding mouse
motions.
Each mouse sample in the byte stream consists of three bytes: the first byte gives the button state
with value Ox87r but, where bu' is the low three bits giving the mouse buttons, where a 0 (zero)
bit means that a button is pressed, and a 1 (one) bit means a button is not pressed. Thus if the
left button is down the value of this sample is Ox83, while if the right button is down the byte is
Ox86.-

The next two bytes of each sample give the % and 11 deltd ts 0/ '''is sample as signed bytes. The
mouse uses a lower-left coordinate system. so moves to the right on the screen yield p06itive %
values and moves down the ecreen yield negative II values.
The beginning of a sample is identifiable because the delta's are constrained to not have values in
the range Ox80-0x87.
FILES

/dev/mouse
SEE ALSO
win(4S1
Mouse System Mouse Manual (Sun 800(0419)
User's Guide for the Sun Workstation Mouse Subsystem (Sun 800-0402)

32

Last change: 21 March 1984

Sun Release 1.1

MTI(.S)

SPECIAL FILES

MTI( 4S)

NAME

mti - Systech MTI-800/1600 multi-terminal interface
SYNOPSIS

device mtlO at mbO ear

oxelo ilap oxmr priority "

DESCRIPTION
The Systech MTI card provides 8 (MTI-800) or 16 (MTI-1600) serial communication lines with
modem control. Each line behaves as described in ttU(4}. Input and output for each line may
independentlY be set to run at any 01 16 speeds; see tty(4) for the encoding.

Bit i 01 8ags may be specified to say that a line is not properly connected, and that the line i
should be treated as hard-wired with carrier always present. Thus specifying "8ags OxOO04" in
the specification of mtiO would cause line tty02 to be treated in this way.
To allow a single tty line to be connected to a modem and used for both incoming and outgoing
calls, a special feature, controlled by the minor device number, has been added. Minor device
numbers in the range 0 - 127 correspond directly to the normal tty lines and are named tt1l*.
Minor device numbers in the range 128 - 256 correspond to the same physical lines as those above
(i.e. the same line as the minor device number minus 128) and are (conventionally) named cua·.
The CUG lines are special in that they can be opened even when there is no carrier on the line.
Once a CUG line is opened, the corresponding tty line can not be opened until the cua line is
closed. Also, if the ttu line has been opened successfully (usually only when carrier is recognized
on the modem) the corresponding CUG line can not be opened. This allows a modem to be
attached to I devlttyOO (usually renamed to I devlttydO) and used for dialin (be enabling the line
for login in I etcl tty,) and also used for dialout (by tip(IC) or uucp(IC)) as I devl cuaO when no one
is logged in on the line. Note that the bit in the 8ags word in the config file (see above) must be
zero for this line.
WIRING
The Systech requires the CTS modem control signal to operate. It the device does not supply
CTS then RTS should be jumpered to CTS at the distribution panel. Also, the CD (carrier
detect) line does not work properly. When connecting a modem, the modem's CD line should be
wired to DSR, which the software will treat as carrier detect.
FILES

Idev IttyO[0-9a-~ hardwired tty lines
Idev Ittyd[0-9a-fJ dialin tty lines
Idev Icua[o-9a-~ dialout tty lines
SEE ALSO
tty(.), zs(.8)
DIAGNOSTICS
Most 01 these diagnostics IIshould never happen" and their occurrence usually indicates problems
elsewhere in the system.

mtl%d,%dl aUo overflow. More than 512 characters have been received by the mti hardware
without being read by the software. Extremely unlikely to occur.
mtl%dl error %x. The mti returned the indicated error code. See the mti manual.
mtl%dl DMA output error. The mti encountered an error while trying to do DMA output.
mtl%d:lmposslble response %x. The mti returned of 8ags may be specified to say that a line
is not From martyQufo Sat Feb 25 16:04:52 1984

SUD Release 1.1

Last change: 16 February 1984

33

MTIO( 4)

SPECIAL FILES

MTIO(4)

NAME
mtio - UNIX magnetic tape interface
SYNOPSIS

#include 
#include 
DES C R.lPTI ON

The files mtOl .. " milS refer to the UNIX magtape drives., which read and write magnetic tape in
2048 byte blocks. (The 2048 ia actually BLKDEV_IOSIZE in .) The following
description applies to- any of the transport/controller pairs. The files mlOI •••, mtS and mt8, •.. ,
mill are rewound when closed; the others are not. When a file open for writing is closed, two
end-of-files are written. If the tape is not to be. rewound it is positioned with the head between
the two tapemarka.
The m' files discussed above are useful when it is desired to access the tape in a way compatible
with ordinary flies. When foreign tapes are to be dealt with, and especially when long records are
to be read or written, the Crawl interlace is appropriate. The associated files are named rmtO, ...,
rmttS,. but the same minor-device considerations as tor tile regular files still apply. A number or
other ioctl operations are available on raw magnetic tape. The following definitions are trom
< sys/mtiO.h> :-

,** Structures and definitions for mag tape io control commands

*'

/* structure ror MTIOCTOP - mag tape op command *'
struct

mtop {
short mt_op;
daddr_t mt_count;

};

'*

*'

operations
#deflne MTWEOF
#define MTFSF
#define MTBSF
#define MTFSR
#define MTBSR
:fI:define MTREW
#define MTOFFL
#define MTNOP

'*

o
1
2
3
4

5
6

7

'* operations defined below */

'*

''**

'''***
''**

'*

how many of them

*'

*'*' *'
*'*'

write an end-of-file record
forward space file
backward space file
forward space record
backward space record

*'

**J

rewind
rewind and put the drive oMine
DO operation, sets status only J

structure for MTIOCGET - mag tape get status command

*J

struct

'*

'*
'*

'*
};

34

mtget {
short mt_type;
/* type of magtape device */
the rollowing two registers are grossly device dependent J
short mt_dsreg;
"drive status" register
short mt_erreg;
"error" register J
end device-dependent registers
short mt_resid;
residual count
the rollowing two are not yet implemented */
daddr_t mt_ftleno;
'* file number or current position */
daddr_t mt_blkno;
block number or current position
end not yet implemented

''***'
'*

*
*'
*
*'

*' '*

Last change: 20 March 1984

*J
Sun Release 1.1

SPECIAL FILES

MTIO(4)

'**
*'

MTIO( 4)

Constants ror mt_type byte

#define MT_ISTS
#define MT_ISHT
#deftne MT_ISTM
#define MT_ISMT
#define MT_ISUT
#define MT_ISCPC
*define MTJSAR

'*

OxOl
OX02
Ox03
Ox04
OX05
Ox06
Ox07

'*

,. vax: unibus ts-ll .,

*'

vax: massbus tu77, etc
,. vax: unibus tm-I1·,
,. vax: massbu8 tu78 .,
,. vax: unibus gcr
,. sun: Multibus tapemaster ./
/* sun: Multihu8 archive ./

*'

mag tape io control commands ./
fdefine MTIOCTOP
_IOW(m, 1, struct mtop)
#deflne MTIOCGET _IOR(m, 2, struct mtget)

,. do a mag tape op ./
,. get tape status ./

#ifndef KERNEL
#define DEF /pub/bin, /usr/ucb -> /pub/usr/ucb.
One requirement in this case is that the server (who has read/write access to this file system)
should not perform write activity with any public filesystem. This is because each client is locally
cacheing blocke.
One last type of unit is provided for use by the server,. These are called local units and are
named / dev/ ndl*. The Sun physical disk sector 0 label only provides a limited number ot partitions per physical disk (eight). Since this number is small and these partitions have somewhat
fixed meanings, the nd driver itselt has a Bubpartitioning capability built-in. This allows the large
server physical disk partition (e.g. / dev/ zyOg ) to be broken up into any number ot diskless client
partitions. Of course on the client side these would be referenced as / dev/ndO,l, ... ; but the
server needs to reference these client partitions from time to time, to do mk/B(8) and /Bck(8) for
example. The I dev/ ndl* entries allow the server 'local' access to his sUbpartitions without causing
any net activity. The actual local unit number to client unit number correspondence is again
recorded in the / etc/ nd.local text file.
The nd device driver is the same on both the client and server sides. There are no user level
processes associated with either side, thus the latency and transfer rates are close to maximal.
The minor device and ioctl encoding used is given in file < Bun/ ndio.h >. The low six bits of the
minor number are the 'unit number. The Ox40 bit indicates a public unit; the OxSO bit indicates a
local unit.
INITIALIZATION
No special initialization is required on the client side; he finds the server by broadcasting the initial request. Upon getting a response, he locks onto that server address.

At the server, the nd(8c) command initializes the network disk service by issuing ioctl's to the
kernel.

36

Last change: 20 March 1084

Sun Release 1.1

SPECIAL FILES

ND( 4P)

ND( 4P)

ERRORS
Generally physical disk 10 errors detected at the server are returned to the client (or action. If
the server is down or unaccessable, the client will see the console message Jile 8erver not re8ponding: 8till trging. The client continues (forever) making his request until he gets positive acknowledgement from the server. This means the server can crash or power down and come back
up without any special action required of the user at the client machine. It also means the pr~
cess performing the 10 to nd will block, insensitive to signals, since the process is sleeping inside
the kernel at PRmIO~
PROTOCOL AND DRIVER INTERNALS
The protocol packet is defined in <8un/ndio.h> and also included below:

'**

'nd' protocol packet format.

*'

.truct ndpaek {
.truct Ip np_Ip,
u_char np_op,
u_char np__mln,
char np_error,
char np~ver,
Ions np_••cu
Ions np_blknoJ
Ions np_bcount.
Ions np_relld.
Ions np-.caddr.
Ions np_ccount,

'*

np_op operation eode••
*define NDOPREAD
*defln. NDOPWRITE
*deflne NDOPERROR
rldeflne NDOPCODE
#deflne NDOPWAIT
#deflneNDOPDONE

'*

mIIc protocol deflne•••,
#deftne NDMAXDATA
#deftne NDMAXIO

*'

'''***
'''***
''**
'''***
'*

*' *'

Ip header, proto IPPROTO_ND
operation code, lee below
mlnor device
b_error
ver.lon number
.equence number
b_blkno, dllk block number
b_beount, byte count
b_re.ld, realdual byte count
current byte off.et of thll packet
current byte count of tht. packet
data foUow.

1
1
3
'I
010
010

*' *' *'
*'

*' *'*'
*'*'
*'

''** *'*'
'* *'

''**
'*

read
write
error
op code mask
waiting for DONE or next requeat
operation done

'* '*

10Z4
13*1014

*'
*'

*'

*'*'

max data per packet
max np_bcount

IP datagrams were chosen instead of UDP datagrams because only the IP header is checksummed,
not the entire packet as in UDP, Also the kernel level interface to the IP layer is simpler. The
min, blleno, and bcount fields are copied directly from the client's strategy request. The sequence
number field Bell is incremented on each new client request and is matched with incoming server
responses. The server essentially echos the request header in his responses, altering certain fields.
The coddr and ccount fields show the current byte address and count of the data in this packet, or
the data expected to be sent by the other side.
The protocol is very simple and driven entirely from the client side. As soon as the client ndstra,.
tegy routine is called, the request is sent to the server; this allOW8 disk 80rting to occur at the
server as 800n as possible. Transactions which send data (client writes on the client side, client
reads on the server side) can only send a set number of packets of NDMAXDATA bytes each,
before waiting for an acknowledgement. The defaults are currently set at 6 packets of lK bytes
each; the NDIOCETHER ioctl allows setting this value on the server side. This allows the

Sun

Rele~

1.1

Last change: 20 March 1984

37

ND( 4P)

SPECIAL FILES

ND( 4P)

normal 4K byte case to occur with just one 'transaction'. The NDOPWAIT bit is set in the op
field by the sender to indicate he will send no more until acknowledged (or requested) by the
other side. The NDOPDONE bit is set by the server side to indicate the request operation has
completed; for both the read and write cases this means the requested disk 10 has actually
occured.
Requests received by the server are entered on an active list which is timed out and discarded if
not completed within NDXTIMER seconds. Requests received by the server allocate a 6coun' size
buffer to minimize buffer copying. Contiguous DMA disk 10 thus occurs in the same size chunks
it would if requested from a local physical disk.
BOOTSTRAP

The Sun workstation has PROM code to perform a net boot using this driver. Usually, the boot
files are obtained from public device 0 (/dev /ndpO) on the server with which the client is
registered; this allows mUltiple servers to exist on the same net (even running different releases of
kernel and boot sortware). If the station you are booting is not registered on any or the servers,
you will have to specify the hex Internet host number or the server in the boot command string
(e.g.): 'bec(O,S,O)vmunix'.
This booting perrorms exactly the same steps involved in a real disk boot which are:
1)

user types 'b' to PROM monitor.

2)
3)
4)

PROM loads blocks 1 thru 15 or /dev /ndpO (bootpr).
bootnd loads '/boot'.
/boot loads '/vmunix'.

SEE ALSO

ioctl(2), nd(8C)
BUGS

The operations described in dkio(4) are not supported.
The local host's disk buffer cache is not used by network disk access. This means that if either a
local host or a remote host is writing, the changes will be visible at random based on the cache hit
frequency on the local host. If both the local and remote hosts are writing to the same filesystem,
one machine's changes can be randomly lost, based again on cache hit and deferred write timings.
If an R/O remote file system is mounted R/W by mistake, it is impossible to umount it.

38

Last change: 20 March 1984

SUD

Release 1.1

NULL ( 4)

SPECIAL FILES

NULL (4)

NAME

null -datasink
SYNOPSIS
.None;includedwith standard system.
DESCRIPTION
Data written on a null special file is discarded.
Reads from a null ;specialfilealways return an end-of.:.file indication.
FILES
/dev/null

SunRele~
L

1.1

Last change: 17 August 1983

39

SPECIAL FILES

OCT(4S)

OCT(4S)

NAME

oct. - Central Data octal serial card
SYNOPSIS

devlee octO at mbO cal' OxitO flag. Ox. priority"
DESCRIPTION
The Central Data card provides 8 serial communication lines with modem control. Eaeh line
behaves as described in ttU{4}. Input and output Cor each liDe may independently- be set to run at
any of 16~ speeds; see tty(4) for the eDcodilll~.

Bit i of BaiS may be spe.cifIed to say that a line is Bot properly connected, and that the line i
shou,ld be treated as hard-wired with carrier always present. .Thus specifying Hllap OxOOO4n in
the specification of odO would cause line "ym2 to be treated in this way ~

FILES

Jd.vfttyfmnotro.-tll... fl
/dev IttrlllO-9~rr

SEE ALSO

ttyC4}, zs(4Sl
Hardware Reference Manual; Octal Serial Interface; Central Data Corporation (Sun 800(0418)
DIAGNOSTICSNone.

BUGS
Input data overruns are silently ignored.
This interrupt-per..character, non..buffered device is expensive in terDll

ot system overhead.

This driver is not supported.

40

Last change: 11 August 1983

Sun Release 1.1

PTY( 4)

SPECIAL FILES

PTY( 4)

NAME
pty - pseudo terminal driver
SYNOPSIS
pseudo-device pty
DESORIPTION
The ptg driver provides support for a pair of devices collectively known as a peeudo-terminal.
The two devices comprising a pseudo-terminal are known asa maeter and a elave. The slave device provides an interface identical to that described in ttll(4), but instead of having a hardware
interface such as the Zilog chip and associated hardware used by ze( 4S) supporting the terminal
functions, the functions of the terminal are implemented by another process manipulating the
master side of the pseudo-terminal.

The master and the slave sides of the pseudo-terminal are tightly connected. Any data written on
the master device is given to the slave device as input, as though it had been received from a
hardware interface. Any data written on the slave terminal can be read from the master device
(rather than being transinitted from a UART).

In configuring, if no optional "count'; is given in the specification, 16 pseudo terminal pairs are
configured.
A· few special ioctl's are provided on the control-side devices of pseudo-terminals to provide the
functionality needed by applicationsprogtams to emulate real hardware interfaces:
TIOCSTOP
Stops output to a terminal (that is, like typing "S). Takes no parameter.
TIOCSTART
Restarts output (stopped by TIOCSTOP or by typing "Q). Takes no parameter.
There are also two independent modes which can be used by applications programs:
TIOCPKT
Enable/disable packet mode. Packet mode is enabled by specifying (by reference) a
nonzero parameter and disabled by specifying (by reference) a zero parameter. When
applied to the master side of a pseudo terminal, each subsequent read from the terminal
will return data written on the slave part of the pseudo terminal preceded by a zero byte
(symbolicallydeftned as TIOCPKT_DATA), or a single byte reflecting control status
information. In the latter case, the byte is an inclusive-or of zero or more of the bits:
TIOCPKT_FLUSHREAD
whenever the read queue for the terminal is flushed.
TIOCPKT_FLUSHWRITE
whenever the write queue for the terminal is flushed.
TIOCPKT_STOP'
whenever 6utput to the terminal is stopped ala "S.

TIOCPKT_START
whenever output to the terminal is restarted.
TIOCPKT_DOSTOP
whenever '-etope is

"s and '-8tarte is AQ.

TIOCPKT_NOSTOP
whenever the start and stop characters are not "S/"Q.
This mode is used by rlogin(IC) and rlogind(8C) to implement a remote-echoed, locally
"S/"Q flow-controlled remote login with proper back-flushing or output when interrupts
occur; it can be used by other similar programs.
TIO CR EMOTE

Sun Release 1.1

Last change: 20 March 1984

41

SPECIAL FILES

PTY( 4)

PTY( 4)

A mode for the master half of a pseudo terminal, independent of TIOCPKT. This mode
causes input to the pseudo terminal to be flow controlled and not input edited (regardless
of the terminal mode). Each write to the control terminal produces a record boundary for
the process reading the terminal. In normal usage, a write of data is like the data typed
as a line on the terminal; a write of 0 bytes is like typing an end-of-file character.
TIOCREMOTE can be used when doing remote line editing in a window manager, or
whenever flow controlled input is required.
FILES

/dev /pty[p-rll0-9a.-Q
/dev /tty[p-r][0-9a-rJ

master pseudo terminals
slave pseudo terminals

BUGS

It is apparently not possible to send an EOT by writing zero bytes in TIOCREMOTE mode.

42

Last change: 20 March 1984

SUD Release 1.1

ROUTING ( 4N)

SPECIAL FILES

ROUTING ( 4N )

NAME
routing - system supporting for local network packet routing
DESCRIPTION

The network facilities provided general packet routing, leaving routing table maintenance to
applications processes.
A simple set of data structures comprise a "routing table" used in selecting the appropriate network interface when transmitting packets. This table con tains a single entry for each route to a
specific network or host. A user process, the routing daemon, maintains this data base with the
aid of two socket specific ioctl(2) commands, SIOCADDRT and SIOCDELRT . The commands
allow the addition and deletion of a single routing table entry, respectively. Routing table manipulations may only be carried out by super-user.
A routing table entry has the following form, as defined in
struct rtentry {
u_long
struct
struct
short
short
. u_long
struct

< net/route.h>;

rt_hash;
sockaddr rt_dst;
sockaddr rt-lateway;
rt_flags;
rt_refcnt;
rt_use;
ifnet *rt_ifp;

};
with rt...flags defined from,
#defineRTF _UP
f/:define R TF _GATEWAY
#define RTF_HOST

Ox!
Ox2
Ox4

/* route usable * /
/* destination is a gateway * /
/* host entry (net otherwise) */

Routing table entries come in three flavors: for a specific host, for all hosts on a specific network,
for any destination not matched by entries of the first two types (a wildcard route). When the
system is booted, each network interrace autoconfigured installs a routing table entry when it
wishes to have packets sent through it. Normally the interface specifies the route through it is a
"direct" connection to the destination host or network. If the route is direct, the transport layer
of a protocol family usually requests the packet be sent to the same host specified in the packet.
Otherwise, the interface may be requested to address the packet to an entity different from the
eventual recipient (i.e. the packet is forwarded).
Routing table entries installed by a user process may not specify the hash, reference count, use, or
interrace fields; these are filled in by the routing routines. If a route is in use when it is deleted
(r,-re/ent is non-zero), the resources associated with it will not be reclaimed until further references to it are released.
The routing code returns EEXIST if requested to duplicate an existing entry, ESRCH if requested
to delete a non-existant entry, or ENOBUFS if insufficient resources were available to install a
new route.
User processes read the routing tables through the / dev/ kmem device.
The r,-use field contains the number of packets sent along the route. This value is used to select
among mUltiple routes to the same destination. When multiple routes to the same destination
exist, the least used route is selected.
A wildcard routing entry is specified with a zero destination address value. Wildcard routes are
used only when the system fails to find a route to the destination host and network. The combination of wildcard routes and routing redirects can provide an economical mechanism for routing

Sun Release 1.1

Last change: 15 August 1983

43

ROUTING ( 4N)

SPECIAL FILES

ROUTING ( 4N)

traffic.
SEE ALSO

route(8C), routed(8C)

44

Last change: 15 August 1983

SUD

Release 1.1

SD( 4S)

SPECIAL FILES

SD (4S)

NAME
sd - Disk driver Cor Adaptec ST-506 Disk Controllers
SYNOPSIS
controller seD at mbO csr Ox80000 priority 2
disk sdO at leO drive 0 ftagl 0
dlak adl at seD drive 1 flags 0
DESCRIPTION
Files with minor device numbers 0 through 7 refer to various portions oC drive O. The standard
device names begin with "sd" followed by the drive number and then a letter a-h for partitions
0-7 respectively. The character? stands here for a drive number in the range 0-7.

The block file's access the disk via the system's normal buffering mechanism and may be read and
written without regard to physical disk records. There is also a 'raw' interface which provides for
dired transmission between the disk and the user's read or write buffer. A single read or write
call results in exactly one I/O operation and thereCore raw I/O is considerably more effficient
when many words are transmitted. The names of the raw files conventionally begin with an extra

'r.'
In raw I/O counts should be a multiple of 512 bytes (a disk sector). Likewise eeek calls should
specify a multiple of 512 bytes.
DISK SUPPORT
This driver handles all ST-506 drives, by reading a label Crom sector 0 of the drive which
describes the disk geometry and partitioning.

The sd?a partition is normally used for the root file system on a disk, the sd?b partition as a paging area, and the sd?c partition Cor pack-pack copying (it normally maps the entire disk). The
rest or the disk is normally the sd?h partition.
FILES
/dev /sd(0-7)[a-h)
/ dev/ r&d (0-7)[ a-h ]

block files
raw flies

SEE ALSO
dkio(4S)
Adaptec ACB 4000 and 5000 Series Disk Controllers OEM Manual
DIAGNOSTICS
ad%d%ca cmd how (mog) blk %d. A command such as read or write encountered a error condition (bow): either it ffJiled, the unit was reetored, or an operation was retry'ed. The meg is
derived from the error number given by the controller, indicating a condition such as "drive not
ready" or "sector not found".

BUGS
In raw I/O refJd and write(2) truncate file offsets to 512-byte block boundaries, and write scribbles
on the tail of incomplete blocks. Thus, in programs that are likely to access raw devices, refJd,
write and leeek(2) should always deal in 512-byte multiples.

SUD

Release 1.1

Last change: 9 March 1984

45

ST( 4S)

SPECIAL FILES

ST( 4S)

NAME

st - Driver for Sysgen SC 4000 (Archive) Tape Controller
SYNOPSIS

controller scO at mbO csr Ox80000 priority 2
tape stO at scO drive 32 flap 1
DESCRIPTION
The Sysgen tape controller is a SCSI bus interface to an Archive streaming tape drive. It pr~
vides a standard tape interface to the device, see mtio(4), with some deficiencies listed under
BUGS below.
FILES

/dev/rstO
/dev /nrstO

non-rewinding

SEE ALSO
mtio(4), tm(4S)
Sysgen SC4000 Intelligent Tape Controller Product Specification
Archive Intelligent Tape Drive Theory of Operation, Archive Corporation (Sun 8000-1058-01)
Archive Product Manual (Sidewinder 1/4" Streaming Cartridge Tape Drive) (Sun 800-0628-01)
DIAGNOSTICS

st%da tape not onllne.
st%da no cartrldse In drive.
st%da eartrldse la write protected.
BUGS

The tape cannot reverse direction so BSF a.nd BSR are not available.
Disk I/O over the SCSI bus will be mostly blocked out when the tape is in use. This is because
the controller does not free the bus while the ta.pe is in motion (even during rewind).
When using the ra.w device, the number of bytes in any given transfer must be a multiple of 512
bytes. If it is not, the device driver returns an error.

46

Last change: 9 March 1984

SUD

Release 1.1

SPECIAL FILES

TCP( 4P)

TCP (4P)

NAME
tcp - Internet Transmission Control Protocol
SYNOPSIS
None; comes automatically with inet(4F).
DESCRIPTION
TCP is a connection-oriented, end-to-end reliable protocol designed to fit into a layered hierarch
of protocols which support multi-network applications. TOP provides for reliable inter-process
communication between pairs of processes in host computers attached to distinct but interconnected computer communication networks. Very few assumptions are made as to the reliability
of the communication protocols below TCP layer. TOP assumes it can obtain a simple, potentially unreliable datagram service from the lower level protocols. In principle, TOP should be
able to operate above a wide spectrum of communication systems ranging from hard-wired connections to packet-switched or circuit switched networks.
TOP fits into a layered protocol architecture just above the basic Internet Protocol (IP) described
in ip(4P) which provides a way for TCP to send and receive variable-length segments of information enclosed in Internet datagram "envelopes." The Internet datagram provides a means for
addressing source and destination TCPs in different networks, deals with any fragmentation or
reassembly of the TCP segments required to achieve transport and delivery through multiple
netwokrs and interconnecting gateways, and has the ability to carry information on the precedence, security classification and compartmentalization of the TOP segments (although this is
not currently implemented under UNIX.)
An application process interfaces to TCP through the socket(2) abstraction and the related calles
bind(2), listen(2), occept(2), connect(2), send(2) and recv(2}. The primary purpose of TCP is to
provide a reliable bidirectional virtual circuit service between pairs of processes. In general, the
TCP's decide when to block and forward data at their own convenience. In the UNIX implementation, it is assumed that any buffering of data is done at the user J~vel, ~,nd the TCP's transmit
available data as soon as possible to their remote peer. They do this and always set the PUSH bit
indicating that the transferred data should be made available to the user process at the remote
end as soon as practicable.
To provide reliable data TCP must recover from data that is damaged, lost, duplicated, or
delivered out of order by the underlying internet c~mmunications system. This is achieved by
assigning a sequence number to each byte of data transmitted and requiring a positive acknowledgement from the receiving TCP. If the ACK is not received within an (adaptively determined) tim.eout interval the data is retransmitted. At the receiver, the sequence numbers are
used to correctly order segments that may be received out of order and to eliminate duplicates.
Damage is handled by adding a checksum to each segment transmitted, checking it at the
receiver, and discarding damaged segments. As long as the TCP's continue to function properly
and the internet system does n~,tJ become completely partitioned, no tranmission errors will affect
the correct delivery of data,
t,bp recovers from communications errors.

as

I"~

TCP provides flow control over the transmitted data. The receiving TCP is allowed to specify
the amount of data which may be sent by the sender, by returning a window with every acknowledgement indicating a range of acceptable sequence numbers beyond the last segment successfully received. The window indicates an allowed number of bytes that the sender may
transmit before receiving further permission.
TOP extends the standard 32-bit Internet host addresses with a 16-bit port number space; the
combined addresses are available at the UNIX process level in the standard soc/coddr_in format
described in inet(4F).
Sockets utilizing the tcp protocol are either "active" or "passive". Active sockets initiate connections to passive sockets. By default TCP sockets are created active; to create a passive socket the
listen(2) system call must be used after binding the socket to an address with the hind(2) system

SUD

Release 1.1

Last change: 17 August 1983

47

TCP(4P)

SPECIAL FaES

TCP(4P)

call. Only passive sockets may use the Gccept(2) call to accept incoming connections. Only
active sockets may use the connect(2) call to initiate connections.
Passive sockets may "underspecify" their location to match incoming connection requests from
multiple networks. This technique, termed "wildcard addressing", allows a single server to provide service to clients on multiple networks. To create a socket which listens on all networks, the
Internet address INADDR.-ANY must be bound. The TCP port may still be specified at this
time; if the port is not specified the system will assign one. Once a connection has been established the socket's address is fixed by the peer entity's location. The address assigned the
socket is the address associated with the network interface through which packets are being
transmitted and received. Normally this address corresponds to the peer entity's network. See
inet(4F) for a complete description of addressing in the Internet family.
A TCP connection is created at the server end by doing a 8ocket(2), a 6ind(2) to establish the
addre88 of the socket, a li8ten(2) to cause connection queueing, and then an Gccept(2) which
returns the descriptor for the socket. A client connects to the server by doing a 8ocket(2} and
then a connect(2}. Data may then be sent from server to client and back using read(2} and
write(2).
TCP implements a very weak out-or-band mechanism, which may be invoked using the out-ofband provisions of 8end( 2}. This mechanism allows setting an urgent pointer in the data stream;
it is reflected to the TCP user by making the byte after the urgent pointer available as out-ofband data and providing a SIOCATMARK ioctl which returns an integer indicating whether the
stream is at the urgent mark, The system never returns data across the urgent mark in a single
read. Thus when a SIGURG signal is received indicating the presence of out-of-band data and
the out-of-band data indicates that the data to the mark should be flushed (as in remote terminal
processing) it suffices to loop checking whether you are at the out-of-band mark, and reading data
while you are not at the mark.
SEE ALSO
inet(4F), ip(4P)

BUGS
It should be possible to send and receive TCP options.

The system always tries to negotiates the maximum. TCP segment size to be 1024 bytes. This
can result in poor performance if an intervening network performs excessive fragmentation.
SIOCSHIWAT and SIOCGHIWAT ioctl's to set and get the high water mark for the socket
queue, and so that it can be changed from 2048 bytes to be larger or smaller, have been defined
(in  :

Last change: 17 August 1983

Sun Release 1.1

TTY(4)

SPECIAL FILES

atruc:t agtty b
char
char
char
char
ahort
};

TTY ( 4)

{
IIs_tapeed;
IIs_oapeecl;

lis_vue,
IIs_kUl;
as_fla.B;

The s,_"speed and su_ospeed fields describe the input and output speeds of the device according to
the following table, which corresponds to the DEC DH-ll interface. If other hardware is used,
impossible speed changes are ignored. Symbolic values in the table are as defined in < sgtty.h> .
BO
BOO
B75
BIIO
B134

Bl50
B200
B300
B600
B1200
B18CO
B2400
B4800
BOOOO
EXTA
EXTB

0
I
2

3
4
5
6
7
8
9
10
11
12
13
14
15

(hang up dataphone)
50 baud
75 baud
110 baud
134.5 baud
150 baud
200 baud
300 baud
600 baud
1200 baud
1800 baud
2400 baud
4800 baud
9600 baud
External A
External B

In the current configuration, only 110, 150, 300 and 1200 baud 1\re really supported on dial-up
lines. Code conversion and line control required for mM 2741's (134.5 baud) must be implemented by the user's program. The half-duplex line discipline required for the 202 dataset (1200
baud) is not supplied; full-duplex 212 dataseta work fine.
The su_erose and sg_leill fields of the argument structure specify the erase and kill characters
respectively. (Defaults are DELETE and AU.)
The sg.Jlags field 'lIthe argument structure contains several bits that determine the system's
treatment of the terminal:
ALLDELAY 0177400 Delay algorithm selection
BSDELAY 0100000 Select backspace delays (not implemented):
BSO
0
BSI
0100000
VTDELAY 0040000 Select form-feed and vertical-tab delays:
FFO
0
FFI
0100000
CRDELAY 0030000 Select carriage-return delays:
CRO
0
CRt
0010000
CR2
0020000
CR3
0030000
TBDELAY 0006000 Select tab delays:
TABO
0
T ABI
0001000
T AB2
0004000
XTABS
0006000

Sun Release 1.1

Last change: 17 August 1983

55

SPECIAL FILES

TTY(4)

TTY(4)

NLDELAY 0001400 Select new-line delays:

NLO
NLI
NL2
NL3
EVENP
ODDP
RAW
CRMOD
ECHO
LCASE
CBREAK
TANDEM

o
0000400
0001000
0001400
0000200 Even parity allowed on input (most terminals)
0000100 Odd parity allowed on input
0000040 Raw mode: wake up on all characters, 8-bit interface
0000020 Map CR into LF; echo LF or CR as CR-LF
0000010 Echo (full duplex)
0000004 Map upper case to lower on input
0000002 Return each character as soon 88 typed
0000001 Automatic flow control

The delay bits specify how long transmission stops to allow for mechanical or other movement
when certain characters are sent to the terminal. In all cases a value of 0 indicates no delay.
Backspace delays are currently ignored but might be used for Terminet 300's.

It a form-feed/vertical tab delay is specified, it lasts for about 2 seconds.
Carriage-return delay type 1 lasts about .08 seconds and is suitable for the Terminet 300. Delay
type 2 lasts about .16 seconds and is suitable for the VT05 and the TI700. Delay type 3 is suit,.
able for the concept,.l00 and pads lines to be at least 9 characters at 9600 baud.
New-line delay type 1 is dependent on the current column and is tuned for Teletype model 37's.
Type 2 is useful for the VT05 and is about .10 seconds. Type 3 is unimplemented and is O.
Tab delay type 1 is dependent on the amount of movement and is tuned to the Teletype model
37. Type 3, called XTABS, is not a delay at all but causes tabs to be replaced by the appropriate
number of spaces on output.
Input characters with the wrong parity)
and CBREAK mode. '

88

determined by bits 200 and 100, are ignored in cooked

RAW disables all processing save output flushing with LFLUSHO; full 8 bits of input are given as
soon as it is available; all 8 bits are passed on output. A break condition in the input is reported
as a null character. If the input queue overflows in raw mode it is discarded; this applies to both
new and old drivers.
CRMOD causes input carriage returns to be turned into new-lines; input of either CR or LF
causes LF-CR both t!) be echoed (for terminals with a new-line function).
CBREAK is a sort of half-cooked (rare?) mode. Programs can read each character as soon as
typed, instead of waiting for a full line; all processing is done except the input editing: character
and word erase and line kill, input reprint, and the special treatment of \ or EOT are disabled.
TANDEM mode causes the system to produce a stop character (default AS) whenever the input
queue is in danger of overflowing l and a start character (default AQ) when the input queue has
drained sufficiently. It is useful for flow control when the 'terminal' is really another computer
which understands the conventions.
Basic ioctm
In additidn to the TIOCSETD and TIOCGETD disciplines discussed in Line dlselpDnee above, a
large number of other ioctl(2) calls apply to terminals, and have the general form:

#lnelude 
loetl(ftldes, code, arg)
struet sgtty b *arg;

56

Last change: 17 August 1983

Sun Release 1.1

SPECIAL FILES

TTY(4)

TTY ( 4)

The applicable codes are:
TIOCGETP
Fetch the basic parameters associated with the terminal, and store in the
pointed-to sgttgb structure.
TIOCSETP

Set the parameters according to the pointed-to sgttyb structure. The interface
delays until output is quiescent, then throws away any unread characters, before
changing the modes.

TIOCSETN

Set the parameters like TIOCSETP but do not delay or flush input. Input is not
preserved, however, when changing to or lrom RA W.

With the lollowing codes the arl is ignored.
TIOCEXCL
Set "exclusive-use" mode: no lurther opens are permitted until the file has been
closed..
TIOCNXCL
TIOCHPCL

Tum 01 "exclusive-use" mode.
When the file is closed lor the last time, hang up the terminal. This is useful
wheD the line is associated with an ACU used to place outgoing calls.

TIOCFLUSH

All characters waiting in input or output queues are flushed.

The remaining calls are not available in vanilla version 7 UNIX. In cases where arguments are
required, they are described; arl should otherwise be given as O.
the argument is the address of a character which the system pretends was typed
TIOCSTI
on the terminal.
TIOCSBRK

the break bit is set in the terminal.

TIOCCBRK
TIOCSDTR

the break bit is cleared.
data terminal ready is set.

TIOCCDTR

data terminal ready is cleared.

TIOCGPGRP

arg is the address of a word into which is placed the process group number of the
control terminal.
arg is a word (typically a process id) which becomes the process group for the
control terminal.
returns in the long integer whose address is arg the number ol immediately readable characters from the argument unit. This works lor files, pipe!, and terminals.

TIOCSPGRP
FIONREAD

The second structure associated with each terminal specifies characters that are special in both
the old and new terminal interlaces: The following structure is defined in , which is
automatically included in· < sgt tg. h> :

.t.. uct tch....
cha..
cha..
cha..
char
cha..
cha..

{
t_Intrcl
t_qultcl
t_startci
t_stopcl
t_eofeJ
t_b..kcJ

/* Inte.... upt */
/* quit */
/* start output */
/* stop output */
/ * end-of-file */
/ * Input deUmlte.. (Uke nl) */

}J
The delault values for these characters are "C, A', "Q, "S, AD, and -1. A character value of -1
eliminates the effect of that character. The Cbrkc character, by default -1, acts like a new-line in
that it terminates a 'line,' is echoed, and is passed to the program. The 'stop' and 'start' characters may be the same, to produce a toggle effect. It is probably counterproductive to make other

Sun Release 1.1

Last change: 17 August 1983

57

TTY ( 4)

SPECIAL FILES

TTY(4)

special characters (including erase and kill) identical. The applicable ioctl calls are:
TIOCGETC Get the special characters and put them in the specified structure.
TIOCSETC Set the special characters to those given in the structure.
Local mode
The third structure associated with each terminal is a local mode word; except for the
LNOHANG bit, this word is interpreted only when the new driver is in use. The bits of the local
mode word are:
LCRTBS
LPRTERA
LCRTERA
LTILDE

LMDMBUF
LLITOUT
LTOSTOP
LFLUSHO
LNOHANG
LETXACK
LCRTKll..,
LCTLECH
LPENDIN
LDECCTQ

000001
000002
000004
000010
000020
000040
000100
000200
000400
001000
002000·
010000
020000
040000

Backspace on erase rather than echoing erase
Printing terminal erase mode
Erase character echoes as backspace-space-backspace
Convert - to ' on output (for Hazeltine terminals)
Stop/start output when carrier drops
Suppress output translations
Send SIGTTOU for background output
Output is being flushed
Don't send hangup when carrier drops
Diablo style butler hacking (unimplemented)
BS-space-BS erase entire line on line kill
Echo input control chars as AX, delete as A1
Retype pending input at next read or input character
Only AQ restarts output after AS, like DEC systems

The applicable ioctl functions are:
TIOCLBIS

arg is the address of a mask which is the bits to be set in the local mode word.

TIOGLBIC

arg is the address of a mask or bits to be cleared in the local mode word.

TIOCLSET

arg is the address of a mask to be placed in the local mode word.

TIOCLGET

arg is the address of a word into which the current mask is placed.

Local special chan
The final structure associated with each terminal is the leehors structure which defines interrupt
characters (or the new terminal driver. Its structure is:

Itruct ltcharl
char
char
char
char
char
char

{
t_SUJPC;
t_dsuspc;
t_rprntcI
t_flushe;
t_werasc;
t_Inexte;

'''***
''**
'*

*' *'
*' *'
*' *'

stop proeess signal
delayed atop proeell Ilgnal
reprint llne
flush output (toggles)
word erase
nteral next eharacter

The default values for these characters are AZ, Ay, "R, "0, AW, and
the character.

"v. A value of -1 disables

The applicable ioetl functions are:
TIOCSL TC args is the address o( a ltehors structure which defines the new local special characters.
TIOCGLTC args is the address of a ltehors structure into which is placed the current set of local
special characters.

58

Last change: 17 August 1983

Sun Release 1.1

TTY(4)

SPECIAL FILES

TTY ( 4)

FILES

/dev/tty
/dev/tty·
/ dev / console
SEE ALSO
cah(l), sttY(I), ioctl(2), sigvec(2), stty(3C), getty(8), init(8)

BUGS
Halt-duplex terminals are not supported.

SUD

Release 1.1

Last change: 17 August 1983

59

UDP( 4P)

SPECIAL FILES

UDP( 4P)

NAME

udp - Internet User Datagram Protocol
SYNOPSIS
None; comes automatically with inet( 4F).
DESCRIPTION
The User Datagram Protocol (UDP) is defined to make available a datagram mode 01 packet
switched computer communicaton in the environment 01 an interconnected set 01 computer networks. The protocol assumes that the Internet Protocol (IP) as described in ip(4P) is used as the
underlying protocol.

The protocol provides a procedure lor application programs to send messages to other programs
with ~a minimum 01 protocol mechanism. The protocol is transaction oriented, and delivery and
duplicate protection are not guaranteed. Applications requiring ordered reliable delivery 01
streams 01 data should use the Transmi88ion Control Protocol (TCP) as described in tcp(4P).
The UNIX implementation 01 UDP makes it available as a socket 01 type SOCK_DGRAM. UDP
sockets are normally used in a connection less lashion, with the ,endto and recvJrom calls described
in send(2) and recv(2).
A UDP socket is created with a 'Dcket(2) call:

• == .octet(AF_INET, SOCK_DGRAM, 0).
The socket initially has no address associated with it, and may be given an address with a bind(2)
call as described in inet(4F). II no hind call is done, then the address a88ignment procedure
described in inet(4F) is repeated as each datagram is sent.
When datagrams are· sent the system encapsulates the user supplied data with UDP and IP
headers. Unless the invoker is the super-user data,rams which would become broadcast packets
on the network to which they are addressed are not allowed. Unless the locket has had a
SO_DONTROUTE option enabled (see 'Dcket(2» the outgoin, datagram is routed through the
routing tables as described in routing( 4N). It there is insufficient system buffer space to temporarily hold the datagram while it is being trasmitted, the ,endtD may result in a ENOBUFS
error. Other errors (ENETUNREACH, EADDRNOTAVAIL, EACCES, EMSGSIZE) may be generated by icmp(4P) or by the network interlaces themselves, and are reflected back in the ,end
call.
each UDP datagram arrives at a host the system strips out the IP options and checksums the
data field, discarding the datagram it the checksum indicates that the datagram has been damaged. II no socket exists for the datagram to be sent to then an IC:MP error is returned to the
originating socket. If a socket exists tor this datagram to be sent to, then we will append the
datagram and the address trom which it came to a queue associated with the datagram socket.
This queue has limited capacity (2048 bytes 01 datagrams) and arriving datagrams which will not
fit within its high-water capacity are silently discarded.
At,

UDP processes ICMP errors reflected to it by icmp(4P). QUENCH errors are ignored (this is well
considered a bug); UNREACH, TIMXCEED and P ARAMPROB errors cause the socket to be
disconnected Irom its peer it it was bound to a peer using 6ind(2) so that subsequent attempts to
send datagrams via that socket will give an error indication.
The UDP datagram protocol differs trom IP datagrams in that it adds a cllecksum over the data
bytes and contains, a 16-bit socket address on each machine rather than just the 32-bit machine
address; UDP datagrams are addressed to sockets; IP packets are addressed to hosta.
SEE ALSO
recv(2), send(2), inet(4F)
"User Datagram Protocol", RFC768, John Postel, USC-lSI (Sun 800-1054-01)

60

Last change: 17 August 1983

Sun Release 1.1

UDP( 4P)

SPECIAL FILES

UDP( 4P)

BUGS
SIOCSHIWAT and SIOCGHIWAT ioctl's to set and get the high water mark tor the socket
queue, and so that it can be changed trom 2048 bytes to be larger or smaller, have been defined
(in  and use the ioctl(2) call
ioctl(f, VSETSTATE, plotmd);
where plotmd is defined to be

lnt plotmd[) == { VPLOT, 0, 0 };
When going back into print mode from plot mode you normally eject paper by sending it an EOT
after putting into print mode:
lnt prtmd[) = { VPRINT, 0, 0 };
fflush(vp );
ioctl(f, VSETSTATE, prtmd);
write(f, "\04", 1);
FILES

/dev/vpO
SEE ALSO
Multibus/Versatec Interface, Ikon Corp (Includes Versatec Manual) (Sun 800-1065-(1)

BUGS
If you use the standard i/o library on the Versatec, be sure to explicitly set a buffer using Betbu/,
since the library will not use buffered output by default, and will run very slowly.
This driver is not supported.

Writes must start on even byte boundaries and be an even number of bytes in length.

62

Last change: 11 August 1983

Sun Release 1.1

SPECIAL FaES

VPC( 4S)

VPC( 4S)

NAME
vpc - Systech VPC-2200 Versatec printer/plotter and Centronics printer interface
SYNOPSIS
device vpcOat mbO car Ox480 priority· 2
DESCRIPTION
The Sun Multibus interface to the Versatec printer/plotter and to Centronics printers is supported by the Systech parallel interface board, an output-only byte-wide DMA device. The device
has one channel for Versatec devices and one channel for Centronics devices, with an optional
long lines interface for Versatec devices.
Devices attached to this interface are normally handled by the line printer spooling system and
should not be accessed by th~ user directly.
Opening the devices / dev/ vpO / dev/ IpO may yield one or two errors: ENXIO indicates that the
device is already in use. EIO indicates that the device is omine.
The Versatec printer/plotter operates in either print or plot mode. To set the printer into plot
mode you should include  and use the ioct/(2) call:
ioctl(f, VSETSTATE, plotmd);
where plotmd is defined to be
tnt plotmd[ I = { VPLOT, 0, 0 };
When going back into print mode from plot mode you normally eject paper by sendi_g it an EOT
after putting into print mode:
tntprtmd[ I == {VPRINT, 0, 0 };
fflush (v pc );
ioctl(f, VSETSTATE, prtmd);
write(t, "\04", 1);
FILES
/dev/vpO
/dev/lpO
SEE ALSO
Systech vPC-2200 Versatec Printer/plotter Controller Technical Manual
BUGS

It you use the standard I/O library on the Versatec, be sure to explicitly set a buffer using setbu/,
since the library will not use buffered output by default, and will run very slowly.
Currently only 8 bit I/O is supported in the driver, even though the device supports 16 bit I/O.

Sun Release 1.1

Last change: 6 January 1984

63

WIN( 4S)

SPECIAL

F~ES

WIN ( 4S)

NAME

win - Sun window system
SYNOPSIS
pseudo-device wlnlZ8
pseudo-device dtop4
DESCRIPTION

The win device accesses the system drivers supporting the Sun window system.
Each window in the system is represented by a /dev twin· device. The windows are organized as
a tree with windows being subwindows of their parents, and covering/covered by their siblings.
Each window has a position in the tree, a position on a display screen, an input queue, and information telling what parts of it are exposed.
The window driver multiplexes keyboard and mouse input among the several windows, tracks the
mouse with a cursor on the screen, provides each window access to information about what parts
of it are exposed, and notifies the manager process for a window when the exposed area of the
window changes so that the window may repair its display.
The dtop4 pseudo device line in a kernel configuration file indicates the number of separate
"desktops" (frame buffers) that can be actively running the Sun window system at once.
Full information on the window system functions is given in the Programmer's R e/erence Manual
lor Sun Windows.
FILES

/dev /win(0-9)
/dev /win(0-9)(0-9)
SEE ALSO

Programmer's Re/erence Manual/or SunWindows

64

Last change: 21 March 1984

Sun Release 1.1

XY(4S)

SPECIAL FILES

XY( 4S)

NAME

xy - Disk driver for Xylogics S:MD Disk Controllers
SYNOPSIS

eontroller xyeO at mbO ear Oxee40 priority 2
disk xyO at xyeO drive 0
disk xyl at xyeO drive 1
DESCRIPTION
Files with minor device numbers 0 through 7 refer to various portions of drive 0; minor devices 8
through 15 refer to drive 1, and so on. The standard device names begin with "xy" followed by
the drive number and then a letter a-h for partitions 0-7 respectively. The character! stands
here fo~ a drive number in the range 0-7.

The block file's access the disk via the system's norma.l buffering mechanism and may be read and
written without regard to physical disk records. There is also a 'raw' interface which provides for
direct transmission between the disk and the user's read or write buffer. A single read or write
call results in exactly one I/O operation and therefore raw I/O is considerably more effficient
when many words are transmitted. The names of the raw files conventionally begin with an extra

'r.'
In raw I/O counts should be a multiple of 512 bytes (a disk sector). Likewise seek calls should
specify a multiple of 512 bytes.
DISK SUPPORT
This driver handles ail SMD drives, by reading a label from sector 0 of the drive which describes
the disk geometry and partitioning.

The xy!a partition is normally used for the root file system on a disk, the xy!b partition as a paging area, and the xy!c partition for pack-pack copying (it normally maps the entire disk). The
rest of the disk is normally the xy!h partition.
FILES

/dev /xy(0-7](a.-h)
/dev /rxy[0-7][ ..h}

block files
raw flies

SEE ALSO
dkio{4S), xy(4S)
Xylogics Model 440 Peripheral Processor SMD Disk Subsystem Maintenance and Reference
Manual (Sun 800-1005-01)
Xylogics Model 450 Peripheral Processor SMD Disk Subsystem Maintenance and Reference
Manual (Sun 800-102&-01)
DIAGNOSTICS

xye%ds lelf telt error %x - %1. Self test error in controller, see the Maintenance and Reference Manual
xye%da addr•• mode Jumper 11 wronll. The controller is strapped for 24-bit Multibus
addresses; the Sun uses 2O-bit addresses. See the Hardware Configuration and Expansion section
of the System Manager's Manual for your Sun Workstaiton Cor instructions on setting the jumpers
on the 450.
xyattaebl ean't Bet bad seetor Info. The bad sector rorwarding inrormation for the disk,
which is kept on the last cylinder, could not be read.
xy%d. drive type %d elub wltb xy%d. The 450 does not support mixing the drive types
found on these units on a single controller.
xy%da lnltlallzatloD falled.

Sun Release 1.1

Last change: 11 August 1983

65

XY( 45)

SPECIAL FILES

XY(4S)

xy%dz error %x reading label on head %d. Error reading drive geometry/partition table
information.
xy%dl Corrupt label. The geometry/partition label checksum was incorrect.
xy%dl Unsupported phys partition

*

%d.

xy%d: oftUne.
x)'%d%e: cmd how (mag) blk %d. A command such as read, write, or format encountered a
error condition (how): either it Jailed, the unit was reBtored, or an operation was retrlled. The
mBI is derived from the error number given by the controller, indicating a condition such as
"drive not ready", "sector not found" or "disk write protected"'.

BUGS
In raw I/O read and write(2) truncate file offsets to 512-byte block boundaries, and write scribbles
on the tail of incomplete blocks. Thus, in programs that are likely to access raw devices, read,
write and IBeek(2) should always deal in 512-byte multiples.

66

Last change: 11 August 1983

Sun Release 1.1

ZS (4S)

SPECIAL FILES

ZS (4S)

NAME

zs - zilog 8530 SCC serial comunications driver
SYNOPSIS
device .aO at mbO car Oxt5aOOO flaga 3 priority G
DESCRIPTION
The Zilog 8530 provides 2 serial communication lines with full modem control. Each line behaves
as described in tty(4). Input and output for each line may independently be set to run at any of
16 speeds; see tty( 4) for the encoding.
FILES

/dev /ttyla-d)
SEE ALSO
tty(4)
Zilog Z8030/Z8530 SCC Serial Communications Controller (Sun 800-1052-01)
DIAGNOSTICS
z.%d%cl aUo overflow. The character input silo overflowed before it could be serviced.

SUD

ReleasA 1.1

Last change: 11 August 1983

67

A.OUT(5)

A.OUT( 5)

NAME

a.out - assembler and link editor output
SYNOPSIS

#lnclude 
#lnclude <.tab.h>
#lnclude 
DESCRIPTION

A.out is the output file of the assembler 08(IS) and the link editor ld(I). The latter makes o.out
executable if there were no errors and no unresolved external references. Layout inCormation as
given in the include file for the Sun system is:

/*

* Header prepended to each a.out file.

*/

struct exec {
long
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned

a_magic;
a_text;
a_data;
a_bss;
a_Byms;
a_entry;
a_trsize;
a_drsize;

/* magic number */

/* size of text segment */

/* size of initialized data */
/* size of un initialized data */
/* size of symbol table */
/* entry point */

/* size of text relocation */

/* size of data relocation */

};
#define OMAGIC 0407
#define NMAGIC 0410
#define ZMAGIC 0413

/* old impure format */
/* read-only text * /

/* demand load format */

#define PAGSIZ 2048
#define SEGSIZ Ox8000
#define TXTREL OC SEGSIZ

/*

* Macros which take exec structures as arguments and tell whether
* the file has a reasonable magic number or offsets to text Isymbols Istrings.

*/.,

#define NJ3ADMAG(x) \
(((x).aJDagic)!=O~GIC &&

((x).a_magic)!=NMAGIC && ((x).a_magic)!=ZMAGIC)

#define N_TXTOFF(x) \
((x).a_magic==ZMAGIC 1 P AGSIZ : sizeof (struct exec))
:fI:define N_SYMOFF(x) \
(N_TXTOFF(x) + (x).a_text+ (x).a_data + (x).a_trsize+ (x).a_drsize)
:f/:define N_STR OFF(x) \
(N_SYMOFF(x) + (x).a_syms)

/*

* Macros which take exec structures as arguments and tell where the
* various pieces will be loaded.
*/

#define N_TXTADDR(x) TXTRELOC
#define N_DATADDR(x) \
(((x).a_magic==OMAGIC)? (N_TXTADDR(x)+ (x).a_text) \
: (SEGSIZ+ ((N_TXTADDR(x)+ (x).a_text-l) & -SEGRND)))

Sun Release 1.1

Last change: 15 January 1983

1

A.OUT(5)

FILE FORMATS

A.OUT( 5)

#define N_BSSADDR(x) (N_DATADDR(x)+ (x).a_data)
The a.out file has five sections: a header,the program text and data, relocation information, a
symbol table and a string table (in that order). The last three may be omitted il the program was
loaded with the '-s' option of ld or if the symbols and relocation have been removed by strip(l).
In the header the sizes of each section are given in bytes. The size of the header is not included
in any of the other sizes.
When an a.out file is executed, three logical segments are set up: the text segment, the data segment (with uninitialized data, which starts off as
0, follOWing initialized data), and a stack.
The header is not loaded with the text segment. If the magic number in the header is OMAGIC
(0407), it means that this is a non-sharable text which is not to be write-protected, 80 the data
segment is immediately contiguous with the text segment. This is rarely used. If the magic
number is NMAGIC (0410) or ZMAGIC (0413), the data segment begins at the first segment
boundary following the text segment, and the text segment is not writable by the program; other
processes executing the same file will share the text segment. For ZMAGIC format, the text segment begins on a page boundary in the a.out file; the remaining bytes after the header in the first
block are reserved and should be zero. In this case the text and data sizes must both be multiples
of the page size, and the pages of the file will be brought into the running image as needed, and
not pre-loaded as with the other formats. This is especially suitable for very large programs and
is the default format produced by Id(l). The macros N_TXTADDR, N_DATADDR, and
N_BSSADDR give the core addresses at which the text, data, and bss segments, respectively, will
be loaded.

all

The stack starts at the highest possible location in the memory image, and grows downwards.
The stack is automatically extended as required. The data segment is extended as requested by
6rk(2) or 86rk(2).
Arter the header in the file follow the text, data, text relocation data relocation, symbol table and
string table in that order. The text begins at byte PAGSIZ in the file for ZMAGIC format or just
arter the header for the other formats. The N_TXTOFF macro returns this absolute file position
when given the name of an exec structure as argument. The data segment is contiguous with the
text and immediately followed by the text relocation and then the data relocationinlormation.
The symbol table fonows all this; its position is computed by the N_SYMOFF macro. Finally,
the string table immediately follows the symbol table at a position which can be gotten easily
using N_STROFF. The first 4 bytes of the string table are not used for string storage, but rather
contain the size of the string table; this size INCLUDES the 4 bytes, the minimum string table
size is thus 4.
.•.

RELOCATION
The value of a byte in the text or data which is not a portion 01 a reference to an undefined
external symbol is exactly that value which will appear in memory when the file is executed. If a
byte in the text or data involves a reference to an undefined external symbol, as indicated by the
relocation information, then the value stored in the file is an offset from the associated external
symbol. When the file is processed by the link editor and the external symbol becomes defined,
the value of the symbol is added to the bytes in the file.
It relocation information is pre.sent, it amounts to eight bytes per relocatable datum as in the fol-

lowing structure:

'**
*'

F(jrrilat of a relocation datum.

struct relocation_info {
int
r_address;

2

'*

address which is relocated

Last change: 15 January 1983

*'
Sun Release 1.1

FILE FORMATS

A.OUT(S)

unsigned r_symbolnum:24,
r-pcrel:l,
r_length:2,
r_extern:l,
:4;

A.OUT( 5)

'* local symbol ordinal *'
'* was relocated pc relative already *'
'* O=byte, l=word, 2=long *'
'* does not include value of sym referenced *'
'* nothing, yet *'

};
There is no relocation information if a_trsize+ a_drsize==O. If r_extern is 0, then r_symbolnum
is actually a n_type for the relocation (i.e. N_TEXT meaning relative to segment text origin.)

SYMBOL TABLE
The layout of a symbol table entry and the principal flag values that distinguish symbol types are
given in the include file 38 follows:

'*
*'

* Format of a symbol table entry.

struct nlist {
union {
char
*n_name; '* for use when in-memory *'
long
n_strx;
'* index into file string table *'
} n_un;
unsigned char n_type; '* type flag, i.e. N_TEXT etc; see below *'
char
n_other;
short
n_desc; '* see  */
unsigned
n_value; '* value of this symbol (or adb offset) *'
n_desc

'* used internally by Id *'

'*
* Simple values for n_type.
*'
OxO
#define N_UNDF
Ox2
#define N_ABS
Ox4
#define N_TEXT
Ox6
#define N_DATA
Ox8
#define N_BSS
Ox12
#define N_COMM
Oxlf
#deflne N_FN

'*
'*
'*
'*
'*
'*
'*

#deflne N_EXT
#deflne N_TYPE

'* external bit, or'ed in */
'* mask for all the type bits *'

01
Ox Ie

undefined *'
absolute *'
text *'
data *'
bss *'
common (internal to Id) *'
file name symbol *'

'*

* Other permanent symbol table entries have some of the N_STAB bits set.
* These are given in 

*'

#deflne N_STAB

":'UxeO

'* if any of these bits set, don't discard *'

In the tJ.out file a symbol's n_un.D_strx field gives an index into the string table. A n_strx value
of 0 indicates that no name is associated with a particular symbol table entry. The field
D_un.n_name can be used to refer to the symbol name only if the program sets this up using
D_strx aDd appropriate data from the string table. Because or the union in the nlist declaration,
it is impossible in C to statically initialize such a structure. If this must be done (as when using
nliBt(3)) the file  should be included, rather that ; this contains the

SUD Release 1.1

Last change: 15 January 1983

3

FILE FORMATS

A.OUT( 5)

A.OUT(5)

declaration without the union.
If a symbol's type is undefined external, and the value field is non-zero, the symbol is interpreted
by the loader ld as the name of a common region whose size is indicated by the value of the symbol.

STAB SYMBOLS
Stall.h defines some values or the n_type field of the symbol table 01 a.out files. These are the
types for permanent symbols (that is, not local labels, etc.) used by the debuggers adll(lS) and
dbz(l) and the Berkeley Pascal compiler pe(l). Symbol table entries can be produced by the
.stabs assembler directive. This allows one to specify a double-quote delimited name, a symbol
type, one char and one short of information about the symbol, and an unsigned long (usually an
address). To avoid having to produce an explicit label for the address field, the .8tabd directive
can be used to implicitly address the current location. II no name is needed, symbol table entries
can be generated using the .stalln directive. The loader promises to preserve the order of symbol
table entries produced by .8tab directives.
The n_value field or a symbol is relocated by the link editor as an address within the appropriate
segment. N_value fields or symbols not in any segment are unchanged by the linker. In addition,
the linker will discard certain symbols, according to rules of its own, unless the n_type field has
one of the bits masked by N_ST AB set.
This allows up to 112 (7 * 16) symbol types, split between the various segments. Some of these
have already been claimed. The debugger, adb(lS), uses the following n_type values:

''**
''**
''**
''**
'''***
''**
''**
'''***
'*

*' *'
*'*'*'
*'*' *'
*' *' *'
*' *'
*'*'
*'*' *'
*'

#define N_GSYM Ox20
global symbol: name"O,type,O
#define N_FNAME Ox22
procedure name (rT7 kludge): name"O
#define N_FUN
Ox24
procedure:~ name"O,linenumber,address
#define N_STSYM Ox26
static symbol: name"O,type,address
#define N_LCSYM Ox28
.Icomm symbol: name"O,type,address
#define N_RSYM Ox40
register sym: name"O,type,register
#define N_SLINE Ox44
src line: O"O,linenumber,address
#define N_SSYM Ox60
structure elt: name"O,type,struct_offset
#define N_SO
Ox64
source file name: namellO,O,address
#define N_LSYM Ox80
local sym: name"O,type,offset
fldefine N_SOL
Ox84
#included file name: name"O,O,address
#define N_PSYM OxaO
parameter: name"O,type,offset
#define N_ENTRY Oxa4
alternate entry: name,linenumber,address
#define N_LBRAC OxcO
left bracket: OllO,nesting level, address
#define N,.RBRAC OxeO
right bracket: O"O,nesting level,address
#define N_BCOMMOxe2
begin common: name"
#define N_ECOMMOxe4
end common: name"
#define N_ECOML Oxe8
end common (local name): "address
#define N_LENG Oxfe
second stab entry with length information
where the comments give the adb conventional use for .8tabs and the n_name, n_other, n_desc,
and n_value fields of the given n_type. Adb uses the n_desc field to hold a type specifier in the
form used by the Portable C Compiler, ee(l), in which a base type is qualified in the following
structure:
struct desc {
short q6:2,
q5:2,
q4:2,
q3:2,
q2:2,
q1:2,

4

Last change: 15 January 1983

Sun Release 1.1

A.OUT( 5)

FILE FORMATS

A.OUT(5)

basic:4;

};
There are four qualifications, with ql the most significant and q6 the least significant:
o
none
1
pointer
2
function
3
array
The sixteen basic types are assigned as follows:
o
undefined
1
function argument
2
character
3
short
4
int
5
long
6
float
7
double
8
structure
9
union
10
enumeration
11
member of enumeration
12
unsigned character
13
unsigned short
14
unsigned int
15
unsigned long

'*

The Berkeley Pascal compiler, pc(I), uses the following n_type value:

*'

#define N_PC Ox30
global pascal symbol: name"O,subtype,line
and uses the following subtypes to do type checking across separately compiled files:
1
source file name
2
included file name
3
global label
4
global constant
5
global type
global variable
6
7
global function
8
global procedure
9
external function
10
external procedure
11
library variable
12
library routine
The new dbz(l) debugger uses an entirely different interpretation for the stabs symbol-table
entries. Currently, this is understood only by dbz and cc, but its use should supplant the current
interpretation as soon as adb and pc can be modified to use it.
SEE ALSO

adb(lS), 38(lS), Id(l); nm(l), dbx(l), strip(l)

BUGS
There are currently two interpretations of the stabs symbol-table information. This creates great
confusion when trying to build a program for debugging.
Due to the amount of symbolic information necessary for high-level debugging, the whole a.out
structure has been streched well beyond its original design, and should be replaced by something
with a more sophisticated symbol-table mechanism. The demands of future languages will only

Sun Release 1.1

Last change: 15 January 1983

5

A.OUT( 5)

FILE FORMATS

A.OUT(5)

compound the problems.

6

Last change: 15 January 1983

Sun Release 1.1

FILE FORMATS

ALIASES ( 5)

ALIASES ( 5)

NAME
aliases - aliases file for sendmail

SYNOPSIS
lusl" IDbl aliases
I USI" I libI aliases.dlr
IusI' IlIbl alIases.paS
DESCRIPTION
These files describe user id aliases used by / usr/lib/sendmail. / usr/lib/ aliase8 is formatted as a
series of lines of the form
. name: name_I, name2, name_3, ...
The name is the name to alias, and the name_n are the aliases for that name. Lines beginning
with white space are continuation lines. Lines beginning with':#' are comments.
Aliasing occurs only on local names. Loops can not occur, since no message will be sent to any
person more than once.
After aliasing has been done, local and valid recipients who have a ".forward" file in their home
directory have messages forwarded to the list of users defined in that file.

/ usr/lib/ aliases is only the raw data file; the actual aliasing information is placed into a binary
format in the files/usr/lib/aliases.dir and /usr/lib/aliases.pag using the program newaliase8(8). A
neWalit1.Se8 command should be executed each time that /usr/lib/aliase8 is changed for the change
to take elect.
Several kinds of name!s are special:
owner-mary: fred
any errors resulting from a mail to mary are directed to fred instead of back to the person
who sent the message. This is most useful when mary is a mailing list rather than an
individual.
beer: :include: lusf / cyndi/beer;

All colonB and semicolons are required as shown. The list of names in / usr/ cyndi/ beer is
included in the name_n list for the beer alias, in addition to any other names in the
name_n list. This mechanism is for setting up a mailing list so that / usr/lib/ alia8es
doesn't have to be changed when people are added to or removed from the list. The
included file (that is, / usr/ cyndi/ beer in this case) may be changed at any time, and
changes take effect immediately.

SEE ALSO
newaliases(8), dbm(3X), sendmail(8)
SENDMJ\IL Installation and Operation Guide.
SEND~iAIL An Internetwork Mail Router.

BUGS
Because of restrictions in dbm(3X) a single alias cannot contain more than about 1000 bytes of
information. You can get longer aliases by "chaining"; that is, make the last name in the alias be
a dummy name which is a continuation alias.

Sun Release 1.1

Last change: 3 January 1984

7

FILE FORMATS

AR(5)

AR(5)

NAME

ar - archive (library) file format
SYNOPSIS

#lnelude 
DESCRIPTION

The archive command or combines several files into one. Archives are used mainly as libraries to
be searched by the link-editor Id.
A file produced by or has a magic string at the start, followed by the constituent files, each preceded by a file header. The magic number and header layout as described in the include file are:
/*

O(#)ar.h 1.1 83/08/01 SMI; from UCB 4.1 83/05/03*/

#define ARMAG "! \n"
#define SARMAG 8
#define ARFMAG "'\n"
struct ar_hdr {
char
char
char
char
char
char
char
};

ar_name[16);
ar_date[12);
ar_uid[6);
ar~id[6);

ar_mode(8);
ar_size(10);
ar_fmag[2);

The name is a blank-padded string. The orJmog field contains ARFMAG to help verify the pre&ence of a header. The other fields are left-adjusted, blank-padded numbers. They are decimal
except for or_mode, which is octal. The date is the modification date of the file at the time of its
insertion into the archive.
Each file begins on a even (0 mod 2) boundary; a new-line is inserted between files if necessary.
Nevertheless the size given reflects the actual size of the file exclusive of padding.
There is no provision for empty areas in an archive file.
The encoding of the header is portable across machines. If an archive contains printable files, the
archive itself is priDt~ble.
SEE ALSO

ar{l), Id(l), nm{l)

BUGS
File names lose trailing blanks. Most software dealing with archives takes even an included blank
as a name terminator.

8

Last change: 15 January 1983

Sun Release 1.1

CORE(S)

FILE FORMATS

CORE( 5)

NAME
core - format of memory image file
SYNOPSIS
#lnelude 
DESCRIPTION

The UNIX System writes out a memory image of a terminated process when any of various errors
occur. See 8igvec(2) for the list of reasons; the most common are memory violations, illegal
instructions, bus errors, and user-generated quit signals. The memory image is called 'core' and is
written in the process's working directory (provided it can be; normal access controls apply).
The maximum size of a core file is limited by 8etrlimit(2). Files which would be larger than the
limit are not created.
Set-user-id programs do not produce core files when they terminate as this would be a security
loophole.
The core file consists of the u. area, whose size (in pages) is defined by the UP AGES manifest in
the < machine/ ptJram.h > file. The u. area starts with a U8er structure as given in
< 8118/ u8er.h >. The remainder of the core file consists first of the data pages and then the stack
pages or the proce88 image. The amount or data space image in the core file is given (in pages) by
the variable U_d8ize in the u. area. The amount or stack image in the core file is given (in pages)
by the variable u_B8ize in the u. area.
SEE ALSO
adb(l), dbx(l), sigvec(2), setrlimit(2)

Sun

Rele~

1.1

Last change: 9 March 1984

CPIO( 5)

FILE FORMATS

CPIO (5)

NAME

cpio - format of cpio archive
DESCRIPTION

The old format, header structure, when the e option is not used, is:

atruet {
ahort h_magic,
h_dev,
h_ino,
h_mode,
h_uid,
h..gid,
h_nlink,
h_rdev,
h_mtime[2],
h_namesize,
h_filesizeI2J;
ehar h_namelh_namesize rounded to a word];
} Hdr;
but note that the byte order here is that of the PDP-II and the VAX, and that for the Sun you
have to use 8wab(3) after reading and before writing headers.
When the e option is used, the header information is described by the statement below:
s8canf( Chdr "%60%60%60%60%60%60%60%60%1110%60%60%s",
&Hdr.h_magic, &Hdr.h_dev, &Hdr.h_ino, &Hdr.h_mode,
&Hdr.h_uid, &Hdr.h..gid, &Hdr.h_nlink, &Hdr.h_rdev,
&Hdr.h_mtime, &Hdr.h_namesize, &Hdr.h_filesize, &Hdr.h_name);
I

Longtime and LongfiJe are equivalent to Hdr.h_mtime and Hdr.hJUe8ize, respectively. The contentB of each file is recorded in an element of the array of varying length structures, archive,
together with other items describing the file. Every instance of h_magic contains the constant
070707 (octal). The items h_dev through h_mtime have meanings explained in 8tat(2). The
length or the null-terminated path name h_name, including the null byte, is given by h_name8ize.
The last record or t.he archive always contains the name TRAILER!!!. Special files, directories,
and the trailer, are recorded with hJile8ize equal to zero.
SEE ALSO

cpio(l), find(I), stat(2)

10

Last change: 8 February 1983

Sun Release 1.1

FILE FORMATS

CRONTAB(5)

CRONTAB( 5)

NAME
crontab - table of times to run periodic jobs
DESCRIPTION
The I etcl cron utility is a permanent process, started by I etcl rc.local, that wakes up once every
minute. I etcl cron consults the file I uerllibl crontab to find out what tasks are to be done, and at
what time.
Each line in I uerllibl crontab consists of six fields, separated by spaces or tabs, as follows:
1.

minutes field, which can have values in the range 0 through 59.

2.

hours field, which can have values in the range 0 through 23.

3.

day of the month, in the range 1 through 31.

4.

month of the year, in the range 1 through 12.

5.

day of the week, in the range 1 through 7. Monday is day 1 in this scheme of things.

6.

(the remainder of the line) is the command to be run. A percent character in this field is
translated to a new-line character. Only the first line (up to a % or end of line) of the
command field is executed by the Shell. The other lines are made available to the command as standard input.

Any of fields 1 through 5 can be a list of values separated by commas. A field can be a pair of
numbers separated by a hyphen, indicating that the job is to be done for all the times in the
specified range. If a field is an asterisk character (*) it means that the job is done for all possible
values of the field.
FILES
lusr/lib/crontab
SEE ALSO
cron(8), rc(8)
EXAMPLE

o 0 * * * calendar 150 * * * letc/sa -5 > /dev Inull

15 4 • • • find lusr/preserve -mtime + 7 -a -exec rm -f {} ;
404 * • * find I-name 'f/:*' -atime + 3 -exec rm -f {} ;

0,15,30,45 * * * • letc/atrun
0,10,20,30,40,50 • • • * letc/dmesg - > >/usr/adm/messages
5 4 * * * sh I etc I new5yslog
The calenJar command run at minute 0 of hour 0 (midnight) of every day. The letcl8a command
runs at 15 minutes after midnight every day. The two find commands run at 15 minutes past
four and at 40 minutes past four, respectively, every day of the year. The atrun command (which
processes shell scripts users have set up with at) runs every 15 minutes. The I etcl dme8g command appends kernel messages to the I uerl adml me8sages file every ten minutes, and finally, the
/ uar/ admlellelog script runs at five minutes after four every day.

Sun Release 1.1

Last change: Zl October 1983

11

Dffi(5)

FILE FORMATS

Dffi(5)

NAME

dir - rormat or directories
SYNOPSIS

#lne1ude 
#lnelude 
DESCRIPTION

A directory behaves exactly like an ordinary file, save that no user may write into a directory.
The ract that a file is a directory is indicated by a bit in the flag word or its i-node entry; see
/8(5). The structure of a directory entry as given in the include file is:

,.

• A directory consists of some number or blocks or DmBLKSIZ
• bytes, where DmBLKSIZ is chosen such that it can be transferred
• to disk in ill single atomic operation (e.g. 512 bytes on most machines) .

•

•
•
•
•
•
•
•

•

Each DmBLKSIZ byte block contains some number or directory entry
structures, which are or variable length. Each directory entry has
a struct direct at the front of it, containing its inode number,
the length of the entry, and the length or the name contained in
the entry. These are followed by the name padded to a 4 byte boundary
with null· bytes. All names are guaranteed null terminated.
The maximum length or a name in a directory is MAXNA:MLEN .

•
•
•
•
•
•
•

The macro DIRSIZ(dp) gives the amount or space required to represent
a directory entry. Free space in a directory is represented by
entries which have dp->d_reclen > DmSIZ(dp). All DmBLKSIZ bytes
in a directory block are claimed by the directory entries. This
usually results in the last entry in a directory having a large
dp->d_reclen. When entries are deleted from a directory, the
space is returned to the previous entry in the same directory
41 block by increasing its dp->d_reclen. It the first entry of
• a directory block is rree, then its dp->d_ino is set to o.
• Entries other than the first in a directory do not normally have
• dp->djno set to o.

.
/

=Rifdef KERNEL
#define nffiBLKSIZ DEV_BSIZE
#else
#define DffiBLKSIZ 512
#endif

,.

#define MAXNA:MLEN 255

• The DffiSIZ macro gives the minimum record length which will hold

* the directory entry. This requires the amount of space in struct direct
* without the d_name field, plus enough space ror the name with a terminating
* null byte (dp->d_lrlamlen+ 1), rounded up to a 4 byte boundary.

*'

#under DffiSIZ
#define DIRSIZ(dp)
struct

12

((sizeof (struct direct) - (MAXNA:MLEN+ 1)) + (((dp)->d_namlen+ 1 + 3~

direct {

Last change: 15 January 1983

Sun Release 1.1

Dffi(5)

Fll.,E FORMATS

OIR (5)

u_long
d_ino;
short
d_reclen;
short
d_namlen;
char
d_name[MAXNAMLEN + 1];
/* typically shorter */

};
struct _dirdeec {
int
long
long
char

dd_fd;
dd_Ioc;
dd_size;
dd_buf[OIRBLKSIZ);

};
By convention, the first two entries in each directory are for '.' and ' .. '. The first is an entry for
the directory itself. The second is for the parent directory, The meaning of ' .. ' is modified for
the root directory of the master file system ("/"), where ' .. ' has the same meaning as '.'.
SEE ALSO

fs(5), readdir(3)

SUD

Release 1.1

Last change: 15 January 1983

13

FILE FORMATS

DUMP(5)

DUMP ( 5)

NAME

dump, dumpdates - incremental dump format
SYNOPSIS

#lnclude 
#lnelude < sys/lnode.h>
#lnelude 
DESCRIPTION

Tapes used by dump and reetore(8) contain:
a header record
two groups of bit map records
a group of records describing directories
a group of records describing files
The format of the header record and of the first record of each description as given in the include
file < dumpreBtor.h> is:
#define NTREC
#define ~EN
#define MSIZ

10
16
4096

#define
#define
#define
#define
#define
#define
#define
#define

TS_TAPE
TS_INODE
TS_BITS
TS_ADDR
TS_END
TS_CLRI
MAGIC
CHECKSUM

struct

spcl {
int
time_t
time_t
int
daddr_t
ino_t
int
int
struct
int
char

c_type;
c_date;
c_ddate;
c_volume;
c_tapea;
c_inumber;
c_magic;
c_checksum;
dinode
c_dinode;
c_count;
c_addr(BSIZE);

idates {
char
char
time_t

id_name I16J;
id_incno;
id_ddate;

1
2

3
4
5
6

(int) 60011
(int) 84446

} spcl;
struct

};
#define DUMPOUTFMT

"%-168 %c %s"

#defineDUMPINFMT "%168 %c %(,,\n)\n"

14

1* for print! *1
/* name, inc no, ctime(date) *1
1* inverse for scanf *1

Last change: 15 January 1983

Sun Release 1.1

DUMP(5)

FILE FORMATS

DUMP(5)

NTREC is the default number of 1024 byte records in a physical tape block, changeable by the b
option to dump. MLEN is the number of bits in a bit map word. MSIZ is the number of bit map
words.
The TS_ entries are used in the c_type field to indicate what sort of header this is. The types and
their meanings are as follows:
TS_TAPE
TS_INODE

Tape volume label
A file or directory follows. The c_dinode field is a copy of the disk inode and contains bits telling what sort of file this is.
TS_BITS
A bit map follows. This bit map has a one bit for each inode that was dumped.
TS..,ADDR
A sub record of a file description. See c_tJddr below.
TS_END
End of tape record.
TS_CLRI
A bit map follows. This bit map contains a zero bit for all inodes that were empty
on the file system when dumped.
All header records have this number in c_mtJgic.
MAGIC
CHECKSUM Header records checksum to this value.
The fields of the header structure are as follows:
c_type
c_date
c_ddate
c_volume
c_t ape a
cjnumber
cJDagic
c_checksum
c_dinode
c_count
c_addr

The type of the header.
The date the dump was taken.
The date the file system was dumped from.
The current volume number of the dump.
The current number of this (1024-byte) record.
The number of the inode beinl dumped if this is of type TS_INODE.
This contains the value MAGIC above, truncated as needed.
This contains whatever value is needed to make the record sum to CHECKSUM.
This is a copy of the inode aa it appears on the file system; see Is( 5).
The count of characters in c_tJddr.
An array of characters describing the blocks of the dumped file. A character is
zero if the block associated with that character was not present on the file system,
otherwise the character is non-zero. If the block was not present on the file system, no block was dumped; the block will be restored as a hole in the file. If there
is not sufticient space in this record to describe all of the blocks in a file,
TS_ADDR records will be scattered through the file, each one picking up where the
last left oft.

Each volume except the last ends with a tapemark (read as an end of file). The last volume ends
with a TSJ;ND record and then the tapemark.
The structure idates describes an entry in the file
The fields of the structure are:
id_name
id_incno
id_ddate
FILES

! etc! dumpdtJtes

where dump history is kept.

The dumr>.ed filesystem is '!deyI id_ntJm '.
The level number of the dump tape; see dump(8).
The date of the incremental dump in system format see types(5).

! etcldumpdates

SEE ALSO
dump(8), restore(8), fs(5), types(5)

BUGS
Should more explicitly describe format of dumpdates file.

Sun Release 1.1

Last change: 15 January 1983

15

FILE FORMATS

ENVffiON(5)

ENVIRON(5)

NAME

environ - user environment
SYNOPSIS

extern char **envJron;
DESCRIPTION

An array of strings called the 'environment' is made available by ezecve(2) when a process begins.
By convention these strings have the form 'nGme=vGlue'. The following names are used by various commands:
PATH
The sequence of directory prefixes that 8", lime, nice(l), etc., apply in searching for a
file known by an incomplete path name. The prefixes are separated by':'. The
login(l) process sets PATH=:/usr/ucb:/bin:/usr/bin.
HOME

A user's login directory, set by login(l) from the password file pG88wd(5).

TERM

The kind of terminal for which output is to be prepared. This information is used by
commands, such as nroJ! or plot(lG), which may exploit special terminal capabilities.
See I etcl termctJp (termctJp(5» for a list or terminal types.

SHELL

The file name of the user's login shell.

TERMCAP The string describing the terminal in TERM, or the name or the termcap flle, see
termcGP(3),termcGP(5),
EXINIT
A startup list or commands read by ez(l), edit(I), and tri(I).
USER

The login name or the user.

Further names may be placed in the environment by the ezport command and 'name=value'
arguments in B"(I), or by the Betenv command if you use cB"(I). Arguments may also be placed
in the environment at the point of an ezecve(2). It is unwise to conOid with certain 8"(1) variables that are frequently exported by '.profile' files: MAIL, PSI, PS2, IFS.
SEE ALSO

csh(I), eX(l), login(l),sh(l), getenv(3), execve(2), system(3), termcap(3X), termcap(5)

16

Last change: 13 June 1983

Sun Release 1.1

Fll.,E FORMATS

FCNTL(5)

FCNTL(5)

NAME

fcntl- file control options
DESCRIPTION
#lnclude 
DESCRlfT10N
The /cntl(2) function provides for control over open files. This include file describes requests and
argument, to /cntl and open(2) as shown below:

'*
'***
*'

a(#)fcntl.h 1.283'12'08 SMI; from UCB 4.283'09'25

*'

Flag values accessible to open(2) and (cntl(2)
(The first three can only be set by open)

#define 0 _RDONL Y
#defineO_WRONLY
#defineO,..RDWR
#define 0 _NDELAY
:f/:define _APPEND

°

#ifndef F _DUPFD
,. fcntl(2) requests */
#define F _DUPFD
#deflne F _GETFD
#deflne F _SETFD
#deflne F _GETFL
#deflne F _SETFL
#define F _GETOWN 5
#deflne F _SETOWN 6

'*

0
1
2

FNDELAY
F APPEND

0
1
2

3
4

,.

/*

'*

*'

Non-blocking I/O
,. append (writes guaranteed at the end)

*'
*'*'

,. Duplicate fildes .,
,. Get fildes flags
,. Set fildes flags .,
Get file flags
,. Set file flags
Get owner • /
Set owner • /

'*

*'

*' *'

8ags for F_GETFL, F_SETFL- copied from 
#define FNDELAY
00004
,. non-blocking reads
#deflne F APPEND
00010
/. append on each write • /
#define F ASYNC
00100
signal pgrp when data ready·,
#~ndir'

'*

SEE ALSO

fcntl(2), open(2)

Sun Release 1.1

Last change: 1 September 1983

17

FS(5)

FILE FORMATS

FS(5)

NAME

fs, inode - format of file system volume
SYNOPSIS

#lnclude 
#lndude 
#lndude < sys/lnode.h>
DESCRIPTION
Every file system storage volume (disk, nine-track tape, for instance) has a common format for
certain vital information. Every such volume is divided into a certain number of blocks. The
block size is a parameter of the file system. Sectors 0 to 15 on a file system are used to contain
primary and secondary bootstrapping programs.

The actual file system begins at sector 16 with the Buper block. The layout of the super block as
defined by the include file < BIIB/!B.h > is:
#define FS_MAGIC
OxOl1954
struct fs {
struct fs *rs_link;
/* linked list or file systems */
struct fs *fs_rlink;
/* used for inc ore super blocks */
daddr_t fs_sblkno;
/* addr of super-block in filesys */
daddr_t rs_cblkno;
/* offset or cyl-block in filesys */
daddr_t fs_iblkno;
/* offset of inode-blocks in filesys */
daddr_t fs_dblkno;
/* offset or first data after cg */
long
fs_cgoffset;
/* cylinder group offset in cylinder */
long
fs_cgma.sk;
/* used to calc mod rs_ntrak */
time_t fs_time;
/* last time written */
long
fs_size;
/* number of blocks in rs */
long
fs_dsize;
/* number of data blocks in fs */
long
fS_Dcg;
/* number of cylinder groups */
long
fs_bsize;
/* size or basic blocks in fs */
long
fs_fsi~e;
size of frag blocks in fs
long
fs_frag;
/* number of frags in a block in fs */
/* these are configuration parameters */
long
fs_minfree;
minimum percentage of free blocks
long
fs_rotdelay;
/* num of ms for optimal next block *'
long
fs_rps;
/* disk revolutions per second
these fields can be computed from the others
long
fs_bmask;
/* "blkoff" calc of bIk offsets */
long
fs_fmask;
/* "fragoff" calc of frag offsets */
long
fs_bshift;
/* "IbIkno" calc of logical blkno */
long
fs_fshift;
/* "numfrags" calc number of frags */
/* these are configuration parameters */
long
fs_maxcontig;
max number of contiguous blks */
long
fs_maxbpg;
/* max number of blks p_er cyl group */
/* these fields can be computed from the others */
long
fs_fragshift;
block to frag shift
long
fs_fsbtodb;
fsbtodb and dbtofsb shift constant
long
fs_sbsize;
/* actual size of super block */
long
fs_csmask;
/* csum block offset *'
long
fs_csshirt;
/* csum block number */
long
fS_Dindir;
/* value of NINDm */
long
fs_inopb;
/* value of INOPB */
long
fS_DSpf;
/* value of NSPF *'
long
fS_5parecon[6J;
/* reserved for future constants */

'*

*'

'*

'*

'*
''**

18

*'

*/

Last change: 3 April 1983

*'

*/

*/

Sun Release 1.1

FS(5)

FILE FORMATS

FS(5)

,. sizes determined by number of cylinder groups and their sizes *'
daddr_t fs_csaddr;
,. blk addr of cyl grp summary area *'
long
fs_cssize;
,. size of cyl grp summary area *'
long
fs_cgsize;
'* cylinder group size *'
,. these fields should be derived from the hardware *'
long
fs_ntrak;
'* tracks per cylinder *'
long
fs~nsect;
,. sectors per track *'
long
fs_spc;
,. sectors per cylinder .,
,. this comes from the disk driver partitioning .,
long
fs_ncyl;
,. cylinders in file system *'
,. these fields can be computed from the others .,
long
fs_cpg;
,. cylinders per group .,
10ngfs_ipS;
,. inodes per group .,
long
fs_fpg;
,. blocks per grou-p *fs_frag *'
,. this data must bere-computed after crashes .,
struct csum fs_cstotal; ,. cylinder summary information *'
'* these fields are cleared at mount time *'
char
fs_fmod;
'* super block modified flag *'
charfs_clean;
,. file system is clean ftag·'
char
fs_ronly;
,. mounted read-only flag .,
char
fs_flags;
,. currently unused flag *'
. char
fs_fsmnt[MAXMNTLEN);
,. name mounted on .,
,. these fields retain the current block allocation info .,
long
fs_cgrQtor;
,·last cg searched .,
etruct csum·fs_csp[MAXCSBUFS);'· list of fs_cs info buffers *'
long
fs_cpc;
cylper cycle in postbl *'
short fs...postbl(MAXCPG][NRPOS);'· head of blocks for each rotation *'
long
fs_magic;
,. magic number .,
u_char fs_rotbl[l);
,. list of blocks for each rotation *'
,. actually longer .,

'*

};
Each disk drive contains some number of file systems. A file system consists of a number of
cylinder groups. Each cylinder group has inodes and data.
A file system is described by its super-block, which in turn describes the cylinder groups. The
super-block is critical data and is replicated in each cylinder group to protect against catastrophic
lou. This is done at file system creation time and the critical super-block data does not change,
so the copies need not be referenced further unless disaster strikes.
Addresses stored in inodes are capable of addressing fragments of 'blocks'. File system blocks of
at most size MAXBSIZE can be optionally broken into 2, 4, or 8 pieces, each of which is addressable; these pieces may be DEV_BSIZE, or some mUltiple of a DEV_BSIZE unit.
Large files consist of exclusively large data blocks. To avoid undue wasted disk space, the last
data block of a small file is allocated as only as many fragments of a large block as are necessary.
The file system form6t retains only a single pointer to such a fragment, which is a piece of a single large block that has been divided. The size of such a fragment is determinable from information in the inode, using the "blksize(fs, ip, Ibn)" macro.
The file system records space availability at the fragment level; to determine block availability,
aligned fragments are examined.
The root inode is the root of the file system. Inode 0 can 't be used for normal purposes and historically bad blocks were linked to inode 1, thus the root inode is 2 (inode 1 is no longer used for
this purpose, however numerous dump tapes make this assumption, so we are stuck with it). The
1081+ found directory is given the next available inode when it is initially created by mk/s.

Sun Release 1.1

Last change: 3 April 1983

19

FS(5)

FS(5)

FILE FORMATS

fs_minfree gives the minimum acceptable percentage of file system blocks which may be free. If
the freelist drops below this level only the super-user may continue to allocate blocks. This may
be set to 0 if no reserve of free blocks is deemed necessary, however severe performance degradations will be observed if the file system is run at greater than 90% full; thus the default value of
fs_minfree is 10%.
Empirically the best trade-off between block fragmentation and overall disk utilization at a loading of 90% comes with a fragmentation of 4, thus the default fragment size is a fourth of the
block size.

CI/linder group related limits: Each cylinder keeps track of the availability of blocks at different
rotational positions, so that sequential blocks can be laid out with minimum rotational latency.
NRPOS is the number of rotational positions which are distinguished. With NRPOS 8 the resolution of the summary information is 2ms for a typical 3600 rpm drive.
fs_rotdelol/ gives the minimum number of milliseconds to initiate another disk transfer on the
same cylinder. It is used in determining the rotationally optimal layout for disk blocks within a
file; the default value for fs_rotdelol/ is 2ms.
Each file system has a statically allocated number of inodes. An inode is allocated for each NBPI
bytes of disk space. The inode allocation strategy is extremely conservative.
MAXIPG bounds the number of inodes per cylinder group, and is needed only to keep the structure simpler by having·the only a single variable size element (the free bit map).

N.B.I MAXIPG must be a multiple of INOPB(fs).
MINBSIZE is the smallest allowable block size. With a MINBSIZE of 4096 it is possible to create
files of size 2"32 with only two levels of indirection. MINBSIZE must be big enough to hold a
cylinder group block, thus changes to (struct cg) must keep its size within MINBSIZE. MAXCPG
is limited only to dimension an array in (struct cg); it can be made larger as long 38 that
structure's size remains within the bounds dictated by MINBSIZE. Note that super blocks are
never more than size SBSIZE.
The path name on which the file system is mounted is maintained in fsJsmnt. MAXMNTLEN
defines the amount of space allocated in the super block for this name. The limit on the amount
of summary information per file system is defined by MAXCSBUFS. It is currently parameterized
ror a maximum of two million cylinders.
P~r cylinder group information is summarized in blocks allocated from the first cylinder group's
data blocks. These blocks are read in from fS_c8oddr (size fs_cBBize) in addition to the super
block.

N.B.I sizeof (struct csum) must be a power of two in order for the "fs_cs macro to work.
Super block for 0 file 8l/stem: MAXBPC bounds the size of the rotational layout tables and is limited by the fact that the super block is of size SBSIZE. The size of these tables is Inversely pro1l

portional to the block size of the file system. The size of the tables is increased when sector sizes
are not powers of two, 38 this increases the number of cylinders included before the rotational
pattern repeats (fB_CpC). The size of the rotational layout tables is derived from the number of
bytes remaining in (struct fs).
MAXBPG bounds the number of blocks of data pet cylinder group, and is limited by the fact that
cylinder groups are at most one block. The size of the free block table is derived from the size of
blocks and the number of remaining bytes in the cylinder group structure (struct cg).

Inode: The inode is the focus of all file activity in the UNIX file system. There is a unique inode
allocated for each acthre file, each current directory, each mounted-on file, text file, and the root.
An inode is 'named' by its device/i-number pair. For further information, see the include file
< sys/inode.h>.

20

Last change: 3 April 1983

Sun Release 1.1

FILE FORMATS

FSTAB( 5)

FSTAB( 5)

NAME

fstab - static information about the filesystems
SYNOPSIS

#lnelude 
DESCRIPTION
The file / dc/lstGb describes the file systems and swapping partitions on the local machine. It is
created by the system administrator using a text editor and processed by commands which
mount, unmount, check consistency of, dump and restore file systems, and by the system in providing swap space.

It consists of a number of lines of the form:
fs_spec:fs_file:fs_type:fs_freq:fsJ8.8sno
an example of which would be:
/dev /xyOa:':rw:l~l
The entries from .his file are accessed using the routines in getlsent(3), which returns a structure
of the following form:
struct lstab {
char
char
char
int
int

IIIfs_spec;
·fs_file;
·fs_type;
fs_freq;
fS..l>8.8sno;

'* block special device name */
/* file system path prefix */
/* rw ,ro,sw or xx */

/* dump frequency, in days *'

/* pass number on parallel dump ./

};
The lines in the file give for each file system or swap area on the local machine the disk partition
it is contained in fs_spec and the directory on which it is to be mounted (unless it is a swap area)
in /aJUe. The Is_spec special file name is the block special file name, and not the character specia.l file name which the rest of the entry refers to. It a program needs the character special file
name, the program must create it by appending a IIr" after the last" /" in the special file name.
The I'_type indicates whether it it to be read-only "ro", rea.dable and writable "rw", or readable
and writable subject to quotas "rq". It Is_type is "sw" then the special file is made available as a
piece of swa.p space by the sWGpon(8) command at the end of the system reboot procedure. The
fields other than Is_spec and Is_type are not used in this case. If la_type is "rq" then at boot time
the file system is automatically processed by the quotGcheck(8) command and disk quotas are then
enabled with quotGon(8). File system quotas are maintained in a file "quotas", which is located
at the root of the associated file system. It Is_type is specified as "XXII the entry is ignored. This
is useful to show disk partitions which are currently not used.
The field /sJreq indica.tes how often each partition should be dumped by the dump(8) command
(and triggers that commands w option which tells which file systems should be dumped). Most
systems set the IsJreq field to 1 indicating that the file systems are dumped each day.
The final field IS-PG88no is used by the disk consistency check program Isck(8) to allow overapped
checkinl of file systems during a reboot. All file systems with IS-PG8ano of 1 are first checked
simultaneosly, then all file systems with IS-PGssno 01 2, and so on. It is usual to make the
18-PGs8no of the root file system have the value 1 and then check one file system on each available
disk drive in each subsequent pass to the exhaustion of file system partitions.

I etc/lstGb is only

reGd by programs, and not written; it is the duty of the system administrator to
properly create and maintain this file. The order of records in / etc//8tab is important because
Isck, mount, and umount process the file sequentially; file systems must appear alter file systems
they are mounted witliin.

SUD

Release 1.1

Last change: 18 September 1983

21

FSTAB( 5)

FILE FORMATS

FSTAB(5)

FILES

/etc/fstab
SEE ALSO

getfsent(3), quotacheck(8), quotaon(8)

22

Last change: 18 September 1983

Sun Release 1.1

GETTYTAB ( 5 )

FILE FORMATS

GETTYTAB ( 5 )

NAME

gettytab - terminal configuration data base
SYNOPSIS
/etc/gettytab
DESCRIPTION

Gettl/tab is a simplified version of the termcap(5) data base used to describe terminal lines. The
initial terminal login process gettl/(8) accesses the gettl/tab file each time it starts, allowing simpler
reconfiguration of terminal characteristics. Each entry in the data base is used to describe one
class of terminals.
There is a default terminal class, default, that is used to set global defaults for all other classes.
(That is, the default entry is read, then the entry for the class required is used to override particular settings.)
CAPABILITIES
Refer to termcap(5) for a description of the file layout. The de/auit column below lists defaults
obtained if there is no entry in the table obtained, nor one in the special default table.

Name Type Default Description
bool falaeterminal uses any parity
num
0
backspace delay
atr
0377 alternate end of line character (input break)
bool false use crt backspace mode
num
0
carriage-return delay
bool false use crt er38e algorithm
bool false use crt kill algorithm
str
NULL screen clear eequence
bool false console - add \n after login prompt
etr
Ay
delayed suspend character
bool false leave echo OFF
bool false terminal uses even parity
A1
erase character
str
AD
end of text (EOF) character
str
NULL initial enviroment
str
unused" tty mode Bags to write messages
num
unused tty mode Bags to read login name
num
unused tty mode Bags to leave terminal as
num
o form-feed (vertical motion) delay
num
str
"0
output Bush character
bool false do NOT hangup line on 138t close
NULL hostname editing string
atr
hostname
hostname
atr
bool false terminal has real tabs
boot false ignore garbage characters in login name
il
NULL initial (banner) message
str
im
AO
interrupt character
str
in
unused input speed
is
num
AU
kill character
str
kl
bool false terminal has lower case
Ie
login: logjn prompt
str
1m
AV
"literal next lt character
str
In
str
/bin/login
program to exec when name obtained
10
num
o newline (line-feed) delay
nd
bool false terminal has (or might have) a newline character
nl
ap
bd
bk
cb
cd
ee
ek
cl
co
ds
ee
ep
er
et
ev
fO
f1
(2
fd
B
he
he
hn
ht

Sun Release 1.1

Last change: Z7 October 1983

23

GETTYTAB ( 5 )

nx
op
os
pc
pe
pf
ps
qu
rp
rw
sp
su
tc

tp
U

ub
uc
we
xc
xf
xn

str
booI
num
str
bool
num
bool
Btr
str
pool
num
Btr
str
num
Btr
bool
bool
str
bool
str
str

FILE FORMATS

GETTYTAB ( 5 )

default next table (for auto speed selection)
false terminal uses odd parity
unused output speed
\0
pad character
false use printer (hard copy) erase algorithm
o delay between first prompt and following flush (seconds)
false line connected to a MICOM port selector
A\
quit character
AR
line retype character
false do NOT use raw for input, use cbreak
unused line speed (input and output)
•Z
suspend character
none table continuation
o timeout (seconds)
NULL terminal type (for enviroment)
false do unbuffered output (01 prompts etc)
false terminal is known upper case only
"W
word erase character
false do NOT echo control chars as AX
AS
XOFF (stop output) character
AQ
XON (start output) character

If no line speed is specified, speed will not be altered from that which prevails when gett1J is
entered. Specifying an input or output speed overrides line speed for stated direction only.

Terminal modes to be used for the output of the message, for input of the login name, and to
leave the terminal set as upon completion, are derived from the Boolean flags specified. If the
derivation should prove inadequate, any (or all) of these three may be overriden with one of the
to, tt, or t2 numeric specifications, which can be used to specify (usually in octal, with a leading
'0') the exact values of the flags. Local (new tty) flags are set in the top 16 bits of this (32 bit)
value.
Should getty receive a null character (presumed to indicate a line break) it will restart using the
table indicated by the ox entry" If there is none, it will re-use its original table.
Delays are &pecified in milliseconds, the nearest possible delay available in the tty driver will be
used. Should greater certainty be desired, delays with values 0, 1, 2, and 3 are interpreted as
choosing that particular delay algorithm from the driver.
The cI screen clearbtring may be preceded by a (decimal) number of milliseconds of delay
required (a la termcap). This delay is simulated by repeated use of the pad character pc.
The initial message, and login message, 1m and 1m may include the character sequence %h to
obtain the hostname. (%% obtains a single '%' character.) The hostname is normally obtained
from the system, but may be set by the hn table entry. In either case it may be edited with he.
The he string is a sequence of characters, each character that is neither 'a' nor '#' is copied into
the final hostname. A 'a' in the he string, causes one character from the real hostname to be
copied to the final hostname. A '#' in the he string, causes the next character of the real hos~
name to be skipped. Surplus 'a' and '# characters are ignored.
I

When getty execs the login process, given in the 10 string (usually" /bin/login"), it will have set
the enviroment to include the terminal type, as indicated by the tt string (if it exists). The ev
string, can be used to enter additional data into the environment. It is a list of comma separated
strings, each of which will presumably be of the form name=value.
If a non-zero timeout is specified, with to, then getty will exit within the indicated number of
seconds) either having received a login name and passed control to login, or having received an
alarm signal, and exited. This may be useful to hangup dial in lines.

24

Last change: Z1 October 1983

Sun Release 1.1

GETTYTAB ( 5 )

FILE FORMATS

GETTYTAB ( 5 )

Output from getty is even parity unless op is specified. Op may be specified with ap to allow
any parity on input, but generate odd parity output. Note: this only applies while getty is being
run, terminal driver limitations prevent a more complete implementation. Getty does not check
parity of input characters in RA W mode.
SEE ALSO

termcap(5), getty(8).

Sun Release 1.1

Last change: Zl October 1983

25

GROUP(5)

FILE FORMATS

GROUP(5)

NAME

group - group file
DESCRIPTION
Group contains for each group the following information:

group name
encrypted password
numerical group ID
a comma separated list of all users allowed in the group
This is an ASCII file. The fields are separated by colons; Each group is separated from the next
by a new-line. If the password field is null, no password is demanded.
This file resides in directory letc. Because or the encrypted passwords, it can and does have general read permission and can be used, for example, to map numerical group ID's to names.
FILES

letclgroup
SEE ALSO

setgroups(2), initgroups(3), crypt(3), passwd(l), passwd(5)

BUGS
The ptJ88wd(1) command won't change the passwords.

26

Last change: 15 January 1983

Sun Release 1.1

HOSTS(S)

FILE FORMATS

HOSTS ( 5)

NAME

hosts - host name d·ata base
DESCRIPTION
The hod8 tile contains information regarding the known hosts on the DARPA Internet. For each
host a single line should be present with the following information:

official host name
Internet address
aliases
Items are separated by any number of blanks and/or tab characters. A "#" indicates the beginning 01 a comment; characters up to the end of the line are not interpreted by routines which
search the file. This file is normally created from the official host data base maintained at the
Network Information Control Center (NIC), though local changes may be required to bring it up
to date regarding unofficial aliases and/or unknown hosts.
Network addresses a~e specified in the conventional "." notation using the ineCoddr() routine
from the Internet address manipulation library, inet(3N). Host names may contain any printable
character other than a field delimiter, newline, or comment character.
FILES

/etc/hosti
SEE ALSO
gethosten t(3N)

BUGS
A name server should be used instead of a static file. A binary indexed file format should be
available for fast access.

Sun Release 1.1

Last change: 15 January 1983

27

FILE FORMATS

KBD( 5)

KBD(5)

NAME"
kbd - keyboard translation table format and default table
SYNOPSIS
#lnelude 
DESCRIPTION
Keyboard translation is done in the UNIX kernel via a set of tables. A translation table is 128
bytes of 'entries', which are bytes (unsigned chars). The top 4 bits of each entry are decoded by a
case statement in the keyboard translator. If the entry is less than Ox80, it is sent out as an ASCU
character (possibly with the META bit OR-ed in). 'Special' entries are Ox80 or greater, and
invoke more complicated actions.
struct keymap {
unsigned char

keymap(128J;

'* maps keycodes to actions *'

};
A keyboard is defined by its keymaps.

struct keyboard {
struct keymap
struct keymap
struct keymap
struct key map
struct key map
int
int
unsigned char
unsigned char

*k_norma1;
*k_shiCted;
*k_caps;
*k_control;
*k_up;
k_idleshifts;
k_idlebuckys;
k_abortl;
k_abort2;

'* Unshifted *'
'* Shifted *'
'* Caps locked *'
'* Controlled *'
'* Key went up *'
'* Shifts *'
'* Bucky bits *'
'* 1st key of abort sequence *'
'* 2nd key ot abort sequence *'

};
The following defines the bit positions used within k_idleshifts to indicate the 'pressed' (1) or
'released' (0) state of shift keys. The bit numbers and the aggregate masks are defined.
Since it is possible to have more than one bit in the shift mask on at once, there is an implied
priority given to each shift state when determining which translation table to use. The order is
(from highest priority to lowest) UPMASK, CTRLMASK, SHIFTMASK, and lastly CAPSMASK.
#deflne CAPSLOCK
#define SHIFTLOCK
#define LEFTSHIFT
#define RIGHTSHIFT
#define LEFTCTRL
#define R IGHTCTRL
#define CAPS MASK
#define SHIFTMASK
#define CTRLMASK
#define l;l>MASK

0

1
2
3

4
5
OxOOOl
OxOOOE
Ox0030

Ox0080

'* Caps Lock key *'
'* Shift Lock key *'
'* Left-hand shift key *'
Right-hand shift key *'
'* Left-hand (or only) control key *'
'* Right-hand control key *'
'* Caplock translation table *'
'* Shifted translation table *'
'* Otrl shift ~ranslation table *'
'* Key up translation table *'

'*

Speelal Entry Key.

The 'special' entries' top 4 bits are defined below. Generally they are used with a 4-bit parameter
(such as a bit number) in the low 4 bits. The bytes whose top 4 bits are OxO thru Ox7 happen to
be AScn characters. They are not special cased, but just normal cased.
#define SHIFTKEYS

Ox80

thru Ox8F. This key helps to determine the translation table used. The bit position of
its bit in 'shiftmask' is added to the entry, for example, SHIFTKEYS+ LEFTCTRL. When

28

Last change: 19 March 1984

Sun Release 1.1

KBD(5)

KBD(5)

FILE FORMATS

this entry is invoked, the bit in 'shiftmask' is toggled. Depending which tables you put it
in, this works well for hold-down keys or press-on, press-off keys.
:fI:define BUCKYBITS

Ox90

thru Ox9F. This key determines the state of one of the 'bucky' bits above the returned
character. This is basically a way to pass mode-key~up'down information back to
the caller with each 'real' key depressed. The concept, and name 'bucky' (derivation
unknown) cornea trom the MIT/SAIL 'TV' system - they had TOP, META, CTRL, and a
tew other bucky bits. The bit position ot its bit in 'buckybits', minus 7, is added to the
entry; tor example, bit OxOOO00400 is BUCKYBITS+ 3. The '-7' prevents us from messing
up the ASOD char, and gives us 16 useful bucky bits. When this entry is invoked, the
designated bit in 'buckybits' is toggled. Depending which tables you put it in, this works
well tor hold-down keys or press-on, press-off keys.

ASoo

tdefine METABI1'

L.

0

Meta key depressed with key. This is the only user accessible bucky bit. This value is
added to BUCKYBITS in the translation table.

f:define SYSTEMBIT

1

'System' key was down w,key. This is a kernel-accessible bucky bit. This value is added
to BUCKYBITS in the translation table. The system key is currently not used except as a
place holder to indicate the key used as the k_tJ6ortl key (as defined above).

OxAO

'*

*' *' *'
*'

thru OxAF. This key does one ot 16 funny
things based on the low 4 bits:
OxAO l* This key does nothing.
:fI:defineNOP
OxAl l* This key exists but is undefined.
:fI:define OOPS
0xA2 l* This key does not exist on the keYboard.
'define HOLE
Its position code should never be
generated. This indicates a software'
hardware mismatch, or bugs.
:fI:define NOSCROLL OxA3 l* This key alternately sends AS or AQ *l
OxA4 l* This sends AS and lets NOSCROLL know *l
:fI:define CTRL S
OxA5 l* This sends AQ and lets NOSCROLL know
#define CTRL Q
OxA6 l* Kbd was just reset
#define RESET
OxA7 l* Kbd just detected an internal error
#define ERROR
OxAs l* Kbd is idle (no keys down)
*define IDLE
CQQlbinttions OxA9 to OxAIt" are reserved for non-parameterized functions.
"define FUNNY

*'

,define STRING

*' *'

*'

OxBO

thru OxBF. The low-order 4 bits index a table select a string to be returned, char by
char. Each entry in the table is null terminated.

'*

#deftne KTAB_STRLEN
10
Maximum string length (including null)
Definitions for the individual string numbers:
#define HOlvlEARROW
:fI:define UPARROW
#define DOWNARROW
#defineLEFTARROW
#define RIGHTARROW

Sun Release 1.1

*'

OxOO
OxOI
Ox02
Ox03
Ox04

Last change: 19 March 1984

29

KBD(5)

FILE FORMATS

KBO(5)

String numbers 5 thru F are available to users making custom entries.

Function Key Grouplnp
In the following function key groupings, the low-order 4 bits indicate the function key number
within the group:
#define LEFTFUNC
#define RIGHTFUNC
#define TOPFUNC
#define BOTTOMFUNC
#define LF(n)
#define RF(n)
#define TF(n)
#define BF(n)

OxCO /* thru OxCF. The
OxOO /* thru OxDF. The
OxEO
thru OxEF. The
OxFO /* thru OxFF. The
(LEFTFUNC+ (n}-l)
(RIGHTFUNO+ (n}-l)
(TOPFUNO+ (n}-l)
(BOTTOMFUNO+ (n}-l)

'*

*'

'left' group. */
'right' group.
'top' group. */
'bottom' group.

*/

The actual keyboard positions may not be on the left/right/top/bottom of the physical keyboard
(although they usually are). What is important is that we have reserved 64 keys for function
keys.
Normally, when a function key is preMed, the following escape sequence is sent through the char·
acter stream:
ESC(O .. 9z
where ESC is a single escape character and 0 ..9 indicate some number of digits needed to encode
the function key as a decimal number.
DEFAULT TABLES

The kernel has 3 sets of initial translation tables, one set for each type of keyboard supported.
#ifndef lint
static char sccsid[) = "Q(#)keytables.c 1.3 83/10/25 Copyr 1983 Sun Micro~;
#endif

/*

* Copyright (0) 1983 by Sun Microsystems, Inc.
*/

'***

keytables.c

* This module contains the translation tables for the up-down encoded
* Sun keyboards.

*/

#include " .. /sun/kbd.h"

'* handy way

to define control characters in the tables
#define c(char) (char&OxlF)
#define ESC OxlB

*/

/* UnshiCted keyboard table for Micro Switch 103S032-2 */
static struct keymap keytab_ms_lc = {
/* 0 */HOLE, BUCKYBITS+ SYSTEMBIT,
LF(2), LF(3), HOLE, TF(I), TF(2), TF(3),
/* 8 */TF(4), TF(5), TF(6), TF(7), TF(8), TF(9), TF(10), TF(11),
/* 16 */
TF(12), TF(13), TF(14),c('('), HOLE, RF(I), '+ "
'.'

30

Last change: 19 March 1984

Sun Release 1.1

FILE FORMATS

KBO(5)

'*
'''***
'''***

24
32
40
48
56
64
72

*'
*'*'
*'
*'*'*'

''** *'*'
'* *'
80
88

96

,*104 *'
,*112 *'
,*120 *'

HOLE, LF(4),

KBD( 5)

'\f',

LF(6), HOLE, SHIFTKEYS+ CAPSLOCK,
'1',
'2',
'4',
'5',
'6',
'7',
'8',
'9',
'3',
'0',
'9',
'8',
'-',
'-',
"',
'\b',
HOLE, '7',
HOLE, LF(7), STRING+ UPARROW,
'w',
LF(9), HOLE, '\t',
'q',
'p',
'e',
'r',
't',
'y',
'u',
'i',
'0',
'6',
'f,
'}',
'_',
HOLE, '4',
'5',
HOLE,
STRING+ LEFTARROW,
STRING+ HOMEARROW,
STRING+ RIGHTARROW,
HOLE, SHIFTKEYS+ SHIFTLOCK,
's',
'a',
'd',
'.'. ,
'.', ,
'f',
'g',
'h',
'j',
'1' ,
'k',
'3',
'2',
HOLE, NOSCROLL,
'I',
'\r', HOLE, '1',
STRING+ OOWNARROW,
LF(97), HOLE, HOLE, SHIFTKEYS+ LEFTSHIFT,
'Z',
'x',
'c',
'v',
'b',
'n',
'm',
',',
'.',
'I',
SHIFTKEYS+ RIGHTSHIFT,
NOP, Ox7F, '0',
NOP, '.',
HOLE, HOLE, HOLE,
HOLE; HOLE, SHIFTKEYS+ LEFTCTRL,
,"
SHIFTKEYS+ RIGHTCTRL,
HOLE, HOLE, IDLE,

};

'*

Shifted keyboard table for Micro Switch 103S032-2 *'

static struct keymap keytab_ms_uc = {
'* 0 *,HOLE, BUCKYBITS+ SYSTElvfBIT,
LF(2), LF(3),
'* 8 *'TF(4), TF(5), TF(6), TF(7), TF(8),
'* 16 *'
TF(12), TF(13), TF(14),c('['),
'* 24 *'
HOLE, LF(4), '\f',
LF(6),

'''***
'''***

32
40
48
56
64
72

*'*'*'
*'*'*'

''** *'*'
'* *'
80
88

96

,*104 *'
,*112 *'
,*120 *'

SUD

Release 1.1

'#',
'=',

HOLE,
TF(9),
HOLE,
HOLE,

TF(I), TF(2), TF(3),
TF(lO), TF(ll),
RF(l), '+',
'-',
SHIFTKEYS+ CAPSLOCK,
,,,,
't'

.,

,

'%',

')',
'0',
'&',
'\",
'(',
'9',
'g',
'\b',
HOLE, '7',
'8',
HOLE, LF(7), STRING+ UPARROW,
'Q',
'W',
LF(9), HOLE, '\ t',
'0',
'E',
'R',
'T',
'Y',
'U',
'I',
'P',
'6',
HOLE,
'I',
'J',
'_',
HOLE, '4',
'5',
STRING+ LEFTAR~OW,
STRING+ HOMEARROW,
STRING+ RIGHTARROW,
HOLE, SHIFTKEYS+ SHIFTLOCK,
'A',
'S',
'D',
'F',
'G',
'H',
'J',
'K',
'L',
'+', '*',
'\\',
'\r',
HOLE, '1',
'2',
'3',
HOLE, NOSCROLL,
STRING+ DOWNARROW,
LF(97), HOLE, HOLE, SHIFTKEYS+ LEFTSHIFT,
'Z',
'X',
'C',
'V',
'B',
'N',
'M',
'<', '>', '7',
SHIFTKEYS+ RIGHTSHIFT,
Nap, Ox7F, '0',
Nap, '.',
HOLE, HOLE, HOLE,
HOLE, HOLE, SHIFTKEYS+ LEFTCTRL,
'$',
'A',

.L~st

change: 19 March 1984

31

KBO( 5)

KBD(5)

FILE FORMATS

,,

SHIFTKEYS+ RIGHTCTRL,
HOLE, HOLE, IDLE"

};

1* Caps Locked keyboard table for Micro Switch

103S032-2 *1

static struct keymap keytab_ms_c1 = {
0 *IHOLE, BVCKYBITS+ SYSTEMBIT,
LF(2), LF(3),
1* 8 */TF(4), TF(5), TF(6), TF(7), TF(8),
1* 16 *1
TF(12), TF(13), TF(14),c('l'),
1* 24 *1
HOLE, LF(4), '\r,
LF(6),

HOLE,
TF(9),
HOLE,
HOLE,

1*

1* 32 *1
1* 40 *1
1* 48 *1
1* 56 *1
1* 64 *1
1* 72 *1

1* 80 *1
1* 88 *1
/* 96 *1
1*104 *1
1*112 *1
1*120 *1

TF(l), TF(2), TF(3),
TF(lO), TF(ll),
RF(l), '+',
'-',
SHIFTKEYS+ CAPSLOCK,
'2',
'1',
'0',
'8',
'9',
'7',
'6',
'5',
'3',
'4',
,-,,
'If
'8',
'9',
HOLE, '7',
,
'\b',
'-' ,
HOLE, LF(7), STRING+ UP ARROW,
'W',
'Q',
LF(9), HOLE, '\t',
'P',
'1',
'0',
'Y',
'V',
'T',
'E',
'R',
,,
HOLE,
'6',
HOLE,
'4',
'5',
'}',
'{',
-,
STRING+ LEFTARROW,
STRING+ HOMEARROW,
STRING+ RIGHTARROW,
HOLE, SHIFTKEYS+ SHIFTLOCK,
'S',
'D',
'A',
'.'. ,
'L',
'.', ,
'K',
'F',
'G',
'H',
'J',
HOLE, NOSCROLL,
'3',
'2',
'I' ,
'\r' , HOLE " '1'
STRING+ OOWNARROW,
LF(97), HOLE, HOLE, SHIFTKEYS+ LEFTSHIFT,
'Z',
'X',
'C',
'V',
'B"
'N',
'M', ',',
'.',
'I',
SHIFTKEYS+ RIGHTSHIFT,
NOP, Ox7F, '0',
NOP, '.',
HOLE, HOLE, HOLE,
HOLE, HOLE, SHIFTKEYS+ LEFTCTRL,
SHIFTKEYS+ RIGHTCTRL,
,"
HOLE, HOLE, IDLE,

};

1* Controlled keyboard table for Micro Switch 103SD32-2 *1
static struct keymap keytab_ms_et = {
0 */HOLE, BUCKYBITS+ SYSTEMBIT,
LF(2), LF(3),
1* 8 *ITF(4), TF(5), TF(6), TF(7), TF(8),
1* 16 *1
TF(12), TF(13), TF(14),c('['),
1* 24 *1
HOLE, LF(4), 'V',
LF(6),

1*

1* 32 *1
1* 40 *1
1* 48 *1
1* 56 *1
1* 64 */
1* 72 */
32

HOLE,
TF(9),
HOLE,
HOLE,

TF(l), TF(2), TF(3),
TF(10), TF(ll),
RF(l), OOPS, OOPS,
SHIFTKEYS+ CAPSLOCK,
OOPS, OOPS,
OOPS, OOPS, OOPS, OOPS. OOPS, OOPS, OOPS, OOPS,
OOPS~ e(,A,), c('a'), '\b',
HOLE, OOPS, OOPS, OOPS,
HOLE, LF(7), STRING+ UPARROW,
LF(9), HOLE, '\t',
CTRLQ,
c('W'),
c( 'E'), c('R '), c('T'), c('Y'), c('V'), c('I'), c('O'), c('P'),
c{'['), c('J'), c('_'), HOLE, OOPS, OOPS, OOPS, HOLE,
STRING+ LEFTARROW,

Last change: 19 March 1984

Sun Release 1.1

KBD(5)

Fll..E FORMATS

/* 80 */
/* 88 */
/* 96 */
/*104 */
/*112
/*120

*/
*/

c('F'),

c('\ \'),

KBD( 5)

STRING+ HOMEARROW,
STRING+ RIGHT ARROW,
HOLE, SHIFTKEYS+ SHIFTLOCK,
c('A'), CTRLS,
c('D'),
c('G'), c('H'), c(' J'), c('K'), c('L'), OOPS, OOPS,

'\r

t

,
HOLE, OOPS, OOPS, OOPS, HOLE, NOSCROLL,
STRING+ DOWNARROW,
LF(97), HOLE, HOLE, SHlFTKEYS+ LEFTSHIFT,
c('Z'), c('X'), c('C'),
c('V'), c('B'), c('N'), c('M'), OOPS, OOPS, OOPS, SHIFTKEYS+ RIGHTSHIFT,
NOP, Ox7F, OOPS, NOP, OOPS, HOLE, HOLE, HOLE,
HOLE, HOLE, SHIFTKEYS+ LEFTCTRL,
'\0',
SHIFTKEYS+ RIGHTCTRL,
HOLE, HOLE, IDLE,

};

/*

"Key Up" keyboard table for Micro Switch 103SD32-2

*1

static struct key map keytab_ms_up = {
/* 0 */HOLE, BUCKYBITS+ SYSTEMBIT,
NOP, NOP,
/* 8 ·/NOP, NOP, NOP, NOP, NOP,
/* 16 */
NOP, NOP, NOP, NOP,
/* 24
HOLE, NOP, NOP, NOP,

*'
*'
/* *'
'*
/* 32
40

*/
/* 48
56 */

'* 64 */
'* 72 */

'* *'
'* *'*'
*'
/* 80
88 */
96

/*104

,*112

,*120 *'

HOLE, NOP, NOP, NOP,
NOP, NOP, NOP,
HOLE, NOP, NOP, NOP,
HOLE, SHIFTKEYS+ CAPSLOCK,
NOP, NOP,
NOP, NOP, NOP, NOP, NOP NOP, NOP) NOP,
NOP, NOP, NOP, NOP, HOLE, NOP, NOP, NOP,
HOLE, NOP, NOP, NOP, HOLE, NOP, NOP, NOP,
NOP, NOP, NOP, NOP, NOP, NOP, NOP, NOP,
NOP, NOP, NOP, HOLE, NOP, NOP, NOP, HOLE,
NOP, NOP, NOP, HOLE, SHIFTKEYS+ SHIFTLOCK,
NOP, NOP, NOP,
NOP, NOP, NOP, NOP, NOP, NOP, NOP, NOP,
NOP, NOP, HOLE, NOP, NOP, NOP, HOLE, NOP,
NOP, NOP, HOLE, HOLE, SHIFTKEYS+ LEFTSHIFT,
Nap, NOP, NOP,
Nap, NOP, NOP, NOP, NOP, Nap, Nap, SHIFTKEYS+ RIGHTSHIFT,
NOP, NOP, NOP s NOP, NOP, HOLE, HOLE, HOLE,
HOLE, HOLE, SHIFTKEYS+ LEFTCTRL,
NOP, SHIFTKEYS+ RIGHTCTRL,
HOLE, HOLE, RESET,
I

};

'*

Index to keymaps for Micro Switch 103SD32-2
static struct keyboard keyindex_ms = {
&keytab_ms.Jc,
&keytab_ms_1lc,
&keytab_ms_cl,
&keytab_ms_d,
& keytab_ms_up,

Sun Release 1.1

*'

Last change: 19 March 1984

33

CTLSMASK,
OxOOOO,

1,

};

'*

KBD(S)

FILE FORMATS

KBD( S)

77,

''**
'*

*'*'

Shift bits which stay on with idle keyboard
Bucky bits which stay on with idle keyboard
abort keys

*'

Unshifted key beard table for Sun-2 keyboard

*'

static struct keymap keytab_s2_lc = {
'* 0 *,HOLE, BUCKYBITS+ SYSTEMBIT,
LF(2), LF(3), HOLE,
'* 8 *'TF(4), TF(5), TF(6), TF(7), TF(8), TF(9),
'* 16 *'
TF(12), TF(13), TF(14), TF(IS), HOLE,
'* 24 *'
HOLE, LF(4), LF(S), LF(6), HOLE,
'* 32 *'
'3',
'4',
'S',
'6',
'7',
'* 40 *'
'-',
'It,
'\b', HOLE,
'* 48
HOLE, LF(7), LF(8), LF(9), HOLE,
S6
'e',
'r',
't',
'y',
'ut,
'* 64 *'
'[',
'I',
Ox7F, HOLE, RF(7),

'*

tf 72

''**
'*

80
88

*'*'
*'
*'*'
*'

96
,*104 *'

TF(l), TF(2), TF(3),
TF(10), TF(11),
RF(I), RF(2), RF(3),
c('['), '1',
'2',
'8',
'9',
'0',
RF(4), RF(S), RF(6),
'\t',
'q',
'w',
'i',
'0',
'p',
STRING+ UPARROW,
RF(9), HOLE,
LF(10), LF(11), LF(12), HOLE, SHIFTKEYS+ LEFTCTRL,
'a',
's',
'd',
'f',
'g',
'h',
'j',
'k',
'1',
';',
'\",
'\\', '\r', HOLE, STRING+LEFTARROW,
RF(11), STRING+ RIGHTARROW,
HOLE, LF(13),
LF(14), LF(IS), HOLE, SHIFTKEYS+ LEFTSHIFT,
'z',
'x',
·'c',
'v',
,,,,
'n',
'b',
'm',
'.',
'/',
SHIFTKEYS+RIGHTSHIFT,

'="

'\n',
,*112 *'
,*120

*'

RF(13), STRING+ DOWNARROW,
RF(IS), HOLE, HOLE, HOLE, HOLE, HOLE,
BUCKYBITS+ METABIT,
BUCKYBITS+ METABIT,
,"
HOLE, HOLE, HOLE, ERROR,
IDLE,

};

'*

Shifted keyboard table for Sun-2 keyboard

*'

static struct keymap keytab_s2_uc = {
'* 0 *,HOLE, BUCKYBITS+ SYSTEMBIT,
_
LF(2), LF(3), HOLE, TF(I), TF(2), TF(3),
'* 8 *'TF(4), TF(S), TF(6), TF(7), TF(8), TF(9), TF(10), TF(11),
TF(12), TF(13), TF(14), TF(IS), HOLE, RF(I), RF(2), RF(3),
16
HOLE, LF(4), LF(S), LF(6), HOLE, c('['), 'I',
'a',
'-11.'
'*' ,
'%'
,A, ,
'&',
'*',
'(',
')' ,
24
.". ,
" ,
32
'_',
'+ "
'N',
'\b', HOLE, RF(4), RF(S), RF(6),
40
HOLE, LF(7), LF(8), LF(9), HOLE, '\t',
'Q',
'W',
'E',
'H',
'T',
'Y',
'V',
'1',
'0',
'P',
48
56
'{',
'}',
Ox7F, HOLE, RF(7), STRING+ UPARROW,
64
RF(9), HOLE,
LF(lO), LF(11), LF(12), HOLE, SHIFTKEYS+ LEFTCTRL,
72
'A',
'S',
'D',
'F',
'G',
'H',
'J',
'.'. ,
'K',
'L',
"",

''**
''**
''**
'*
'*
'*

34

80

*'*'
*'*'*'
*'*'
*'
*'

.

Last change: 19 March 1984

Sun Release 1.1

FILE FORMATS

KBD(S)

KBD( 5)

'* *'
'* *'

HOLE, STRING+LEFTARROW,
RF(II), STRING+ RIGHT ARROW,
HOLE, LF(13),
LF(14), LF(lS), HOLE, SHIFTKEYS+ LEFTSHIFT,
'Z',
'X',
'C',
'V',
'B',
'N',
'M',
'<', '>', '7',
SHIFTKEYS+ RIGHTSHIFT,

,*112 *'

RF(13), STRING+ DOWNARROW,
RF(lS), HOLE, HOLE, HOLE, HOLE, HOLE,
BUCKYBITS+ METABIT,
BUCKYBITS+ METABIT,
,"
HOLE, HOLE, HOLE, ERROR,
IDLE,

88

96
,*104 *'

'I',

'\r',

'\n',
,*120 *'

};
'* Controlled keyboard table for Sun-2 keyboard .,
static struet keymap keytab_s2_et = {
'* 0 *,HOLE, BUCKYBITS+ SYSTEMBIT,
LF(2), LF(3), HOLE, TF(l), TF(2), TF(3),
TF(5),
TF(6),
TF(7),
TF(8), TF(9), TF(IO), TF(II),
8 */TF(4),
TF(12), TF(13), TF(14), TF(15), HOLE, RF(l), RF(2), RF(3),
HOLE, LF(4), LF(5), LF(6), HOLE, e('I'), '1',
c('O'),
16
'3',
'4',
'5',
c(, ..
'7',
'8',
'9',
'0',
24
e('_'), '=-',
e(""), '\b',
HOLE, RF(4), RF(5), RF(6),
32
40·'
HOLE, LF(7), LF(8), LF(9), HOLE, '\t',
c('q'), c('w'),
1* 48
e('e'),
e('r'),
e('t'),
e('y'),
c{'u'),
c('i'),
e('o'),
c('p'),
/* 56 *'
c{'['), e('J'), Ox7F, HOLE, RF(7), STRING+ UPARROW,
RF(9), HOLE,
64
LF(lO), LF(ll), LF(12), HOLE, SHIFTKEYS+ LEFTCTRL,
c('a'), c('s'), c('d'),
72
cff'), c('g'), c('h'), c('j'), c('k'), e('I'), ';',
'\",

'*
''**
''**
'*
'*
'*
'*

,. 80

*'*'
*'
*'
*'
*'*'

88·'

96

'·104

*'
*'
*'

,*112 *'
'·120

t

c('\ \'),
'\r',

HOLE, STRING+LEFTARROW,
RF(11), STRING+ RIGHTARROW,
HOLE, LF(13),
LF(14), LF(lS), HOLE, SHIFTKEYS+ LEFTSHIFT,
c('z'), c('x'), c('ct c('v'),
c('h'), e('n'), c('m'), ',',
'.',
c{'_'), SHIFTKEYS+ RIGHTSHIFT,

'\n',
RF(13), STRING+ DOWNARROW,
RF{lS), HOLE, HOLE, HOLE, HOLE, HOLE,
BUCKYBITS+ METABIT,
c(' '), BUCKYBITS+ METABIT,
HOLE, HOLE, HOLE, ERROR,
IDLE,

};

'* "Key Up" keyboard table for Sun-2 keyboard .,
static struct keymap keytab_s2_up = {
,. 0 *,HOLE, BUCKI13ITS+ SYSTEMBIT,

SUD Releas~

1.1

Last change: 19 March 1984

35

KBD(5)

FILE FORMATS

KBD(5)

/* 8 */ OOPS,
/* 16 */
/* 24 */
/* 32 */
/* 40 */
/* 48 */
/* 56 */
/* 64 */
/* 72 */
/* 80 */
/* 88 */
/* 00 */
/*104 */
/*112 */
1*120 */

HOLE, OOPS, OOPS, OOPS,
OOPS, OOPS, OOPS,
HOLE, OOPS, OOPS, NOP,
HOLE, NOP, NOP, NOP,
NOP, NOP, NOP, NOP,
HOLE, OOPS, OOPS, NOP,
HOLE, NOP, NOP, NOP,
NOP, NOP, NOP, NOP,
OOPS, OOPS, NOP, HOLE,
SHIFTKEYS+ LEFTCTRL,
NOP, NOP, NOP,
NOP, NOP, NOP, Nap, NOP, NOP, NOP, NOP,
NOP, NOP, HOLE, OOPS, OOPS, NOP, HOLE, OOPS,
OOPS, OOPS, HOLE, SHIFTKEYS+ LEFTSHIFT,
NOP, NOP, NOP, NOP,
NOP, NOP, NOP, Nap, NOP, NOP, SHIFTKEYS+ RIGHTSHIFT,
NOP,
OOPS, OOPS, Nap, HOLE, HOLE, HOLE, HOLE, HOLE,
BtTCKYBITS+ METABIT,
NOP, BUCKYBITS+ METABIT,
HOLE, HOLE, HOLE, HOLE, RESET,
OOPS,
OOPS,
HOLE,
NOP,
NOP,
HOLE,
NOP,
NOP)
OOPS,

OOPS,
OOPS,
OOPS,
NOP,
NOP,
OOPS,
NOP,
NOP,
OOPS,

OOPS,
OOPS,
OOPS,
OOPS,
NOP,
NOP,
OOPS,
NOP,
NOP,
OOPS,

OOPS,
OOPS,
OOPS,
OOPS,
Nap,
NOP,
OOPS,
Nap,
HOLE,
HOLE,

};
/* Index to keymaps for Sun·2 keyboard
static struct keyboard keyindexJ2 .. {
Ilkey tab_!2_lc ,
Il key tab_!2_uc,

*/

0,
Il key tab_!2_ct,

&keytab_!i2_up,
OxOOOO,
/* Shift bits which 8tay on with idle keyboard */
OxOOOO,
/* Bucky bits which stay on with idle keyboard */
1,
77,
/* abort keys */

};
/* Unshifted keyboard table for "VT100 style" */
static struct keymap keytab_vt_lc = {
/* 0 */HOLE, BUCKYBITS+ SYSTEMBIT,
HOLE, HOLE, HOLE, HOLE, HOLE, HOLE,
/* 8 */HOLE, HOLE, STRING+ UPARROW,
.
STRING+ DOWNARROW,
STRING+ LEFTARROW,
STRING+ RIGHTARROW,
HOLE, TF(l),
TF(2), TF(3), TF(4), c('['), 'I',
'2',
'3',
'4',
/* 16 */
'5',
'6',
'7',
'8',
'9',
'0',
'.'
/* 24 */
-,
'-'
"',
c('H'), BUCKYBITS+ :METABIT,
/* 32 */
,.,,
'7',
'8',
'9',
'\t',
,.,
l
'q',
'w',
'e ,
'r',
't',
'y',
'u',
/* 40 */
I ,
'0',
'I',
Ox7F, '4',
'p',
'(',
'5',
/* 48 */
'6',
, t
,,
SHIFTKEYS+ LEFTCTRL,
/* 56 */
SHIFTKEYS+ CAPSLOCK,

36

Last change: 19 March 1984

SUD

Release 1.1

F~EFORMATS

KBD(5)

''** *'*'
'* *'
80
88

96 *'
,*104
,*112 *'
,*120 *'

'h',
'1',

'j',
'2',

'c',

'v',

KBD( 5)

'r',

'g',

'\r',

'\ \',

'a',

's',

'd',

'k',

'1' ,

'.', ,

'3',

Nap,

'\ ",

NOSCROLL,
SHIFTKEYS+ LEFTSHIFT,
'x',
'z',

'b',
'n',
SHIFTKEYS+ RIGHTSHIFT,
'\n',
'0',
HOLE,
HOLE,
HOLE, HOLE, , "
HOLE, HOLE, HOLE, HOLE,
HOLE, HOLE, HOLE, HOLE,
HOLE, HOLE, HOLE, HOLE,

'm',
'.',
HOLE,
HOLE,
HOLE,
HOLE,

,,

,,

'\r',
HOLE,
HOLE,
HOLE,
HOLE,

HOLE,
HOLE,
HOLE,
HOLE,
HOLE,

,,

.,

'I',
HOLE,
HOLE,
HOLE,
HOLE,
IDLE,

};
'* Shifted keyboard table for "VT100 style" *'
static struct keymap' keytab_vt_uc - {
,. 0 *,HOLE, BUCKYBITS+ SYSTEMBIT,
HOLE, HOLE, HOLE, HOLE, HOLE, HOLE,
'* 8 ·,HOLE, HOLE, STRING+ UPARROW,
STRING+ DOWNARROW,
STRING+LEFTARROW,
STRING+ RIGHTARROW,
HOLE, TF(l),
TF(2), TF(3), TF(4), c('l'), 'I',
'0',
':/1:',
'.',

48·'*'
,.''** 56·'
40

''*·64·'*'

'01'.'
70,

,A, ,

,~,

c('H'), BUCKYBITS+ METABIT,

'Q',
'W',
'0', '-" 'P',
',',

80

'·104·'

,*112 *'
'·120·'

'E',
'{',

'*'

'7"
'R',
'}',

'(',

')' ,

,,
-,

'+',

'8',
'T',

'9',

'-' ,

'\t',

'yI,

Ox7F~

'4',

'V',
'5',

'I' ,
'6',

SHIFTKEYS+ LEFTCTRL,
SHIF'TKEYS+ CAPSLOCK,
'A',
'S' ,
'D',
'F',
'G',
'.'. ,
'J',
'K',
'L',
'\r',
'''',
'I',
Nap, NOSCROLL,
'3',
'2',
SHIFTKEYS+ LEFTSHIFT,

'H',

'1',

72

'** 88·'*'
',·96*,

,oc."
0..'

'Z',

'C',

'V',

'B',

'N',

SHIFTKEYS+ RIGHTSHIFT I
'\n',
'O'~
HOLE,
HOLE, HOLE, , "
HOLE,
HOLE, HOLE, HOLE, HOLE,
HOLE, HOLE, HOLE, HOLE,
HOLE, HOLE, HOLE, HOLE,

'M',

'<',

'>',

'X',
'?'
.,

'.',
HOLE,
HOLE,
HOLE,
HOLE,

'\r',
HOLE,
HOLE,
HOLE,
HOLE,

HOLE,
HOLE,
HOLE,
HOLE,
HOLE,

HOLE,
HOLE,
HOLE,
HOLE,
IDLE,

};

-

--

,

'* Caps Locked keyboard table tor "VT100 style" */
static struct keymap keytab_vt_c1 = {
'* 0 *,HOLE, BVCKYBITS+ SYSTEMBIT,
HOLE, HOLE, HOLE, HOLE, HOLE, HOLE,
'* 8 *,HOLE, HOLE, STRING+ UPARROW,

Sun Release 1.1

Last change: 19 March 1984

37

''**
'*
'''***
''**
''**
'*

KBD(5)

FILE FORMATS

KBD( 5)

16

24
32
40
48
56

64

72
80
88

*'*'*'
*'*'*'
*'*'
*'*'
*'

96 *'
,*104
,*112 *'
,*120 *'

STRING+ DOWNARROW,
STRING+ LEFTARROW,
STRING+ RIGHTARROW,
HOLE, TF(l),
'3',
'4',
'2',
'1',
TF(4),
c('['),
TF(3),
TF(2),
'.'
'0',
'7',
'9',
'8',
- ,
'5',
'6',
'-'
II'
c('H'), BUCKYBITS+ METABIT,
,
'.' ,
'9',
'7',
'8',
'\t',
'1',
'U',
'T',
'Y',
'E',
'R',
'W',
'Q',
'6',
Ox7F, '4',
'5',
'P',
'0',
'['
,
'
J
'
,
,,,,
SHIFTKEYS+ LEFTCTRL,
SHIFTKEYS+ CAPSLOCK,
'G',
'S',
'F',
'A',
'D',
'K',
'L',
'J',
'.', ,
'H',
'\r',
'\",
'\\',
'3',
NOP, NOSCROLL,
'2',
'1',
SHIFTKEYS+ LEFTSHIFT,
'X',
,'Z',
.,,
'C',
'V',
'B',
'N',
'M',
',',
'I',
SHIFTKEYS+ RIGHTSHIFT,
'\n',
'0',
HOLE, '.',
'\r',
HOLE, HOLE,
HOLE, HOLE, ",
HOLE, HOLE, HOLE, HOLE, HOLE,
HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE,
HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE,
HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, IDLE,

};
'* Controlled keyboard table for "VT100 style" *'
static struct keymap keytab_vt_ct == {
'* 0 *,HOLE, BUCKYBITS+ SYSTEMBIT,
HOLE, HOLE, HOLE, HOLE, HOLE, HOLE,
8 *,HOLE, HOLE, STRING+ UPARROW,
STRING+ DOWNARROW,
STRING+ LEFTARROW,
STRING+ RIGHTARROW,
HOLE, TF(I),
TF(2), TF(3), TF(4), c('('), '1',
c('a'), '3',
'4',
,~,
c('''') " '7'
'8' ,
'9' ,
'0' ,
c('_'), '-'
16
-,
v,
c(''''), c('H'), BUCKYBITS+ METABIT,
24
'.' ,
'7',
'8',
'9',
32
'\t',
CTRLQ,
c('W'), c('E'), c('R '), c('T'), c('Y'), c('U'), c('I'),
c('O'), c('P'}, c('('), c('J'), Ox7F, '4',
'5',
'6',
40
',',
48
SHIFTKEYS+ LEFTCTRL,
56
SHIFTKEYS+ CAPSLOCK,
c('A'), CTRLS,
c('D'), c('F'), c('G'),
c('H'}, c('J'), c('K'), c('L'), ':',
'''',
'\r',
c('\ \'),
'2';
64
'I',
'3',
NOP, NOSCROLL,
72
SHIFTKEYS+ LEFTSHIFT,
c('Z'), c('X'),
c('C'), c('V'), c('B'), c('N'), c('M'), ' ,',
'.',
c('_'),
80 */
SHIFTKEYS+ RIGHTSHIFT,
88
'\n',
'0',
HOLE, '.',
'\r',
HOLE, HOLE,
HOLE, HOLE, c(' '), HOLE, HOLE, HOLE, HOLE, HOLE,

'*

''**
'*
'''***
''**
''**
'*
38

96

*'*'
*'
*'*'*'
*'*'
*'
*'

Last change: 19 March 1984

Sun Release 1.1

FILE FORMATS

KBD(5)

'·104·'
'·112 .,
'·120·'

KBD( 5)

HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE,
HOLE, HOLE, HOLE,HOLE, HOLE, HOLE, HOLE, HOLE,
~~~~~~~~~~~~~~~~

};

,. "Key up" keyboard table for "VT100 style"

*'

static struct keymap keytab_vt_up = {
,. 0 ·,HOLE, BUCKYBITS+ SYSTEMBIT,
HOLE, HOLE, HOLE, HOLE, HOLE, HOLE,
,. 8 ·,HOLE, HOLE, Nap, NOP, NOP, NOP, HOLE, NOP,
,. 16·'
NOP, Nap, NOP, NOP, NOP, NOP, NOP, NOP,
'·24·'
NOP, NOP, NOP, NOP, NOP, NOP, NOP, NOP,
'·32·'
NOP, Nap, BUCKYBITS+ METABIT,
NOP, NOP, NOP, NOP, NOP,
NOP, NOP, NOP, NOP, NOP, NOP, NOP, NOP,
40·'
NOP, NOP, NOP, Nap, NOP, NOP, NOP, NOP,
NOP, SHIFTKEYS+ LEFTCTRL,
SHIFTKEYS+ CAPSLOCK,
NOP, NOP, NOP, NOP, NOP,
NOP, NOP, NOP, NOP, NOP, NOP, NOP, NOP,
'·64
NOP, NOP, NOP, NOP, NOP, SHIFTKEYS+ LEFTSHIFT,
NOP, NOP,
NOP, NOP, NOP, NOP, NOP, NOP, NOP, NOP,
,. 88·'
SHIFTKEYS+ RIGHTSHIFT,
NOP, NOP, HOLE, NOP, NOP, HOLE, HOLE,
HOLE, HOLE, NOP, HOLE, HOLE, HOLE, HOLE, HOLE,
/$ 96 .,
,*104
HOLE/HOLE, HOLE, HOLE, HOLE, HOLE,HOLE, HOLE,
,*112 ~,
HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE,
HOLE,HOLE,HOLE, HOLE, HOLE,HOLE, HOLE, RESET,
'·120 .,

,.,.'* 56·'
48·'

'·72·'*'
'·80 *'

*'

};
,. Index to keymaps for "VT100 style" keyboard .,
static struct keyboard keyindex_vt = {
&keytab_vt_lc,
&keytab_vt_uc,
&keytab_vt_cl,
&keytab_vt_ct,
&key tab_v t_u p,
CAPSMASK+ CTLSMASK,
Shirt keys that stay on at idle keyboard .,
OxOOOO,
,. Bucky bits that stay on at idle keyboard .,
1,
59,
,. abort keys .,

'*

};

, •••••**.******************************************* ••** •••••••••••••••••••• ,

/*

Index table for the whole shebang

.,

,.*•••*•••••••••••••••••••••••***** •• *••••••••••••••• *••••••** •••••• *••••••• ,

'*

int nkeytables = 3;
max 16
struct keyboard ·keytables[] = {
&keyindex_ms,
&keyindex_vt.

Sun Releasr 1.1

*'

Last change: 19 March 1984

39

FILE FORMATS

KBD( 5)

KBD(5)

};

1*

Keyboard String Table
This defines the strings sent by various keys (as selected in the
tables above).

*1
#define kstescinit(c)
{,\033', '[', 'c', '\O'}
char keystringtab[16J[KTAB_STRLEN] =
kstescinit(H) I*home* I ,
kstescinit(A) /*up* I,
kstescinit(B) I*down* I,
kstescinit(D) I*left* I,
k~tescinit(C) I*right* I,

r

};

SEE ALSO

cons(4S)
BUGS

This keyboard translation implementation is essentially the PROM monitor mechanism moved
into the kernel. It will almost certainly be reworked in the future to take advantage of the
greater. flexibility available to the kernel that was not available in the PROM.

40

Last change: 19 March 1984

Sun Release 1.1

MTAB(5)

FILE FORMATS

MTAB(5)

NAME

mtab - mounted file system table
SYNOPSIS

#lnclude 
#lnclude 
DESCRIPTION
MttJb resides in directory / etc and contains a table of devices mounted by the mount command.
Umount removes entries.

The table is a series or mttJb structures, as defined in < mtab.h>. Each entry contains the nullpadded' name of the place where the special file is mounted, the null-padded name of the special
file, and a type field, one of those defined in . The special file has all its directories
stripped away; that is, everything through the last'/, is thrown away. The type field indicates if
the file system is mounted read-only, read-write, or read-write with disk quotas enabled.
This table is present only 80 people can look at it. It does not matter to mount if there are duplicated entries nor to umount it a name cannot be found.
FILES

/etc/mtab
SEE ALSO
mount(8)

Sun Release 1.1

Last change: 26 June 1983

41

FILE FORMATS

NETWORKS ( 5 )

NETWORKS ( 5 )

NAME

networks - network name data base
DESCRIPTION
The network8 file contains information regarding the known networks which comprise the DARPA
Internet. For each network a single line should be present with the following information:

official network name
network number
aliases
Items are separated by any number of blanks and/or tab characters. A ":f/:" indicates the beginning of a comment; characters up to the end of the line are not interpreted by· routines which
search the file. This file is normally created Crom the official network data base maintained at the
Network InCormation Control Center (NIC), though local changes may be required to bring it up
to date regarding unofficial aliases and/or unknown networks.
Network number may be specified in the conventional "." notation using the ineCnetworl() routine from the Internet address manipulation library, inet(3N). Network names may contain any
printable character other than a field delimiter, newline, or comment character.
FILES

/ etc /networks
SEE ALSO
getnetent(3N)
BUGS

A name server should be used instead of a static file. A binary indexed file format should be
available for fast access.

42

Last change: 15 January 1983

Sun Release 1.1

FILE FORMATS

NEWS(S)

NEWS(5)

NAME
news - USENET network news article, utility files
DESCRIPTION
There are two formats of news articles: A and B. A format is the only format that version 1 netnews systems can read or write. Systems running the version 2 netnews can read either format
and tllere "re provisions for the version 2 netnews to write in A format. A format looks like this:

Aarticle-ID
new,group8
path
date
title
Bodll 0/ article
Only venio.. ~ netnews systems can read and write Bformat. B format contains two extra pieces
of information: receival date and expiration date. The basic structure of a B format file consists
of a series of headers and then the body. A header field is defined as a line with a capital letter in
the 1st column and a colon somewhere on the line. Unrecognized header fields are ignored. News
is store4 in the (lame format transmitted, see "Standard for the Interchange of USENET Messages" for a full description. The following fields are among those recognized:
Header

Information

From.
NeWSlroup..
Meaaqe-m.
Subject.
Dat.

userGhod.domain{.domain ...J (Full Name)
NewI,roupl
< Unigue Identifier>
descriptive title
Date POlted

Date-Received.
Explr_.

Reply-To.
Reterenc...
Controb

Date received on lo.cal machine
. Ezp(ration Date
Addre88/or mail repliel
Article ID 0/ article thil il
Tezt 0/ a control me88ale

Here is an example or an article:
Relay.Version: B 2.10 2/13/83 cb08gd.UUCP
P08ti.. I·Veraion: B 2.10 2/13/83 eagle.UUCP
Path: cbosgd!mhuxj!mhuxt!eagle!jerry
From: jerryGeagle.uucp (Jerry Schwarz)
Newsgroups: net.general
Subject: U8enet Etiquette - Please Read
Message-ID: <642Qeag)e.UUCP>
Date: Friday, 19-Nov-82 16:14:55 EST
Followup-To: net.news
Expires: Saturday, 1-Jan-83 00:00:00 EST
Date-Received: Friday, 19-Nov-82 16:59:30 EST
Organization: Bell Labs, Murray Hill
The body of the article comes here, after a blank line.

Sun

Rele~,

·r

1.1

Last change: 6 January 1984

43

FILE FORMATS

NEWS ( 5)

NEWS(5)

A 81/8 file line has four fields, each seperated by colons:

81/8tem-name:8ubscription8:flags:tran8mis8ion command
OC these fields, on the 81/8tem-name and 8ubscription8 need to be present.
The 81/8tem name is the name oC the system being sent to. The 8ubscription8 is the list of new~
groups to be transmitted to the system. The flags are a set of letters describing how the article
should be transmitted. The deCault is B. Valid flags include A (send in A format), B (send in B
Cormat), N (use ihave/sendme protocol), U (use uux -c and the name ot the stored article in a %s
string).
The tran8mi88ion command is executed by the shell with the article to be transmitted as the standard input. The default is Umt - -s -r 81/8name!rnewl. Some examples:

xyz:net.all
oldIYI:net.all,fa.all,to.oldIYI:A
berklYlznet.all,ueb.allu/ulr/Ub/newl/lendnewl -b berklYlrnewl
arpaaYI:net.all,arpa.alln/ulr /Ub/newi/aendnewl -a rn8WlaarpalYI
oldZ:net.all,fa.alllAz/ulr/Ub/iendnewl -0 oldZrnewl
ulerda.lf-loverlnmaU uler
Somewhere in a SI/' file, there must be a line Cor the host system. This line has no flag. or commands. A as the first character in a line denotes a comment.
The history, active, and ngflle flies have one line per item.

*

SEE ALSO

inews(I), p08tnew8(1), sendnews(8), uurec(8), readnews(l)

44

Last change: 6 January 1984

Sun Release 1.1

FILE FORMATS

NEWSRC(5)

NEWSRC(5)

NAME
newsre - information file for readnews{l) and ehecknews{l)

DESCRIPTION
The .neW8rc file contains the list of previously read articles and an optional options line for readnew8(1) and checknew8(1). Each newsgroup that articles have been read from has a line of the
form:
.m newsgroup : " range"
R Gnge is a list of the articles read. It is basically a list of numbers separated by commas with
sequential numbers collapsed with hyphens. For instance:
lenerall 1-78,80,85-00

ta.lnto-epmll-7
net.newIII
la.lnlo-vaxl 1-5
If the: is replaced with an ! (as in info-vax above) the newsgroup is not subscribed to and is not
be shown to the user.
An options line starts with the word options (left-justified). Then there are the list of options
j'lst as they would be on the command line. For instance:

options -n aU lta••I-lover. Ita.human-net. -r
options -e -r
A string of lines beginning with a space or tab after the initial options line are considered continuation lines.

FILES
-,.newsrc

options and list of previously read articles

SEE ALSO
readnews{l), ehecknews(l)

Sun Release 1.1

Last change: 6 January 1984

45

PASSWD(5)

FILE FORMATS

PASSWD(5)

NAME

passwd - password file
DESCRIPTION
P088Wd contains for each user the following information:

name (login name, contains no upper case)
encrypted password
numerical user ID
numerical group ID
user's real name, office, extension, home phone.
initial working directory
program to use as Shell
The name may contain' &', meaning insert the login name.
The password file is an ASCII tlle. Each field within each user's entry is separated from the next
by a colon. Each user is separated from the next by a new-line. If the password field is null, no
password is demanded; if the Shell field is null, I bin/,/a is used.
The password file resides in directory lete. Because of the encrypted passwords, it can and does
have general read permission and can be used, for example, to map numerical user ID's to names.
Appropriate precautions must be taken to lock the file against changes if it is to be edited with a
text editor; vipw(8) does the necessary locking.
FILES

letc/passwd
SEE ALSO
getpwent(3), 10gin(I), crypt(3), passwd(I), group(5), vipw(8), adduser(8)
BUGS

A binary indexed file format should be available for fast access.
User information (name, office, etc.) should be stored elsewhere.

46

Last change: 13 June 1983

Sun Release 1.1

PHONES (5)

FILE FORMATS

PHONES ( 5)

NAME
phones - remote host phone number data base

DESCRIPTION
The file /etc/phones contains the system-wide private phone numbers for the tip(IC) program.
This file is normally unreadable, and so may contain privileged information. The format of the
file is a series of lines of the form: [ \t]*. The system name is
one of those defined in the remote(5) file and the phone number is constructed from [0123456789=*%J. The "=" and "*,, characters are indicators to the auto call units to pause and wait for a
second dial tone (when going through an exchange). The "=" is required by the DF02-AC and
the "*,, is required by the BIZC01\1P 1030.
Only one phone number per line is permitted. However, if more than one line in the file contains
the same system name tip(lC) will attempt to dial each one in turn, until it establishes a connection.

FILES

/ etc I phones

SEE ALSO
tip(lC), remote(S)

SUD

Release 1.1

Last change: 15 January 1983

47

PLOT(5)

FILE FORMATS

PLOT( 5)

NAME

plot - graphics interface
DESCRIPTION
Files of this format are produced by routines described in plot(3X), and are interpreted for various
devices by commands described in plot(IG). A graphics file is a stream or plotting instructions.
Each instruction consists or an ASCII letter usually rollowed by bytes or binary inrormation. The
instructions are executed in order. A point is designated by four bytes representing the x and y
values; each value is a signed integer. The last designated point in an I, m, D, or p instruction
becomes the 'current point' for the next instruction.

Each of the following descriptions begins with the name of the corresponding routine in plot(3X).
m move: The next rour bytes give a new current point.
D

cont: Draw a line from the current point to the point given by the next rour bytes. See

plot(IG).
p

point: Plot the point given by the next four bytes.

I

line: Draw a line from the point given by the next rour bytes to the point given by the rollowing four bytes.

t

label: Place the following ASCII string so that its first character ralls on the current point.
The string is terminated by a newline.

a

arc: The first rour bytes give the center, the next four give the starting point, and the last rour
give the end point or a circular arc. The least significant coordinate of the end point is used
only to determine the quadrant. The arc is drawn counter-clockwise.

c

circle: The first four bytes give the center of the circle, the next two the radius.

e

erase: Start another rrame or output.

t

linemod: Take the"rollowing string, up to a newline, as the5~y~e 19r drawing further lines.
The styles are 'dotted,' 'solid,' 'longdashed,' 'shortdashed,' and 'dotdashed.' Effective only in
plot 4014 and plot ver.

•

space: The next four bytes give the lower left corner or the plotting area; the rollowing four
give the upper right corner. The plot will be magnified or reduced to fit the device as closely
aa possible.
Space settings that exactly fill the plotting area with unity scaling appear below ror devices
supported by the filters of plot(IG). The upper limit is just outside the plotting area. In
every case the plotting area is taken to be square; points outside may be displayable on devices whose face isn't square.
4014
space(O~ 0, 3120,
ver
space(O, 0, 2048,
300, 300s space(O, 0, 4096,
450
space(O, 0, 4096,

3120);
2048);
4096);
4096);

SEE ALSQ
plot(IG), plot(3X), graph(IG)

48

Last change: 15 January 1983

Sun Release 1.1

FILE FORMATS

PRINTCAP ( 5 )

PRINTCAP ( 5 )

NAME
printcap - printer capability data base
SYNOPSIS
/etc/printcap
DESCRIPTION

PrintclJp is a simplified version of the termclJp(5) data base for describing printers. The spooling
system accesses the printclJp file every time it is used, allowing dynamic addition and deletion or
printers. Each entry in the data base describes one printer. This data base may not be substituted for, as is possible for termclJp, because it may allow accounting to be bypassed.
The default printer i.s normally Ip, though the environment variable PRINTER may be used to
override this. Each spooling utility support! a -P printer option to explicitly name a destination
printer.
Refer to the Line Printer Spooler MlJnual in the Sun SY8tem MlJnager'e ManulJI ror a discussion of
how to set up the database for a given printer.
Each entry in the printcap file describes a printer, and is a line consisting of a number or fields
separated by':! characters. The first entry for each printer gives the names which are known ror
the printer, separated by 'I' characters. The first name is conventionally a number. The second
name given is the most common abbreviation for the printer, and the last name given should be a
long name fully identifying the printer. The second name should contain no blanks; the last
name may well contain blanks for readability. Entries may continue onto multiple lines by giving
a \ as the last character of a line, and empty fields may be included for readability.
Capabilities in printcap are all introduced by two-character codes, and are of three types:

Boolean
Numeric

String

capabilities indicate that the printer has some particular feature. Boolean capabilities
are simply written between the ':' characters, and a~e indicated by the word 'boor in
the type column of the capabilities table below.
capabilities supply information such as baud-rates, number of lines per page, and so
on. Numeric capabilities are indicated by the word 'num' in the type column of the
capabilities table below. Numeric capabilities are given by the two-character capability code followed by the '#' character) followed by the numeric value. For example:
:br*1200: is 3 numeric entry stating that this printer should run at 1200 baud.
capabilities give a sequence which can be used to perform particular printer operations
such as cursor motion. String valued capabilities are indicated by the word 'str' in the
type column of the capabilities table below. String valued capabilities are given by
the two-character capability code followed by an '=' sign and then a string ending at
the next foUowinl ':'. For example, :rp=spinwriter: is a sample entry stating that
the remote printer is named 'spinwriter'.

OAPABILITIES

Name

Type

Default

Description

af
br
ct
df
du
fc

str
num
str
str
str
num
str
bool
num
str
bool

NULL
none
NULL
NULL

name of accounting file
if Ip is a tty, set the baud rate (ioctl call)
ciCplot data filter
TeX data filter (DVI format)
User ID of user 'daemon'.
if Ip is a tty, clear fiag bits (sgtty.h)
string to send for a form feed
print a form feed when device is opened
like 'fe' but set bits
graph data filter (plot (3X) format)
driver supports (non standard) ioctl

tr
fo
rs
If
ic

SUD

Releaer 1.1

0

0

"\!"
false
0

NULL
false

Last change: 20 December 1983

49

FILE FORMATS

PRINTCAP( 5)

if
If
10
Ip
mc
mx
nd
nf
of
pi
pw
px
py
rf
rm
rp
rs
rw
sb
sc
sd

sf
sh
st
tf
tr
vf
xc
X8

str
str
str
str
num
num
str
str
str
num
num
num
num
str
str
str
bool
bool
bool
bool
str
bool
bool
str
str
str
str
num
num

NULL
" / dev / console"
"lock"
"/dev /lp"
0
1000
NULL
NULL
NULL
66
132
0
0
NULL
NULL
"Ip"
false
false
false
false
"/usr/spool/lpd"
false
false
"status"
NULL
NULL
NULL
0
0

PRINTCAP ( 5 )

call for indenting printout
name of text filter which does accounting
error logging file name
name of lock file
device name to open for output
maximum number of copies
maximum file size (in BUFSIZ blocks), zero = unlimited
next directory for list of queues (unimplemented)
ditroff data filter (device independent troff)
name of output filtering program
page length (in lines)
page width (in characters)
page width in pixels (horizontal)
page length in pixels (vertical)
filter for printing FORTRAN style text files
machine name for remote printer
remote printer name argument
restrict remote users to those with local accounts
open printer device read/write instead of read-only
short banner (one line only)
suppress multiple copies
spool directory
suppress form feeds
suppress printing of burst page header
status file name
troff data filter (cat phototypesetter)
trailer string to print when queue empties
raster image filter
if Ip is a tty, clear local mode bits (tty (4))
like 'xc' but set bits

Error messages sent to the console have a carriage return and a line feed appended to them,
rather than just a line feed.

It the local line printer driver supports indentation, the daemon must understand how to invoke
it.
SEEALSQ
termcap(5), Ipc(8), Ipd(8), pac(8), Ipr(I), Ipq(l), Iprm(l)
The Line Printer Spooler Manual in the Sun System Manager's Manual.

50

Last change: 20 December 1983

Sun Release 1.1

F~EFORMATS

PROTOCOLS ( 5 )

PROTOCOL S ( 5 )

NAME
protocols - protocol name data base
SYNOPSIS

I ete/protocoJa

DESCRIPTION
The protocol, file contains information regarding the known protocols used in the DARPA Internet. For each protocol a single line should be present with the following information:
official protocol name
protocol number
aliases
Items are separated by any number of blanks and/or tab characters. A ":#" indicates the beginning of a comment; characters up to the end of the line are not interpreted by routines which
search the file.
Protocol names may contain any printable character other than a field delimiter, newline, or comment character.
EXAMPLE
The following example is taken from the Sun UNIX system.

''**

Internet (IP). protocols

*ip
icmp
ggp
tcp
pup
udp

o

IP

1

ICMP

2
6

12
17

GGP

TCP
PUP
UDP

:# internet protocol, pseudo protocol number
:# internet control message protocol

'*

gateway-gateway protocol

:# transmission control protocol
:# PAR C universal packet protocol
:# user datagram protocol

FILES
/ etc /protocols
SEE ALSO
getprotoent(3N)

BUGS
A name se"er should be used instead of a static file. A binary indexed file format should be
available for fast accellS.

Sun Release 1.1

Last change: 13 December 1983

51

REMOTE(5)

FILE FORMATS

REMOTE(5)

NAME

remote - remote host description file
DESCRIPTION

The systems known by tip(IC) and their attributes are stored in an ASCD file which is structured
somewhat like the termcap(5) file. Each line in the file provides a description for a single system.
Jf;'ields are separated by a colon (":"). Lines ending in a \ character with an immediately followi~g newline are continued on the next line.
The first entry is the name(s) of the host system. If there is more than one name tor a system,
the names are separated by vertical bars. After the name of the system comes the fields of the
description. A field name followed by an '==' sign indicates a string value follows. A field name
followed by a '#' sign indicates a following numeric value.
Entries, named "tip·" and "cu·" are used as default entries by tip, and the cu interface to tip, as
follows. When tip is invoked with only a phone number, it looks for an entry of the form
"tip300", where 300 is the baud rate with which the connection is to be made. When the cu
interface is used, entries of the form "cu300" are used.
CAPABILITIES

Capabilities are either strings (str), numbers (num), or boolean flags (bool). A string capability is
specified by capabiIUy=value; e.g. "dv=/dev/harris". A numeric capability is specified by
capability#value; e.g. "xa#99". A boolean capability is specified by simply listing the capability.

52

at

(str) Auto call unit type.

bl"

(num) The baud rate used in establishing a connection to the remote host. This is a
decimal number. The default baud rate is 300 baud.

em

(str) An initial connection message to be sent to the remote host. For example, if a host
is reached through port selector, this might be set to the appropriate sequence required to
switch to the host.

cu

(str) Call unit if making a phone call. Default is the same as the 'dv' field.

dl
du

(8tr) Disconnect message sent to the host when a disconnect is requested by the user.

dv

(str) UNIX device(s) to open to establish a connection. If this file refers to a terminal line,
tip(lC) attempts to perform an exclusive open on the device to insure only one user at a
time has access to the port.

el

(str) Characters marking an end-of-line. The default is NULL. ,-, escapes are only recognized by tip after one of the characters in 'el', or after a carriage-return.

t.

(str) Frame size for transfers. The deCault frame size is equal to BUFSIZ.

hd

(bool) The host uses half-duplex communication, local echo should be performed.

Ie

(str) Input end-of-file marks. The default is NULL.

oe

(str) Output end-of-file string. The default is NULL. When tip is transferring a file, this
string is sen t at end-of-file.

pa

(str) The type of parit; to use when sendillg data to the host. This may be one of
"even", "odd " , "none", "zero" (always set bit 8 to zero), "one" (always set bit 8 to 1).
The default is even parity.

pn

(str) Telephone number(s) for this host. If the telephone number field contains an a sign,
tip searches the file / etc/phones file for a list of telephone numbers; c.t. phoncs(5).

te

(str) Indicates that the list or capabilities is continued in the named description. This is
used primarily to share common capability inrormation.

(bool) This host is on a dial-up line.

Last change: 1 March 1983

Sun Release 1.1

REMOTE(5)

FILE FORMATS

REMOTE(5)

Here is a short example showing the use of the capability continuation feature:
UNIX-1200: \
:dv=/dev/cauO:el="D"U"C"S"Q"O@:du:at=ventel:ie=#$%:oe="D:br#1200:
arpavaxlax:\
:pn=7654321%:tc=UNIX-I200
FILES
/etc/remote
SEE ALSO
tip(IC), phones(5)

Sun Release 1.1

Last change: 1 March 1983

53

SCCSFILE ( 5 )

FILE FORMATS

SCCSFILE ( 5 )

NAME
sccsfile - format of sees file
DESCRIPTION

An sees file is an ASen file. It consists of six logical parts: the checksum, the delttJ ttJ61e (contains information about each delta), user names (contains login names and/or numerical group
IDs of users who may add deltas), flags (contains definitions of internal keywords), comments
(contains arbitrary descriptive information about the file), and the 60dU (contains the actual text
lines intermixed with control lines).
Throughout an sees file there are lines which begin with the ASCll SOH (start of heading) character (octal (01). This character is hereafter referred to 38 the control character and will be
represented graphically as O. Any line described below which is not depicted 38 beginning. with
the control character is prevented from beginning with the control character.
Entries of the form DDDDD represent a five digit string (a number between 00000 and 99999).
Each logical part of an

sees file is described in detail below.

Checksum
The checksum is the first line of an

sees file.

The form of the line is:

@hDDDDD

The value of the checksum is the sum of all characters, except those of the first line. The
Oh provides a magic number of (octal) 064001.

DelttJ table
The delta table consists of a variable number ot entries of the form:
eSDDDDD/DDDDD/DDDDD
ad   yr/mo/da hr:mi:se DDDDD DDDDD
Ol DDDDD •••
@x DDDDD •••
el DDDDD •••
am 

ac 

•••

ae
The first line (@s) contains the number of lines inserted/deleted/unchanged respectively.
The second rine (@d) contains the type of the delta (currently, normal: D, and removed:
R), the sees ID of the delta, the date and time of creation of the delta, the login name
corresponding to the real user ID at the time the delta was created, and the serial
numbers of the delta and its predecessor, respectively.
The @l, ax, and @s lines contain the serial numbers of deltas included, excluded, and
ignored, respectively. These lines are optional.
The @m lines (optional) each contain one MR number associated with the delta; the Oc
lines contain comments associated with the delta.
The @e line ends the delta table entry.

54

Last change: 15 March 1983

Sun Release 1.1

FILE FORMATS

SCCSFILE( 5)

SCCSFILE( 5)

UBer nomeB
The list of login names and/or numerical group IDs of users who may add deltas to the
file, separated by new-lines. The lines containing these login names and/or numerical
group IDs are surrounded by the bracketing lines @u and au. An empty list allows anyone to make a delta.
Flog'
Keywords used internally (see odmin(l) for more inCormation on their use). Each flag line
takes the form:

or 



The following flap are defined:
or t < type of program>
or v 

Ori
Orb
Gtm

Otd




< default-sid>

atn
otj
at I
Of q




atf
atc

The t flag defines the replacement for the identification keyword. The v flag controls
prompting for MR numbers in addition to comments; if the optional text is present it
defines an MR number validity checking program. The i flag controls the warning/error
aspect of the "No id keywords" message. When the I flag is not present, this message is
only a warning; when the I flag is present, this message will cause a "fatal" error (the file
will not be gotten, or the delta will not be made). When the b flag is present the -b
key letter may be used on the get command to cause a branch in the delta tree. The m
flag defines the first choice for the replacement text of the sccsflle.5 identification keyword. The r flag defines the "floor" release; the release below which no deltas may be
added. The e flag deflnes the "ceiling" release; the release above which no deltas may be
added. The d flag defines the default SID to be used when none is specified on a get command. The D flag causes delta to insert a "null" delta (a delta that applies no changes)
in those releases that are skipped when a delta is made in a new release (for example,
when delta 5.1 is made after delta 2.7, releases 3 and 4 are skipped). The absence of the
D 8ag causes skipped releases to be completely empty. The J flag causes get to allow concurrent edits of the same base SID. The 1 flag defines "a list of releases that are locked
against editing (get(!) with the -e keyletter). The q flag defines the replacement for the
%Q% identification keyword.
Comment,

Arbitrary text surrounded by the bracketbig lines @t and
typically will contain a description of the file's purpose.

aT. The comments section

Body

The body consists of text lines and control lines. Text lines don't begin with the control
character, control lines do. There are three kinds of control lines: insert, delete, and end,
represented by:
CIIDDDDD

SUD

Release 1.1

Last change: 15 March 1983

55

FaEFORMATS

SCCSFaE( 5)

SCCSFaE(5)

QD DDDDD
QE DDDDD

respectively. The digit string is the serial number corresponding to the delta for the controlline.
SEE ALSO

admin(I), delta(I), get(I), prs(I).
Source Code Control Syatem User's Guide by L. E. Bonanni and C. A. Salemi.

56

Last change: 15 March 1983

SUD

Release 1.1

FILE FORMATS

SERVERS (5)

SERVERS ( 5)

NAME

servers - inet server data base
DESCRIPTION
The servers file contains the list of servers that inetd(8) operates. For each server a single line
should be present with the following information:

name of server
protocol
server location
Items are separated by any number of blanks and/or tab characters. A "#" indicates the beginning of a comment; characters up to the end or the line are not interpreted by routines which
search the file.
The name of the server should be the official service name as contained in serviCt8(5). The protocol entry is either udp or tcp. The server location is the full path name of the server program.
EXAMPLE
The following example is taken from the Sun UNIX system.

tcp
telnet
shell
login
exec
ttcp
syslog
coinsat
talk
time

tcp
tcp
tcp
tcp
tcp
udp
udp
udp
udp
tcp

/usr/etc/in.tcpd
/usr/ etc lin. telnetd
/etc/in.rshd
/etc/in.rlogind
/usr/etc/in.rexecd
/usr/etc/in.ttcpd
/usr/etc/in.syslog
/usr/etc/in.comsat
/usr/etc/in.talkd
/usr/etc/in.timed

FILES

/etc/servers
SEE ALSO

services(5), inetd(8)

Sun Release 1.1

Last change: 13 December 1983

57

SERVICES ( 5 )

FILE FORMATS

SERVICES (5)

NAME

services - service name data base
SYNOPSIS
/ ete/ael'vleea
DESCRIPTION
The services file contains inCormation regarding the known services available in the DARPA Inter-

net. For each service a single line should be present with the following information:
official service name
port number
protocol name
aliases
Items are separated by any number of blanks and/or tab characters. The port number and protocol name are considered a single item; a "/" is used to separate the port and protocol (for
instance, "512/tcp"). A ":J/:" indicates the beginning of a comment; characters up to the end of
the line are not interpreted by routines which search the file.
Service names may contain any printable character other than a field delimiter, newline, or comment character.
EXAMPLE

Here is an example of the / etc/service, file from the Sun UNIX System.

:J/:
:J/: Network services, Internet style

*

echo
discard
systat
daytime
netstat
ftp
tel net
smtp
time
name
whois
mtp

7/udp
g/udp
II/tcp
13/tcp
15/tcp
21/tcp
23/tcp
25/tcp
37/tcp
42/tcp
43/tcp
57/tcp

sink null

mail
timserver
nameserver

:# deprecated

:J/:
#- Host specific functions
:J/:
trtp
rje
finger
link
supdup

69/udp
77/tcp
7g/tcp
87/tcp
95/tcp

tty link

:J/:
:#= UNIX specific services

:J/:
exec
login
shell
eCs
biff
who

58

512/tcp
513/tcp
514/tcp
520/tcp
512/udp
513/udp

Last change: 13 December 1983

cmd
comsat
whod

Sun Release 1.1

SERVICES ( 5 )

8Y810g
talk
route

FILE FORMATS

514/udp
517/udp
520/udp

SERVICES (5)

router routed# 521 also

FILES
/etc /services
SEE ALSO
getservent(3N)

BUGS
A name server should be used instead of a static file. A· binary indexed file· format should be
available forrast access.

SUD· Release

1.1

Last change: 13 December 1983

59

FILE FORMATS

TAR (5)

TAR(5)

NAME

tar - tape archive file format
DESCRIPTION

Tar, (the tape archiv~ command) dumps several files into one, in a medium suitable for transportation.
A "tar tape" or file is a series of blocks. Each block is of size TBLOCK. A file on the tape is
represented by a header block which describes the file, followed by zero or more blocks which give
the contents of the file. At the end of the tape are two blocks filled with binary zeros, as an endof-file indicator.
The blocks are grouped for physical I/O operations. Each group of n blocks (where n is set by
the b keyletter on the tar(l) command line - default is 20 blocks) is written with a single system
call; on nine-track tapes, the result of this write is a single tape record. The last group is always
written at the full size, so blocks after the two zero blocks contain random data. On reading, the
specified or default group size is used for the first read, but if that read returns less than a full
tape block, the reduced block size is used for further reads, unless the B key letter is used.
The header block looks like:
#define TBLOCK
#define NAMSIZ

512
100

union hblock {
char dummy(TBLOCK);
struct header {
char name(NAMSIZ);
char mode(8);
char uid(8);
char gid(8);
char l!Iize(12);
char mtime(12J;
char chksum[8);
char linkflag;
char linkname(NAMSIZ);
} dbufj

};
Name is a null-terminated string. The other fields are zero-filled octal numbers in ASCII. Each
fleld (of width w) contains w-2 digits, a space, and a null, except size and mtime, which do not
contain the trailing null. Name is the name 01 the file, as specified on the tar command line.
Files dumped because they were in a directory which was named in the command line have the
directory name as prefix and / filename as suffix. Mode is the file mode, with the top bit masked
off. Uid and gid are the user and group numbers which own the file. Size is the size 01 the file in
bytes. Links and symbolic links are dumped with thil!! field specified as zero. Mtime is the
modification time of the file at the time it was dumped. Ohksum is a decimal ASCII value which
represents the sum 01 all the bytes in the header block. When calculating the checksum, the
chk8um field is treated as if it were all blanks. Linlcflag is ASCII '0' if the file is "normal" or a
special file, ASCII 'I' if it is an hard link, and ASCII '2' if it is a symbolic link. The name
linked-to, if any, is in linkname, with a trailing null. Unused fields of the header are binary zeros
(and are included in the checksum).
The first time a given i-node number is dumped, it is dumped as a regular file. The second and
subsequent times, it is dumped as a link instead. Upon retrieval, il a link entry is retrieved, but
not the file it was linked to, an error message is printed and the tape must be manually rescanned to retrieve the iinked-to file.

60

Last change: 15 January 1983

Sun Release 1.1

TAR(5)

FILE FORMATS

TAR (5)

The encoding of the header is designed to be portable across machines.
SEE ALSO
tar(l)
BUGS

Names or linknameslonger than NAMSIZ produce error reports and cannot be dumped.

Sun Release 1.1

Last change: 15 January 1983

61

FILE FORMATS

TERM(5 )

TERM(5)

NAME

term - terminal driving tables for nroff
DESCRIPTION

Nroff(l) uses driving tables to customize its output for various types of output devices, such as
printing terminals, special word-processing terminals (such as Diablo, Qume, or NEC Spinwriter
mechanisms), or special output filter programs. These driving tables are written as C programs,
compiled, and installed in /ulr/Hb/term/tabname , where name is the name for that terminal
type as given in term(7}.
Here's how to construct a driver table for USG UNIX "nroff", in 25 easy lessons. The only
changes for the V7 nroff (on 4.xBSD as well) are that the "iton" and "itoff" entries are missing,
the "bset" and "breset" entries affect the "S8-8a&S" word in the "S&tty" structure, and the pr~
cedures for making the table are different.
Special thanks to the people at AT&T responsible for the UNIX documentation, without whose
help this posting would not have been necessary. The structure of the tables is as follows:
*deflne

INCH

240

struct {
int bset;
int breset;
int Hor;
int Vert;
int Newline;
int Char;
int Em;
int Halftine;
int Adj;
char ·twinit;
char ·twrest;
char ·twnl;
char ·hlr;
char ·hlf;
char ·8r;
char ·bdon;
char ·bdoff;
char ·iton;
char ·itoff;
char ·ploton;
char ·plotoff;
char ·up;
char ·down;
char ·right;
char ·left;
char ·codetab[256-32J;
char ·zzz;
} t;

The meanings of the various fields are as follows:
baet

bits to set in the c_oftag field of the lermio structure (see 111/(4)) before output.

breset

bits to reset in the c_oftag field of the termio structure before output.
horizontal resolution in fractions of an inch.

Hor
Vert

62

vertical resolution in fractions of an inch.

Last change: 14 March 1984

Sun Release 1.1

TERM(5)

FILE FORMATS

TERM ( 5)

Newline

space moved by a newline (linefeed) character in fractions of an inch.

ChGr

quantum of character sizes, in fractions of an inch. (that is, a character is a multiple
of Char units wide)

Em
HGlfline

size of an em in fractions of an inch.

Adj

quantum of white space, in fractions of an inch. (that is, white spaces are a multiple
of Adj units wide)

space moved by a halt-linefeed (or half-reverse-linefeed) character in tractions of an
inch.

Note: it this is less than the size of the space character (in units of Char; see below for
how the sizes ot characters are defined), nroff will output fractional spaces using plot
mode. Also, if the -e switch to nroO is used, Adj is set equal to Hor by nroO.
set of characters used to initialize the terminal in a mode suitable for nroO.

twini'
'wrest
twnl

set of characters used to move down one line.

hlr

set of characters used to move up one-half line.

hU

set of characters used to move down one-half line.

fir
6don
6d08
iton
it 08
,Ioto,.

set of characters used to move up one line.

set of characters used to restore the terminal to normal mode.

set of characters used to turn on hardware boldface mode, if any.
set of characters used to turn off hardware boldface mode, if any.
set of characters used to turn on hardware italics mode, it any.
set of characters used to turn off hardware italics mode, if any.
.set of characters used to turn on hardware plot mode (for Diablo type mechanisms), it
any.

,10100

set of characters used to turn off hardware plot mode (tor Diablo type mechanisms), it
any.

up

set of characters used to move up one resolution unit (Vert) in plot mode, if any.

down

set of characters used to move down one resolution unit (Vert) in plot mode, if any.

right

set of characters used to move right one resolution unit (Hor) in plot mode, if any.

leI'

set of characters used to move left one resolution unit (Hor) in plot mode, it any.

coddGb

deflnitioQ of characters needed to print an nroJ! character on the terminal. The first
byte is the ~umber of character units (Char) needed to hold the character; that is,
"\001" is one unit wide, "\002" is two units wide, etc. The high-order bit (0200) is
on if the character is to be underlined in underline mode (.ul). The rest of the bytes
are the characters used to produce the character in question. If the character has the
sign (0200) bit on, it is a code to move the terminal in plot mode. It is encoded as:

zzz

Sun Release 1.1

0100 bit on-; --,

vertical motion.

0100 bit off

horizontal motion.

040 bit on

negative (up or left) motion.

040 bit off

positive (down or right) motion.

037 bits

number of such motions to make.

a zero terminator at the end.

Last change: 14 March 1984

63

TERM(S)

FILE FORMATS

TERM(S)

All quantities which are in units of fractions of an inch should be expressed as
INCH*num/denom, where num and denom are respectively the numerator and denominator of
the traction; that is, 1/48 of an inch would be written as "INCH/48".
If any sequence
as a null string.

ot characters does not pertain to the output device, that sequence should be given

The source code for the terminal name is in /ulr /Irc/cmd/text/roft.d/terma.d/tabname.e.
When a new terminal type is added, the file maketerml.c should be updated to '#include' the
source to that driving table; note that the various terminal types are grouped into "parts"
labelled PARTI, PARTI, and PART3. If necessary, more parts can be added. Other changes
necessary to maketerms.c are left as an exercise to the reader. The makefile lerm8.mk in that
directory should then be updated.
FILES

/usr/lib/term/tabname driving tables
tabname.c
source lor driving tables
SEE ALSO

troff( 1), term(7)

64

Last change: 14 March 1984

Sun Release 1.1

FILE FORMATS

TERMCAP(5)

TERMCAP(5)

NAME
termcap - terminal capability data base
SYNOPSIS
/etc/termcap
DESCRIPTION
TermctJp is a data base describing terminals, used, for example, by vi(1) and curses(3X). Terminals are described in termctJp by giving a set 01 capabilities which they have, and by describing
how opera.tions are performed. Padding requirements and initialization sequences are included in
termcDp.

Each entry in the termctJp file describes a terminal,and is a line consisting 01 a number of fields
separated by':' characters. The first entry Cor each terminal gives the names which are known
for the terminal, separated by 'I' characters. The first name is always 2 characters long and is
used by older version 6 systems which store the terminal type in a 16 bit word in a systemwide
da.ta base. The second name given is the most common abbreviation Cor the terminal, and the
last name given should be a long name Cully identifying the terminal. The second name should
contain no blanks; the last name may well contain blanks Cor readability. Entries may continue
onto multiple lines by giving a \ as the last character 01 a line, and empty fields may be included
for rea.dability.
Capabilities in termctJp are all introduced by two-character codes, and are of three types:
capabilities indicate that the terminal has some particular leature. Boolean capabilities are simply written between the ':' characters, and are indicated by the word 'bool'
in the type column of the capabilities table below.
Numeric capabilities supply inlormation such as the size 01 the terminal or the size 01 particular
delays. Numeric capabilities are indicated by the word 'num' in the type column of
the capabilities table below. Numeric capabilities are given by the two-character
character and then the numeric value. For examcapability code lollowed by the
ple: :eo,80: is a numeric entry stating that this terminal has 80 columns.
Strin,
capabilities give a sequence which can be used to perlorm particular terminal operations such as cursor motion. String valued capabilities are indicated by the word 'str'
in the type column ot the capabilities table below. String valued capabilities are
given by the two-character capability code lollowed by an '=' sign and then a string
ending at the next following ':'. For example, :ce=16\E"S: is a sample entry for
clear to end-ot-line.

Boolean

'*"

OAPABILITIES
(P)
indicates pads are destructive, magic so char (Teleray 1061)

The following entty, which describes the Concept-lod, is among the more complex entries in the
termctJp file as of this writing. This particular concept entry is outdated, and is used as an exam~,.
ple only.
cll clOO IconceptlOO:is=\EU\Ef\E7\E5\E8\EI\ENH\EK\E\200\Eo&\200:\
:aI=3*\E R:am:bs:cd=16*\E"C:ce=16\E"S:cI=2*"L:cm=\Ea%+ %+ :co#80:\
:dc=16\E A:dl=3*\E"B:ei=\E\200:eo:im=\E"P:in:ip=16*:li#24:mi:nd=\E=:\
:se=\Ed\Ee:so=\ED\EE:ta=8\t:ul:up=\E;:vb=\Ek\EK:xn:
Entries may continue,,4nto multiple lines by giving a \ as the last character of a line, and empty
fields may be included for readability (here between the last field on a line and the first field on
the next).
Type. of CapabUltle.
Capabilities in termctap are of three types: Boolean capabilities which indicate that the terminal
h36 some particular feature, numeric capabilities giving the size of the terminal or the size of particular. delays, and string capabilities, which give a sequence which can be used to perform particular terminal operatioos. All capabilities have two letter codes.
A

A

Boolean

Sun Release 1.1

~'""

.,-

capabilities .are introduced simply by stating the two-character capability code in the
field between C:' characters. For instance, the fact that the Concept has "automatic
margins" (t)lat is, an automatic return and linefeed when the end of a line is reached)
is indicated by the capability am. Hence the description of the Concept includes am.

Last change: 16 December 1983

67

FILE FORMATS

TERMCAP(5)

TERMCAP(5)

Numeric

capabilities are followed by the character ':/I:' and then the value. Thus eo which indicates the number of columns the terminal has gives the value '80' for the Concept.

String

valued capabilities, such as ee (clear to end of line sequence) are given by the two
character code, an '=', and then a string ending at the next following ':'. A delay in
milliseconds may appear after the '=' in such a capability, and padding characters are
supplied by the editor after the remainder of the string is sent to provide this delay.
The delay can be either a integer, for instance, '20', or an integer followed by an '*',
that is, '3*'. A '*' indicates that the padding required is proportional to the number
of lines affected by the operation, and the amount given is the per-affected-unit padding required. When a ,*, is specified, it is sometimes useful to give a delay of the
form '3.5' to specify a delay per unit to tenths of milliseconds.
A number of escape sequences are provided in the string valued capabilities for easy
encoding of characters there. A \E maps to an ESCAPE character, AX maps to a
control-x for any appropriate x, and the sequences \0 \r \t \b \f give a newline,
return, tab, backspace and formfeed. Finally, characters may be given as three octal
digits after a \, and the characters " and \ may be given as \" and \ \. If it is necessary to place a I in a capability it must be escaped in octal as \072. If it is necessary
to place a null character in a string capability it must be encoded as \ZOO. The routines which deal with termedp use C strings, and strip the high bits of the output very
late 80 t~at a ,\200 comes out 88 a \000 would.

Preparing Deserlptlon.
:-.....
We now outline how to prepare descriptions of terminals. The most effective way to prepare a
terminal description is by imitating the description of a similar terminal in termedp and to build
up a description gradually, using partial descriptions with ez to check that they are correct. Be
aware that a very unusual terminal may expose deficiencies in the ability of the termedp file to
describe it or bugs in ez. To easily test a new terminal description you can set the environment
variable TERMCAP to a pathname of a file containing the description you are working on and
the editor will look there rather than in I etcl termedp. TERMCAP can also be set to the termcap
entry itseIr to avoid reading the file when starting up the editor.
Basic eapabllltiel
.

i"

The nunther of totdmns on eacH lhlti for the terminal is given by the eo numeric capability. If
the terminal is a CRT, then the number of lines on the screen is given by the n capability. If the
terminal wraps around to the beginning of the next line when it reaches the right margin, then it
should have the am capability. If the terminal can clear its screen, then this is given by the e1
string capability. If the terminal can backspace, then it should have the bs capability, unless a
backspace is accomplished by a character other than "H (ugh) in which case you should give this
character as the be string capability. If it overstrikes (rather than clearing a position when a
character is struck over) then it should have the os capability.
"..:---

A very important point here is that the local cursor motions encoded in termcdp are undefined at
the left and top edges of a CRT terminal. The editor will never attempt to backspace around the
left edge, nor will it attempt to go up locally off the top. The editor assumes that feeding off the
bottom of the screen will cause the screen to scroll up, and the am capability tells whether the
cursor sticks at the right edge of the screen. If the terminal has switch selectable automatic margins, the termeDp file usually assumes that this is on, that is, am.
These capabilities suffice to describe hardcopy and "glass-tty" terminals. Thus the model 33 teletype is described as . ~.
t3i33i tty33:co#72:08
while the Lear Siegler ADM-3 is described as

68

Last change: 16 December 1983

Sun Release 1.1

TERMCAP(5)

FILE FORMATS

TERMCAP(5)

cll admSISllsi admS:am:bs:cI= AZ:1i#24:co#80
Cursor addreulns
Cursor addressing in the terminal is described by a cm string capability, with print!(SS) like
escapes %x in it. These substitute to encodings or the current line or column position, while
other characters are passed through unchanged. If the em string is thought or as being a function, then its arguments are the line and then the column to which motion is desired, and the %
encodings have the following meanings:
as in print/, 0 origin
like %2d
like %Sd
%.
like %c
%+ x adds z to value, then %.
% >xy if value > x adds y, no output.
%r
reverses order of line and column, no output
increments line/column (ror 1 origin)
%i
%%
gives a single %
%n
exclusive or row and column with 0140 (DM2500)
%B
BCD (16*(x/I0)) + (x% 10), no output.
Reverse coding (x-2*(x%16)), no output. (Delta Data).
%D

%d
. %2
%S

Consider the HP2645, which, to get to row 3 and column 12, needs to be sent \E&aI2c03Y padded for 6 milliseconds. Note that the order of the rows and columns is inverted here, and that
the row and column are printed as two digits.
Thus its em capability is
"cm=6\E&%r%2c%2Y". The Microterm ACT-IV needs the current row and column sent preceded by a AT, with the row and column simply encoded in binary, "cm=AT%.%.". Terminals
which use "%." need to be able to backspace the cursor (bs or be), and to move the cursor up
one line on the screen (up introduced below). This is necessary because it is not always safe to
transmit \t, \n AD and \1', as the system may change or discard them.

A final example is ttt~'LSI ADM-Sa, which uses row and column offset by a blank character, thus
"cm= \E=%+ %+ ".
Cursor mottons ~:<:
It the terminal can move the cursor one position to the right, leaving the character at the current
position unchanged, then this sequence should be given as nd (non-destructive space). It it can
move the cursor up a line on the screen in the same column, this should be given as up. If the
terminal has no cursor addressing capability, but can home the cursor (to very upper left corner
of screen) then this can be given as hOi similarly a fast way of getting to the lower left hand
corner can be given ~ U; this may involve going up with up from the home position, but the editor will never do this itself (unless n does) because it makes no assumption about the effect of
moving up from tile home position.
Area clears
If the terminal can clear from the current position to the end of the line, leaving the cursor where
it is, this should be gi!~n as ee. It the terminal can clear from the current position to the end of
the display, then this. should be given as cd. The editor only uses cd from the first column of a
~L:
line.
Insert/delete line f'''-'If the terminal can open a new blank line before the line where the cursor is, this should be given
as aI; this is done only from the first position or a line. The cursor must then appear on the
newly blank line. If the terminal can delete the line which the cursor is on, then this should be
given as dl; this is done only from the first position on the line to be deleted. If the terminal can
scroll the screen backwards, then this can be given as lib, but just al suffices. It the terminal can

SUD

Release 1.1

Last change: 16 December 1983

69

TERMCAP(5)

FILE FORMATS

TERMCAP(5)

retain display memory above then the da capability should be given; if display memory can be
retained below then db should be given. These let the editor understand that deleting a line on
the screen may bring non-blank lines up from below or that scrolling back with sb may bring
down non-blank lines.
InsertI delete eharaeter
There are two basic kinds of intelligent terminals with respect to insert/delete character which
can be described using termeDp. The most common insert/delete character operations affect only
the characters on the current line and shift characters off the end of the line rigidly. Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make a distinction between typed and
untyped blanks on the screen, shifting upon an insert or delete only to an untyped blank on the
screen which is either eliminated, or expanded to two untyped blanks. You can find out which
kind of terminal you have by clearing the screen and then typing text separated by cursor
motions. Type "abc der" using local cursor motions (not spaces) between the "abc" and the
fldef". Then position the cursor before the "abc" and put the terminal in insert mode. It typing
characters causes the rest of the line to shirt rigidly and characters to fall off the end, then your
terminal does not distinguish between blanks and untyped positions. It the "abc" shifts over to
the "def" which then move together around the end of the current line and onto the next as you
insert, you have the second type of terminal, and should give the capability In, which stands for
"insert null". It your terminal does something different and unusual then you may have to
modify the editor to get it to use the insert mode your terminal defines. We have seen no terminals which have an insert mode not not falling into one ot these two classes.
The editor can handie both terminals which have an insert mode, and terminals which send a simple sequence to open a blank position on the current line. Give as 1m the sequence to get into
insert mode, ot give it an empty value if your terminal uses a sequence to insert a blank position.
Give as el the sequence to leave insert mode (give this, with an empty value also it you gave 1m
so). Now give as Ie any sequence needed to be sent just before sending the character to be
inserted. Most terminals with a true insert mode will not give Ie, terminals which send a
sequence to open a screen position should give it here. (Insert mode is preferable to the sequence
to open a position oil the screen if your terminal has both.) It post insert padding is needed, give
this as a number of milliseconds in Ip (a string option). Any other sequence which may need to
be sent after an insert of a single character may also be given in Ip.
It is occasionally necessary to move around while in insert mode to delete characters on the same
line (for example, if there is a tab after the insertion position). It your terminal allows motion
while in insert mode.'y~u can give the capability ml to speed up inserting in this case. Omitting
ml will affect only speed. Some terminals (notably Datamedia's) must not have ml because of
the way their insert mode works.
Finally, you can specify delete mode by giving dm alld eel to enter and exit delete mode, and de
to delete a single character while in delete mode.
HlghUghtlng, undel"Unlng, and visible bella

It your terminal has sequences to enter and exit standout mode these can be given as so and se
respectively. If there are several flavors 01 standout mode (such as inverse video, blinking, or
underlining - half bright is not usually an acceptable "standout" mode unless the terminal is in
inverse video mode constantly) the preferred mode is inverse video by itself. If the code to
change into or out of standout mode leaves one or even two blank spaces on the screen, as the
TVI 912 and Teleray 1061 do, then ug should be given to tell how many spaces are left.
Codes to begin underlining and end underlining can be given as us and ue respectively. It the
terminal has a code to underline the current character and move the cursor one space to the right,
such as the Microterm Mime, this can be given as ue. (It the underline code does not move the
cursor to the right, giV,e.·.the code followed by a nondestructive space.)

70

Last change: 16 December 1983

Sun Release 1.1

TERMCAP(5)

FILE FORMATS

TERMCAP(5)

Many terminals, such as the lIP 2621, automatically leave standout mode when they move to a
new line or the cursor is addressed. Programs using standout mode should exit standout mode
before moving the cursor or sending a newline.
If the terminal has a way of Bashing the screen to indicate an error quietly (a bell replacement)
then this can be given as vb; it must not move the cursor. If the terminal should be placed in a
different mode during open and visual modes of ex, this can be given as V8 and ve, sent at the
start and end or these modes respectively. These· can be used to change, ror example, from a
underline to a block cursor and back.
If the terminal needs to be in a special mode when running a program that addresses the cursor,
the codes to enter and exit this mode can be given as tl and teo This arises, Cor example, Crom
terminals like the Concept with more than one page of memory. If the terminal has only memory
relative cursor addressing and not screen relative cursor addressing, a one screen-sized window
must be fixed into the terminal for cursor addressing to work properly.
If your terminal correctly generates underlined characters (with no special codes needed) even
though it does not overstrike, then you should give the capability ul. If overstrikes are erasable
with a blank, then this should be indicated by giving eo.

ANSI terminals have modes Cor the character highlighting. Dim characters may be generated in
dim mode, entered by mb; reverse video characters in reverse mode, entered by mr; bold characters in bold mode, entered by md; and normal mode characters restored by turning off all attributes with me.
Keypad
If the terminal has a keypad that transmits codes when tbe keys are pressed, this information can
be given. Note that it is not possible to handle terminals where the keypad only works in local
(this applies, for example, to the unshiCted lIP 2621 keys). If the keypad can be set to transmit
or not transmit, give these codes as Ita and ke. Otherwise the keypad is assumed to always
transmit. The codes'sent by the leCt arrow, right arrow, up arrow, down arrow, and home keys
can be given as kl, kr, ku, kd, and kb respectively. If there are runction keys such as ro, fl, ... ,
f9, the codes they send can be given as kO, kl, •••, kO. If these keys have labels other than the
deCault to through 19, the labels can be given as 10, II, •••, 10. If there are other keys that
transmit the same code as the terminal expects Cor the corresponding function, such as clear
screen, the termetJp 2 letter codes can be given in the ko capability, ror example,
":ko==cl,lI,sf,sb:", which says that the terminal has clear, home down, scroll down, and scroll up
keys that transmit the same thing as the cl, II, sf, and sb entries.

The ma entry is also··used to indicate arrow keys on terminals which have single character arrow
keys. It is obsolete but still in use in version 2 of vi, which must be run on some minicomputers
due to memory limitations. This field is redundant with kl, kr, ku, kd, and kh. It consists oC
groups of two characters. In each group, the first character is what an arrow key sends, the
second character is th, corresponding vi command. These commands are h for kI, J for kd, k for
ku, 1 for kr, and H for kh. For example, the mime would be :ma=AKjAZkAXI: indicating
arrow keys left ("H), down ("K), up (" Z), and right ("X). (There is no home key on the mime.)

Mlaeellaneou.
If. the terminal requires other than a null (zero) character as a pad, then this can be given as pe.
lf tabs on the terminal require padding, or if the terminal uses a character other than AI to tab,
then this can be given as tao

Hazeltine terminals, which don't allow ,-, characters to be printed should indicate hz. Datamedia
terminals, which echo carriage-return linefeed for carriage return and then ignore a following
linefeed should indicate De. Early Concept terminals, which ignore a linefeed immediately after
an am wrap, should indicate xn. If an erase-eol is required to get rid of standout (instead of
merely writing on top of it), X8 should be given. Teleray terminals, where tabs turn all characters

Sun Release 1.1

Last change: 16 December 1983

71

FILE FORMATS

TERMCAP(5)

TERMCAP(5)

moved over to blanks, should indicate xt. Other specific terminal problems may be corrected by
adding more capabilities or therorm xz.
Other capabilities include la, an initialization string for the terminal, and If, the name of a file
containing long initialization strings. These strings are expected to properly clear and then set
the tabs on the terminal, if the terminal has settable tabs. If both are given, Is will be printed
before It. This is useful where It is / fJ8r/lib/ tab8et/8td but la clears the tabs first.

Slmllar Termlnala
It there are two very similar terminals, one can be defined as being just like the other with certain
exceptions. The string capability tc can be given with the name of the similar terminal. This
capability must be last and the combined length or the two entries must not exceed 1024. Since
termlib routines search the entry from left to right, and since the tc capability is replaced by the
corresponding entry, the capabilities given at the lert override the ones in the similar terminal. A
capability can be canceled with xxG where xx is the capability. For example, the entry
hn I 2621nl:ksC:keC:tc=2621:
defines a 2621nl that does not have the k. or ke capabilities, and hence does not turn on the
function key labels when in visual mode. This is userul for different modes for a terminal, or for
different user prererences.
FILES
/etc/te~mcap

file containing terminal descriptions

SEE ALSO
ex(I), curses(3X), termcap(3X), tset(I), vi(I), ul(I), more(l)
BUGS

Ez allows only 256 characters for string capabilities, and the routines in termcap(3X) do not check
for overflow or this buffer. The total length of a single entry (excluding only escaped newlines)
may not exceed 1024 ..
The ma, va, and ve entries are specific to the vi program.
Not all programs support all entries. There are entries that are not supported by any program.

72

Last change: 16 December 1983

Sun Release 1.1

Fll.,E FORMATS

TP(5)

TP(5)

NAME

tp - DEC/mag tape formats
DESCRIPTION
Tp dumps files to and extracts files from DECtape and magtape. The formats of these tapes are
the same except that magtapes have larger directories.
Block zero contains a copy of a stand-alone bootstrap program. See reboot(8).
Blocks 1 through 24 for DECtape (1 through 62 for magtape) contain a directory of the tape.
There are 192 (resp. 496) entries in the directory; 8 entries per block; 64 bytes per entry. Each
entry has the foUowin, format:
struct {
char
pathname(32) ;
unsigned short mode;
char
uid;
gid;
char
unused 1;
char
size(3);
char
modtime;
lon,
unsigned short tapeaddr;
char
unused2(16);
unsigned short checksum;

};
The path name entrY~is the path name 01 the file when put on the tape. If the pathname starts
with a zero word, the entry is empty. It is at most 32 bytes long and ends in a null byte. Mode,
uid, gid, size and time modified are the same as described under i-nodes (see file system /8(5)).
The tape address is the tape block number of the start 01 the contents of the file. Every file
starts on a block boundary. The file occupies (size+ 511 )/512 blocks of continuous tape. The
checksum entry has a value such that the sum of the 32 words of the directory entry is zero.
Blocks above 25 (resp. 63) are available lor file storage.
A fake entry has a size-- 01 zero.
SEE ALSO
Is(5), tp(l)

BUGS
The pat/mame, uid, gid, and 8ize fields are too small.

Sun Release 1.1

Last change: 15 January 1983

73

FILE FORMATS

TTYS( 5)

TTYS(5)

NAME

ttys - terminal initialization data
DESCRIPTION

The tty8 file is read by the init program and specifies which terminal special files are to have a
process. created for them so that people can log in. There is one line in the IIy8 file per special file
associated with a terminal.
The first character 01 a line in the IIy8 file is either '0' or '1'. II the first character on the line is a
'0', the init program ignores that line. If the first character on the line is a '1', the init program
creates a login process for that line.
The second character OD each line is used 38 an argument to gelly(8), which performs such tasks
as baud-rate recognition, reading the login name, and calling login. For normal lines, the second
character is '0'; other characters can be used, for example, with hard-wired terminals where speed
recognition is unnecessary or which have special characteristics. The remainder 01 the line is the
terminal's entry in the device directory, /dev.

Getty uses the second character in the tty8 file to look up the characteristics of the terminal in the
file. CODsuit the gettytab(5) manual page for an explanation of the layout of
/ etc/ gettyta6.

I etc/ gettytab
FILES

letc/ttys
SEE ALSO

init(8), getty(8), 10gin(I), gettytab(5)

74

Last change: 28 October 1983

SUD Release 1.1

TTYTYPE(5)

FILE FORMATS

TTYTYPE(5)

NAME
tty type - data base of terminal types by port
SYNOPSIS
/ etc /ttytype
DESCRIPTION
Ttl/tl/pe is a database containinl, for each tty port on the system, the kind of terminal that is
attached to it. There is one line per port, containing the terminal kind (as a na.me listed in
termcap (5)), a space, and the name of the tty, minus /dev/.

This information is read by tBet(l) and by login(!) to initia.lize the TERM variable at login time.
SEE ALSO
teet(!), login(!)

BUGS
Some lines are merely known as "dialup" or "plugboard".

SUD

Release 1.1

Last change: 25 October 1979

75

FILE FORMATS

UUENCODE ( 5 )

UUENCODE( 5)

NAME

uuencode - format of an encoded uuencode file
DESCRIPTION

Files output by uuencode(10J consist of a header line, followed by a number of body lines, and a
trailer line. Uudecode will ignore any lines preceding the header or followinl the trailer. Lines
preceding a header must not, of course, look like a header.
The header line is distinguished by having the first 6 characters "begin". The word begin is followed by a mode (in octal), and a string which names the remote file. Spaces separate the three
items in the header line.
The body consists of a number of lines, each at most 62 characters long (including the trailing
newline). These consist of a character count, rollowed by encoded characters, rollowed by a newline. The character count is a single printing character, and represents an integer, the number of
bytes the rest of the line represents. Such integers are always in the range rrom 0 to 63 and can
be determined by subtracting the character space (octal 40) from the character.

are

Groups of 3 bytes
stored in 4 characters, 6 bits per character. AU are offset by a space to
make the characters printing. The last line may be shorter than the normal 45 bytes. If the size
is not a multiple of 3, this fact can be determined by the value of the count on the last line.
Extra garbage will be included to make the character count a multiple of 4. The body is terminated by a line with a count or zero. This line consists of one ASCII space.
The trailer line consists of "end" on a line by itself.
SEE ALSO

uuencode(lC), uudecode(lC), uusend(lC), uucp(lC), mail(l)

76

Last change: 1 June 1980

Sun Release 1.1

VFONT(5)

FILE FORMATS

VFONT(5)

NAME

vlont - lont lormats
SYNOPSIS
#lnc:lude 
DESCRIPTION
The lonts used by the window system and printer/plotters have the following format. Each font
is in a file, which contains a header, an array of character description structures, and an array of
bytes containing. the bit maps for the characters. The header has the following format:

struct header {
,. Magic number VFONT_MAGIC·'
magic;
short
,. Total :#= bytes of bitmaps .,
unsigned short size;
/. Maximum horizontal glyph size .,
maxx;
short
,. Maximum vertical glyph size .,
maxy;
short
,. (unused) .,
xtend;
short
};
0436
,define VFONT_MAGIC
Mazz and maz1l are intended to be the maximum horizontal and vertical size of any glyph in the
font, in raster lines. (A glyph is just a printed representation of a character, in a particular size
and lont.) The 8ize is the total size 01 the bit maps for the characters in bytes. The ztend field is
not currently used.
Arter the header iS aJl array 01 NUM_DISPATCH structures, one lor each 01 the possible characters in the lont. Each element 01 the array has the form:

t

striaet dispatch
/. &(glyph) - &(start of bitmaps) .,
unsigned short addr;
nbytes;
,. , bytes of glyphs (0 if no glyph) .,
short
up, down, left, right; /. Widths from baseline point .,
char
width;
,. Logical width, used by troff .,
short
};
:#=define NUM_DISPATCH
256
The n611te8 field is nonzero lor characters which actually exist. For such characters, the addr field
is an offset into the bit maps to where the character's bit map begins. The up, down, left, and
right fields are offsets from the base point 01 the glyph to the edges of the rectangle which the bit
map represents. (The imaginary "base point" is a point which is vertically on the "base line" ot
the glyph (the bottom line 01 a glyph which doesn't have a descender) and horizontally near the
lelt edge 01 the glyph; often 3 or 60 pixels past the lett edge.) The bit map contains up+ down
rows 01 data for the character, each ot which has left+ right columns (bits). Each row is rounded
up to a number 01 bytes. The widt" field represents the logical width of the glyph in bits, and
shows the horizontal displacement to the base point of the next glyph.
FILES
'USf /lib'vlont'·

/usr /suntool/fixedwidthlonts/·
SEE ALSO
trol(I), pti(I), vlontinro(I), vswap(l)

BUGS
A machine-independent lont lormat should be defined. The .horts in the above structures contain dilerent bit patterns depending whether the font file is for use on a Vax or a Sun. The
"8wap program must be used to convert one to the other.

SUD

Release 1.1

Last change: 23 February 1984

77

Interprocess Communication Primer

Table of Contents

1. Introduction ............................. ............................................................... ...................... ...................

2

2. Basics ...................................................................................................................................................
2.1. Socket Types .........................................................................................................................
2.2. Socket Creation ...................................................................................................................
2.3. Binding Names .....................................................................................................................
2.4. Connection Establishment ................................. ............. ....................... .......................
2.5~ Data Transfer .......................................................................................................................
2.6. Discarding Sockets ......... ...................................................... .............. ......... ............. ..........
2.7. Connectionless Sockets ..................................................... .............. ................................
2.8. Input/Output Multiplexing .........................................................................................

3
3

3. Network Librar;y Routines ...... ,...............................................................................................
3.1. Host Names ............................................................................................................................
3.2. Networ'k Names ...............................................................'....................................................
3.3. Protocol Names ...................................................................................................................
3.4. Service Names ......................................................................................................................
3.5. Miscellaneous ........................................................................................................................

10
10
11
12
12
13

4. Client/Server Model ...................................................................................................................
4.1. Servers ......................................................................................................................................
4.2. Clients, .......................................................................................................................................
4.3. Connectionless Servers ....................................................................................................

16
15
17
18

s.

22

Advanced Topics ..........................................................................................................................

-i-

4
5

5
7
7
8
8

5.1.
5.2.
5.3.
5.4.
5.5.
5.6.'

Out of Band Data ..............................................................................................................
Signals and Process Groups .........................................................................................
Pseudo Terminals ................................................................................................................
Internet Address Binding ..............................................................................................
Broadcasting and Datagram Sockets .....................................................................
Signals .......................................................................................................................................

-ii-

22
22
23
24
26
26

Interprocess Communication Primer

This document provides an introduction to the interprocess communication facilities included in
the Sun Workstation version of the UNIXt operating system.
It discusses the overall model for interprocess communication and introduces the interprocess
communication primitives which have been added to the system. The majority·of the document
considers the use of these primitives in developing applications. The reader is expected to be
familiar with the C programming language as all examples are written in C.

t UNIX is a trademark of Bell Laboratories.

Revision E of 7 January 1984

1

Interprocess Communication Primer

Sun System Interface Manual

1. Introduction
One of the most important features added in the Berkeley 4.2 release of the UNIX operating
system is substantial new interprocess communication facilities. These facilities are the result of
more than two years of discussion and research. The facilities provided in this release incorporate many of the ideas from current research, wbile trying to maintain the UNIX philosophy
of simplicity and conciseness. We hope that these interprocess communication facilities will
establish a standard. From the response to the design, it appears that it is being adopted on
many systems.
UNIX has previously been very weak in the area of interprocess communication. Until recently,
the only standard mechanism which allowed two processes to communicate were pipes (the mpx
files which were part of Version 7 were experimental). Unfortunately, pipes are restrictive in
that the two communicating processes must be related through a common ancestor. Further,
the semantics of pipes makes them almost impossible to maintain in a distributed environment.
Earlier attempts at extending the ipc facilities of UNIX have met with mixed reaction. The
majority of the problems have been related to the fact these facilities have been tied to the
UNIX file system; either through naming, or implementation. Consequently, the ipc facilities
provided in this release have been designed as a totally independent subsystem, and allow
processes to rendezvous in many ways. Processes may rendezvous through a UNIX file systemlike name space (a space where all names are path names) as well as through a network name
space. In fact, new name spaces may be added at a future time with only minor changes visible
to users. Further, the communication facilities have been extended to included more than the
simple byte stream provided by a pipe-like entity. These extensions have resulted in a completely new part of the system which users will need time to familiarize themselves with. It is
likely that as more use is made of these facilities they will be refined; only time will tell.
The remainder of this document is organized in four sections. Section 2 introduces the new system calls and the basic model of communication. Section 3 describes some of the supporting
library routines users may find useful in constructing distributed applications. Section 4 is concerned with the client/server model used in developing applications and includes examples of
the two major types of servers. Section 5 delves into advanced topics which sophisticated users
are likely to encounter when using the ipc facilities.

2

Revision E of 7 January 1984

Sun System Interface Manual

Interprocess Communication Primer

2. Basics
The basic building block for communication is the ,ocket. A socket is an endpoint of communication to which a name may be bound. Each socket in use has a type and one or more associated processes. Sockets exist within communication domain,. A communication domain is an
abstraction introduced to bundle common properties of processes communicating through sockets. One such property is the scheme used to name sockets. For example, in the UNIX communication domain sockets are named with UNIX path names; e.g. a socket may be named
"/dev/foo". Sockets normally exchange data only with sockets in the same domain (it may be
possible to cross domain boundaries, but only if some translation process is performed). The ipc
supports two separate communication domains: the UNIX domain, and the Internet domain is
used by processes which communicate using the the DARPA standard communication protocols.
The underlying communication facilities provided by these domains have a significant influence
on the internal system implementation as well as the interface to socket facilities available to a
user. An example of the latter is that a socket "operating" in the UNIX domain sees a subset
of the possible error conditions which are possible when operating in the Internet domain.

2.1. Socket Types
Sockets are typed according to the communication properties visible to a user. Processes are
presumed to communicate only between sockets of the same type, although there is nothing
that prevents communication between sockets of different types should the underlying communication protocols support this.
Three types of sockets currently are available to a user. A dream socket provides for the
bidirectional, reliable, sequenced, and unduplicated flow of data without record boundaries.
Aside from the bidirectionality of data flow, a pair of connected stream sockets provides an
interface nearly identical to that of pipes •.
A datagram socket supports bidirectional flow of data which is not promised to be sequenced,
reliable, or unduplicated. That is, a process receiving messages on a datagram socket may find
messages duplicated, and, possibly, in an order different from the order in which it was sent. An
important characteristic of a'datagram socket is that record boundaries in data are preserved.
Datagram sockets closely model the facilities found in many contemporary packet switched networks such as the Ethernet.
A raw socket provides users access to the underlying communication protocols which support
socket abstractions. These sockets are normally datagram oriented, though their exact characteristics are dependent on the interface provided by the protocol. Raw sockets are not intended
for the general user; they have been provided mainly for those interested in developing new
communication protocols, or for gaining access to some of the more esoteric facilities of an existing protocol.
Two potential socket types which have interestitlg properties are the .equenced packet socket
and the reliabl, delivered me"age socket. A sequenced packet socket is identical to a stream
socket with the exception that record boundaries are pre~erved. This interface is very similar to
that provided by the Xerox NS Sequenced Packet protocol. The reliably delivered message
socket has similar properties to a datagram socket, but with reliable delivery. While these two
socket types, have been loosely defined, they are not currently implemented. So, in this
• In the ffi\ijX domain, in fact, the semantics are identical and, as one might expect, pipes have
been implemented internally as simply a pair of connected stream sockets.

Revision E of 7 January 1984

3

Interprocess Communication Primer

Sun System Interface Manual

document, we will concern ourselves only with the three supported socket types.

2.2. Socket Creation
To create a socket the locket system call is used:
s

=

socket( domain, type, protocol);

This call requests that the system create a socket in the specified domain and of the specified
type. A particular protocol may also be requested. It the protocol is left unspecified (a value of
0), the system will select an appropriate protocol from those protocols which comprise the communication domain and which may be used to support the requested socket type. The user is
returned a descriptor (a small integer number) which may be used in later system calls which
operate on sockets. The domain is specified as one of the manifest constants defined in the file
< IYII locket.h>. For the UNIX domain the constant is AF _UNIX.; for the Internet domain
AF _I NET . The socket types are also defined in this file and one of SOCK_STREAM,
SOCK_DGRAM, or SOCK_RAW must be specified. To create a stream socket in the Internet
domain the following call might be used:
s

=

socket{AF _I NET, SOCK_STREAM, 0);

This call would result in a stream socket being created with the TOP protocol providing the
underlying communication support. To create a datagram socket for on-machine use a sample
call might be:
s = socket{AF _UNIX, SOCK_DGRAM, 0);
To obtain a particular protocol one selects the protocol number, as defined within the communication domain. For the Internet domain the available protocols are defined in < nelinet/ in.la>
or, better yet, one may use one of the library routines discussed in section 3, such as getprotobyname:
#include
#include
#include
#include






pp = getprotobyname("tcp");
s = socket{AF _INET, SOCK_STREAM, pp->p-proto);
There are several reasons a socket call may fail. Aside from the rare occurrence of lack of
memory (ENOBUFS), a socket request may fail due to a request for an unknown protocol
(EPROTONOSUPPORT), or a request for a type of socket for which there is no supporting
protocol (EPR OTOTYPE).

* The

manifest constants are named AF_whatever as they indicate the "address format" to use in

interpreting names.

4

Revision E of 7 January 1984

Sun System Interface Manual

Interprocess Communication Primer

2.3. Binding Names
A socket is created without a name. Until a name is bound to a socket, processes have no way
to reference it and, consequently, no messages may be received on it. The bind call is used to
assign a name to a socket:
bind{s, name, namelen);
The bound name is a variable length byte string which is interpreted by the supporting
protocol(s). Its interpretation may vary from communication domain to communication domain
(this is one of the properties which comprise the "domain"). In the UNIX domain names are
path names while in the Internet domain names contain an Internet address and port number.
If one wanted to bind the name "/dev/foo" to a UNIX domain socket, the following would be
used:
#include 
struct sockaddr_un sun;
sun.sun_family = AF _UNIX;
strcpy( sun.sunJath, " / dev / foo" );
bind(s, &sun, strlen(" /dev/foo")+ 2);
In binding an Internet address things become more complicated. The actual call is simple,
#include 
#include 
struct sockaddr_in sin;
bind(s, &sin, sizeof (sin»;
but the selection of what to place in the address ,in requires some discussion. We will come
back to the problem of formulating Internet addresses in section 3- when the library routines
used in name resolution are discussed.

2.4. Connection Establishment
With a bound socket it is possible to rendezvous with an unrelated process. This operation is
usually asymmetric with one process a "client" and the other a "server". The client requests
services from the server by initiating a "connection" to the server's socket. The server, when
willing to ofTer its advertised services, passively "listens" on its socket. On the client side the
connect call is used to initiate a connection. Using the UNIX domain, this might appear as,
struct sockaddr_un server;
connect(s, &server, strlen(server.sun....,path)+ 2);
while in the Internet domain,
struct sockaddr_in server;
connect(s, &server, sizeof (server»;
If the client process's socket is unbound at the time of the connect call, the system will
automatically select and bind a name to the socket; c.f. section 5.4 1. An error is returned when
1

You mqst do a ,etlOd".me(2) call to retrieve the binding.

Revision E of 7 January 1984

5

Interprocess Communication Primer

Sun System Interface Manual

the connection was unsuccessful (any name automatically bound by the system, however,
remains). Otherwise, the socket is associated with the server and data transfer may begin.
Many errors can be returned when a connection attempt fails. The most common are:
ETIMEDOUT
After failing to establish a connection for a period of time, the system decided there was no
point in retrying the connection attempt any more. This usually occurs because the destination host is down, or because problems in the network resulted in transmissions being
lost.
ECONNREFUSED
The host refused service for some reason. When connecting to a host running the 0.0
release version of UNIX this is usually due to a server process not being present at the
requested name.
ENETDOWN or EHOSTDOWN
These operational errors are returned based on status information delivered to the client
host by the underlying communication services.
ENETUNREACHorEHOSTUNREACH
These operational errors can occur either because the network or host is unknown (no route
to the network or host is present), or because of status information returned by intermediate gateways or switching nodes. Many times the status returned is not sufficient to distinguish a network being down from a host being down. In these cases the system is conservative and indicates the entire network is unreachable.
For the server to receive a client's connection it must perform two steps after binding its socket.
The first is to indicate a willingness to listen for incoming connection requests:
listen(s, 5);
The second parameter to the li3ten call specifies the maximum number of outstanding connections which may be queued awaiting acceptance by the server process. Should a connection be
requested while the queue is full, the connection will not be refused, but rather the individual
messages which comprise the request will be ignored. This gives a harried server time to make
room in its pending connection queue while the client retries the connection request. Had the
connection been returned with the ECONNREFUSED error, the client would be unable to tell if
the server was up or not. As it is now it is still possible to get the ETIMEDO UT error back,
though this is unlikely. The backlog figure supplied with the listen call is limited by the system
to a maximum of 5 pending connections on anyone queue. This avoids the problem of
processes hogging system resources by setting an infinite backlog, then ignoring all connection
requests.
With a socket marked as listening, a server may accept a connection:
fromlen = sizeof (from);
snew = accept(s, &from, &fromlen);
A new descriptor is returned on receipt of a connection (along with a new socket). If the server
wishes to find out who its client is, it may supply a bufter for the client socket's name. The
value-result parameter fromlen is initialized by the server to indicate how much space is associated with from, then modified on return to reflect the true size of the name. If the client's name
is not of interest, the second parameter may be zero.
Accept normally blocks. That is, the call to accept wilt not return until a connection is available or the system call is interrupted by a signal to the process. Further, there is no way for a
process to indicate it will accept connections from only a specific individual, or individuals. It is

6

Revision E of 7 January 1984

Sun System Interface Manual

Interprocess Communication Primer

up to the user process to consider who the connection is from and dose down the connection if
it does not wish to speak to the process. If the server process wants to accept connections on
more than one socket, or not block on the accept call there are alternatives; they will be considered in section 5.

2.5. Data Transfer
With a connection established, data may begin to flow. To send and receive data there are a
number of possible calls. With the peer entity at each end of a connection anchored, a user can
send or receive a message without specifying the peer. As one might expect, in this case, then
the normal read and write system calls are useable,
write(s, buf, sizeof (buf»;
read(s, buf, sizeof (buf»;
In addition to read and write, the new calls ,end and recti may be used:
send(s, buf, sizeof (buf), flags);
recv(s, buf, sizeof (buf), flags);
While ,end and recti are virtually identical to read and write, the extra flag, argument is important. The flags may be specified as a non-zero value if one or more of the following is required:
MSG_OOB
MSG_PEEK
MSG_DONTROUTE

send/receive out of band data
look at data without reading
send data without routing packets

Out of band data is a notion specific to stream sockets, and one which we will not immediately
consider. The option to have data sent without routing applied to the outgoing packets is
currently used only by the routing table management process, and is unlikely to be of interest
to the casual user. The ability to preview data is, however, of interest. When MSG_PREVIEW
is specified with a recti call, any data present is returned to the user, but treated as still
"unread". That is, the next read or recti call applied to the socket will return the data previously previewed.

2.8. Discarding Sockets
Once a socket is no longer of interest, it may be discarded by applying a clo,e to the descriptor,
dose(s);

If data is associated with a socket which promises reliable delivery (e.g. a stream socket) when a
close takes place, the system will continue to attempt to transfer the data. However, after a
fairly long period of time, if the data is still undelivered, it will be discarded. Should a user
have no use for any pending data, it may perform a ".utdown on the socket prior to dosing it.
This call is of the form:
shutdown(s, how);
where how is 0 if the user is no longer interested in reading data, 1 if no more data will be sent,
or 2 if no data is to be sent or received. Applying shutdown to a socket causes any data queued
to be immediately discarded.

Revision E of 7 January 1984

7

Interprocess Communication Primer

Sun System Interface Manual

2.7. Connectionless Sockets
To this point we have been concerned mostly with sockets which follow a connection oriented
model. However, there is also support for connectionless interactions typical of the datagram
facilities found in contemporary packet switched networks. A datagram socket provides a symmetric interface to data exchange. While processes are still likely to be client and server, there
is no requirement for connection establishment. Instead, each message includes the destination
address.
Datagram sockets are created as before, and each should have a name bound to it in order that
the recipient of a message may identify the sender. To send data, the ,ent/to primitive is used,
sendto(s, buf, buflen, flags, &to, tolen);
The " buJ, buJlen, and flag' parameters are used as before. The to and tolen values are used to
indicate the intended recipient of the message. When using an unreliable datagram interface, it
is unlikely any errors will be reported to the sender. Where information is present locally to
recognize a message which may never be delivered (for instance when a network is unreachable),
the call will return -1 and the global value errno will contain an error number.
To receive messages on an unconnected datagram socket, the rectJ/rom primitive is provided:
recvfrom{s, buf, buflen, flags, &from, &fromlen);
Once again, the fromlen parameter is handled in a value-result fashion, initially containing the
size of the from buffer.
In addition to the two calls mentioned above, datagram sockets may also use the connect call to
associate a socket with a specific address. In this case, any data sent on the socket will
automatically be addressed to the connected peer, and only data received from that peer will be
delivered to the user. Only one connected address is permitted for each socket (i.e. no multicasting). Connect requests on datagram sockets return immediately, as this simply results in
the system recording the peer's address (as compared to a stream socket where a connect
request initiates establishment of an end to end connection). Other of the less important details
of datagram sockets are described in section 5.

2.8. Input/Output Multiplexing
One last facility often used in developing applications is the ability to multiplex ilo requests
among multiple sockets and/or files. This is done using the ,eled call:
select{nfds, &readfds, &writefds, &execptfds, &timeout);
Select takes as arguments three bit masks, one for the set of file descriptors for which the caller
wishes to be able to read data on, one for those descriptors to which data is to be written, and
one for which exceptional conditions are pending. Bit masks are created by or-ing bits of the
form "1 < < fd". That is, a descriptor fd is selected if a 1 is present in the 11th bit of the
mask. The parameter nfd, specifies the range of file descriptors (i.e. one plus the value of the
largest descriptor) specified in a mask.

A timeout value may be specified if the selection is not to last more than a predetermined
time. If timeout is set to 0, the selection takes the form of a poll, returning immediperiod
ately. If the last parameter is a null pointer, the selection will block indefinitely.. Select

or

1

'*

nal is

8

To be more specific, a. return ta.kes pla.ce only when a descriptor is selecta.ble, or when a. sigby the caller, interrupting the system call.

receiy~d

Revision E of 7 January 1984

Sun System Interface Manual

Interprocess Communication Primer

normally returns the number of file descriptors selected. If the ,elect call returns due to the
timeout expiring, then a value of -1 is returned along with the error number EINTR.
Select provides a synchronous multiplexing scheme. Asynchronous notification of output completion, input availability, and exceptional conditions is possible through use of the SIGIO and
SIGURG signals described in section 5.

Revision E of 7 January 1984

9

Interprocess Communication Primer

Sun System Interface Manual

3. Network Library Routines
The discussion in section 2 indicated the possible need to locate and construct network
addresses when using the interprocess communication facilities in a distributed environment.
To aid in this task a number of routines have been added to the standard C run-time library.
In this section we will consider the new routines provided to manipulate network addresses.
While the Sun system release networking facilities support only the DARPA standard Internet
protocols, these routines have been designed with flexibility in mind. As more communication
protocols become available, we hope the same user interface will be maintained in accessing
network-related address data bases. The only difference should be the values returned to the
user. Since these values are normally supplied the system, users should not need to be directly
aware of the communication protocol and/or naming conventioDs in use.
Locating a service on a remote host requires many levels of mapping before client and server
may communicate. A service is assigned a name which is intended for human consumption; e.g.
"the login ,erver on host monet". This name, and the name of the peer host, must then be
translated into network tJddre"e. which are not necessarily suitable for human consumption.
Finally, the address must then used in locating a physicalloctJtion and route to the service. The
specifics of these three mappings is likely to vary between network architectures. For instance,
it is desirable for a network to not require hosts be named in such a way that their physical
location is known by the client host. Instead, underlying services in the network may discover
the actual location of the host at the time a client host wishes to communicate. This ability to
have hosts named in a location independent manner may induce overhead in connection establishment, as a discovery process must take place, but allows a host to be physically mobile
without requiring it to notify its clientele of its current location.
Standard routines are provided for: mapping host names to network addresses, network names
to network numbers, protocol names to protocol numbers, and service names to port numbers
and the appropriate protocol to use in communicating with the server process. The file
< netdb.h> must be included when using any of these routines.

3.1. Host Names
A host name to address mapping is represented by the ho.tent structure:

struct hostent {
char
*h_name;
char
**h_aliases;
h_addrt ype;
int
h_length;
int
char
*h_addr;
};

/ * official name of host
/ * alias list */
/ * host address type
/ * length of address
/ * address */

*,*,

*/

Note that the h_tJddr field in the structure definition is defined as a pointer to char. In the
case of Internet addresses (the only case implemeted to date) you should cast this to a (atruct
in_addr *) when using the item.
The official name of the host and its public aliases are returned, along with a variable length
address and address type. The routine getholfbgntJme(3N) takes a host name and returns a ho,.
tent structure, while the routine getholtbytJddr(3N) maps host addresses into a ho,tent structure.
It is possible for a host to have many addresses, aU having the same name. Getl.o.tybyntJme
returns the first matching entry in the data base file Ietcl hod.; if this is unsuitable, the lower
level routine getho8tent(3N) may be used. For example, to obtain a hodent structure for a host
H)

Revision E of 7 January 1984

Sun System Interlace Manual

Interprocess Communication Primer

on a particular network the following routine might be used (for simplicity, only Internet
addresses are considered):
*include
*include
*include
*include






struct hostent *
gethostbynameandnet( name, net)
char *name;
int net;
{
register struct hostent *hpi
register char **cp;
sethostent( 0);
while «hp = gethostent(» != NULL) {
if (hp- > h_addrtype !=- AF _INET)
continue;
if (strcmp(name, hp->h_name» {
for (cp = hp->h_aliases; cp && *cp != NULL; cp+ + )
if (strcmp(name, *cp) =-=- 0)
goto found;
continue;
}
found:
if (in_netof( *(struct in_addr *)hp- > h_addr» == net)
break;
}
endhostent(0);
return (hp);

}

(in_netof(3N) is a standard routine which returns the network portion of an Internet address.)

3.2. Network Names
As for host names, routines for mapping network names to num hers, and back, are provided.
These routines return a netent structure:

Revision E of 7 January 1984

11

Sun System Interface Manual

Interprocess Communication Primer

/*

* Assumption here is that a network number
* fits in 32 bits - probably a poor one.

*/

struct netent {
char
char
int
int
};

tn_name;
**n_alia5e!;
n_addrtype;

,*

official name of net .,
,. alias list .,
/* net address type .,
,. network

*.,

The routines getnetbyname(3N), getnetbynum6er(3N), and getnetent(3N) are the network counterparts to the host routines described above.

3.3. Protocol Names
For protocols the protoent structure defines the protocol-name mapping used with the routines
getprotobyname(3N), getprotobynumber(3N), and getprotoent(3N):
struct protoent {
*p_name;
char
char
**p_aliases;
p-proto;
int
};

/. official protocol name .,
/* alias list .,
/. protocol

*.,

3.4. Service Names
Information regarding services is a bit more complicated. A service is expected to reside at a
specific "port" and employ a particular communication protocol. This view is consistent with
the Internet domain, but inconsistent with other network architectures. Further, a service may
reside on multiple ports or support multiple protocols. If either of these occurs, the higher level
library routines will have to be bypassed in favor of homegrown routines similar in spirit to the
"gethostbynameandnet" routine described above. A service mapping is described by the ,ervent
structure,
struct servent {
char
*s_name;
char
**s_aliases;
int
s-port;
char
*s-proto;
};

,*
,*/* **,

official service name .,
/ * alias list .,
port
protocol to use .,

The routine get8ervbyname{3N) maps service names to a servent structure by specifying a service name and, optionally, a qualifying protocol. Thus the call
sp

= getservbyname{"telnet", (char *)0);

returns the service specification for a telnet server using any protocol, while the call
sp

= getservbyname{"telnet", "tcp");

returns oply that telnet server which uses the TCP protocol. The routines get,erv6wort(3N)

12

Revision E of 7 January 19S4

Sun System Interface Manual

Interprocess Communication Primer

and gellervent(3N) are also provided. The get,ervbyport routine has an interlace similar to that
provided by get.ervbl/f'ltJme; an optional protocol name may be specified to qualify lookups.

3.5. Miscellaneous
With the support routines described above, an application program should rarely have to deal
directly with addresses. This allows services to be developed as much as possible in a network
independent fashion. It is clear, however, that purging all network dependencies is very
difficult. So long as the user is required to supply network addresses when naming Bervices and
sockets there will always some network dependency in a program. For example, the normal
code included in client programs, such as the remote login program, is of the form shown in Figure 1. (This example will be considered in more detail in section 4.)
If we wanted to make the remote login program independent of the Internet protocols and
addressing scheme we would be forced to add a layer of routines which masked the network
dependent aspects from the mainstream login code. For the current facilities available in the
system this does not appear to be worthwhile. Perhaps when the system is adapted to different
network architectures the utilities will be reorganized more cleanly.
Aside from the address-related data base routines, there are several other routines available in
the run-time library which are of interest to UBers. TheBe are intended mostly to simplify manipulation of names and addresses. Table 1 summarizes the routines for manipulating variable
length byte strings and handling byte swapping of network addresses and values.
The byte swapping routines are provided because the operating system expects addresses to be
supplied in network order. On a VAX, or machine with similar architecture, this is usually
reversed. Consequently, programs are sometimes required to byte swap quantities. The library
routines which return network addresses provide them in network order so that they may simply be copied into the structures provided to the system. This implies users should encounter
the byte swapping problem only when interpreting network addresses. For example, if an Internet port is to be printed out the following code would be required:

Revision E of 7 January 1984

13

Interprocess Communication Primer

#include
#include
#include
#include
#include

Sun System Interfaee Manual







main(argc, argv)
char *argvD;
{
struct sockaddr_in sin;
struct servent *sp;
struct hostent *hpj
int S;
sp = getservhyname{"login" , "tcp");
ir (sp == NULL) {
rprintr(stderr, "rlogin: tcp/login: unknown service\n");
exit(I);

}
hp = gethosthyname{argv[I]);
ir (hp == NULL) {
rprintr(stderr, "rlogin: %15: unknown host\n" , argvll]);
exit(2);
}
hzero((char *)&sin, sizeor (sin»;
bcopy( hp- > h_addr, (char *)&sin.sin_addr, hp- > h_Iength);
sin.sin_ramily = hp- > h_addrtype;
sin.sin-port = sp- >s-J>ort;
s = socket(AF _INET, SOCK_STREAM, 0);
ir (s < 0) {
perror("rlogin: socket");
exit(3);
}
ir (connect(s, (char *)&sin, sizeor (sin» < 0) {
perror(" rlogin: connect");
exit(5);
}

}
Figure 1. Remote login client code.
printr("port number %d\n", ntohs(sp->s..,port»;
On machines other than the VAX these routines are defined as null macros.

Revision E of 7 January 1984

Sun System Interface Manual

Call
bcmp(sl, s2, n)
bcopy(sl, s2, n)
bzero(base, n)
htonl(val)
htons(val)
ntohl(val)
ntohs(val)

Interprocess Communication Primer

Synopsis
compare byte-strings; 0 if same, not 0 otherwise
copy n bytes from sl to s2
zero-fill n bytes starting at base
convert 32-bit quantity from host to network byte
convert I6-bit quantity from host to network byte
convert 32-bit quantity from network to host byte
convert I6-bit quantity from network to host byte

order
order
order
order

Table 1. C run-time routines.

4. Client/Server Model
The most commonly used paradigm in constructing distributed applications is the client/server
model. In this scheme client applications request services from a server process. This implies an
asymmetry in establishing communication between the client and server which has been examined in section 2. In this section we will look more closely at the interactions between client and
server, and consider some of the problems in developing client and server applications.
Client and server require a well known set of conventions before service may be rendered (and
accepted). This set of conventions comprises a protocol which must be implemented at both
ends of a connection. Depending on the situation, the protocol may be symmetric or asymmetric. In a symmetric protocol, either side may play the master or slave roles. In an asymmetric protocol, one side is immutably recognized as the master, with the other the slave. An
exam pie of a symmetric protocol is the TEL NET protocol used in the Internet for remote terminal emulation. An example of an asymmetric protocol is the Internet file transfer protocol,
FTP. No matter whether the specific protocol used in obtaining a service is symmetric or asymmetric, when accessing a service there is a "client process" and a "server process". We will first
consider the properties of server processes, then client processes.
A server process normally listens at a well know address for service requests. Alternative
schemes which use a service server may be used to eliminate a flock of server processes clogging
the system while remaining dormant most of the time. The Xerox Courier protocol uses the
latter scheme. When using Courier, a Courier client process contacts a Courier server at the
remote host and identifies the service it requires. The Courier server process then creates the
appropriate server process based on a data base and "splices" the client and server together,
voiding its part in the transaction. This scheme is attractive in that the Courier server process
may provide a single contact point for all services, as well as carrying out the initial steps in
authentication. However, while this is an attractive possibility for standardizing access to services, it does introduce a certain amount of overhead due to the intermediate process involved.
Implementations which provide this type of service within the system can minimize the cost of
client server rendezvous.

4.1. Servers
In this release, most servers are accessed at well known Internet addresses or UNIX domain
names. When a server- is started at boot time it advertises it services by listening at a well
know location. For example, the remote login server's main loop is of the form shown in Figure

2.

Revision E of 7 January 1984

15

Sun System Interface Manual

Interprocess Communication Primer

main(argc, argv)
int argc;
char

**argv;

{
int f;
struct sockaddr_in from;
struct servent *sp;
sp = getservbyname("login", "tep");
if (sp == NULL) {
fprintf(stderr, "rlogind: tep/login: unknown serviee\n");
exit(I);
}
#ifndef D EBU G
< < disassociate server from eontrolling terminal> >
#endif
sin.sin-POrt = sp->s-portj
f = socket(AF _INET, SOCK_STREAM, 0);
if (bind(f, (caddr_t)&sin, sizeof (sin»

< 0) {

}
Iisten(f, 5);
for (;;) {
int g, len

=

sizeof (from);

g = accept(f, &from, &len);

if (g

< 0) {

if (errno != EINTR)
perror("rlogind: accept");
continue;
}
if (forkO == 0) {
close(f);
doit(g, &from);
}
close(g);

}
}
Figure 2. Remote login server.
The first step taken by the server is look up its service definition:
sp = getservbyname("login", "tcp");
if (sp == NULL) {

Revision E of 7 January 1984

Sun System Interface Manual

Interprocess Communication Primer

fprintf(stderr, "rlogind: tcp/login: unknown service\n");
exit(l);

}
This definition is used in later portions of the code to define the Internet port at which it listens
for service requests (indicated by a connection).
Step two is to disassociate the server from the controlling terminal of its invoker. This is
important as the server will likely not want to receive signals delivered to the process group of
the controlling terminal.
Once a server has established a pristine environment, it creates a socket and begins accepting
service requests. The bind call is required to insure the server listens at its expected location.
The main body of the loop is fairly simple:
for (;;) {
int g, len

=

sizeof (from);

g = accept(f, &from, &Ien);
if (g < 0) {
if (ermo != EINTR)
perror{"rlogind: accept");
continue;
}
if (forkO == 0) {
close(f);
doit(g, &from);
}
c1ose(g);

}
An accept call blocks the server until a client requests service. This call could return a failure
status if the call is interrupted by a signal such as SIGCHLD (to be discussed in section 5).
Therefore, the return value from accept is checked to insure a connection has actually been est&blished. With a connection in hand, the server then forb a child process and invokes the main
body of the remote login protocol processing. Note how the socket used by the parent for
queueing connection requests is closed in the child, while the socket created as a result of the
accept is closed in the parent. The address of the client is also handed the doit routine because
it requires it in authenticating clients.

4.2. Clients
The client side of the remote login service was shown earlier in Figure 1. One can see the
separate, asymmetric roles of the client and server clearly in the code. The server is a passive
entity, listening for client connections, while the client process is an active entity, initiating a
connection when invoked.
Let us consider more closely the steps taken by the client remote login process. As in the server
process the first step is to locate the service definition for a remote login:

Revision E of 7 January 1984

17

Sun System Interface Manual

Interprocess Communication Primer

sp = getservbyname{"login", "tcp");
if (sp == NULL) {
fprintf(stderr, "rlogin: tcp/login: unknown service\n");
exit(l );
}
Next the destination host is looked up with a getho,tbJlfltJme call:
hp = gethostbyname(argv[l]);
if (hp == NULL) {
fprintf(stderr, "rlogin: %s: unknown host\n", argv[I]);
exit(2);
}
With this accomplished, all that is required is to establish a connection to the server at the
requested host and start up the remote login protocol. The address buffer is cleared, then filled
in with the Internet address of the foreign host and the port number at which the login process
resides:
bzero(( char *)&sin, sizeof (sin»;
bcopy(hp->h_addr, (char *)sin.sin_addr, hp->h_length);
sin.sin_family = hp- > h_addrtype;
sin.sin-J>Ort = sp- >s-port;
A socket is created, and a connection initiated.
s = socket(hp- >h_addrtype, SOCK_STREAM, 0);
if (s < 0) {
perror(" rio gin: socket");
exit(3);
}
if (connect(s, (char *)&sin, sizeof (sin»
perror("rlogin: connect");
exit( 4);
}

< 0) {

The details of the remote login protocol will not be considered here.

4.3. Connectionless Servers
While connection-based services are the norm, some services are based on the use of datagram
sockets. One, in particular, is the "rwho" service which provides users with status information
for hosts connected to a local area network. This service, while predicated on the ability to
broadcad information to all hosts connected to a particular network, is of interest as an example usage of datagram sockets.
A user on any machine running the rw ho server may find out the current status of a machine
with the ruptime(l) program. The output generated is illustrated in Figure 3.
Status information for each host is periodically broadcast by rwho server processes on each
machine. The same server process also receives the status information and uses it to update a
database. This database is then interpreted to generate the status information for each host.
Servers operate autonomously, coupled only by the local network and its broadcast capabilities.

18

Revision E of 7 January 1984

Sun System Interface Manual

arpa
cad
calder
dati
degas
ear
ernie
esvax
ingres
kim
matisse
medea
merlin
mlro
monet
oz
st atv ax
ucbvax

up
up
up
up
up
up
down
down
down
up
up
up
down
up
up
down
up
up

Interprocess Communication Primer

9:45,
2+ 12:04,
10:10,
2+ 06:28,
25+ 09:48,
5+ 00:05,
0:24
17:04
0:26
3+ 09:16,
3+ 06:18,
3+ 09:39,
19+ 15:37
1+ 07:20,
1+ 00:43,
16:09
2+ 15:57,
9:34,

5 users,
8 users,
o users,
9 users,
o users,
o users,

load
load
load
load
load
load

1.15,
4.67,
0.27,
1.04,
1.49,
1.51,

1.39,
5.13,
0.15,
1.20,
1.43,
1.54,

1.31
4.59
0.14
1.65
1.41
1.56

8 users, load
o users, load
2 users, load

2.03,
0.03,
0.35,

2.46,
0.03,
0.37,

3.11
0.05
0.50

7 users, load
2 users, load

4.59,
0.22,

3.28,
0.09,

2.12
0.07

3 users, load
2 users, load

1.52,
6.08,

1.81,
5.16,

1.86
3.28

Figure 3. ruptime output.
The rwho server, in a simplified form, is pictured in Figure 4. There are two separate tasks performed by the server. The first task is to act as a receiver of status information broadcast by
other hosts on the network. This job is carried out in the main loop of the program. Packets
received at the rwho port are interrogated to insure they've been sent by another rwho server
process, then are time stamped with their arrival time and used to update a file indicating the
status of the host. When a host has not been heard from for an extended period of time, the
database interpretation routines assume the host is down and indicate such on the status
reports. This algorithm is prone to error as a server may be down while a host is actually up,
but serves our current needs.
The second task performed by the server is to supply information regarding the status of its
host. This involves periodically acquiring system status information, packaging it up in a message and broadcasting it on the local network for other rwho servers to hear. The supply function is triggered by a timer and runs off a signal. Locating the system status information is
somewhat involved, but uninteresting. Deciding where to transmit the resultant packet does,
however, indicates some problems with the current protocol.
Status information is broadcast on the local network. For networks which do not support the
notion of broadcast another scheme must be used to simulate or replace broadcasting. One possibility is to enumerate the known neighbors (based on the status received). This, unfortunately, requires some bootstrapping information, as a server started up on a quiet network
will have no known neighbors and thus never receive, or send, any status information. This is
the identical problem faced by the routing table management process in propagating routing
status information. The standard solution, unsatisfactory as it may be, is to inform one or
more servers of known neighbors and request that they always communicate with these neighbors. If each server has at least one neighbor supplying it, status information may then propagate through a neighbor to hosts which are not (possibly) directly neighbors. If the server is
able to support networks which provide a broadcast capability, as well as those which do not,
then networks with an arbitrary topology may share status information*.
1 • One must, however, he concerned about "loops". That is, if a host is connected to multiple
networks, it will receive status information from itself. This can lead to an endless, wasterul, ex-

1) evision

E of 7 January 1984

19

Sun System Interface Manual

Interprocess Communication Primer

mainO
{
sp = getservbyname{"who", "udp");
net = getnetbyname("localnet");
sin.sin_addr = inet_makeaddr{INADDR_ANY, net);
sin.sin-POrt = sp- >s..,port;
s

=

socket(AF _I NET, SOCK_DGRAM, 0);

bind(s, &sin, sizeof (sin»;
sigset(SIGALRM, onalrm);
onalrmO;
for (;;) {
struct whod wd;
int cc, whod, len = sizeof (from);
cc = recvfrom(s, (char t )&wd, sizeof (struet whod), 0, &from, &Ien);
if (ce <= 0) {
if (cc < 0 && err no != EINTR)
perror("rwhod: recv");
continue;

}
if (from.sin.....Port != sp->s-POrt) {
.
fprintC(stderr, "rwhod: %d: bad from port\n" ,
n to hs( Crom .sin-POrt »;
continue;
}

if (!veriCy(wd.wd_hostname)) {
Cprintf( stderr, "rw hod: malformed host name from %x \n" ,
ntohl(Crom.sin_addr.s_addr»;
continue;
}
(void) sprintC(path, "%s/whod.%s", RWHODIR, wd.wd_hostname);
whod = open(path, O_FWRONLYIO_FCREATEIO_FTRUNCATE, 0666);
(void) time( &wd.wd_recvtime);
(void) write(whod, (char t)&wd, ce);
(void) close(whod);

}
}
Figure 4. rwho server.

change of information.

Revision E of 7 January 1984

Sun System Interface Manual

Interprocess Communication Primer

The second problem with the current scheme is that the rwho process services only a single local
network, and this network is found by reading a file. It is important that software operating in
a distributed environment not have any site-dependent information compiled into it. This
would require a separate copy of the server at each host and make maintenance a severe
headache. The Sun system attempts to isolate host,.specific information from applications by
providing system calls which return the necessary informationt. The rwho server performs a
lookup in a file to find its local network. A better, though still unsatisfactory, scheme used by
the routing process is to interrogate the system data structures to locate those directly connected networks. A mechanism to acquire this information from the system would be a useful
addition.

1

t An eX&mple or such a system call is the gdlo,'••me(2)

call which returns the host's "official"

n&me.

11,evision E of 7 January 1984

21

Interprocess Communication Primer

Sun System Interface Manual

5. Advanced Topics
A number of facilities have yet to be discussed. For most users of the ipc the mechanisms
already described will suffice in constructing distributed applications. However, others will find
need to utilize some of the features which we consider in this section.

5.1. Out of Band Data
The stream socket abstraction includes the notion of "out of band" data. Out of band data is a
logically independent transmission channel associated with each pair of connected stream sockets. Out of band data is delivered to the user independently of normal data along with the
SIGURG signal. In addition to the information passed, a logical mark is placed in the data
stream to indicate the point at which the out 01 band data was sent. The remote login and
remote shell applications use this facility to propagate signals from between client and server
processes. When a signal is expected to flush any pending output from the remote proceS5{es),
all data up to the mark in the data stream is discarded.
The stream abstraction defines that the out 01 band data facilities must support the reliable
delivery of at least one out of band message at a time. This message may contain at least one
byte of data, and at least one message may be pending delivery to the user at anyone time.
For communications protocols which support only in-band signaling (that is, the urgent data is
delivered in sequence with the norma! data) the system extracts the data from the normal data
stream and stores it separately. This allows users to choose between receiving the urgent data
in order and receiving it out of sequence without having to buffer all the intervening data.
To send an out of band message the MSG_OOB flag is supplied to a ,end or ,entito calls, while
to receive out or band data MSG_OOB should be indicated when performing a rectJ/rom or rectJ
call. To find out ir the read pointer is currently pointing at the mark in the data stream, the
SIOCATMARK ioctl is provided:
ioctl(s, SIOCATMARK, &yes);

If yel is a 1 on return, the next read will return data after the mark. Otherwise (assuming out
or band data has arrived), the next read will provide data sent by the client prior to transmission or the out of band signal. The routine used in the remote login process to flush output on
receipt of an interrupt or quit signal is shown in Figure 5.

5.2. Signals and Process Groups
Due to the existence of the SIGURG and SIGIO signals each socket has an associated process
group (just as is done for terminals). This process group is initialized to the process group of its
creator, but may be redefined at a later time with the SIOCSPGRP ioctl:

22

Revision E of 7 January 1984

Sun System Interface Manual

Interprocess Communication Primer

oobO

{
int out = 1+ I;
char waste(BUFSIZ], mark;
signal(SIGURG, oob);
,* flush local terminal input and output *,
ioctl(l, TIOCFLUSH, (char *)&out);
for (;;) {
if (ioctl(rem, SIOCATMARK, &mark)
perror(" ioctl" );
break;

< 0) {

}
if (mark)
break;
(void) read{rem, waste, sizeof (waste»;

}
recv(rem, &mark, I, MSG_OOB)j

}
Figure 5. Flushing terminal i/o

OD

receipt of out of band data.

ioctl(s, SIOCSPGRP, &pgrp);
A similar ioctl, SIOCGPGRP, is available for determining the current process group of a socket.

5.3. Pseudo Terminals
Many progra.ms will not function properly without a terminal for standard input and output.
Since a socket is not a terminal, it is often necessary to have a process communicating over the
network do so through a p,eudo terminal. A pseudo terminal is actually a pair of devices, master and slave, VI hich allow a process to serve as an active agent in communication between
processes and users. Data written on the slave side of a pseudo terminal is supplied as input to
a process reading from the master side. Data written on the master side is given the slave as
input. In this way, the process manipulating the master side of the pseudo terminal has control
over the information read and written on the slave side. The remote login server uses pseudo
terminals for remote login sessions. A user logging in to a machine across the network is provided a shell with a slave pseudo terminal as standard input, output, and error. The server process then bandies the communication between the programs invoked by the remote shell and the
user's local client process. When a user sends an interrupt or quit signal to a process executing
on a remqte machine, the client login program traps the signal, sends an out of band message to
the server process who then uses the signal number, sent as the data value in the out of band
message, to perform a killpi,2) on the appropriate process group.

Revision E of 7 January 1984

23

interprocess Communication Primer

Sun System Interface Manual

5.4. Internet Address Binding
Binding addresses to sockets in the Internet domain can be fairly complex. Communicating
processes are bound by an association. An as,sociation is composed of local and foreign
addresses, and local and foreign ports. Port numbers are allocated out of separate spaces, one
for each Internet protocol. Associations are always unique. That is, there may never be duplicate  tuples.
The bind system call allows a process to specify half of an association, , while the connect and accept primitives are used to complete a socket's association.
Since the association is created in two steps the association uniqueness requirement indicated
above could be violated unless care is taken. Further, it is unrealistic to expect user programs
to always know proper values to use for the local address and local port since a host may reside
on multiple networks and the set of allocated port numbers is not directly accessible to a user.
To simplify local address binding the notion of a "wildcard" address has been provided. When
an address is specified as INADDR_ANY (a manifest constant defined in 
#indude 
struct sockaddr_in sin;
s = socket(AF _INET, SOCK_STREAM, 0);
sin.sin_family = AF _INET;
sin.sin_addr.s_addr = INADDR_ANY;
sin.sin-port = MYPORT;
bind(s, (char *)&sin, sizeof (sin»;
Sockets with wildcarded local addresses may receive messages directed to the specified port
number, and addressed to any of the possible addresses assigned a host. For example, if a host
is on networks 46 and 10 and a socket is bound as above, then an accept call is performed, the
process will be able to accept connection requests which arrive either trom network 46 or network 10.
In a similar fashion, a local port may be left unspecified (specified as zero), in which case the
system will select an appropriate port number for it. For example:
sin.sin_addr.s_addr = MYADDRESS;
sin.sin-port = 0;
hindes, (char *)&sin, sizeof (sin»;
The system selects the port number based on two criteria. The first is that ports numbered 0
through IPPORT_RESERVED-l are reserved for privileged users (that is, the super user). The
second is that the port number is not currently bound to some other socket. In order to find a
free port number in the privileged range the following code is used by the remote shell server:

24

Revision E of 7 January 1984

Sun System Interface Manual

Interprocess Communication Primer

struct sockaddr_in sin;
Iport = IPPORT_RESERVED - 1;
sin.sin_addr.s-.addr ::= INADDR_ANY;
for (;;) {
sin.sin..,port = htons((u_short)Iport);
ir (bind(s, (caddr_t)&sin, sizeor (sin» >- 0)
break;
ir (errno f= EADDRINUSE && errDo!== EADDRNOTAVAIL) {
perror(" socket");
break;
}
lport--;
ir (Iport
IPPORT_RESERVED/2) {
rprintr(stderr, "socket: All ports in use \n" );
break;
}
}

==

The restriction on allocating ports was done to allow prOCe88eS executing in a "secure" environment to perform authentication based on the originating address and port number.
In certain cases the algorithm used by the system in selecting port numbers is unsuitable ror an
application. This is due to associations being created in a two step process. For example, the
Internet file transfer protocol, FTP, specifies that data connections must always originate rrom
the same local port. However, duplicate associations are avoided by connecting to different
foreign ports. In this situation the system would disallow binding the same local address and
port number to a socket if a previous data connection's socket were around. To override the
default port selection algorithm then an option call must be performed prior to address binding:
setsockopt(s, SOL_SOCKET, SO_REUSEADDR, (char .)0, 0);
bind( s, (char • )&sin, sizeor (sin»;
With the above call, local addresses may be bound which are already in use. This does not
violate the uniqueness requirement as the system still checks at connect time to be sure any
other sockets with the same local address and port do not have the same foreign address and
port (if an association already exists, the error EADDRINUSE is returned).
Local address binding by the system is currently done somewhat haphazardly when a host is on
multiple networks. Logically, one would expect the system to bind the local address associated
with the network through which a peer was communicating. For instance, if the local host is
connected to networks 46 and 10 a.nd the foreign host is on network 32, and traffic from network 32 were arriving via network 10, the local address to be bound would be the host's address
on network 10, not net-work 46. This unfortunately, is not. always the case. For reasons too
complicated to discuss here, the local address bound may be appear to be chosen at random.
This property or local address binding will normally be invisible to users unless the roreign host
does not understand how to reach the address selected•.
1 • For example, if network 48 were unknown to the host on network 32, and the local address
were bound tQ that loeatecl on network 48, then even though a route between the two hosts existed
throu!h network 10, a eo~nection would faiJ.

Revision

E of 7 January

1984

25

Interprocess Communication Primer

Sun System Interface Manual

5.5. Broadcasting and Datagram Sockets
By using a datagram socket it is possible to send broadcast packets on many networks supported by the system (the network itself must support the notion of broadcasting; the system
provides no broadcast simulation in software). Broadcast messages can place a high load on a
network since they force every host on the network to service them.
To send a broadcast message, an Internet datagram socket should be created:
s

=

socket(AF _INET, SOCK_DGRAM, 0);

and at least a port number should be bound to the socket:
sin.sin_family = AF _INET;
sin.sin_addr.s_addr = INADDR_ANY;
sin.sin-port = MYPORT;
bind(s, (char *)&sin, sizeof (sin»;
Then the message should be addressed as:
dst.sin_family = AF _I NET;
inet....makeaddr( net, INAD DR_ANY);
dst.sin-port = DESTPORT;
and, finally, a sendto call may be used:
sendto(s, buf, bufien, 0, &dst, sizeof (dst»;
Received broadcast messages contain the senders address and port (datagram sockets are
anchored before a message is allowed to go out).
There are a couple of minor problems in the above example. One is created because
INADDR....ANY has two meanings:
1. Fill in my own address, and,
2. Broadcast.
Unfortunately, broadcast must at some time in the future be changed to -1 instead of 0, so that
broadcast will no longer be The second problem is how do you get your net number! You could
use the SIOCGICONF ioetl call, or you could get your own address and do a ind_netof on that.
INADDR....ANY.

5.6. Signals
Two new signals have been added to the system which may be used in conjunction with the
interprocess communication facilities. The SIGURG signal is associated with the existence of an
"urgent condition". The SIGIO signal is used with "interrupt driven i/o" (not presently implemented). SIGURG is currently supplied a process when out of band data is present at a socket.
If multiple sockets have out of band data awaiting delivery, a select call may be used to determine those sockets with such data.
An old signal which is useful when constructing server processes is SIGCHLD. This signal is
delivered to a process w hen any children processes have changed state. Normally servers Use
the signal to "reap" child processes after exiting. For example, the remote login server loop
shown in Figure 2 may be augmented as follows:

26

Revision E of 7 January 1984

Sun System Interface Manual

Interprocess Communication Primer

int reaper();
signal( SI GCULD , reaper);
listen(f, 10);
for (;;) {
int g, len = siz~of (from);
g = accept(f, &from, klen, 0);
if (g < 0) {
if (errno !- EINTR)
perror("rlogind: accept");
continue;
}

}
#include 
reaper()
{
union wait status;
while (wait3(kstatus, WNOHANG, 0) > 0)

}
If the parent server process fails to reap its children, a large number of "zombie" processes may
be created.

Revision E of 7 January 1984

27
Source Exif Data: 
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Create Date                     : 2012:09:28 09:29:03-08:00
Modify Date                     : 2012:09:28 10:04:05-07:00
Metadata Date                   : 2012:09:28 10:04:05-07:00
Producer                        : Adobe Acrobat 9.52 Paper Capture Plug-in
Format                          : application/pdf
Document ID                     : uuid:152af4bf-369a-42cc-bc89-5726fae7ff28
Instance ID                     : uuid:60afebd9-38e1-43fc-8b55-e2ac124f54ea
Page Layout                     : SinglePage
Page Mode                       : UseOutlines
Page Count                      : 508
EXIF Metadata provided by EXIF.tools

Navigation menu