UNIK V/386

(1)

-

- •

:. . AT8aT

UNIKSystem V/386

fiB3se3.2

PRC::ERA~'S FEFEREI\ICE ^MANUAL

(2)

---AllaY

UNIX® System V/386 Release 3.2

Programmer's Reference Manual

-il

Prentice Hall, Englewood Cliffs, New Jersey 07632

(3)

Library of Congress Catalog Card Number: 88·62527

EditoriaUproduction supervision: Karen Skrable Fortgang Manufacturing buyer: Mary Ann Gloriande

II

=- Published by Prentice-Hall, Inc.

- A Division of Simon & Schuster - Englewood Cliffs, New Jersey 07632

NOTICE

The information in this document is subject to change without notice.

AT&T assumes no responsibility for any errors that may appear in this document.

DEC is a trademark of Digital Equipment Corporation.

DOCUMENTER'S WORKBENCH is a trademark of AT&T.

HP is a trademark of Hewlett Packard Co.

Intel is a registered trademark of Intel Corporation.

TEKTRONIX is a registered trademark of Tektronix, Inc.

TELETYPE is a registered trademark of AT&T.

UNIX is a registered trademark of AT&T.

VAX is a trademark of Digital Equipment Corporation.

XENIX is a registered trademark of Microsoft Corporation.

The publisher offers discounts on this book when ordered in bulk quantities. For more information, write or call:

Special Sales Prentice-Hall. Inc.

College Technical and Reference Division Englewood Cliffs, NJ 07632

(20 I) 592-2498

Printed in the United States of America 10 9 8 7 6 5 4 3 2

ISBN 0-13-944901-9

Prentice-Hall International (UK) Limited,London Prentice-Hall of AustraliaPty.Limited,Sydney Prentice-Hall Canada Inc.,Toronto

Prentice-Hall Hispanoamericana, S.A.,Mexico Prentice-Hall of India Private Limited,New Delhi Prentice-Hall of Japan, Inc.,Tokyo

Simon&Schuster Asia Pte. Ltd.,Singapore

(4)

T ABLE OF CONTENTS 1. Commands

intro(1) . . . introduction to programming commands

admin(1) create and administer

sees

files

ar(1). . . . • . . . archive and library maintainer for portable archives as(1) • . . . • . . . common assembler

cb(1)

e

program beautifier

cc(1)

e

^compiler

ccoff(1) . . . convert aeOFFfile cdc(1) . . . change the delta commentary of an

sees

^delta

cflow(1) generate

e

^flowgraph

chkshlib(1) • . . . compare shared libraries tool comb(1) • • . . . combine

sees

^deltas

conv(1) . • . . . common object file converter convert(1) . . . • . . . convert archive files to common formats cpp(1) • . . . • . . . the

e

language preprocessor cprs(l) • . . . compress a common object file cscope(1) . . . interactively examine a

e

program ctags(1) • • . . . create a tags file ctrace(1) • • • • . • . . . • . . .

e

program debugger cxref(1). . . generate

e

program cross-reference delta(1) • . . . make a delta (change) to an

sees

file dis(1) . • . . . object code disassembler dump(1) • • • . . . . • . . . dump selected parts of ail object file gencc(1) • • • . . . create a front-end to the cc command get(1) . . . get a version of an

sees

^file

hdr(1) . . . display selected parts ofaXENIX object file i286emul(1) . . . emulate 80286 infocmp(1M) . . . compare or print out terminfo descriptions Id(1) • . • . • . . . link editor for common object files

lex(1) generate programs for simple lexical tasks

lint(1) . . • . . . • . . . a

e

program checker list(1) produce

e

source listing from a common object file lorder(1) • • . . . find ordering relation for an object library Iprof(1) • . • . . . display line-by-line execution count profile data m4(1) . . . macroprocessor make(1) • . . . maintain, update, and regenerate groups of programs mcs(1) • . . . manipulate the object file comment section mkshlib(1) . . . create a shared library nm(1) . • • . . . print name list of common object file prof(1) . . . display profile data prs(1) . . . print an

sees

^file

regcmp(l) regular expression compile

rmdel(1) . . . remove a delta from an

sees

^file

sact(1). • . . • . . . print current

sees

file editing activity

sccsdiff(l) compare two versions of an

sees

file

sdb(1). . • . . . symbolic debugger size(1) . • • . . . print section sizes in bytes of common object files strings(1) . . . find the printable strings in an object file

- iii -

(5)

Table of Contents

strip(l) . . . strip symbol and line number info from a common object file

tic(lM) " terminfo compiler

tsort(1) . . . topological sort unget(l) . . . undo a previous get of an

sees

file val(l) . . . validate

sees

file vc(l) . . . version control what(l) . . . identify

sees

files x286emul(1) . . . emulate XENIX 80286

yacc(l) yet another compiler-compiler

2. System Calls

intro(2) introduction to system calls and error numbers access(2) . . . determine accessibility of a file

acct(2) enable or disable process accounting

alarm(2) set a process alarm clock

brk(2) . . . change data segment space allocation chdir(2) . . . change working directory chmod(2). . . change mode of file chown(2). . . change owner and group of a file chroot(2) . . . change root directory close(2) . . . close a file descriptor creat(2) . . . create a new file or rewrite an existing one

dup(2) duplicate an open file descriptor

exec(2) . . . execute a file

exit(2) . . . terminate process fcntl(2) . . . file control

fork(2) create a new process

getdents(2) read directory entries and put in a file-system-independent format getmsg(2) . . . get next message off a stream getpid(2) get process, process group, and parent process IDs getuid(2) . get real user, effective user, real group, and effective group IDs ioctl(2) . . . control device kill(2) . . . send a signal to a process or a group of processes

link(2) link to a file

Is€ek(2) move read/write file pointer

mkdir(2) make a directory

mknod(2) . . . make a directory or a special or ordinary file or a FIFO mount(2) . . . mount a file system

msgctl(2) message control operations

msgget(2) . . . get message queue msgop(2) . . . message operations nice(2) . . . change priority of a process open(2) . . . open for reading or writing

pause(2) . . . suspend process until signal

pipe(2) . . . create an interprocess channel plock(2) . . . lock process, text, or data in memory

pol1(2) . . . . STREAMS input/output multiplexing

profi1(2) . . . execution time profile - iv -

(6)

Table of Contents

ptrace(2) . . . process trace putmsg(2) . . . send a message on a stream read(2). . . read from file rmdir(2) . • . . . remove a directory

semctl(2) semaphore control operations

semget(2) . . . get set of semaphores semop(2) . . . • . . . • . semaphore operations

setpgrp(2) . . . set process group ID

setuid(2) . . . set user and group IDs shmctl(2) . . . shared memory control operations shmget(2) . . . get shared memory segment identifier shmop(2). . . shared memory operations

signal(2) specify what to do upon receipt of a signal

sigset(2) signal management

stat(2) . . . get file status statfs(2) .'. . . get file system information

stime(2) . . . set time

sync(2) . . . update super block sysfs(2) . . . get file system type information sysi86(2) . . . machine-specific functions time(2) . . . get time

times(2) . . get process and child process times

uadmin(2) . . . administrative control

ulimit(2) . . . get and set user limits

umask(2) . . . set and get file creation mask

umount(2) . . . unmount a file system

uname(2) get name of current UNIX system

unlink(2) . . . remove directory entry ustat(2) . . . get file system statistics

utime(2) set file access and modification times

wait(2) . . . wait for child process to stop or terminate write(2) . . . write on a file 3. Subroutines

intro(3) . . . introduction to functions and libraries a641(3C) . . . convert between long integer and base-64 ASCII string

abort(3C) generate an abort fault

abs(3C) . . return integer absolute value

assert(3X) verify program assertion

bessel(3M) . . . Bessel functions bsearch(3C) . . . binary search a sorted table clock(3C) . . . report CPU time used crypt(3C) . . . generate hashing encryption crypt(3X) . . . password and file encryption functions

ctermid(3S) generate file name for terminal

ctime(3C) convert date and time to string

ctype(3C) . . . character handling curses(3X) terminal screen handling and optimization package

(7)

Table of Contents

cuserid(3S). . . get character login name of the user dial(3C) • . . . establish an outgoing terminal line connection directory(3C) . . . directory operations drand48(3C) . . . generate uniformly distributed pseudo-random numbers dup2(3C) . . . duplicate an open file descriptor ecvt(3C) • . . . convert floating-point number to string

end(3C) last locations in program

erf(3M). • . . . error function and complementary error function exp(3M). . . exponential, logarithm, power, square root functions

fclose(3S) . . . close or flush a stream

ferror(3S) stream status inquiries

field(3X) . . . FIELD library routines

fieldtype(3X) FIELDTYPE library routines

floor(3M) . . . floor, ceiling, remainder, absolute value functions fopen(3S) . . . open a stream form(3X) • . . . FORM library routines fpgetround(3C) IEEE floating point environment control fread(3S) • . . . binary inputjoutput frexp(3C) . . . manipulate parts of floating-point numbers fseek(3S) . . . reposition a file pointer in a stream ftw(3C) . . . walk a file tree

gamma(3M) log gamma function

getc(3S) . . . get character or word from a stream getcwd(3C) . . . get path name of current working directory getenv(3C) . . • . . . return value for environment name getgrent(3C). . . get group file entry gethz(3C) return the frequency of the system clock in ticks per second getlogin(3C). . . get login name getopt(3C) • . . . get option letter from argument vector getpass(3C) . . . read a password

getpw(3C) get name from UID

getpwent(3C) get password file entry

gets(3S). . . get a string from a stream getut(3C) . . . access utmp file entry

hsearch(3C) manage hash search tables

hypot(3M) . . . Euclidean distance function isnan(3C). . . test for floating point NaN (Not-A-Number) item(3X) . . . CRT item routines 13tol(3C) convert between 3-byte integers and long integers Idahread(3X) read the archive header of a member of an archive file Idclose(3X) . . • . . . close a common object file Idfhread(3X) read the file header of a common object file Idgetname(3X) . . retrieve symbol name for common object file symbol table entry Idlread(3X) • . . . manipulate line number entries of a common object file function Idlseek(3X) . . . . seek to line number entries of a section of a common object file Idohseek(3X) . . . seek to the optional file header of a common object file Idopen(3X) . . . open a common object file for reading Idrseek(3X) . . . seek to relocation entries of a section of a common object file Idshread(3X). . . . read an indexed/named section header of a common object file

(8)

Table of Contents

Idsseek(3X) . . . seek to an indexed/named section of a common object file Idtbindex(3X) . • compute the index of a symbol table entry of a common object file Idtbread(3X) • . . . . read an indexed symbol table entry of a common object file Idtbseek(3X) . . . seek to the symbol table of a common object file

libwindows(3X) windowing terminal function library

lockf(3C) . . . record locking on files logname(3X). . . return login name of user Isearch(3C) . . . linear search and update

malloc(3C) . . . main memory allocator

malloc(3X) • . . . fast main memory allocator matherr(3M) . • . . . error-handling function

memory(3C) memory operations

menu(3X). • • . • . . . • . . . CRT menu routines mktemp(3C) . . . make a unique file name monitor(3C) . . . prepare execution profile nlist(3C) • . . . • . . . get entries from name list nlsgetcall(3N) . . . get client's data passed via the listener nlsprovider(3N) . . . get name of transport provider nlsrequest(3N) . . . format and send listener service request message panel(3X) . . . PANEL library routines perror(3C) . . . system error messages plot(3X) . . . graphics interface subroutines

popen(3S) initiate pipe to/from a process

printf(3S) . • . . • . . . print formatted output putc(3S) . . . put character or word on a stream

putenv(3C) change or add value to environment

putpwent(3C) . . . • . . . write password file entry puts(3S) . . . put a string on a stream qsort(3C) . . . • . . . quicker sort rand(3C) . . . simple random-number generator

regcmp(3X) . compile and execute regular expression

scanf(3S) . . . convert formatted input

setbuf(3S) assign buffering to a stream

setjmp(3C) non-local goto

sinh(3M). . . hyperbolic functions sleep(3C) . . . suspend execution for interval sputl(3X) access long integer data in a machine-independent fashion ssignal(3C) . . . software signals stdio(3S) . . . standard buffered input/output package stdipc(3C). . . standard interprocess communication package string(3C) . . . string operations strtod(3C) . . convert string to double-precision number strtol(3C) . . . convert string to integer swab(3C). . . swap bytes system(3S) . . . issue a shell command

tam(3C) TAM transition libraries

tmpfile(3S) . . . create a'temporary file tmpnam(3S) . . . create a name for a temporary file

trig(3M) trigonometric functions

(9)

Table of Contents

tsearch(3C) . . . • . . . manage binary search trees ttyname(3C). . . find name of a terminal ttyslot(3C) . . . find the slot in the utmp file of the current user Laccept(3N) . . . accept a connect request Lalloc(3N) . . . allocate a library structure Lbind(3N) . . . bind an address to a transport endpoint Lclose(3N) • . . . close a transport endpoint Lconnect(3N) . . . establish a connection with another transport user

Lerror(3N) . . . produce error message

Lfree(3N) . . . . free a library structure

Lgetinfo(3N) . . get protocol-specific service information

Lgetstate(3N) get the current state

Llisten(3N) . . . listen for a connect request Llook(3N) . . . look at the current event on a transport endpoint Lopen(3N) . . . establish a transport endpoint

Loptmgmt(3N) manage options for a transport endpoint

Lrcv(3N) receive data or expedited data sent over a connection Lrcvconnect(3) . . . receive the confirmation from a connect request Lrcvdis(3N) . . . retrieve information from disconnect Lrcvrel(3N) . . . . acknowledge receipt of an orderly release indication Lrcvudata(3N) . . . receive a data unit Lrcvuderr(3N) . . . receive a unit data error indication Lsnd(3N) send data or expedited data over a connection Lsnddis(3N) . . . send user-initiated disconnect request Lsndrel(3N). . . initiate an orderly release

Lsndudata(3N) send a data unit

Lsync(3N) . . . synchronize transport library Lunbind(3N) . . . disable a transport endpoint ungetc(3S) . . . push character back into input stream vprintf(3S) . . . print formatted output of a varargs argument list 4. File Formats

intro(4) . . . introduction to file formats

a.out(4) common assembler and link editor output

acct(4). . . • . . . per-process accounting file format ar(4) . . . common archive file format cftime(4) . . . • . . . language specific strings checklist(4) . . . list of file systems processed by fsck and ncheck

core(4) . . . format of core image file

cpio(4) format of cpio archive

dir(4) . . . format of directories dirent(4) . . . file-system-independent directory entry

filehdr(4) file header for common object files

fs(4). . . format of system volume fspec(4) . . . format specification in text files fstab(4) . . . file-system-table gettydefs(4) . . . speed and terminal settings used by getty gps(4) graphical primitive string, format of graphical files

(10)

Table of Contents

group(4). . . group file inittab(4). . . script for the init process inode(4) . . . format of an inode issue(4) . . . issue identification file Idfcn(4) . . . common object file access routines limits(4) . . . file header for implementation-specific constants linenum(4) . • . . . line number entries in a common object file loginlog(4) . . . log of failed login attempts

mdevice(4) . . . file format

mfsys(4) . . . file format

mnttab(4) . . . mounted file system table

mtune(4) file format

passwd(4) . . . password file

plot(4) . . . graphics interface

pnch(4) . . . • . . . file format for card images profile(4) . . . setting up an environment at login time reloc(4) relocation information for a common object file rfmaster(4) . • . . . Remote File Sharing name server master file sccsfile(4) . . . format of SCCS file scnhdr(4) . . . section header for a common object file scr_dump(4) • . . . format of curses screen image file

sdevice(4) . . . file format

sfsys(4) . . . file format

stune(4) file format

syms(4) common object file symbol table format

term(4) . . . format of compiled term file terminfo(4) . . . • . . . terminal capability data base timezone(4) . . . set default system time zone

unistd(4) file header for symbolic constants

utmp(4). . . utmp and wtmp entry formats 5. Miscellaneous Facilities

intro(5) . . . . .. . . introduction to miscellany

ascii(5) map of ASCII character set

environ(5) • . . . • . . . user environment fcntl(5) . . . • . • . file control options jagent(5) . . . host control of windowing terminal layers(5) . . . protocol used between host and windowing terminal under math(5) . . . math functions and constants prof(5) . . . profile within a function regexp(5) . . . • . . . regular expression compile and match routines stat(5) . . . • . data returned by stat system call term(5). . . conventional names for terminals

types(5) primitive system data types

values(5) . . . machine-dependent values varargs(5) . • • . . . handle variable argument list xtproto(5) multiplexed channels protocol used by xt(7) driver

(11)

(12)

Introduction

This manual describes the programming features of theUNIXsystem. For more information onUNIX System V/386, see the available documentation listed in the UNIXSystem V/386Product Overview/Documentation Roadmap.

Not all commands, features, and facilities described in this manual are available in everyUNIXsystem. Some of the features require additional utilities which may not exist on your system.

This manual is divided into five sections, some containing subsections.

1. Commands 2. System Calls 3. Subroutines:

3C. C Programming Language Libraries 3S. Standard I/O Library Routines 3M. Mathematical Library Routines 3N. Networking Support Utilities 3X. Specialized Libraries

4. File Formats

5. Miscellaneous Facilities.

Section 1(Commands) describes commands that support C and other programming languages.

Section2(System Calls) describes the services provided by theUNIX Sys- tem kernel, including the C language interface.

Section3(Subroutines) describes available subroutines. Their binary versions reside in various system libraries in the directories /lib and /usr/lib.

See intro(3) for descriptions of these libraries and the files in which they are stored.

Section4(File Formats)documents the structure of particular kinds of files; for example, the format of the output of the link editor is given in a.out(4). Excluded are files used by only one command (for example, the assembler's intermediate files). In general, the C language structures corresponding to these formats can be found in the directories/usr/include and /usr/include/sys.

(13)

Introduction

Section5 (Miscellaneous Facilities)contains a variety of things. Included are descriptions of character sets, macro packages, etc.

References with numbers other than those above mean that the utility is contained in the appropriate section of another manual. References with(1) or (1M)following the command mean that the utility is contained in this manual or theUser'sjSystem Administrator's Reference Manual. Those followed by(7)

are contained in the User'sjSystem Administrator's Reference Manual.

Each section consists of a number of independent entries of a page or so.

Entries within each section are alphabetized, with the exception of the intro- ductory entry that begins each section (also Section 3 is in alphabetical order by suffixes). Some entries may describe several routines, commands, etc. In such cases, the entry appears only once, alphabetized under its "primary"

name, the name that appears at the upper comers of each manual page.

All entries are based on a common format, not all of whose parts always appear:

• TheNAME part gives the name(s) of the entry and briefly states its purpose.

• TheSYNOPSIS part summarizes the use of the program being described. A few conventions are used, particularly in Section 2(Sys- tem Calls):

D Boldface strings are literals and are to be typed just as they appear.

o

Italic strings usually represent substitutable argument prototypes and program names found elsewhere in the manual.

o

Square brackets [] around an argument prototype indicate that the argument is optional. When an argument prototype is given as

"name" or "fileII , it usually refers to a file name.

D Ellipses. .. are used to show that the previous argument prototype may be repeated.

o

A final convention is used by the commands themselves. An argument beginning with a minus - or plus

+

is often taken to be some sort of flag argument, even if it appears in a position where a file name could appear. Therefore, it is unwise to have files whose names begin with - or

+.

(14)

Introduction

• TheDESCRIPTION part describes the utility.

• TheEXAMPLE(S) part gives example(s) of usage, where appropriate.

• TheFILES part gives the file names that are built into the program.

• TheSEE ALSO part gives pointers to related information.

• TheDIAGNOSTICS part discusses the diagnostic messages that may be produced. Messages that are intended to be. self-explanatory are not listed.

• The NOTESpart gives generally .. helpful hints^II about the use of the utility.

• TheWARNINGS part points out potential pitfalls.

• TheBUGS part gives known bugs and deficiencies.

• The CAVEATSpart gives details of the implementation that might affect usage.

A "Table of Contents" and a .. Permuted Index" derived from that table precede Section 1. The "Permuted Index" is a list of keywords, given in the second of three columns, together with the context in which each keyword is found. Keywords are either topical keywords or the names of manual entries.

Entries are identified with their section numbers shown in parentheses. This is important because there is considerable duplication of names among the sections, arising principally from components that exist only to exercise a particular system call. The right column lists the name of the manual page on which each keyword may be found. The left column contains useful information about the keyword.

(15)

(16)

INTRO(l)

NAME

INTRO(l)

intro - introduction to programming commands DESCRIPTION

This section describes, in alphabetical order, commands available for your computer. The top of each page indicates the utilities package to which the command belongs. The packages are:

Base System

C Software Development Set Extended Terminal Interface COMMAND SYNTAX

Unless otherwise noted, the commands described accept options and other arguments according to the following syntax:

name [option(s)] [cmdarg(s)]

where:

name is the name of an executable file option is - noargletter(s)or

- argletter<>optarg where:

noargletter is a single letter representing an option without an option-argument

argletter is a single letter representing an option requiring an option-argument

<> is optional white space

optarg is an option-argument (character string) satisfying the precedingargletter.

cmdarg is a path name (or other command argument) not beginning with

"_", or "_" by itself indicating the standard input.

Throughout the manual pages there are references to TMPDIR, BINDIR, INCDIR, LIBDIR, and LLIBDIR. These represent directory names whose value is specified on each manual page as necessary. For example, TMPDIR might refer to Itmpor /usr/tmp. These are not environment variables and cannot be set. [There is also an environment variable called TMPDIR which can be set. Seetmpnam(3S).]

SEE ALSO

exit(2), wait(2), getopt(3C).

getopts(l) in theUser's/SystemAdministrato~'s Reference Manual.

Programmer's Guide.

DIAGNOSTICS

Upon termination, each command returns two bytes of status, one supplied by the system and giving the cause for termination and (in the case of "normal" termination) one supplied by the program [see wait(2) and exit(2)].

The former byte is 0 for normal termination; the latter is customarily 0 for

(17)

INTRO(l) INTRO(l)

successful execution and non-zero to indicate troubles such as erroneous parameters, or bad or inaccessible data. It is called variously ^IIexit code/If lIexit status/If or liretum code" and is described only where special conventions are involved.

WARNINGS

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

(18)

ADMIN(l)

NAME

(C Software Development Set) ADMIN(l)

admin - create and administer sees files SYNOPSIS

admin [-n] [-i[name]] [-rrel] [-t[name]] [-fflag[flag-val]] [-dflag[flag-val]]

[-alogin] [-elogin] [-m[mrlist]] [-y[comment]] [-h] [-z] files DESCRIPTION

The admin command is used to create new sees files and change parameters of existing ones. Arguments toadmin,which may appear in any order, consist of keyletter arguments that begin with a hyphen (-), and named files (note that sees file names must begin with the characters s.). If a named file does not exist, it is created, and its parameters are. initialized according to the specified keyletter arguments. Parameters not initialized by a keyletter argument are assigned a default value. If a named file does exist, parameters corresponding to specified keyletter arguments are changed, and other parameters are left as is.

If a directory is named, admin behaves as though each file in the directory were specified as a named file, except that non-seCS files (last component of the path name does not begin with s.) and unreadable files are silently ignored. If a name of - is given, the standard input is read; each line of the standard input is taken to be the name of an sees file to be processed.

Again, non-Sees fues and unreadable files are silently ignored.

The keyletter arguments are as follows. Each is explained as though only one named file is to be processed since the effects of the arguments apply independently to each named file.

-n This keyletter indicates that a new sees file is to be created.

-i[name] Thenameof a file from which the text for a new sees file is to be taken. The text constitutes the first delta of the file (see -r keyletter for delta numbering scheme). If the -i keyletter is used but the fue name is omitted, the text is obtained by reading the standard input until an end-of-file is

encounter~d. If this keyletter is omitted, then the sees file is created empty. Only one sees file may be created by an admin command on which the -i keyletter is supplied.

Using a single admin to create two or more sees files requires that they be created empty (no -i keyletter). Note that the -i keyletter implies the -n keyletter.

-rrel The release into which the initial delta is inserted. This keyletter may be used only if the -i keyletter is also used. If the -r keyletter is not used, the initial delta is inserted into release 1. The level of the initial delta is always 1 (by default initial deltas are named 1.1).

-t[name] The name of a file from which descriptive text for the sees file is to be taken. If the -t keyletter is used and admin is creating a new sees file (the -n and/or -i keyletters also used), the descriptive text file name must also be supplied.

In the case of existing sees fues: (1) a-t keyletter without a

(19)

ADMIN(l) (C Software Development Set) ADMIN(1)

-£flag

file name causes removal of descriptive text (if any) currently in the

sees

file, and (2) a ^-t keyletter with a file name causes text (if any) in the named file to replace the descriptive text (if any) currently in the

sees

file.

This keyletter specifies a flag, and, possibly, a value for the flag, to be placed in the

sees

file. Several f keyletters may be supplied on a single admin command line. The allowable flagsand their values are:

b Allows use of the-bkeyletter on a get(l) command to create branch deltas.

(ceil The highest release (Le., "ceiling"), a number greater than 0 but less than or equal to 9999, which may be retrieved by a get(l) command for editing. The default value for an unspecified ( flag is 9999.

ffloor The lowest release (Le., "floor"), a number greater than 0 but less than 9999, which may be retrieved by aget(l) command for editing. The default value for an unspecifiedf flag is 1.

dSID The default delta number ^(5105+1) to ^{be used by} a get(l)command.

i[str] Causes the "No id keywords (ge6)" message issued byget(l) ordelta(l) to be treated as a fatal error. In the absence of this flag, the message is only a warning. The message is issued if no

sees

identification keywords [seeget(I)] are found in the text retrieved or stored in the

sees

file. If a value is supplied, the keywords must exactly match the given string; how- ever, the string must contain a keyword and no embedded newlines.

Allows concurrent get(l) commands for editing on the same ^SID of an

sees

file. This allows multiple concurrent updates to the same version of the

sees

file.

llist A list of releases to which deltas can no longer be made (get -e against one of these "locked" releases fails). Thelisthas the following syntax:

<range>-::= Ia

The character a in the listis equivalent to specifying all releases for the named

sees

file.

n Causes delta(l) to create a "null" delta in each of those releases (if any) being skipped when a delta is made in a new release (e.g., in making delta 5.1 after delta 2.7, releases 3 and 4 are skipped). These null deltas serve as "anchor points" so that branch deltas

(20)

ADMIN(l) (C Software Development Set) ADMIN(l)

-dflag

-alogin

-elogin

may later be created from them. The absence of this flag causes skipped releases to be nonexistent in the

sees

file, preventing branch deltas from being created from them in the future.

qtext User-definable text substituted for all occurrences of the %Q% keyword in

sees

file text retrieved by get(l).

mmod Module name of the

sees

file substituted for all occurrences of the %M% keyword in

sees

file text retrieved byget(l). If the m flag is not specified, the value assigned is the name of the

sees

file with the leading s. removed.

ttype Type of module in the

sees

file substituted for all occurrences of %yOlo keyword in

sees

file text retrieved byget(l).

vpgm Causes delta(l) to prompt for Modification Request (MR) numbers as the reason for creating a delta. The optional value specifies the name of an MR number validity checking program [see delta(1)]. (If this flag is set when creating an

sees

file, the m keyletter must also be used even if its value is null.)

Causes removal (deletion) of the specifiedflag from an

sees

file. The-dkeyletter may be specified only when processing existing

sees

files. Several-dkeyletters may be supplied on a single admin command. See the -fkeyletter for allowable flagnames.

llist A list of releases to be "unlocked." See the -f keyletter for a description of the I flag and the syntax of alist.

Alogin name or numerical UNIX system group ID to be added to the list of users which may make deltas (changes) to the

sees

file. A group ID is equivalent to specifying all login names common to that group ID. Several a keyletters may be used on a singleadmin command line. As many logins or numerical group IDs as desired may be on the list simultane- ously. If the list of users is empty, then anyone may add deltas. If login or group ID is preceded by a ! it is to be denied permission to make deltas.

Aloginname or numerical group ID to be erased from the list of users allowed to make deltas (changes) to the

sees

file.

Specifying a group ID is equivalent to specifying all login names common to that group ID. Several e keyletters may be used on a singleadmin command line.

(21)

-m[mrlist] The list of Modification Requests (MR) numbers is inserted into the

sees

file as the reason for creating the initial delta in a manner identical todelta(1). The v flag must be set; the MRnumbers are validated if the v flag has a value (the name of anMRnumber validation program). Diagnostics will occur if the v flag is not set orMRvalidation fails.

-y[comment] Thecommenttext is inserted into the

sees

file as a comment for the initial delta in a manner identical to that ofdelta(l).

Omission of the -y keyletter results in a default comment line being inserted in the form:

date and time createdYY /MM/DD HH:MM:SSbylogin The -y keyletter is valid only if the -i and/or -nkeyletters are specified (Le., a new

sees

file is being created).

-h Causes admin to check the structure of the

sees

file [see sccsfile(5)], and to compare a newly computed check-sum (the sum of all the characters in the

sees

file except those in the first line) with the check-sum that is stored in the first line of the

sees

file. Appropriate error diagnostics are produced.

This keyletter inhibits writing on the file, so that it nullifies the effect of any other keyletters supplied, and is, therefore, only meaningful when processing existing files.

-z The

sees

file check-sum is recomputed and stored in the first line of the

sees

file (see-h,above).

Note that use of this keyletter on a truly corrupted file may prevent future detection of the corruption.

The last component of all

sees

file names must be of the form s.file-name.

New

sees

files are given mode 444 [see chmod(l)]. Write permission in the pertinent directory is, of course, required to create a file. All writing done byadmin is to a temporary x-file, calledx.file-name [seeget(l)] created with mode 444 if the admin command is creating a new

sees

file, or with the same mode as the

sees

file if it exists. After successful execution ofadmin, the

sees

file is removed (if it exists), and the x-file is renamed with the name of the

sees

file. This ensures that changes are made to the

sees

file only if no errors occurred.

It is recommended that directories containing

sees

files be mode 755 and that

sees

files themselves be mode 444. The mode of the directories allows only the owner to modify

sees

files contained in the directories. The mode of the

sees

files prevents any modification at all except by

sees

commands.

If it should be necessary to patch an

sees

file for any reason, the mode may be changed to 644 by the owner allowing use ofed(l). Care must be taken! The edited file shouldalways be processed by anadmin-h to check for corruption followed by an admin -z to generate a proper check-sum.

Anotheradmin-his recommended to ensure the

sees

file is valid.

(22)

The admin command also makes use of a transient lock file (called z.file- name), which is used to prevent simultaneous updates to the

sees

file by different users. Seeget(l) for further information.

FILES

g-file Existed before the execution of delta; removed after completion ofdelta.

p-file Existed before the execution of delta; may exist after completion ofdelta.

q-file Created during the execution of delta; removed after completion ofdelta.

x-file Created during the execution ofdelta; renamed to

sees

file after completion ofdelta.

z-file Created during the execution ofdelta; removed during the execution ofdelta.

d-file Created during the execution of delta; removed after completion ofdelta.

/usr/bin/bdiff Program to compute differences between the "gotten" file and theg-file.

SEE ALSO

delta(l), get(l), prs(l), what(l), sccsfile(4).

ed(l), in theUser's/System Administrator's Reference Manual.

(23)

AR(l)

NAME

(C Software Development Set) AR(l)

ar - archive and library maintainer for portable archives SYNOPSIS

ar key [keyarg] [posname] afile [name] ...

DESCRIPTION

The ar command maintains groups of files combined into a single archive file. Its main use is to create and update library files as used by the link editor. It can be used, though, for any similar purpose. The magic string and the file headers used by ar consist of printableASCII characters. If an archive is composed of printable files, the entire archive is printable.

Archives of text files created byarare portable between implementations of System V.

When ar creates an archive, it creates headers in a format that is portable across all machines. The portable archive format and structure is described in detail in ar(4). The archive symbol table [described inar(4)] is used by the link editor[Id(l)] to effect multiple passes over libraries of object files in an efficient manner. An archive symbol table is only created and main- tained by aT when there is at least one object file in the archive. The archive symbol table is in a specially named file that is always the first file in the archive. This file is never mentioned nor is it accessible to the user.

Whenever the ar(l) command is used to create or update the contents of such an archive, the symbol table is rebuilt. The s option, described in the following text, will force the symbol table to be rebuilt.

Unlike command options, the command key is a required part of ar'scommand line. The key (which may begin with a -) is formed with one of the following letters: drqtpmx. Arguments to the key, alternatively, are made with one or more of the following set: vuaibcls. Posname is an archive member name used as a reference point in positioning other files in the archive. Afile is the archive file. The names are constituent files in the archive file. The meanings of thekey characters are as follows:

d Delete the named files from the archive file.

r Replace the named filesinthe archive file. If the optional character u is used with r, then only those files with dates of modification later than the archive files are replaced. If an optional positioning character from the set abiis used, then the posname argument must be present and specify that new files are to be placed after (a) or before (b or i) posname. Otherwise new files are placed at the end.

q Quickly append the named files to the end of the archive file.

Optional positioning characters are invalid. The command does not check whether the added members are already in the archive. This option is useful to avoid quadratic behavior when creating a large archive piece-by-piece. Unchecked, the file may grow exponentially up to the second degree.

Print a table of contents of the archive file. If no names are given, all files in the archive are tabled. If names are given, only those files are tabled. .

(24)

AR(l) (C Software Development Set) AR(l)

FILES

p Print the named files in the archive.

m Move the named files to the end of the archive. If a positioning character is present, then the posname argument must be present and, as inr,specify where the files are to be moved.

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

The meanings of the key arguments are as follows:

v Give a verbose file-by-file description of the making of a new archive file from the old archive and the constituent files. When used with t, give a long listing of all information about the files.

When used with x, precede each file with a name.

c Suppress the message that is produced by default when afile is created.

1 Place temporary files in the local (current working) directory rather than in the default temporary directory,TMPDIR.

s Force the regeneration of the archive symbol table even if ar(1) is not invoked with a command which will modify the archive contents. This command is useful to restore the archive symbol table after thestrip(l)command has been used on the archive.

$TMPDIR/* temporary files

$TMPDIR is usually /usr/tmp but can be redefined by setting the environ- ment variableTMPDIR[seetempnam() intmpnam(3S)].

SEE ALSO

ld(l), lorder(l), strip(l), tsort(l), tmpnam(3S), a.out(4), ar(4).

NOTES

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

(25)

AS(l)

NAME

(C Software Development Set)

as - common assembler

AS(l)

SYNOPSIS

as [options] fue name DESCRIPTION

The as command assembles the named file. The following flags may be specified in any order:

-0objfile Putt~eoutput of the assembly in objfile. By default, the output file name is formed by removing the ^.8 suffix, if there is one, from the input file name and appending a^.0suffix.

-n Turn off long/short address optimization. By default, address optimization takes place.

-m Run them4macro processor on the input to the assembler.

-R Remove (unlink) the input file after assembly is completed.

-dl Do not produce line number information in the object file.

- V 'Write the version number of the assembler being run on the standard error output.

-y[md],dir Find the m4 preprocessor (m) and/or the file of predefined macros (d) in directorydirinstead of in the customary place.

FILES

TMPDIR/* temporary files

TMPDIR is usually /usr/tmp but can be redefined by setting the environment variableTMPDIR [seetempnamOintmpnam(3S)].

SEE ALSO

cc(1), Id(1), m4(1), nm(1), strip(1), tmpnam(3S), a.out(4).

NOTES

Wherever possible, the assembler should be accessed through a compilation system interface program [such ascc(1)].

WARNING

If the -m (m4macro processor invocation) option is used, keywords for m4 [see m4(1») cannot be used as symbols (variables, functions, labels) in the input file since m4 cannot determine which are assembler symbols and which are realm4macros.

BUGS

The .align assembler directive may not work in the .text section when optimization is performed.

CAVEATS

Arithmetic expressions may only have one forward referenced symbol per expression.

(26)

CB(l) (C Software Development Set) CB(l)

NAME

cb - C program beautifier SYNOPSIS

cb [ -8 ] [ -j ] [ -I leng ] [ file ... ] DESCRIPTION

The cb command reads C programs either from its arguments or from the standard input and writes them on the standard output with spacing and indentation that display the structure of the code. Under default options,cb preserves all user new-lines.

and Ritchie, D. M., The C Programming Language, Thecbcommand accepts the following options:

-8 Canonicalizes the code to the style of Kernighan and Ritchie in TheCProgramming Language.

Causes split lines to be put back together.

Causes cbto split lines that are longer thanleng.

-j -Ileng

o

compiler 2 optimizer a assembler 1 link editor

8 directory containing the start-up routines I default include directory searched bycpp(l) L first default library directory searched by ld (1) U second default library directory searched by ld(l)

If the location of a tool is being specified, then the new path name for the tool will be dirname/ tool. If more than one - Y option is applied to anyone tool or directory, then the last occurrence holds.

-Zp[11214]

Packs structure members in memory. Normally, structure members are aligned as follows: items of typecharare byte-aligned, items of type short are aligned on two-byte boundaries, and all other types of structure members are word-aligned.

Specifying an option to -Zpwill force alignment on the given byte boundary. If no option is used with-Zp, structure members will be packed on one-byte boundaries. The alignment may be altered with the#pragma packpreprocessor directive.

(29)

CC(l) (C Software Development Set) CC(l)

FILES

The cc command also recognizes -C, -D, -I, and -U and passes these options and their arguments directly to the preprocessor without using the -W option. Similarly, the cc command recognizes -a, -1, -m, -r, -s, -t, -u, -x, -z, -L, -M, and

-v

and passes these options and their arguments directly to the loader. See the manual pages for cpp(1) and Id(1) for descriptions.

Other arguments are taken to be C compatible object programs, typically produced by an earlier cc run, or perhaps libraries of C compatible routines and are passed directly to the link editor. These programs, together with the results of any compilations specified, are link edited (in the order given) to produce an executable program with name a.out unless the -0 option of the link editor is used.

If the cc command is put in a file prefixccthe prefix will be .parsed off the command and used to call the tools, Le., prefixtool. For example, OLDcc will call OLDcpp, OLDcomp, OLDoptim, OLDas, and OLDld and will link OLDcrt1.o. Therefore, one MUST be careful when moving the cc command around. The prefix will apply to the preprocessor, compiler, optimizer, assembler, link editor, and the start-up routines.

The C language standard was extended to allow arbitrary length variable names. The option pair "-Wp,-T -WO,-XT"will cause cc to truncate arbitrary length variable names.

C source file

preprocessed C source file object file

assembly language file link edited output start-up routine start-up routine temporary files preprocessor, cpp(1) compiler

optimizer assembler,as(1) link editor,Id(1) standard C library standard C shared library file.c

file.i file.o file.s a.out

LIBDIR/*crt1.o LIBDIR/crtn.o TMPDIR/*

LIBDIR/cpp LIBDIR/comp LIBDIR/optim BINDIR/as BINDIR/ld LIBDIR/libc.a LIBDIR/libe-s.a LIBDIR is usually/lib.

BINDIR is usuallyIbin.

TMPDIR is usually lusr/tmp but can be redefined by setting the environment variableTMPDIR [seetempnam()intmpnam(3S)].

SEE ALSO

as(1), Id(1), cpp(1), gencc(1M), lint(1), prof(1), sdb(1), tmpnam(3S).

Kernighan, B. W., and Ritchie, D. M., The C Programming Language, Prentice-Hall, 1978.

(30)

CC(l) (CSoftware Development Set) CC(l)

DIAGNOSTICS

The diagnostics produced by the C compiler are sometimes cryptic.

NOTES

By default, the return value from a compiledC program is completely random. The only two guaranteed ways to return a specific value is to expli- citly call exit(2) or to leave the function mainO with a "return expression;"

construct.

(31)

CCOFF(l)

NAME

(C Software Development Set) CCOFF(l)

ccoff - convert a COFF file SYNOPSIS

ccoff [-r] [-v] file ...

DESCRIPTION

The ccoff command converts a COFF file by byte-swapping all multi-byte integers in the file. Thus, if the COFF file has been built by a cross compiler running on a big-endian development machine (Motorola 68000, etc.), ccoff will convert the file to a format suitable for running on the target (80386) machine. The ccoffcommand will convert relocated executables, non-relocated objects, and archives (libraries). The -r flag performs the reverse conversion, so that a file that has already been run through ccoffcan be restored to its original state; or a file that has been built on a target machine can be manipulated on the development machine. The -v flag causes ccoffto operate verbosely.

sees

file names are supplied to the cdc command via the standard input (- on the command line), then the-mand-ykeyletters must also be used.

(34)

CFLOW(l)

NAME

(C Software Development Set) CFLOW(l)

cflow - generate C flowgraph SYNOPSIS

cflow [-r] [-ix] [-L ] [-dnum] files DESCRIPTION

The cflow command analyzes a collection of C, yacc, lex, assembler, and object files and attempts to build a graph charting the external references.

Files suffixed with .y, .I, and .c are yacced, lexed, and C-preprocessed as appropriate. The results of the preprocessed files, and files suffixed with.i, are then run through the first pass of lint(l). Files suffixed with .8 are assembled. Assembled files, and files suffixed with .0, have information extracted from their symbol tables. The results are collected and turned into a graph of external references which is displayed upon the standard output.

Each line of output begins with a reference number, followed by a suitable number of tabs indicating tHe level, then the name of the global symbol followed by a colon and its definition. Normally only function names that do not begin with an underscore are listed (see the -i options below). For information extracted from C source, the definition consists of an abstract type declaration (e.g., char*),and, delimited by angle brackets, the name of the source file and the line number where the definition was found. Defini- tions extracted from object files indicate the file name and location counter under which the symbol appeared (e.g., text). Leading underscores in C- style external names are deleted.

Once a definition of a name has been printed, subsequent references to that name contain only the reference number of the line where the definition may be found. For undefined references, only< > is printed.

As an example, given the following infile.c:

int i;

mainO {

f();

gO;

f();

fO {

i=hO;

}

(35)

CFLOW(l)

the command

(C Software Development Set) CFLOW(l)

cflow -ix file.c produces the output

1 main: intO, <file.c 4>

2 f: intO, <file.c 11>

3 h:<>

4 i: int, <file.c 1>

5 g: <>

When the nesting level becomes too deep, the output ofcflow can be piped to pr(I), using the -e option, to compress the tab expansion to something less than every eight spaces.

In addition to the -D, -I, and -U options [which are interpreted just as they are bycc(l) andcpp(I)],the following options are interpreted bycflow:

-r Reverse the ^{/ I}caller:callee"relatio~shipproducing an inverted listing showing the callers of each function. The listing is also sorted in lexicographical order by callee.

-ix Include external and static data symbols. The default is to include only functions in the flowgraph.

-L Include names that begin with an underscore. The default is to exclude these functions (and dataif-ixis used).

-dnum The num decimal integer indicates the depth at which the flowgraph is cut off. By default this is a very large number. Attempts to set the cutoff depth to a nonpositive integer will be ignored.

SEE ALSO

as(I), cc(I), cpp(I), lex(I), lint(l), nm(l), yacc(I).

pr(l) in theUser's/System Administrator's Reference Manual.

DIAGNOSTICS

Complains about bad options. Complains about multiple definitions and only believes the first. Other messages may come from the various programs used (e.g., the C-preprocessor).

BUGS

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

(36)

CHKSHLIB(l)

NAME

(C Software Development Set) CHKSHLIB(l)

chkshlib - compare shared libraries tool SYNOPSIS

chkshlib [-b] [-i] [-n] [-v] filel [file2 file3 ... ] DESCRIPTION

chkshlib checks for compatibility between files. Input files can be combinations of host shared libraries, non-stripped target shared libraries, and non- stripped executable files. A file is compatible with another file if every library symbol in it that should be matched is matched in the second (Le., the symbol exists and has the same address in both files). The path name for the target shared library in both files must be identical (unless the -i option is set).

It is possible for filel to be compatible with file2 without the reverse also being true.

If one incompatibility is found it is reported to stdout and processing stops (unless the-voption is set).

The options to chkshlibare:

-v Cause verbose reporting of all incompatibilities to stdout.

-b If there are symbols found in filel that are not in the bounds of file2, report warning messages to stderr.

-i Tum off the restriction that the path names for the target shared library need to be identical for two files to be compatible.

-n Indicate that there are exactly two input files, which are target shared libraries, where the first references symbols in the second ( "includes" the second).

The output ofchkshlib depends upon the input. If the first input file is an executable file and the other input files, if any, are target shared libraries, the output states whether or not the executable file can execute using each target shared library. If there are no target shared libraries supplied, chkshlibperforms the compatibility check against the target shared libraries specified in the.lib section of the executable file.

If the first input file is an executable file and the other input file(s) is a host shared library, the output states whether or not the executable file could have been produced using each host.

If one input file is a host shared library and the other input file, if any, is a target shared library, the output states whether or not the host shared library could produce executable files that will run with the target shared library. If no target shared library is supplied, then chkshlib performs the compatibility check against the target specified in the .lib section of the library definition file found in the host.

If both input files are target shared libraries or both input files are host shared libraries, the output states whether or not the first file could replace the second and vice versa.

(37)

CHKSHLIB(l) (C Software Development Set) CHKSHLIB(l)

If both input files are target libraries and the -n option is set, the output states if the first file references symbols in the second file (" includes" the second).

Compatibility of all other combinations of host shared libraries, target shared libraries, and executable files has no useful meaning, and these other combinations of files are not accepted as valid input to chkshlib.

SEE ALSO

mkshlib(1).

"Shared Libraries" chapter in theUNIXSystem V Programmer's Guide.

DIAGNOSTICS

Exit status is 0 if no incompatibilities are found, 1 if an incompatibility is found, and 2 if a processing error occurs.

CAVEAT

chkshlibrequires that you use the-ioption whenever you use the-noption.

Standard binaries distributed with the UNIX system are stripped, and chkshlibcannot be used with them.

UNIK V/386

-

- •

:. . AT8aT

UNIKSystem V/386

fiB3se3.2

PRC::ERA~'S FEFEREI\ICE MANUAL

---AllaY

UNIX® System V/386 Release 3.2

Programmer's Reference Manual

-il

II

ISBN 0-13-944901-9

sees

e

e

sees

e

sees

e

e

e

e

sees

sees

e

e

sees

sees

sees

sees

sees

sees

sees

Introduction

o

o

o

+

+.

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

sees

PRC::ERA~'S FEFEREI\ICE ^MANUAL