0130176826_System_Files_and_Devices_Reference_1992 0130176826 System Files And Devices Reference 1992

User Manual: 0130176826_System_Files_and_Devices_Reference_1992

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

Download
Open PDF In Browser	View PDF

-----

- - --

REFERENCE

SYSTEM FILES
AND DEVICES
REFERENCE
UNIX®SVR4.2

•

~
~

UNIX
PRESS

REFERENCE MANUAL

DESCRIPTION

Command Reference
(Commands a - I)

General-Purpose User Commands
Basic Networking Commands
Form and Menu Language Interpreter
System Maintenance Commands

Command Reference
(Commands m - z)

(same as above)

Operating System API
Reference

Windowing System API
Reference

System Files and Devices
Reference

Device Driver
Reference

SECTIONS

1
1C
1F
1M

System Calls
BSD System Compatibility Library
Standard C Library
ETI-curses Library
Executable and Linking Format Library
General-Purp0l>e Library
Identification and Authentication Library
Math Library
Networking Library
Standard I/O Library
Multibyte/wide Character Conversion Library
Specialized Libraries

2
3

Desktop Metaphor
Drag and Drop
MoOLIT
ETI-curses Library

3Dt
3DnD
30lit
3curses

System File Formats
Miscellaneous Facilities
Special Files (Devices)

4
5
7

DDI/DKI Driver Data Definitions
DDI/DKI Driver Entry Point Routines
DDI/DKI Kernel Utility Routines
Portable Device Interface (PDI) Routines
SCSI Device Interface (SDI) Routines
DDI/DKI Kernel Data Structures
SCSI Device Interface (SDI) Data Structures
DDI/DKI Kernel Defines

D1
D2
D3
D3G
D31
D4
D41
D5

3C
3curses
3E
3G
31
3M
3N
3S
3W
3X

SYSTEM FILES
AND DEVICES
REFERENCE
UNIXSVR4.2

Edited by Lynda Feng

UNIX
Press

Copyright © 1992,1991 UNIX System laboratories, Inc.
Copyright © 1990,1989,1988,1987,1986,1985,1984 AT&T
Portions Copyright © 1988-1990 Sun Microsystems, Inc.
Portions Copyright © 1980-1985 Regents of the University of California
Portions Copyright © 19911992 VERITAS Software Corporation
All Rights Reserved
Printed In USA
Published by Prentice-Hall, Inc.
A Simon & Schuster Company
Englewood Cliffs, New Jersey 07632
No part of this publication may be reproduced or transmitted in any form or by any means-graphic,
electronic, electrical, mechanical, or chemical, including photocopying, recording in any medium, taping, by any computer or information storage and retrieval systems, etc., without prior permissions in
writing from UNIX System Laboratories, Inc. (USL).
IMPORTANT NOTE TO USERS
While every effort has been made to ensure the accuracy and completeness of all information in this
document, USL assumes no liability to any party for any loss or damage caused by errors or omissions
or by statements of any kind in this document, its updates, supplements, or speCial editions, whether
such errors, omissions, or statements result from negligence, accident, or any other cause. USL further assumes no liability ariSing out of the application or use of any product or system described herein;
nor any liability for incidental or consequential damages arising from the use of this document. USL
disclaims all warranties regarding the information contsined herein, whether expressed, implied
or statutory, including Implied warranties of merchantability or fitness for a particular purpose.
usi.. makes no representation that the interconnection of products in the manner described herein will
not infringe on existing or future patent rights, nor do the descriptions contained herein imply the granting of any license to make, use or sell equipment constructed in accordance with this description.
USL reserves the right to make changes to any products herein without further notice.
TRADEMARKS
UNIX is a registered trademark of UNIX System Laboratories, Inc. in the USA and other countries.
WE is a registered trademark of AT&T.
XENIX is a registered trademark of Microsoft Corporation.

10 9 8 7 6 5 4 3 2 1

ISBN 0-13-017682-6

UNIX
PRESS

A Prentice Hall Title

PRENTICE

HALL

ORDERING INFORMATION
UNIX@ SYSTEM V RELEASE 4.2 DOCUMENTATION

To order single copies of UNIX@ SYSTEM V Release 4.2 documentation, please
call (515) 284-6761.

ATTENTION DOCUMENTATION MANAGERS AND TRAINING DIRECTORS:

For bulk purchases in excess of 30 copies, please write to:
Corporate Sales Department
PTR Prentice Hall
113 Sylvan Avenue
Englewood Cliffs, N.J. 07632
or
Phone: (201) 592-2863
FAX: (201) 592-2249

ATTENTION GOVERNMENT CUSTOMERS:

For GSA and other pricing information, please call (201) 461-7107.

Prentice-Hall International (UK) Limited, London
Prentice-Hall of Australia Pty. 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
Editora Prentice-Hall do Brasil, Ltda., Rio de Janeiro

Table of Contents
Introduction
File Formats
a.out(4) ............................................................................ ELF (Executable and Linking Format) files
acct(4) ............................................................................................ per-process accounting file format
admin(4) .......................................................................................................... installation defaults file
aliases, addresses, forward(4) ........................................ (BSD) addresses and aliases for sendmail
ar(4) ......................................................................................................................... archive file format
archives (4) ................................................................................................................. device header file
binarsys(4) .............................................. remote system information for the ckbinarsys command
boot (4) ................................................................................................................................ boot options
bootparams(4) ............................................................................................. boot parameter data base
compver(4) ..................................................................................................... compatible versions file
copyright (4) ................................................................................................ copyright information file
core (4) ............................................................................................................................. core image file
cron, queuedefs(4) .............................................................................. option files for crontab and at
depend (4) ................................................................................................. software dependencies files
dfstab (4) ................................................................ file containing commands for sharing resources
dirent(4) ............................................................................... file system independent directory entry
dir (cdfs)(4) .................................... format of CD-ROM file system (cdfs) directory data structure
dir (s5)(4) ......................................................................................................... format of s5 directories
dir (ufs) (4) ...................................................................................................... format of ufs directories
disk.dg(4) ............................................. configuration defaults for mass-storage and SCSI devices
dump (4) .......................................................................................................... boot dump timeout file
ethers (4) ............................................................ Ethernet address to hostname database or domain
fd(4) .......................................................................................................................... file descriptor files
filehdr(4) .......................................................................... file header for common object file (COFF)
fspec(4) .............................................................................................. format specification in text files
fstypes(4) ............................................................ file that registers distributed file system packages
fs (bfs)(4) ................................................................................... format of the bfs file system volume
fs (cdfs)(4) ................................................................................................. format of a cdfs file system
fs (s5) (4) ............................................................................................. format of s5 file system volume
fs (sfs)(4) ........................................................................................... format of sfs file system volume
fs (ufs)(4) .......................................................................................... format of ufs file system volume
fs (vxfs) (4) ...................................................................................... format of vxfs file system volume
gettydefs(4) ..................................................................... speed and terminal settings used by getty
group (4) .................................................................................................................................. group file
help (4) ............................................................................................................ Desktop help file format

Table of Contents

holidays (4) ..................................................................................................................... accounting file
hosts (4) ................................................................................................................. host name data base
hosts.equiv, .rhosts(4) .............................................................. trusted hosts by system and by user
inetd.conf(4) ................................................................................................. Internet servers database
Init(4) ............................................................................................ inittab entries for a kernel module
inittab (4) ............................................................................................................................ script for init
inode (bfs)(4) ...................................................................................................... format of a bfs i-node
inode (cdfs)(4) ................................................................................................... format of a cdfs inode
inode (s5)(4) ...................................................................................................... format of an s5 i-node
inode (sfs)(4) ........................................................................................................ format of a sfs inode
inode (ufs)(4) ....................................................................................................... format of a ufs inode
inode (vxfs)(4) ................................................................................................... format of a vxfs inode
interface (4) .................................................... Internet network interface configuration parameters
issue (4) .............................................................................................................. issue identification file
lid_and-IJriv (4) ................................................................. distributed file system security database
limits (4) ............................................................... header file for implementation-specific constants
login (4) ........................................................................................................................ login default file
loginlog(4) ................................................................................................ log of failed login attempts
mailcnfg(4) .................................................................. initialization information for mail and rmail
mailsurr(4) ................................................ surrogate commands for routing and transport of mail
mapchan(4) ................................................................................... format of tty device mapping files
Master (4) ................................................... generic configuration information for a kernel module
menu (4) ........................................................................ form description file for menu(l) command
mkdev(4) .................................................................................... file format for the pdimkdev utility
mnttab (4) .................................................................................................... mounted file system table
Mtune(4) ............................................................................................... tunable parameter definitions
netconfig(4) ...................................................................................... network configuration database
netdrivers(4) .............................................. data file for networking boards to protocols mappings
netmasks(4) ................................................................................................... network mask data base
netrc(4) .................................................................................................... file for ftp remote login data
networks (4) ................................................................................................... network name data base
Node (4) ........................................................................... device node definitions for a device driver
OHcValues(4) .......................................................... Input Context attribute names and value pairs
OHmValues (4) .................................................................................................... a list of 1M attributes
passwd(4) ......................................................................................................................... password file
pathalias(4) .............................................................................................................. alias file for FACE
pkginfo(4) .................................................................................................. package characteristics file
pkgmap(4) ...................................................................................... package contents description file
pnch(4) ....................................................................................................... file format for card images
priv(4) ........................................................................................................................ privilege data file
PrivTable(4) .................................................................................................................... privilege table
proc(4) ..................................................................................................................... process file system
profile (4) ............................................................................. setting up an environment at login time
protocols (4) ................................................................................................... protocol name data base

Table of Contents

prototype (4) .................................................................................................. package information file
publickey(4) .......................................................................................................... public key database
Rc (4) ..................................................................................................................... system startup script
res_major (4) ............................................. reserved major numbers for base system device drivers
resolv.conf(4) ................................................................. configuration file for name server routines
rfmaster(4) ................................................................... Remote File Sharing name server master file
routing (4) ................................................................ system supporting for packet network routing
rpc (4) .................................................................................................. rpc program number data base
rt_dptbl(4) ................................................................................ real-time dispatcher parameter table
Sassign(4) .............................................................................................. configurable device variables
sccsfile(4) ................................................................................................................ format of SCCS file
Sd (4) ..................................................................................... kernel module system shutdown script
services(4) ................................................................................................ Internet services and aliases
setinfo(4) ............................................................................................................. set characteristics file
setsize(4) .................................................................................................. disk space requirements file
shadow (4) .......................................................................................................... shadow password file
sharetab(4) ...................................................................................................... shared file system table
space (4) ..................................................................................................... disk space requirement file
Space.c(4) ......................... configuration-dependent kernel module data structure initializations
stat (4) ............................................................................... (XENIX) data returned by stat system call
strcf(4) ........................................................... STREAMS Configuration File for STREAMS TCP lIP
strftime(4) ..................................................................................................... language-specific strings
Stubs.c(4) ........................................................................................ stubs for kernel module symbols
stune(4) ........................................................................ local system settings for tunable parameters
su(4) ................................................................................................................................. su options file
syslog.conf(4) .......................................... (BSD) configuration file for syslogd system log daemon
System (4) ..................................... system-specific configuration information for a kernel module
tc.index(4) ............................................................ configuration index file for mass-storage devices
term (4) .................................................................................................... format of compiled term file
terminfo(4 N) ........................................................................................ terminal capability data base
timezone(4) ............................................................................................ set default system time zone
ttydefs(4) .............................................. file contains terminal line settings information for ttymon
ttysrch(4) ..................................................................... directory search list for ttymap and ttyname
unistd (4) ........................................................................................ header file for symbolic constants
updaters(4) ........................... configuration file for Network Information Service (NIS) updating
utrnp, wtmp(4) ................................................................................... utmp and wtmp entry formats
utrnpx, wtmpx(4) ........................................................................... utrnpx and wtrnpx entry formats
uuencode(4) ............................................................................... format of an encoded uuencode file
vfstab(4) .................................................................................................... table of file system defaults
Xwincmaps(4) ..................................................................................................... XWIN color map file
Xwinconfig(4) ................................................................................................ XWIN configuration file
Xwinfont(4) ........................ XWIN font configuration and defaults file (scalable and bitrnapped)
ypfiles(4) ..................... the Network Information Service (NIS) database and directory structure

Table of Contents

Miscellaneous Facilities
intro(5) ....................................................................................................... introduction to miscellany
ascii (5) ....................................................................................................... map of ASCII character set
environ (5) ................................................................................................................. user environment
eqnchar(5) ....................................................................... (BSD) special character definitions for eqn
eucioctl(5) ........................................... generic interface to EVC handling tty drivers and modules
fcntl(5) ..................................................................................................................... file control options
font (5) .................................................................................. font description files for troff and dpost
iconv(5) ....................................................................................................... code set conversion tables
langinfo(5) ........................................................................................ language information constants
man (5) ............................................................................. macros to format Reference Manual pages
math (5) .................................................................................................. math functions and constants
me (5) .......................................................................................... (BSD) macros for formatting papers
ms(5) ...................................................................................................... (BSD) text formatting macros
nl_types(5) ................................................................................................ native language data types
priv(5) ....................................................................... include file for user-level privilege definitions
privilege (5) ............................................................ include file for privilege mechanism definitions
prof (5) ............................................................................................................ profile within a function
. regexp: compile, step, advance (5) ....................... regular expression compile and match routines
siginfo(5) .............................................................................................. signal generation information
signal (5) ............................................................................................................................... base signals
stat (5) ............................................................................................... data returned by stat system call
stdarg(5) ................................................................................................ handle variable argument list
term (5) ........................................................................................... conventional names for terminals
types (5) .................................................................................................... primitive system data types
ucontext(5) ......................................................................................................................... user context
values (5) .................................................................................................... machine-dependent values
varargs (5) .............................................................................................. handle variable argument list
wstat(5) ................................................................................................................................. wait status

Special Files
intro(7) ...................................................................................................... introduction to special files
adsc (7) ........................................................................ Adaptec 1542A SCSI host adapter subsystem
alp(7) ......................................................................................... algorithm pool management module
ARP(7) .................................................................................................... Address Resolution Protocol
asyc(7) ........................................................................................................... asynchronous serial port
clone(7) ................................................. open any major/minor device pair on a STREAMS driver
connld (7) .................................................................... line discipline for unique stream connections
console (7) ..................................................................................... STREAMS-based console interface
cram (7) ............................................................................................................... CMOS RAM interface

Table of Contents

DCD(7) ...................................................................... Direct-Coupled Disk host adapter SubsystenL
display (7) ......................................................................................................... system console display
dpt(7) .............................................................................. DPT PM2012 SCSI host adapter subsystem
ee16(7) .............................................................................. EtherExpress 16 Ethernet Adapter Driver
e116(7) ..................................................................................... EtherLink 16 Ethernet Adapter Driver
fd(7) ..................................................................................................................... diskette (floppy disk)
file system (7) ................................................................................................... file system organization
iS96 (7) ................................................................................................................... iS96 Ethernet Driver
ibmtok(7) ........................................................................................................ IBM Token Ring Driver
ICMP (7) ........................................................................................ Internet Control Message Protocol
ie6(7) ....................................................................................................... 3CS03 3Com Ethernet Driver
if (7) ....................................................... general properties of Internet Protocol network interfaces
imxS86 (7) ...................................................................................... IMXLANS86 Intel Ethernet Driver
inet(7) ............................................................................................................. Internet protocol family
IP(7) ............................................................................................................................ Internet Protocol
kbd(7) ...................................................................................... generalized string translation module
keyboard (7) .................................................................................................. system console keyboard
kmem(7) ................................................... perform I/O on kernel memory based on symbol name
Idterm(7) ........................................................ standard STREAMS terminal line discipline module
10(7) ........................................................................................... software loopback network interface
log(7) .......................................................... interface to STREAMS error logging and event tracing
lp(7) ..................................................................................................................... parallel port interface
mcis(7) ................................................................................................ MCIS SCSI host adapter driver
mem, kmem (7) ................................................................................................................. core memory
mouse(7) .......................................... mouse device driver for bus, serial, and PS/2 mouse devices
null (7) ................................................................................................................................... the null file
pckt(7) .............................................................................................. STREAMS Packet Mode module
prf(7) ............................................................................................................ operating system profiler
ptem(7) .................................................................... STREAMS pseudo-terminal emulation module
pty(7) ............................................................................................ STREAMS pseudo-terminal driver
rtc(7) ................................................................................................................ real time clock interface
sad(7) .............................................................................................. STREAMS Administrative Driver
sc01(7) ............................................................................................................. CD-ROM Target Driver
sd01 (7) ................................................................................................................ PDI disk target driver
sockio(7) .................................................................................. ioctls that operate directly on sockets
st01 (7) .................................................................. Portable Device Interface (PDI) tape target driver
streamio (7) ................................................................................................ STREAMS ioctl commands
swOl(7) ........................................................ Portable Device Interface (PDI) WORM Target Driver
sxt(7) .................................................................................................................... pseudo-device driver
TCP(7) .................................................................................. Internet Transmission Control Protocol
termio (7) ...................................................................................................... general terminal interface
termiox(7) ................................................................................... extended general terminal interface
ticlts, ticots, ticotsord (7) ...................................................................... loopback transport providers
timod(7) .......................................................... Transport Interface cooperating STREAMS module
Table of Contents

tirdwr(7) ........................................... Transport Interface read/write interface STREAMS module
ttcompat(7) ............................................... V7, 4BSD and XENIX STREAMS compatibility module
tty (7) ...................................................................................................... controlling terminal interface
UDP(7) ............................................................................................ Internet User Datagram Protocol
vxfsio (7) .......................................................................................... vxfs file system control functions
wd(7) ................................................................................. Western Digital WD8003 Ethernet Driver
wd7000 (7) ......................................................................... WD7000 FASST2 host adapter subsystem
zero (7) .......................................................................................................................... source of zeroes

Permuted Index

Table of Contents

Introduction
Computers keep track of thousands and thousands of details. To save the labor of
continuously respecifying these details, information that is used repeatedly is
stored in files, which the operating system references when needed. For example,
when you turn the power on, the operating system reads a file that specifies which
disks to mount; when you log in, it validates your password and sets up your
environment; when you copy files from a remote system, it maps the software
names to the network addresses.
The System Files and Devices Reference describes the system and device files in
the UNIX System, including both special files and regular files. Special files pertain to a particular hardware device; regular files are hardware-independent. The
book also includes a set of miscellaneous manual pages. Not all of the files and
devices described in this manual are available on every UNIX system. Some of the
features require additional utilities that may not exist on your system.
The System Files and Devices Reference is part of a comprehensive UNIX system
reference set, which describes commands, system calls, libraries, and files. This
book includes all manual pages in sections 4, 5, and 7. References to manual pages
in other sections are found in other books in the reference set. The inner front
cover of this book lists the various section numbers and the books in which they
are found.

Manual Page Format
All manual page entries use a common format, not all of whose parts always
appear:
• The NAME section gives the name(s) of the entry and briefly states its
purpose.
• The SYNOPSIS section summarizes the use of the command, program or
function, or names the relevant special file.
• The DESCRIPTION section describes the utility.
• The EXAMPLE section gives example(s) of usage, where appropriate.
• The FILES section gives the file names that are built into the program.
• The SEE ALSO section gives pointers to related information. Reference to
manual pages with section numbers other than those in this book can be
found in other reference manuals, as listed above.

Introduction

• The DIAGNOSTICS section discusses the diagnostic indications that may be
produced. Messages that are intended to be self-explanatory are not listed.
• The NOTES section gives generally helpful hints about the use of the utility.

Request for Comment
A Request for Comment (RFC) is a document that describes some aspect of networking technology. The RFCs cited in the SEE ALSO section of these manual
pages are available in hardcopy from:
Jon Postel
RFC Editor
USC Information Sciences Institute
4676 Admiralty Way
Marina del Rey, CA 90292-6695
Online versions of the RFCs are available by FTP from nic.ddn.mil. To connect
to this host, type:
ftp -n nic.ddn.mil

Log in with the user name anonymous and the password guest. To retrieve the
RFC, type get rfc: rfcnum • txt, where num is replaced by the number of the
RFC. For example, to retrieve RFC 1171, type
get rfc:rfcl171.txt

At the end of the ftp session, type quit to exit.

Introduction

a.out(4)
NAME

a.out - ELF (Executable and Linking Format) files
SYNOPSIS

#include
DESCRIPTION

The file name a.out is the default output file name from the link editor, Id(l). The
link editor will make an a. out executable if there were no errors in linking. The
output file of the assembler, as(l), also follows the format of the a.out file
although its default file name is different.
Programs that manipulate ELF files may use the library that el£(3E) describes. An
overview of the file format follows. For more complete information, see the references given below.
Execution View
Linking View
ELF header
ELF header
Program header table
Program header table
optional
Section 1
Segment 1
...
Section n
...
.. .
Section header table

Segment 2
. ..
Section header table
optional

An ELF header resides at the beginning and holds a "road map" describing the
file's organization. Sections hold the bulk of object file information for the linking
view: instructions, data, symbol table, relocation information, and so on. Segments
hold the object file information for the program execution view. As shown, a segment may contain one or more sections.
A program header table, if present, tells the system how to create a process image.
Files used to build a process image (execute a program) must have a program
header table; relocatable files do not need one. A section header table contains
information describing the file's sections. Every section has an entry in the table;
each entry gives information such as the section name, the section size, and so on.
Files used during linking must have a section header table; other object files mayor
may not have one.
Although the figure shows the program header table immediately after the ELF
header, and the section header table following the sections, actual files may differ.
Moreover, sections and segments have no specified order. Only the ELF header has
a fixed position in the file.
When an a.out file is loaded into memory for execution, three logical segments are
set up: the text segment, the data segment (initialized data followed by uninitialized, the latter actually being initialized to all D's), and a stack. The text segment is
not writable by the program; if other processes are executing the same a.out file,
the processes will share a single text segment.

a.out (4)
The data segment starts at the next maximal page boundary past the last text
address. (If the system supports more than one page size, the "maximal page" is
the largest supported size.) When the process image is created, the part of the file
holding the end of text and the beginning of data may appear twice. The duplicated chunk of text that appears at the beginning of data is never executed; it is
duplicated so that the operating system may bring in pieces of the file in multiples
of the actual page size without having to realign the beginning of the data section to
a page boundary. Therefore, the first data address is the sum of the next maximal
page boundary past the end of text plus the remainder of the last text address
divided by the maximal page size. If the last text address is a multiple of the maximal page size, no duplication is necessary. The stack is automatically extended as
required. The data segment is extended as requested by the brk(2) system calL
SEE ALSO

as(l), brk(2), cc(l), elf(3E), Id(l)

acct(4)
NAME

acct - per-process accounting file format
SYNOPSIS

#include
#include
DESCRIPTION

Files produced as a result of calling acct(2) have records in the form defined by
sys/acct.h, whose contents are:
typedef ushort COInp_ti /* "floating point" */
/* 13-bit fraction, 3-bit exponent */
struct
acct
{

char
char
uid_t
gid_t
dev_t
time_t
COInp_t
comp_t
COInp_t
COInp_t
COInp_t
COInp_t
char

ac_flagi
ac_stati
ac_uidi
aC--9'idi
ac_ttYi
ac_btimei
ac_utimei
ac_stimei
ac_etimei
ac_memi
ac_ioi
ac_rwi
ac_camm[81i

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

Accounting flag */
Exit status */
Accounting user ID */
Accounting group ID */
control typewriter */
Beginning time */
acctng user time in clock ticks */
acctng system time in clock ticks */
acctng elapsed time in clock ticks */
memory usage in clicks */
chars trnsfrd by read/write */
number of block reads/writes */
command name * /

extern
extern

struct
struct

acct acctbufi
vnode *acctpi

#define AFORK
01
/*
#define
ASU
02
#define
ACCTF
0300
#define
AEXPND 040

/* vnode of accounting file */

has executed fork, but no exec */
/* used super-user privileges */
/* record type: 00 = acct */
/* Expanded Record Type*/

In ac_flag, the AFORK flag is turned on by each fork and turned off by an exec.
The ac_camm field is inherited from the parent process and is reset by any exec.
Each time the system charges the process with a clock tick, it also adds to ac_mem

the current process size, computed as follows:
(data size) + (text size) / (number of in-core processes using text)

The value of ac_mem/ (ac_stime+ac_utime) can be viewed as an approximation
to the mean process size, as modified by text sharing.
The structure tacct, which resides with the source files of the accounting commands, represents the total accounting format used by the various accounting commands:

acct(4)
/*

* total accounting (for acct period), also for day

struct tacct {
uid_t
char
float
float
float
float
long
unsigned short
unsigned short
unsigned short

ta_uid;
ta_name[8];
ta_cpu[2] ;
ta_kcore[2];
ta_con[2];
ta_du;
ta-pc;
ta_sc;
ta_dc;
ta_fee;

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

userid */
login name */
cum. cpu time, p/np (mins) */
cum kcore-minutes, p/np */
cum. connect time, p/np, mins */
cum. disk usage */
count of processes */
count of login sessions */
count of disk samples */
fee for special services */

} ;

SEE ALSO

acct(lM), acct(2), acctcom(l), exec(2), fork(2)
NOTES

The ac_mem value for a short-lived command gives little information about the
actual size of the command, because ac_mem may be incremented while a different
command (for example, the shell) is being executed by the process.

admin(4)
NAME

admin - installation defaults file
DESCRIPTION

admin is a generic name for an ASCII file that defines default installation actions by

assigning values to installation parameters. For example, it allows administrators
to define how to proceed when the package being installed already exists on the
system.
/var/sadm/install/admin/default is the default admin file delivered with your
system. The default file is not writable, so to assign values different from this file,
create a new admin file. There are no naming restrictions for admin files. Name the
file when installing a package with the -a option of pkgadd(lM). If the -a option is
not used, the default admin file is used.

Each entry in the admin file is a line that establishes the value of a parameter in the
following form:
param=value

Eleven parameters can be defined in an admin file. A file is not required to assign
values to all eleven parameters. If a value is not assigned, pkgadd asks the installer
how to proceed.
The eleven parameters and their possible values are shown below except as noted.
They may be specified in any order. Any of these parameters can be assigned the
value ask, which means that, if the situation occurs, the installer is notified and
asked to supply instructions at that time.
basedir
Indicates the base directory where relocatable packages are to be
installed. The value may contain $PKGINST to indicate a base directory that is to be a function of the package instance.
mail
Defines a list of users to whom mail should be sent following installation of a package. If the list is empty, no mail is sent. If the parameter
is not present in the admin file, the default value of root is used. The
ask value cannot be used with this parameter.
runlevel

Indicates resolution if the run level (system state) is not correct for the
installation or removal of a package. Options are:
nocheck
Do not check for run level (system state).
Abort installation if run level (system state) is not met.
Specifies what to do if an installation expects to overwrite a previously installed file, thus creating a conflict between packages. Options
are:

quit
conflict

nocheck

Do not check for conflict; files in conflict will be
overwritten.

quit

Abort installation if conflict is detected.

nochange

Override installation of conflicting files; they will not be
installed.

admin(4)
setuid

action

Checks for executables which will have setuid or setgid bits enabled
after installation. Options are:
nocheck
Do not check for setuid executables.
quit

Abort installation if setuid processes are detected.

nochange

Override installation of setuid processes; processes will
be installed without setuid bits enabled.

Determines if action scripts provided by package developers contain
possible security impact. Options are:
Ignore security impact of action scripts.
quit
Abort installation if action scripts may have a negative
security impact.
Checks to see if a version of the package is already partially installed
on the system. Options are:
nocheck
Do not check for a partially installed package.
quit
Abort installation if a partially installed package exists.
Determines how to handle installation if a previous version of the
package (including a partially installed instance) already exists.
Options are:
quit
Exit without installing if an instance of the package
already exists (does not overwrite existing packages).
nocheck

partial

instance

idepend

overwrite

Overwrite an existing package if only one instance
exists. If there is more than one instance, but only one
has the same architecture, it overwrites that instance.
Otherwise, the installer is prompted with existing
instances and asked which to overwrite. If an instance
of the package was already fully installed, then it does
not do a space check.

unique

Do not overwrite an existing instance of a package.
Instead, a new instance of the package is created. The
new instance will be assigned the next available instance
identifier.

Controls resolution if other packages depend on the one to be
installed. Options are:
nocheck
quit

rdepend

Do not check package dependencies.
Abort installation if package dependencies are not met.

Controls resolution if other packages depend on the one to be
removed. Options are:
nocheck
Do not check package dependencies.
quit
Abort removal if package dependencies are not met.

admin (4)
Controls resolution if disk space requirements for package are not
met. Options are:

space

nocheck

Do not check space requirements (installation fails if it
runs out of space).

quit

Abort installation if space requirements are not met.

NOTES

The value ask should not be defined in an admin file that will be used for noninteractive installation (since by definition, there is no installer interaction). Doing
so causes installation to fail when input is needed.
EXAMPLES

basedir=default
runlevel=quit
conflict=quit
setuid=quit
action=quit
partial=quit
instance=unique
idepend=quit
rdepend=quit
space=quit
SEE ALSO

pkgadd(lM)

aliases (4)

(BSD System Compatibility)

NAME

aliases, addresses, forward - (BSD) addresses and aliases for sendmail
SYNOPSIS

/usr/ucblib/aliases
/usr/ucblib/aliases.dir
/usr/ucblib/aliases.pag
- / • forward
DESCRIPTION

These files contain mail addresses or aliases, recognized by sandmail, for the local
host:
/etc/passwd
Mail addresses (usernames) of local users.
/usr/ucblib/aliases
Aliases for the local host, in ASCII format. This file can be
edited to add, update, or delete local mail aliases.
/usr/ucblib/aliases. { dir , pag}
The aliasing information from /usr/ucblib/aliases, in
binary, dl:m format for use by sandmail. The program,
newaliases, maintains these files.
- / • forward
Addresses to which a user's mail is forwarded (see
AutCllllatic Forwarding, below).
In addition, the Network Information Service (NIS) aliases map mail.aliases contains
addresses and aliases available for use across the network.
Addresses
As distributed, sandmail supports the following types of addresses:
Local Usernames
username
Each local username is listed in the local host's /etc/passwd file.
Local Filenames
pathname
Messages addressed to the absolute pathname of a file are appended to that file.
Commands
I command
If the first character of the address is a vertical bar, ( I ), sandmail pipes the message to the standard input of the command the bar precedes.
DARPA-standard Addresses
username@domain
If domain does not contain any I.' (dots), then it is interpreted as the name of a host
in the current domain. Otherwise, the message is passed to a mailhost that determines how to get to the specified domain. Domains are divided into subdomains
separated by dots, with the top-level domain on the right. Top-level domains
include:

(BSD System Compatibility)

aliases (4)

Commercial organizations.
Educational organizations.
Government organizations.
Military organizations.
For example, the full address of John Smith could be:
js@jsmachine.Podunk-u.EDU

if he uses the machine named j smachine at Podunk University.
uucp Addresses

... [host! ] host! username
These are sometimes mistakenly referred to as "Usenet" addresses. uucp provides
links to numerous sites throughout the world for the remote copying of files.
Other site-specific forms of addressing can be added by customizing the sendmail
configuration file. See the sendmail(lM) for details. Standard addresses are
recommended.
Aliases
Local Aliases
/usr/ucblib/aliases is formatted as a series of lines of the form

aliasname: address[, address]
aliasname is the name of the alias or alias group, and address is the address of a recipient in the group. Aliases can be nested. That is, an address can be the name of
another alias group. Because of the way sendmail performs mapping from uppercase to lower-case, an address that is the name of another alias group must not contain any upper-case letters.
Lines beginning with white space are treated as continuation lines for the preceding
alias. Lines beginning with # are comments.
Special Aliases
An alias of the form:
owner- aliasname : address

directs error-messages resulting from mail to aliasname to address, instead of back to
the person who sent the message.
An alias of the form:

aliasname: : include: pathname
with colons as shown, adds the recipients listed in the file pathname to the aliasname
alias. This allows a private list to be maintained separately from the aliases file.
NIS Domain Aliases
Normally, the aliases file on the master NIS server is used for themail.aliases NIS
map, which can be made available to every NIS client. Thus, the
/usr/ucblib/aliases* files on the various hosts in a network will one day be

aliases (4)

(BSO System Compatibility)

obsolete. Domain-wide aliases should ultimately be resolved into usernames on
specific hosts. For example, if the following were in the domain-wide alias file:
jsmith:js@jsmachine

then any NIS client could just mail to jsmith and not have to remember the
machine and username for John Smith. If a NIS alias does not resolve to an address
with a specific host, then the name of the NIS domain is used. There should be an
alias of the domain name for a host in this case. For example, the alias:
jsmith:root

sends mail on a NIS client to root@podunk-u if the name of the NIS domain is
podunk-u.
Automatic Forwarding

When an alias (or address) is resolved to the name of a user on the local host,
sandmail checks for a . forward file, owned by the intended recipient, in that
user's home directory, and with universal read access. This file can contain one or
more addresses or aliases as described above, each of which is sent a copy of the
user's mail.
Care must be taken to avoid creating addressing loops in the . forward file. When
forwarding mail between machines, be sure that the destination machine does not
return the mail to the sender through the operation of any NIS aliases. Otherwise,
copies of the message may "bounce." Usually, the solution is to change the NIS
alias to direct mail to the proper destination.
A backslash before a username inhibits further aliasing. For instance, to invoke the
vacation program, user j s creates a . forward file that contains the line:
\js, "I/usr/ucb/vacation js"

so that one copy of the message is sent to the user, and another is piped into the
vacation program.
FILES

/etc/passwd
/usr/ucblib/aliases
-/.forward
SEE ALSO

dbn(3), newaliases(lM), sandmail(lM), uucp(lC), vacation(l)
NOTES

Because of restrictions in dbm a single alias cannot contain more than about 1000
characters. Nested aliases can be used to circumvent this limit.

ar(4)
NAME

ar - archive file format
SYNOPSIS

#include
DESCRIPTION

The archive command ar [see ar(l)] is used to combine several files into one.
Archives are used mainly as libraries to be searched by the link editor ld [see ld(l)].
Each archive begins with a unique string identifier called an archive magic string.
#define
#define

1IRMAG

SARMAG

!\n"

/* magic string */
/* length of magic string */

Following the archive magic string are the archive file members. Each file member
is preceded by a file member header which is of the following format:
#define
struct

ARFMAG

"'\n ll

ar_hdr

/* header trailer string */
/* file member header */

{

char
char
char
char
char
char
char

ar_name [16] ;
ar_date[12];
ar_uid[6];
ar_gid[6];
ar_mode[8] ;
ar_size[10];
ar_fmag[2] ;

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

'/' terminated file member name */
file member date */
file member user identification */
file member group identification */
file member mode (octal) */
file member size */
header trailer string */

};

All information in the file member headers is in printable ASCII. The numeric information contained in the headers is stored as decimal numbers (except for ar_mode
which is in octal). Thus, if the archive contains printable files, the archive itself is
printable.
If the file member name fits, the ar_name field contains the name directly, and is terminated by a slash (I) and padded with blanks on the right. If the member's name
does not fit, ar_name contains a slash (I) followed by a decimal representation of the
name's offset in the archive string table described below.
The ar date field is the modification date of the file at the time of its insertion into
the arChive. Common format archives can be moved from system to system as long
as the portable archive command ar is used.
Each archive file member begins on an even byte boundary; a newline is inserted
between files if necessary. Nevertheless, the size given reflects the actual size of the
file exclusive of padding.
Notice there is no provision for empty areas in an archive file.

ar (4)
Each archive that contains object files [see a.out(4)] includes an archive symbol
table. This symbol table is used by the link editor Id to determine which archive
members must be loaded during the link edit process. The archive symbol table (if
it exists) is always the first file in the archive (but is never listed) and is automatically created and/ or updated by ar.
The archive symbol table has a zero length name (that is, ar_name [01 is '/,),
ar_name [1] ==' ',and so on). All "words" in this symbol table have four bytes,
using the machine-independent encoding shown below. (All machines use the
encoding described here for the symbol table, even if the machine's "natural" byte
order is different.)
Ox01020304

The contents of the symbol table are as follows:
1.

The number of symbols. Length: 4 bytes.

The array of offsets, one per symbol, into the archive file. Length: 4 bytes
"the number of symbols".

The name string table. Length: ar_size - 4 bytes
+ 1).

* ("the number of symbols"

As an example, the following symbol table defines 4 symbols. The archive member
at file offset 114 defines name and object. The archive member at file offset 426
defines function and a second version of name.
Offset

o
4
8

12
16
20
24
28
32
36
40

+3
4 offset entries
name
object
function
name

4
114
114
426
426

e
f
t
\0

c
u
i
n

b
t
n

e
j
\0

c
n

The number of symbols and the array of offsets are managed with sgetl and
sputl. The string table contains exactly as many null terminated strings as there
are elements in the offsets array. Each offset from the array is associated with the
corresponding name from the string table (in order). The names in the string table
are all the defined global symbols found in the common object files in the archive.
Each offset is the location of the archive header for the associated symbol.

ar(4)
If some archive member's name is more than 15 bytes long, a special archive
member contains a table of file names, each followed by a slash and a new-line.
This string table member, if present, will precede all "normal" archive members.
The special archive symbol table is not a "normal" member, and must be first if it
exists. The ar_name entry of the string table's member header holds a zero length
name ar_name[O]=='I', followed by one trailing slash (ar_name[l] =='1'), followed by blanks (ar_name [2] ==' " and so on). Offsets into the string table begin
at zero. Example ar_name values for short and long file names appear below.

Offset

o
10
20
30

+0
f
s
n
m

+1
i
a
g
e

+2
1
m

e
x

+3
e
p
r
a

Member Name
short-name
file_name_sample
longerfilenamexample

+4
-

f
m

ar name

short-namel

10
118

+5
n
e
i
p

+6
a

I
1
1

\n
e
e

+8
e

+9
-

a
\n

Note
Not in string table
Offset 0 in string table
Offset 18 in string table

SEE ALSO

a.out(4), ar(I), Id(I), sputl(3X), strip(l)
NOTES

strip will remove all archive symbol entries from the header. The archive symbol
entries must be restored via the -ts options of the ar command before the archive
can be used with the link editor Id.

archives (4)
NAME

archives - device header file
DESCRIPTION

1* Magic numbers *1
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define

CMtCASC
CMtCBIN
CMtCBBS
CMtCCRC
CMS_ASC
CMS_CHR
CMS_CRC
CMICSEC
CMS_SEC
CMS_LEN

Ox070701
070707
0143561
Ox070702
"070701"
"070707"
"070702"
Ox070703
"070703"
6

1*
1*
1*
1*
1*
1*
1*
1*
1*
1*

epio Magic Number for AScii header *1
epio Magic Number for Binary header *1
epio Magic Number for Byte-swap header *1
epio Magic Number for CRe header * I
epio Magic String for AScii header * I
epio Magic String for CHR (-c) header *1
epio Magic String for CRC header *1
Tcpio Magic Number of TIlE header *1
Tcpio Magic String of TIlE header *1
epio Magic String LENgth *1

1* Various header and field lengths *1
#define CHRSZ
#define ASCSZ
#define TARSZ
#define
#define
#define
#define

HNAMLEN
EXPNLEN

HTIMLEN
HSIZLEN

1*
1*
1*
256 1*
1024 1*
2
1*
2
1*

76
110
512

-c hdr size minus filename field *1
ASC and CRC hdr size minus filename field *1
TAR hdr size *1
maximum filename length for binary and -c headers *1
maximum filename length for ABC and CRC headers *1
length of modification time field *1
length of file size field *1

1* cpio binary header definition *1
struct hdr_epio {
short
h_magic,
h_dev;
ushort_t h_ino,
h_mode,
h_uid,
h-9'id;
h_nlink,
short
h_rdev,
h_mtime [HTIMLEN] ,
h_namesize,
h_filesize[HSIZLEN];
h_name[HNAMLEN];
char
} ;

1* epio one header format *1
struct c_hdr {
char
c_magic[CMS_LEN],
c_dev[6] ,
c_ino[6] ,
c_mode[6] ,
c_uid[6] ,
c-9'id[6] ,
c_n1ink[6] ,
c_rdev[6] ,
c_mtime[l1] ,
c_namesz [6],
c_filesz [11],

1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*

magic number field *1
file system of file *1
inode of file *1
modes of file *1
uid of file *1
gid of file *1
number of links to file *1
maj/min numbers for special files *1
modification time of file *1
length of filename *1
size of file *1
filename *1

archives (4)

}

;

1* -c and CRC header format *1
struct Exp_cpio_hdr {
char
E_magic[CMS_LEN],
E_ino[8] ,
E_mode[8] ,
E_uid[8] ,
E.-9id[8] ,
E_nlink [8],
E_mtime[8] ,
E_filesize[8] ,
E_maj[8],
E_min[8] ,
E_rmaj [8],
E_rmin[8] ,
E_namesize[8] ,
E_chksum[8] ,
E_name [EXPNLEN] ;
} ;

1* Tar header structure and format *1
#define TBLOCK
512
1* length of tar header and data blocks *1
#define
100/* maximum length for tar file names *1
TNAMLEN
8
#define TMODLEN
1* length of mode field *1
#define TUIDLEN
8
1* length of uid field *1
#define TGIDLEN
1* length of gid field *1
8
#define TSIZLEN
12
1* length of size field *1
#define TTIMLEN
12
1* length of modification time field *1
#define TCRCLEN
1* length of header checksum field *1
8
1* tar header definition *1
union tblock {
char dummy[TBLOCK];
struct tar_hdr {
char
t_name [TNAMLEN] ,
1*
t_mode [TMODLEN] ,
1*
t_uid [TUIDLEN] ,
1*
t_gid [TGIDLEN] ,
1*
t_size [TSIZLEN] ,
1*
t_mtime [TTIMLEN] ,
1*
t_cksum[TCRCLEN],
1*
t_typeflag,
t_linkname[TNAMLEN] ,1*
t_magic[TMAGLEN],
t_version[TVERSLEN],
t_uname [32],

name of file *1
mode of file *1
uid of file *1
gid of file *1
size of file in bytes *1
modification time of file *1
checksum of header *1
file this file linked with *1

t~[32],

t_devmajor[8] ,
t_devminor[8] ,
tJlrefix[155] ;
} tOOf;

archives (4)
1* volcopy tape label format and structure */
#define VMAGLEN 8
#define VVOLLEN 6
#define VFILLEN 464
struct vol copy_label
char
v_magic [VMAGLEN],
v_volume [VVOLLEN],
v_reels,
v_reel;
v_time,
long
v_length,
v_dens,
v_reelblks,
v_blksize,
v_nblocks;
char
v_fill [VFILLEN];
long
v_offset;
v_type;
int

1* u370 added field *1
1* u370 added field *1
1* u370 added field *1
1* used with -e and -reel options *1
1* does tape have nblocks field? *1

binarsys (4)
NAME

binarsys - remote system information for the ckbinarsys command
DESCRIPTION

binarsys contains lines of the form:

remote_system_name: val
where val is either Y or N. This line indicates whether that particular remote system
can properly deal with messages having binary content. The absence of an entry for
a particular system or absence of the binarsys file altogether will imply No.
Blank lines or lines beginning with # are considered comments and ignored.
Should a line of Default=y be encountered, the default condition for missing
entries described in the previous paragraph is reversed to be Yes. Another line of
Default=n will restore the default condition to No.
mail is distributed with the binarsys file containing only a Default=y line.
FILES

/etc/mail/binarsys
SEE ALSO

ckbinarsys(lM), mailsurr(4), mail(l)

boot (4)
NAME

boot - boot options
DESCRIPTION

Options for the boot program can be set or changed with keywords in
/ stand/boot. The following are recognized by boot.
BOOTMSG=string
Change the default boot message to string.

MEMRANGE=range:flag[,range:flag ... J
Tell boot where to look when sizing memory. A range is a pair of decimal
addresses, separated by a dash such as lM-4M. The flag indicates how the
range should be interpreted. The following flags are recognized:
256 - B MEM BASE (OxlOO)
512 - B=MEM=EXPAN (Ox200)
8704 - B_MEM]ORCE (Ox2000) + B_MEM_EXPAN
If / stand/boot does NOT exist, the boot program uses the CMOS values as
the maximum when probing for RAM (default case).
If / stand/boot does exist, use the MEMRANGE entry to override the
CMOS values. Examples:
Probe for the minimum of 4M or the CMOS values:
MEMRANGE=0-640K:256,lM-4M:512
Probe for 64MB and ignore the CMOS values as the maximum:
MEMRANGE=0-640K:256,lM-16M:512,16M-64M:8704

Note: if B_MEM_FORCE is set it will ignore the CMOS setting for that
range. The CMOS setting can only be ignored for memory above 16MB and
only if the initial address of the range is above 16MB.
In addresses, use "M" to indicate megabytes and "K" to indicate kilobytes.
The first address in the pair is inclusive; the last address is exclusive. When
sizing the base memory (0-640K usually) the boot code checks the CMOS
for the current base memory setting. If this value is less than the current
base memory value, the kernel uses this lower value instead of 640K.
variable=value
All other lines of the form variable=value are passed as arguments to the kernel as is, via argv[].
FILES

/stand/boot
/etc/initprog/boot
SEE ALSO

boot(l)

bootparams ( 4 )
NAME

bootparams - boot parameter data base
SYNOPSIS

bootparams
DESCRIPTION

bootparams contains a list of client entries that diskless clients use for booting.

Each entry contains the following information for each diskless client:
name
server names and pathnames
The first field contains the name of the diskless client. The subsequent field is a list
of keys, names of servers, and pathnames.
Fields are delineated with TABs.
A client entry in the local bootparams file supersedes an entry in the corresponding
Network Information Service (NIS) map.
EXAMPLE

This is an example of the bootparams file.
clientl root=grpserver:/nfsroot/ clientl \
swap=grpserver: / nfsswap / clientl \
dump=grpserver: / nfsdump / clientl
SEE ALSO

bootparamd(lM)

compver(4)
NAME

cOlli>ver - compatible versions file
DESCRIPTION

COlli>ver is an ASCII file used to specify previous versions of the associated package
which are upward compatible. It is created by a package developer.
Each line of the file specifies a previous version of the associated package with
which the current version is backward compatible.

Since some packages may require installation of a specific version of another
software package, compatibility information is extremely crucial. Consider, for
example, a package called "A" which requires version "1.0" of application "B" as a
prerequisite for installation. If the customer installing" A" has a newer version of
"B" (1.3), the compver file for "B" must indicate that "1.3" is compatible with
version "1.0" in order for the customer to install package" A."
NOTES

The comparison of the version string disregards white space and tabs. It is performed on a word-by-word basis. Thus 1.3 Enhanced and 1.3 Enhanced would
be considered the same.
EXAMPLE

A sample compver file is shown below.
1.3
1.0
SEE ALSO

depend(4)

copyright is an ASCII file used to provide a copyright notice for a package. The
text may be in any format. The full file contents (including comment lines) is

displayed on the terminal at the time of package installation.

core (4)
NAME

core - core image file
DESCRIPTION

The UNIX system writes out a core image of a process when it is terminated due to
the receipt of some signals. The core image is called core and is written in the
process's current directory (provided it can be; normal access controls apply). A
process with an effective user ID different from the real user ID will not produce a
core image.
The core file contains all the process information pertinent to debugging: contents
of hardware registers, process status and process data. The format of a core file is
object file specific.
For ELF executable programs [see a.out(4)], the core file generated is also an ELF
file, containing ELF program and file headers. The e_type field in the file header
has type ET_CORE. The program header contains an entry for every loadable and
writable segment that was part of the process address space, including shared
library segments. The contents of the segments themselves are also part of the core
image.
The program header of an ELF core file also contains a NOTE segment. This segment
may contain the following entries. Each has entry name "CORE" and presents the
contents of a system structure:
prstatus_t
The entry containing this structure has a NOTE type of 1. This structure contains things of interest to a debugger from the operating system's u-area,
such as the general registers, signal dispositions, state, reason for stopping,
process ID and so forth. The structure is defined in sys/procfs .h.
fpregset_t
This entry is present only if the process used the floating-point hardware. It
has a NOTE type of 2 and contains the floating-point registers. The
fpregset_t structure is defined in sys/regset.h.
prpsinfo_t
The entry containing this structure has a NOTE type of 3. It contains information of interest to the ps(l) command, such as process status, cpu usage,
"nice" value, controlling terminal, user ID, process ID, the name of the executable and so forth. The structure is defined in sys/procfs.h.
COFF executable programs produce core files consisting of two parts: the first section is a copy of the system's per-user data for the process, including the general
registers. The format of this section is defined in the header files sys/user.h and
sys/reg .h. The remainder of a COFF core image represents the actual contents of
the process data space.
The size of the core file created by a process may be controlled by the user [see
getrlimit(2)].
SEE ALSO

a.out(4), crash(lM), elf(3E), getrlimit(2), sdb(l), setuid(2), signal(5)

eron (4)
NAME

cron, queuedefs - option files for crontab and at
DESCRIPTION

Options for cron(lM) can be set or changed with keywords
/etc/default/cron. The following keywords are recognized by cron:
CRONLOG=YES

or NO

If CRONLOG is set to YES, all cron jobs are logged in
/usr/lib/cron/log. The default is NO.

Options for crontab(l) and at(l) can be set or changed with keywords in
/etc/cron.d/queuedefs. The format of the file is as follows:
a.4jln
b.2j2n90w
The first line specifies how at(l) jobs are to be handled:
Start a maximum of 4 concurrent jobs per user.
Use a nice(l) value of l.
Do not retry jobs that cannot start because fork(2) fails.
The second line specifies how crontab(l) jobs are to be handled:
Start a maximum of 2 concurrent jobs per user.
Use a nice(l) value of 2.
Wait 90 seconds, then try again to start jobs that cannot start because
fork(2) fails.
FILES

/etc/default/cron
/etc/cron.d/queuedefs

Control logging of cron jobs.
Specify concurrency, priority, and retry interval.

SEE ALSO

at(l), cron(lM), crontab(l)

depend (4)
NAME

depend - software dependencies files
DESCRIPTION

an AScn me used to specify information concerning software dependencies for a particular package. The file is created by a software developer.
Each entry in the depend file describes a single software package. The instance of
the package is described after the entry line by giving the package architecture
and/ or version. The format of each entry and subsequent instance definition is:
type pkg name
(arch)version
(arch)version

depend is

The fields are:
type
Defines the dependency type. Must be one of the following characters:
P
Indicates a prerequisite for installation, for example, the referenced package or versions must be installed.
I
Implies that the existence of the indicated package or version
is incompatible.
R
Indicates a reverse dependency. Instead of defining the
package's own dependencies, this designates that another
package depends on this one. This type should be used only
when an old package does not have a depend me but it relies
on the newer package nonetheless. Therefore, the present
package should not be removed if the designated old package
is still on the system since, if it is removed, the old package
will no longer work.
pkg
Indicates the package abbreviation.
name
Specifies the full package name.
(arch)version
Specifies a particular instance of the software. A version name cannot begin with a left parenthesis. The instance specifications, both
arch and version, are completely optional but each must begin on a
new line that begins with white space. If no version set is specified,
any version of the indicated package will match. A version preceded by a tilde (-) indicates that any compatible version will be a
match. [See compver(4).]
EXAMPLE

Here is a sample depend file (for the NFS package):
P base
Base System
P nsu
Networking Support utilities
P inet
Internet utilities
P rpc
Remote Procedure call utilities
P dfs
Distributed File System'Utilities

depend(4)
SEE ALSO

cc:xrg;wer(4)

dfstab(4)
NAME

dfstal> - file containing commands for sharing resources
DESCRIPTION
dfstal> resides in directory /ete/dfs and contains commands for sharing
resources across a network. dfstal> gives a network administrator a uniform

method of controlling the automatic sharing of local resources.
Each line of the dfstal> file consists of a share(lM) command. The dfstal> file can
be read by the shell directly to share all resources, or network administrators can
prepare their own shell scripts to execute particular lines from dfstal>.
The contents of dfstal> are executed automatically when the system enters run
level 3.
SEE ALSO
share(lM), shareal1(lM)

dirent(4)
NAME

dirent - file system independent directory entry
SYNOPSIS

#include
#include
DESCRIPTION

Different file system types may have different directory entries. The dirent structure defines a file system independent directory entry, which contains information
common to directory entries in different file system types. A set of these structures
is returned by the getdents(2) system call.
The dirent structure is defined below.
struct

dirent {
ino_t
off_t

unsigned short
char

d_ino;
d_off;
d_reclen;
d_name[l] ;

};

The d_ino is a number which is unique for each file in the file system. The field
d_off is the offset of the subsequent directory entry in the actual file system directory. The field d_name is the beginning of the character array giving the name of
the directory entry. This name is null terminated and may have at most MAXNAMLEN
characters. This results in file system independent directory entries being variable
length entities. The value of d_reclen is the record length of this entry. This
length is defined to be the number of bytes between the current entry and the next
one, so that the next structure will be suitably aligned.
SEE ALSO

getdents(2)

dir(4)

(CD-ROM)

NAME

dir (cdfs) - format of CD-ROM file system (cdfs) directory data structure
SYNOPSIS

#include
#include
DESCRIPTION

In a cdfs file system, the contents of a file or directory are stored in contiguous

physical sectors called an extent. The contents of a directory are stored in a single
extent. The contents of a file may be stored in multiple non-adjacent extents. More
than one file can share the same extent. The first sector of each extent may contain
an Extended Attribute Record (XAR) that describes additional attributes of the file
or directory (such as the User ID, Group ID, permissions).
Each directory in a cdfs filesystem contains two or more Directory Records. These
directory records identify the file and subdirectories owned by the directory. For
each file or subdirectory in the directory, there will exist one Directory Record for
each extent belonging to that file/subdirectory. Each Directory Record is of variable length and contains information such as:
the name of the file or subdirectory
the location and size of its extent
a System Use Area
Note: For a multi-extent file, there will be one directory record for each extent in the
file.
Each Directory Record has a System Use Area (SUA) that stores information about
other operating system standards, such as additional file-related information not
defined by the ISO-9660 specification. The SUA can be used to store information
required to support POSIX standards. For example, the SUA can contain the device
file major/minor numbers, which are defined by the POSIX standard. The System
Use Sharing Protocol (SUSP) defines how the information in the SUA is defined.
The Directory Record data structure is defined in the iso9660.h header file. For
each cdfs file and directory currently being referenced, an in-core data structure,
struct cdfs_drec, is used to store the relevant portions of all of the Directory
Records belonging to that file or directory. Each cdfs_drec also stores other information relating to the extent and/or Directory Record. The cdfs_drec structure is
defined in the cdfs_inode. h header file.
The cdfs_drec structure is as follows:

(CD-ROM)
struct cdfs_drec {
struct cdfs_drec
struct cdfs_drec
uint_t
uint_t
uint_t
uint_t
daddr_t
uint_t
timestruc_t
uint_t
uint_t
uint_t
uint_t
uint_t
uint_t
uint_t
uint_t
};

*drec_NextDR;
*drec_PrevDR;
drec_Loc;
drec_Offset;
drec_Len;
drec_XarLen;
drec_ExtLoc;
drec_DataLen;
drec_Date;
drec_Flags;
drec_UnitSz;
drec_Interleave;
drec_VolSeqNum;
drec_FileIDLen;
drec_FileIOOff;
drec_SysUseOff;
drec_SysUseSz;

dir(4)

/* Pointer to next Dir Rec */
/* Pointer to previous Dir Rec */
/* Loc of media DREC (L-Sec #) */
/* # bytes from L-sec start */
/* Len of media Dir Rec (Bytes) */
/* Len of media XAR (Log Blk) */
/* Location of Extent (L-Blk #) */
/* Len of File Sec data */
/* Recording date and time */
/* Flags - See below */
/* File Unit Size */
/* Interleave Gap Size */
/* Volume Sequence Number */
/* Len of File ID String */
/* Dir Rec offset of File ID */
/* Dir Rec offset of Sys Use Area */
/* Size of Sys Use Area */

REFERENCES
cdfs-specific fs(4), cdfs-specific inode(4)
System Use Sharing Protocol, and Rock Ridge Interchange Protocol from Rock Ridge
Technical Working Group, ISO 9660 Specification, ISO 9660:1988(E), Working Paper
for Information Processing: Volume and File Structure of CD-ROM Information Interchange in Optical Information Systems magazine, January /February 1987

dir (4)

(S5)

NAME

dir (s5) - format of s5 directories
SYNOPSIS

#include
#include
DESCRIPTION

A directory behaves exactly like an ordinary file, save that no user may write into a
directory. The fact that a file is a directory is indicated by a bit in the mode word of
its i-node entry [see the s5-specific inode(4)]. The structure of a directory entry as
given in the include file is:
#ifndef DIRSIZ
#define DIRSIZ
#endif
struct direct

{

d_ino;
/* s5 inode type */
d_name [DIRSIZ] ;
};

By convention, the first two entries in each directory are . for the entry itself and •.
for the parent directory. The meaning of •• is modified for the root directory of the
master file system; there is no parent, so • • has the same meaning as • has.
SEE ALSO

s5_specific inode(4)

(UFS)

dir(4}

NAME

dir (ufs) - format ofufs directories
SYNOPSIS

#include
#include
#include
DESCRIPTION

A directory consists of some number of blocks of DIRBLKSIZ bytes, where DIRBLKSIZ is chosen such that it can be transferred to disk in a single atomic operation (for
example, 512 bytes on most machines).
Each DIRBLKSlz-byte block contains some number of directory entry structures,
which are of 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 of 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 of a name in a directory is MAXNAMLEN.
DEV_BBIZE
#define DIRBLKSIZ
#define MAXNAMLEN
256
direct
struct
u_long
d_ino;
u_short
d_reclen;
u_short
d_namlen;
char
d_name [MAXNAMLEN + 11 ;

/* inode number of entry */
/* length of this record */
/* length of string in d_name */
/* name IIBlst be no longer than this * /

};

SEE ALSO

ufs-specific fs(4)

disk.efg (4)
NAME

disk. cfg - configuration defaults for mass-storage and SCSI devices
DESCRIPTION

Default values used by the pdiadd and pdinn commands can be set or changed
with keywords in /etc/conf/pack.d/* /disk.cfg, where the * represents the
name of any PDI-capable devices supported by your release of the UNIX System.
Environment Variables

The following variables are recognized in disk.cfg:
NAMES Specifies the short name of this device, and is used in the UNIX System

configuration as the directory name for the device, as represented by the
above. For example,

NAMES=adsc

means that the device driver will be known by the string adsc. The NAMES
variable is required in /etc/conf/pack.d/* /disk.cfg.
NAMEL Specifies the long name of this device in the UNIX System configuration.

For example,
NAMEL="Adaptec Host Adapter"

SHAR

means that the device driver is an Adaptec Host Adapter. Notice that the
long name must be enclosed in double quotes, because it contains space
characters. This name is used for informational messages. The NAMEL variable is required in /etc/conf/pack.d/* /disk.cfg.
Specifies the value for the ishare flag for this device, and this flag is used in
the UNIX System configuration for the device. For example,
SHAR=l

means that the device driver cannot share interrupts with other devices in
your UNIX System.
lVEC

Specifies the value for the interrupt vector used by this device, and is used
in the UNIX System configuration for the device. For example,
lVEC=l

means that the device driver can only be configured at interrupt 1. Another
way that a value for IVEC may be specified is
lVEC="14 15 11"

which means that the device driver can be configured at either interrupt 14,
15, or 11. This line also indicates that interrupt 14 is the default value,
because it is the first value listed. The lVEC variable is required in
/etc/conf/pack.d/* /disk.cfg. If the device does not use interrupts, the
value 0 should be specified.
DMA1

Specifies the value for the DMA channel used by this device, and is used in
the UNIX System configuration for the device. For example,
DMA1=1

disk.efg (4)
means that the device driver can only be configured at DMA channel l.
Another way that a value for DMAl may be specified is
DMAl="5 6 7"

which means that the device driver can be configured at either DMA channelS, 6, or 7. This line also indicates that DMA channelS is the default
value, because it is the first value listed. The DMAl variable is required in
/etc/conf/pack.d/*/disk.cfg. If the device does not use a DMA channel, the value 0 should be specified.
IOADDR

Specifies the value for the I/O addresses used by this device, and is used in
the UNIX System configuration for the device. For example,
IOADDR="170-l7S"

means that the device driver can only be configured at I/O address Ox170,
and needs all addresses up to and including Ox17S. Another way that a
value for IOADDR may be specified is
IOADDR="170-l7S lFO-1FS"

which means that the device driver can be configured at starting I/O
address Ox170 or OxlFO. The value specified after the dash always indicates
the end of the address range required by this device. This line also indicates
that Ox170 is the default value for starting I/O address for this device,
because it is the first value listed. The IOADDR variable is required in
/etc/conf/pack.d/*/disk.cfg if the device uses an address range for
I/O registers. Do not use prefix Ox when specifying values for IOADDR.
MEMADDR

Specifies the value for the memory addresses used by this device, and is
used in the UNIX System configuration for the device. For example,
MEMADDR="CSOOO-C9FFF"

means that the device driver can only be configured at memory address
OXCSOOO and needs all addresses up to and including OXC9FFF. Another
way that a value for MEMADDR may be specified is
MEMADDR="CSOOO-C9FFF D6000-D7FFF"

which means that the device driver can be configured at starting memory
address OXCSOOO or Oxn6000. The value specified after the dash always
indicates the end of the address range required by this device. This line also
indicates that OXCSOOO is the default value for starting memory address for
this device, because it is the first value listed. The MEMADDR variable is
required in /etc/conf/pack.d/*/disk.cfg. If the device does not use an
address range for a boot ROM or other purposes, a value of 0-0" should be
specified. This value is a valid value in a list of acceptable values if the use
of a memory address is optional for this device. The prefix Ox must not be
used in the specification of values for MEMADDR.

disk.cfg ( 4 )
DEVICE

Specifies the controller type for this device, and is used to control the UNIX
System configuration for the device. For example,
DEVICE=DCD

means that the device is a Directly Coupled Device, while
DEVICE=SCSI

means that the device is a SCSI device. The DEVICE variable is required in
/etc/conf/pack.d/*/disk.cfg. The only allowable values for DEVICE
are DCD and SCSI.
DEVTYPE

Specifies the type of this device, and is used to control the UNIX System
configuration for the device. For example,
DEVTYPE=DISK

means that the device is a disk device, while
DEVTYPE=TAPE

means that the device is a tape device. The DEVTYPE variable is required in
/etc/conf/pack.d/*/disk.cfg if the value of DEVICE is DCD. The only
allowable values for DEVTYPE are DISK or TAPE.
DCD_IPL

Must contain the same value as the default value for the IPL variable. This
variable is used during the configuration process to record the current value
of the IPL variable for this device. For example,
DCD_IPL=5

means that this OCD device is configured at IPL 5 in the current UNIX
System
kernel.
The
DCD_IPL
variable
is
required
in
/etc/conf/pack.d/*/disk.cfg if the value of DEVICE is DCD.
DCD_SHAR

Must contain the same value as the default value for the SHAR variable. This
variable is used during the configuration process to record the current value
of the SHAR variable for this device. For example,
DCD_SHAR=3

means that this OCD device is configured at SHAR 3 in the current UNIX
System
kernel.
The
DCD_SHAR
variable
is
required
in
/etc/conf/pack.d/*/disk.cfg if the value of DEVICE is DCD.
DCD_IVEC

Must contain the same value as the default value for the IVEC variable. This
variable is used during the configuration process to record the current value
of the IVEC variable for this device. For example,
DCD_IVEC=14

means that this DCD device is configured at IVEC 14 in the current UNIX
System
kernel.
The
DCD_IVEC
variable
is
required
in
/etc/conf/pack.d/* /disk.cfg if the value of DEVICE is DCD.

disk.cfg (4)
Files
/etc/canf/pack.d/*/disk.cfg
SEE ALSO

pdiadd(lM), pdirm(lM)

dump(4)
NAME

dump - boot dump timeout file
DESCRIPTION

The fete/default/dump file contains keywords recognized by the timeout code.
When the system boots, if there is a system dump in the swap device, the system
asks if you want to save the dump. After n seconds, the system assumes that you
do not. The keyword TIME specifies the number of seconds that the system should
wait before timing out.
TIME=n

If n is zero, the save the dump question is never asked. If the line is
missing, the system waits forever. Otherwise, the system waits n
seconds.

Files
fete/default/dump

environ (4)
NAME

.environ, .pref, . variables - user-preference variable files for FACE
DESCRIPTION

The . environ, •pref, and . variables files contain variables that indicate user
preferences for a variety of operations. The • environ and •variables files are
located under the user's $HaME/pref directory. The .pref files are found under
$HOME/FlLECABlNET, $HaME/WASTEBASKET, and any directory where preferences
were set via the organize command. Names and descriptions for each variable are
presented below. Variables are listed one per line and are of the form
variable=value.

Variables found in • environ include:
LOGINWIN[1-4] Windows that are opened when FACE is initialized
SORTMODE
Sort mode for file folder listings. Values include the following
hexadecimal digits:
1
2
800

sorted alphabetically by name
files most recently modified first
sorted alphabetically by object type

The values above may be listed in reverse order by "ORing" the
following value:
1000 list objects in reverse order. For example, a value of 1002
will produce a folder listing with files least recently
modified displayed first. A value of 1001 would produce
a "reverse" alphabetical by name listing of the folder
DISPLAYMODE

Display mode for file folders. Values include the following hexadecimal digits:
o
file names only
4
file names and brief description
8
file names, description, plus additional information

WASTE PROMPT
WASTEDAYS
PRINCMD[1-3 ]

Prompt before emptying wastebasket (yes/no)?
Number of days before emptying wastebasket
Print command defined to print files.

UMASK
Holds default permissions that files will be created with.
Variables found in .pref are the following:
SORTMODE
which has the same values as the SORTMODE variable described in
• environ above.
DISPMODE
which has the same values as the DISPLAYMODE variable
described in • environ above.
Variables found in . variables include:

environ (4)
EDITOR
PSl

Default editor
UNIX shell prompt

FILES

$HOME/pref/.environ
$HOME/pref/.variables
$HOME/FILECABINET/.pref
$HOME/WASTEBASKET/.pref

ethers (4)
NAME

ethers - Ethernet address to hostname database or domain
DESCRIPTION

The ethers file contains information regarding the known (48 bit) Ethernet
addresses of hosts on the Internet. For each host on an Ethernet, a single line
should be present with the following information:

Ethernet-address

official-hast-name

Items are separated by any number of SPACE and/ or TAB characters. A 'I' indicates
the beginning of a comment extending to the end of line.
The standard form for Ethernet addresses is x:x:x:x:x:x where x is a hexadecimal
number between 0 and ff, representing one byte. The address bytes are always in
network order. Host names may contain any printable character other than a
SPACE, TAB, NEWLINE, or comment character. It is intended that host names in the
ethers file correspond to the host names in the hosts(4) file.
The ether_line routine from the Ethernet address manipulation library,
ethers(3N) may be used to scan lines of the ethers file.
FILES

fete/ethers
SEE ALSO

ethers(3N), hosts(4)

fd(4)
NAME

fd - file descriptor files
SYNOPSIS

/dev/fd/*
DESCRIPTION

These files, conventionally called /dev/fd/O, /dev/fd/l, /dev/fd/2, and so on,
refer to files accessible through file descriptors. If file descriptor n is open, these
two system calls have the same effect:
fd = openC"/dev/fd/n",mode);
fd = dupCn);

On these files creat(2) is equivalent to open, and mode is ignored. As with dup,
subsequent reads or writes on fd fail unless the original file descriptor allows the
operations.
For convenience in referring to standard input, standard output, and standard
error, an additional set of names is provided: /dev/stdin is a synonym for
/dev/fd/O, /dev/stdout for /dev/fd/l, and /dev/stderr for /dev/fd/2.
Errors
open(2) returns -1 and EBADF if the associated file descriptor is not open.
REFERENCES

dup(2), open(2)

filehdr(4)
NAME

filehdr - file header for common object file (COFF)
SYNOPSIS

#include
DESCRIPTION

The common object file format (COFF) is not generated by the most recent compilers provided with UNIX System V. See filehdr.h for information about COFF
header files.
See a. out (4) for information about headers generated by recent compiliers.
SEE ALSO

a.out(4)

fspec(4)
NAME

fspee - format specification in text files
DESCRIPTION

It is sometimes convenient to maintain text files with non-standard tabs (that is,
tabs that are not set at every eighth column). Such files must generally be converted
to a standard format, frequently by replacing all tabs with the appropriate number
of spaces, before they can be processed by commands. A format specification
occurring in the first line of a text file specifies how tabs are to be expanded in the
remainder of the file.
A format specification consists of a sequence of parameters separated by blanks and
surrounded by the brackets <: and : >. Each parameter consists of a keyletter, possibly followed immediately by a value. The following parameters are recognized:
ttabs
The t parameter specifies the tab settings for the file. The value of tabs
must be one of the following:
1. a list of column numbers separated by commas, indicating tabs set at
the specified columns
2. a - followed immediately by an integer n, indicating tabs at intervals
ofn columns
3. a - followed by the name of a "canned" tab specification
Standard tabs are specified by t-8, or equivalently, t1, 9,17,25, and so
on. The canned tabs that are recognized are defined by the tabs(l) command.
ssize
The s parameter specifies a maximum line size. The value of size must be
an integer. Size checking is performed after tabs have been expanded,
but before the margin is prepended.
mmargin The m parameter specifies a number of spaces to be prepended to each
line. The value of margin must be an integer.
d
The d parameter takes no value. Its presence indicates that the line containing the format specification is to be deleted from the converted file.
e
The e parameter takes no value. Its presence indicates that the current
format is to prevail only until another format specification is encountered
in the file.
Default values, which are assumed for parameters not supplied, are t-8 and mO. If
the s parameter is not specified, no size checking is performed. If the first line of a
file does not contain a format specification, the above defaults are assumed for the
entire file. The following is an example of a line containing a format specification:

<:t5,10,15 s72:>

If a format specification can be disguised as a comment, it is not necessary to code
the d parameter.
SEE ALSO

ed(l), newform(l), tabs(l)

fstypes(4)
NAME

fstypes - file that registers distributed file system packages
DESCRIPTION

fstypes resides in directory /etc/dfs and lists distributed file system utilities
packages installed on the system. The file system indicated in the first line of the
file is the default file system. When Distributed File System (DFS) Administration
commands are entered without the option -F fstypes, the system takes the file system type from the first line of the fstypes file.

The default package can be changed by editing the fstypes file with any supported
text editor.
SEE ALSO

dfmounts(lM), dfshares(lM), share(lM), shareall(lM), unshare(lM)

fs(4)

(BFS)

NAME

fs (bfs) - format of the bfs file system volume
SYNOPSIS

#include
#include
DESCRIPTION

The bfs superblock is stored on sector o. Its format is:
struct bfs_bdsuphead
{

bh_bfsmagic;
bh_start;
bh_end;

/* Magic number */
/* Filesystem data start offset */
/* Filesystem data end offset */

};
/*

* The sanity structure is used to promote sanity in compaction. Used
* correctly, a crash at any point during compaction is recoverable.

struct bfs_sanity
{

daddr_t
daddr_t
daddr_t
daddr_t

fromblock;
toblock;
bfromblock;
btoblock;

/*
/*
/*
(*

"From" block of current transfer */
"To" block of current transfer */
Backup of "from" block */
Backup of "to" block */

};

struct bdsuper
{

struct bfs_bdsu~ead bdsup_head;
struct bfs_sanity bdsup_sane;
char
char
long

bdsup_fsname[6];
bdsup_volume[6];
bdsup_filler[118];

/* Header info */
/* Crash recovery info whilst
compacting */
/* file system name */
/* file system volume name */
/* Padding */

};

#define BFS_MAGIC
O~FACE
/* bfs magic number */
The sanity structure is used to promote sanity during compaction. It is used by
fsck(lM) to recover from a sYl>tem crash at any point during compaction.
SEE ALSO

bfs-specific inode(4)

fs(4)

(CD-ROM)

NAME

fs (cdfs) - format of a cdfs file system
SYNOPSIS

#include
#include
DESCRIPTION

The cdfs file system supports the 150-9660 and High Sierra file system format
specifications. In a cdfs file system, sectors 0-15 are reserved for boot information
(this area is not used). The Volume Descriptor list begins at sector 16. The Volume
Descriptor list contains the Primary Volume Descriptor (PVD) (which is known as
the super-block in other types of file systems). Directory and file data make up the
rest of the file system.
The PVD contains information such as:
The location of the root directory
The size of the file system (in logical blocks)
Various identification strings and time stamps
For each cdfs file system that is mounted, an in-core data structure is used to store
the relevant portions of the PVD. This data structure, called the cdfs structure, also
stores the other file system specific information. The cdfs structure is defined in
the cdfs_fs.h header file. The 150-9660 and High Sierra PVD's are defined in the
iso9660.h header file.
The format of the cdfs file system structure is:
struct cdfs {
uint_t
struct pathname
struct pathname
struct vnode
struct cdfs_inode
struct cdfs_fid
enum cdfs_type
daddr_t
uint_t
uint_t
uint_t
uint_t
uint_t

cdfs_Flags;
cdfS_MntPnt;
cdfs_DevNode;
*cdfs_DeVv.node;
*cdfs_RootInode;
cdfs_RootFid;
cdfs_Type;
cdfs_PvdLoc;
cdfs_LogSecSz;
cdfS_LogSecMask;
cdfs_LogSecShift;
cdfS_LoQBlkMask;
cdfs_LogBlkShift;

1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*
1*

State flags for this FS *1
Pathname of mount-point *1
Pathname of device node *1
'specfs' vnode for the device *1
Inode of CDFS root directory * 1
FID of Root Inode *1
File system type (9660/Hi-S) *1
PVD location (Log Sector #) *1
Logical sector size (~es) *1
Convert b¥tes to beg of Sect *1
Convert b¥tes to Log Sect Num *1
Convert b¥tes to beg of Blk * 1
Convert b¥tes to Log Blk Num *1

1*
1*
1*
1*
1*
1*
1*
1*

Logical block size (Bytes) *1
Version # of Vol Descr struct *1
Version # of Dir Rec/Path Tbl *1
Volume Set size (# of discs) *1
Volume Sequence # (Disc #) *1
Volume Space Size (Bytes) *1
Path Table size (Bytes) *1
Path Table loco (Log Block #) *1

1*
* Relevant PVD Information

*1
uint_t
uint_t
uint_t
uint_t
uint_t
uint_t
uint_t
daddr_t

cdfs_LogBlkSz;
cdfs_VolVer;
cdfs_FileVer;
cdfs_volSetSz;
cdfs_VolSeqNum;
cdfs_VolSpaceSz;
cdfs_pathTabSz;
cdfs_PathTabLoc;

fs(4)

(CD-ROM)
timestruc_t
timestruc_t
timestruc_t
timestruc_t
uchar_t
uint_t
uint_t

cdfELCreateDate;
cdfsJ(OdDate;
cdflCExpireDate;
cdfs_BffectDate;
cdfs_VolID[32];
cdfs_RootDirOff;
cdfs.....:RootDirSz;

/* Volume Creation date/time */
/* Volume Modification date/time * /
/* Volume Expiration date/time *1

1* Volume Bffective date/time *1
/* Volume ID string *1
/* PVD offset of Root Dir Rae */
/* Size

(~es)

of Root Dir Rae *1

XCDR specific fields.

struct cd_defs
uint_t
struct cd_uidmap
struct cd-9idmap

cdfs_Dflts;
/* Default IDs, penDS and modes *1
cdfsJi'8IIIeConV;
/* XCDR name conversion mode * /
cdfs_UidMap[CD.JIA,XtDIAP); 1* User ID map array *1
cdfs_GidMap[CD_MAXGNAP]; 1* Group ID map array */

* SOSP specific fields.

*1
uint_t

cdfs_SuspSkip;

1* value for finding SOFs in

* RRIP specific field(s).

uint_t
struct

~dew1ap

cdfs_DevMap_Cnt;
1* MUm of valid Device mappings*1
cdfsJ)eVMap[CD..J(AXmIAP); 1* Device Node (NUmber) Map *1

};

REFERENCES
cdfs-specific dir(4), cdfs-specific inode(4)

ISO 9660 Specification, Working paper for Information Processing: Volume and File Structure of CD-ROM Information Interchange in Optical Information Systems magazine,
January /February 1987

f5(4)

(55)
NAME

fs (s5) - format of s5 file system volume
SYNOPSIS

#include
#include
#include
DESCRIPTION

Every file system storage volume has a common format for certain vital information. Every such volume is divided into a certain number of 512-byte long sectors.
Sector 0 is unused and is available to contain a bootstrap program or other information.
Sector 1 is the super-block. The format of a super-block is:
struct
filsys
{

ushort
daddr_t
short
daddr_t
short
o_ino_t
char

s_isize;
s_fsize;
s_nfree;
s_free[NICFREE];
s_ninode;
s_inode[NIClNOD];
s_flock;

char
char
char
time_t
short
daddr_t
o_ino_t
char
char
long

s_ilock;
s_fmod;
s_ronly;
s_time;
s_dinfo[4];
s_tfree;
s_tinode;
s_fname[6];
s_fpack[6];
s_fi11[12];

long
long

s_state;
s_magic;

long

s_type;

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

size in blocks of i-list */
size in blocks of entire volume */
number of addresses in s_free */
free block list */
number of i-nodes in s_inode */
free i-node list */
lock during free list */
manipulation */
lock during i-list manipulation */
super block modified flag */
mounted read-only flag */
last super block update */
device information */
total free blocks*/
total free i-nodes */
file system name */
file system pack name */
ADJUST to make */
sizeof filsys be 512 */
file system state */
magic number to denote new file
system */
type of new file system * /

};

#define FsMAGIC

Oxfd187e20

/* s_magic number */

#define Fslb
#define Fs2b
#define Fs4b

1
2
3

#define FsOKAY
#define FsACTIVE

Ox7c269d38
Ox5e72d81a

/* 512-b¥te block */
/* 1024-b¥te block */
/* 2048-b¥te block */
/* s_state: clean */
/* s_state: active */

f8(4)

(55)
#define FsBAD
#define FsBADBLK

Oxcb096f43
Oxbadbc14b

/* s_state: bad root */
/* s_state: bad block */
/* corrupted it */

s_type indicates the file system type. Currently, three types of file systems are supported: the original 512-byte logical block, the 1024-byte logical block, and the
2048-byte logical block. s_magic is used to distinguish the s5 file system from
other FSTypes. The s_type field is used to determine the blocksize of the file system; 512-bytes, 1K, or 2K. The operating system takes care of all conversions from
logical block numbers to physical sector numbers.
s_state is unique for each file system and indicates the state of the file system. The
numerical value of the "file system state" is computed as the sum of s_state and
s_time and will ordinarily be one of FsOKAY, FsACTIVE, or FsBAD. A cleanly
unmounted, undamaged file system is indicated by the FsOKAY state. After a file
system had been mounted for update, the state changes to FsACTIVE. The state
reverts to FsOKAY after a file system has been unmounted. A special case is used for
the root file system. If it appears damaged at boot time, it is mounted but marked
FsBAD.
s_isize is the address of the first data block after the i-list; the i-list starts just after
the super-block, namely in block 2; thus the i-list is s_isize-2 blocks long.
s_fsize is the first block not potentially available for allocation to a file. These
numbers are used by the system to check for bad block numbers; if an "impossible"
block number is allocated from the free list or is freed, a diagnostic is written on the
on-line console. Moreover, the free array is cleared, so as to prevent further allocation from a presumably corrupted free list.
The free list for each volume is maintained as follows. The s_free array contains,
in s_free[l], ..., s_free[s_nfree-l], up to 49 numbers of free blocks.
s_free [0] is the block number of the head of a chain of blocks constituting the free
list. The first long in each free-chain block is the number (up to 50) of free-block
numbers listed in the next 50 longs of this chain member. The first of these 50
blocks is the link to the next member of the chain. To allocate a block: decrement
s_nfree, and the new block is s_free [s_nfree]. If the new block number is 0,
there are no blocks left, so give an error. If s_nfree became 0, read in the block
named by the new block number, replace s_nfree by its first word, and copy the
block numbers in the next 50 longs into the s_free array. To free a block, check if
s_nfree is 50; if so, copy s_nfree and the s_free array into it, write it out, and set
s_nfree to O. In any event set s_free [s_nfree] to the freed block's number and
increment s_nfree.
s_tfree is the total free blocks available in the me system.
s_ninode is the number of free i-numbers in the s_inode array. To allocate an inode: if s_ninode is greater than 0, decrement it and return s_inode [s_ninode] .
If it was 0, read the i-list and place the numbers of all free i-nodes (up to 100) into
the s_inode array, then try again. To free an i-node, provided s_ninode is less
than 100, place its number into s_inode [s_ninode] and increment s_ninode. If
s_ninode is already 100, do not bother to enter the freed i-node into any table. This
list of i-nodes is only to speed up the allocation process; the information as to
Whether the i-node is really free or not is maintained in the i-node itself.

(55)

f5(4)

s_tinode is the total free i-nodes available in the file system.
s_flock and s_ilock are flags maintained in the core copy of the file system while
it is mounted and their values on disk are immaterial. The value of s_fmod on disk
is likewise immaterial; it is used as a flag to indicate that the super-block has
changed and should be copied to the disk during the next periodic update of file
system information.
s_ronly is a read-only flag to indicate write-protection.
s_time is the last time the super-block of the file system was changed, and is the
number of seconds that have elapsed since 00:00 Jan. I, 1970 (UTe). During a
reboot, the s_time of the super-block for the root file system is used to set the
system's idea of the time.
s_fname is the name of the file system and s_fpack is the name of the pack.
I-numbers begin at I, and the storage for i-nodes begins in block 2. Also, i-nodes
are 64 bytes long. I-node 1 is reserved for future use. I-node 2 is reserved for the
root directory of the file system, but no other i-number has a built-in meaning.
Each i-node represents one file. For the format of an i-node and its flags, see
inode(4).
SEE ALSO

fsck(IM), fsdb(IM), sS-specific inode(4), mkfs(IM), mount(2)

fs(4)

(SFS)

NAME

fs (sfs) - format of sfs file system volume
SYNOPSIS

#include
#include
#include
DESCRIPTION

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, and by the information in the cylinder
group blocks. The super-block is critical data and is replicated before each cylinder
group block to protect against catastrophic loss. This is done at mkfs time; the critical super-block data does not change, so the copies need not normally be referenced
further.
1*
* Super block for a file system.

*1
#define
#define
#define
#define
#define
struct

SFS_MAGIC
UPS_MAGIC
FSACTIVE
FSORAY
FSBAD

Oxbdl01155
OxOl1954
Ox5e72d81a
Ox7c269d38
Oxcb096f43

1* fs_state: mounted *1
1* fs_state: clean *1
1* fs_state: bad root *1

fs {
struct fs *fs_link;
1* linked list of file systems *1
struct fs *fs_rlink;
1* used for incore super blocks *1
daddr_t fs_sblkno;
1* addr of super-block in filesys *1
daddr_t fS_cblkno;
1* offset of cyl-block in filesys *1
daddr_t fs_iblkno;
1* offset of inode-blocks in filesys *1
daddr_t fs_dblkno;
1* offset of first data after cg *1
long
fs_cgoffset;
1* cylinder group offset in cylinder *1
long
fs_cgmask;
1* used to calc mod fs_ntrak *1
time_t fs_time;
1* last time written *1
long
fs_size;
1* number of blocks in fs *1
long
fS_dsize;
1* number of data blocks in fs *1
long
fs_neg;
1* number of cylinder groups *1
long
fS_bsize;
1* size of basic blocks in fs *1
long
fS_fsize;
1* size of frag blocks in fs *1
long
fs_frag;
1* number of frags in a block in fs *1
1* these are configuration parameters *1
long
fs_minfree;
1* minimum percentage of free blocks *1
long
fs_rotdelay;
1* num of ms for optimal next block *1
long
fs_rps;
1* disk revolutions per second *1
1* these fields can be computed from the others *1
long
fS_bmask;
1* "blkoff" calc of blk offsets *1
long
fs_fmask;
1* "fragoff" calc of frag offsets *1
long
fs_bshift;
1* "lblkno" calc of logical blkno *1
long
fs_fshift;
1* "numfrags" calc number of frags *1
1* these are configuration parameters *1
long
fs_maxcontig;
1* max number of contiguous blks *1
long
fs_maxbpg;
1* max number of blks per cyl group *1

fs(4)

(SFS)

/* 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_csshift;
/* csum block number */
long
fs_nindir;
/* value of NINDIR */
long
fs_inopb;
/* value of INOPB */
long
fs_nspf;
/* value of NSPF */
long
fs_optim;
/* optimization preference, see below */
long
fs_state;
/* file system state */
long
fs_sparecon[2];
/* reserved for future constants */
/* a unique id for this filesystem (currently unused and unmaintained) */
long
fs_id[2];
/* file system id */
/* 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 */
/* sectors per track */
long
fs_nsect;
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 */
long
fs_ipg;
/* inodes per group */
long
fs_fpg;
/* blocks per group * fs_frag */
/* this data must be re-camputed after crashes */
struct csum fs_cstotal;
/* cylinder summary information */
/* these fields are cleared at mount time */
char
fs_fmod;
/* super block modified flag */
char
fs_clean;
/* file system is clean flag */
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_cgrotor;
/* last cg searched */
struct csum *fs_csp[MAXCSBUFS];/* list of fs_cs info buffers */
fs_cpc;
/* cyl per cycle in postbl */
long
fS-PQstbl[MAXCPG] [NRPOS];/* head of blocks for each rotation */
short
long
fs_magic;
/* magic number */
u_char fs_rotbl[l];
/* list of blocks for each rotation */
};

/*
* Cylinder group block for a file system.
*/
#define CG_MAGIC
Ox090255
struct cg {
struct cg *cg_link;
struct cg *cg_rlink;
time_t cg_time;
cg_cgx;
long
cg_ncyl;
short

/*
/*
/*
/*
/*

linked list of cyl groups */
used for incore cyl groups */
time last written */
we are the cgx'th cylinder group */
number of cyl's this cg */

fs(4)

(SFS)
short
long
struct
long
long
long
long
long
short
char
long
u_char

number of inode blocks this cg *1
number of data blocks this cO' *1
cylinder summary information *1
position of last used block *1
/* position of last used frag *1
1* position of last used inode *1
1* counts of available frags * /
cO'_btot[~CPG];
1* block totals per cylinder *1
cg_b[~CPG] [NRPOS]; 1* positions of free blocks *1
cg_iused[~IPG/NBBY];I* used inode map */
cg_magic;
/* magic number *1
cg_free[l];
1* free block map *1

cO'_niblk;
cg_ndblk;
csum cg_cs;
cg_rotor;
cg_frotor;
cg_irotor;
cg_frsum[MAXFRAG] ;

};

SEE ALSO

ufs-specific fs(4)

inode(4)

(VXFS)

NAME

inode (vxfs) - format of a vxfs inode
SYNOPSIS

#include
#include
DESCRIPTION

The inode list consists of fs _inopau inode entries in each allocation unit. An inode
entry has the following format:
i_mode
The mode and type of file.
i_nlink
The number of links to the file.
i_uid The inode owner.
i~id

The inode group.

i_size
The size in bytes of the file. Eight bytes have been allocated. Only
four bytes are used in the first implementation.
i_atime
Time of last access, in timestruc_t format.
i_mtime
Time of last modification, in timestruc_t format.
i_ctime
Time of last inode change, in timestruc_t format.
i_aflags
These flags are used to control the allocation and extension of files.
V)CAF_IFBAD
If this flag is set, the inode is invalid in some way. It should
be cleared when fsck is run.
VX AF_NOEXTEND
If this flag is set, the file may not be extended once the
current reservation is exceeded. The reservation may be
increased by the VX_SETEXT ioctl, but the file will not be
automatically extended.
VX AF_NOGROW
If this flag is set, the file may not be extended once the
current reservation is exceeded. It should be cleared on truncation or when setext is run. This flag is usually set
because an I/O error occurs while extending a file.
VX AF_ALIGN
If this flag is set, the file must be allocated in extents of a
fixed size and alignment. If an extent of i_fixextsize
blocks aligned on an i_fixextsize boundary cannot

(VXFS)

inode(4)

be found, then the allocation will fail. The alignment is relative to the beginning of the allocation unit.
i_orgtype
Mapping type. Indicates how the inode mapping area is to be interpreted. Currently there are two mapping types supported:
IORG_EXT4

Mapping area consists of an array of 32-bit extent block
addresses and sizes.
IORG_IMMED

Mapping area itself is a data block. This mapping is referred
to as Immediate Inode Data.
i_eopflags
Extended inode operation flag area.
i_eopdata
Extended inode operation data area.
i_ftarea
This is a union. The contents are determined by file type.
For devices, the following fields are supported:
i_rdev
The device number of a block or character special device.
For directories, the following fields are supported:
i_dotdot
The parent directory inode inumber if the inode is a directory. This replaces the standard " .. " entry in the first directory ,?l~ck. !he vxfs file system does not have explicit "."
and .. entnes.
For regular files, the following fields are supported:
i_reserve
The number of data blocks reserved for exclusive use by the
file (preallocation). A preallocation may be requested using
ioctl. [See vxfsio(7).]
i_fixextsize
Set when the inode has a fixed extent size. The default is to
have a variable extent size allocation policy. A fixed extent
size may be specified using ioctl. [See vxfsio(7).]
i_blocks
The number of blocks currently allocated to the file, including any
blocks allocated for indirect address extents.
i_gen The generation number. A serial number which is incremented
whenever the inode is freed and reallocated. It is designed to provide a "handle" for stateless servers such as NFS.

inode(4}

(VXFS)

i_serial
A count of the number of times the inode metadata has been
modified. This field is a 64-bit number.
ie_~rg

The mapping area. This field is a union based on the value of
i_orgtype and the file system type.
For the vxfs IORG_IMMED organization type, the following structure is used:
i_innned
The Immediate Inode data area, NIMMED_N (currently 96)
bytes in length (see fs_immedlen). Any directory or symbolic link which is <= 96 bytes in length will be stored
directly in the inode.
For the vxfs IORG_EXT4 organization type, the following structure is used:
i_spare
Four bytes of padding, not used.
i_ies Indirect extent size. This is the size in blocks of the indirect
data extents in the file.
i_ie

Array of indirect address extents. There are NIADDR
(currently 2) indirect address extents. The indirect address
extents are 8192 bytes long. Each indirect address extent
may contain up to 2048 extent addresses. The first indirect
address extent is used for single indirection. With single
indirection, each entry in the indirect address extent indicates
the starting block number of a data extent. The second
indirect address extent is a double indirect address extent.
With double indirection, each entry in the indirect address
extent indicates the starting block number of a single indirect
address extent.
An array of structures containing the direct extent addresses
and sizes. Up to NDADDR_N (currently ten) direct extents are
supported. Since a variable length extent allocation policy is
used, each direct extent may have a different size. Each
structure contains the following elements:
i_de

Direct extent address.

i_des Direct extent size.
reserved
There are 80 bytes reserved for future use.
SEE ALSO

vxfs-specific fs(4), stat(2), types(5)

(INET)

interface (4)

NAME

interface - Internet network interface configuration parameters
SYNOPSIS

/ete/eonfnet.d/inet/interfaee
DESCRIPTION

The /ete/eonfnet .d/inet/interfaee file is used to store network interface
parameters used at boot time. Each line of data in the interface file contains
enough information to configure an IP transport provider. This information is
passed on to the slink [see slink(lM)] and ifeonfig [see ifeonfig(lM)]
programs at boot time by /ete/eonfnet.d/inet/eonfig.boot.sh. The
/ete/eonfnet .d/inet/interfaee file can be maintained by running
/ete/eonfnet.d/eonfigure -i [see eonfigure(lM)] in interactive mode, which
will
call
/ete/eonfnet .d/inet/eonfigure -i
[see
INET-specific
eonfigure(lM) ].
The format of the /ete/eonfnet.d/inet/interfaee line is a collection of colon (:)
separated fields.

prefix: unit#: address: device: ifconfig_opts: slink_opts
Each field and its defaults (if any) are defined below.

prefix is an identifier for a driver's netstat [see netstat(lM)] statistics.
Traditionally this value corresponds to the common name used for a particular
device. This field can not be null and it has no default.
unit# is the index per prefix type in the IP internal netstat array, where zero is the
first element's index. This field should consist of only 0-9. This field can not be null
and it has no default.
address is used by ifeonfig to initialize the transport provider. This may be the
internet name from /ete/hosts [see hosts(4)] or an address in Internet standard
dot notation. Null is expanded to the system nodename, obtained by searching
/ete/hosts for the /usr/bin/uname -n entry. Note the system nodename should
be used for only one interface line.
device is the device node name of the transport provider. It is allocated from available network devices listed in /ete/eonfnet.d/netdrivers [see netdrivers(4)]
through the /ete/eonfnet.d/eonfigure script. This field can not be null and it
has no default.
ifconfig_opts is used to customize the ifeonfig options used at boot time and may
contain any options defined for ifeonfig on ifeonfig(lM). The constructed command line will take the form:
ifeonfig PrefixUnit# Converted_Address ifconfig_opts up
where PrefixUnit# is the result of concatenating prefix and unit#. PrefixUnit#
result may be used as the interface parameter given to ifeonfig and
netstat. Converted Address is the /ete/hosts value for the address
field. ifconfig_opts can be null and has no default, but it is traditionally
populated with -trailers (needed by SVR4 transport providers). See
ifeonfig(lM) and !NET-specific eonfigure(lM).

interface ( 4 )

(INET)

A case where ifconfig_opts is null is when the transport provider is 10,
(10ea1host in /ete/hosts). 10ea1host requires no additional ifeonfig
options at boot time.

slink_opts and the /ete/stref file [see stref(4)] is used by slink to initialize the
device into the TCP lIP protocol stack. slink_opts defines the strcf function and its
first arguments (it is not limited to one word). add_interface is the default slink_opts
value. Additional arguments will be appended to slink_opts to make the final form
of the slink operation:

slink_opts ip device Prefix Unit
where ip will be an open file descriptor to /dev/ip. device and PrefixUnit
are defined in the current interface entry. For a standard Ethernet board,

slink_opts may be null; the defaults will take care of all arguments.
Files
/dev/ip
/ete/eonfnet.d/eonfigure
/ete/eonfnet.d/inet/eonfig.boot.sh
/ete/eonfnet.d/inet/eonfigure
/ete/eonfnet.d/inet/interfaee
/ete/eonfnet.d/netdrivers
/ete/hosts
/usr/bin/uname

USAGE
Examples
The entry:

10:0:10calhost: I dev Iloop:netmask OxffOOOOOO:add_loop
from /ete/eonfnet .d/inet/interfaee will generate the following line to be
used by slink:

slink_opts ip device Prefix Unit
The following ifconfig command would also be generated for boot time:
ifconfig 100127.0.0.1 netmask OxffOOOOOO up
Note that the netmask arguments are present only for the purpose of this example.

REFERENCES
generic eonfigure(lM), INET-specific eonfigure(lM), hosts(4), ifeonfig(lM),
netdrivers(4), netinfo(lM), slink(lM), stref(4)

issue (4)
NAME

issue - issue identification file
DESCRIPTION

The file fete/issue contains the issue or project identification to be printed as a
login prompt. issue is an ASCII file that is read by program getty and then written to any terminal spawned or respawned from the lines file.
FILES

fete/issue
SEE ALSO

lid _and _priv (4)
NAME

lid_and-pri v - distributed file system security database
DESCRIPTION

lid_and-priv is the distributed file system (DFS) security database, located in
/ete/dfs. The lid_and-priv database acts as a mechanism that allows network

administrators to control access to RFS and NFS resources on a server.
File entries have the format

domain name hostname level_name privJist
where
domain name indicates the name of an RFS client's domain. A dash (-) in the
field indicates that the domain is the same as the server's local
domain. The domainname field is ignored by NFS.
hostname
indicates the client's machine name.
level name indicates the security label, or its alias, assigned to requests from
a client. A dash (-) in the level name field indicates the default
behavior.
privJist

is a comma-separated list of privileges that the server will accept
from the client. If the network administrator wants to accept the
same privileges assigned to the process on the client side, then
the field should contain the entry allpri vs. See the intro(2)
manual page for a complete list of privileges and their meanings.

The special character * can be used in a file entry to set up new default values. By
specifying * in the domainname and hostname fields, the network administrator indicates that the values in the level_name and privJist fields in that same entry are to be
used as defaults, overriding the system-defined defaults.
The special character - is a placeholder. It can be used in a file entry in either or
both of the fields level_name and privJist to indicate that the label and/ or privileges
assigned to the client are the same as the defaults.
The contents of lid_and-pri v must be loaded into the kernel whenever changes
are made to the file. A network administrator loads the contents of the file into the
kernel by running the lidload(lM) command. When lidload in run, all changes
in the database immediately affect all NFS resources. All RFS resources
are affected immediately as well, with the exception of those with open files, which
are affected once the files are closed and re-opened.
SEE ALSO

intro(2), lidload(lM)
NOTES

It is possible for the same RFS client to have more than one entry in lid_and-priv,

with a different domain indicated in each entry. NFS clients should have only one
entry each. If an NFS client has two entries in the file, a warning message is printed
and NFS acts on the information in the first entry.

100

limits(4)
NAME

limits - header file for implementation-specific constants
SYNOPSIS

#include
DESCRIPTION

The header file limits.h is a list of minimal magnitude limitations imposed by a
specific implementation of the operating system.
ARG_MAX
CHAR_BIT
CHAR_MAX
CHAR_MIN
CHILD_MAX
CLK_TCK
DBL_DIG
DBL_MAX
DBL_MIN
FCHR_MAX
FLT_DIG
FLT_MAX
FLT_MIN
!NT_MAX
INT_MIN
LINK_MAX
LOGNAME_MAX
LONG_BIT
LONG_MAX
LONG_MIN
MAX_CANON

5120
8
127
-128
25
_sysconf(3)
15
1.7976931348623157E+308
2.2250738585072014E-308
1048576
6

3.40282347e+38F
1. 17549435E-38F
2147483647
( -2147483647-1)
1000
8
32
2147483647
(-2147483647-1)
256

NAME_MAX
14
NGROUPS_MAX 16
NL_ARGMAX
9
NL_LANGMAX
NL_MSGMAX
NL_NMAX

14
32767

NL_SETMAX
NL_TEXTMAX
NZERO
OPEN_MAX

255
255
20
60

max length of arguments to exec */
max # of bits in a "char" */
max value of a "char" */
min value of a "char" */
max # of processes per user id */
clock ticks per second */
digits of precision of a "double" */
max decimal value of a "double"*/
min decimal value of a "double"*/
max size of a file in bytes */
digits of precision of a "float" */
max decimal value of a "float" */
min decimal value of a "float" */
max value of an "int" */
min value of an "int" */
max # of links to a single file */
max # of characters in a login name */
# of bits in a "long" */
max value of a "long int" */
min value of a "long int" */
max bytes in a line for canonical
processing */
/* max size of a char input buffer */
/* max # of bytes in a multibyte
character */
/* max # of characters in a file name */
/* max # of groups for a user */
/* max value of "digit" in calls to the
NLS printf() and scanf() */
/* max # of bytes in a LANG name */
/* max message number */
/* max # of bytes in N-to-1 mapping
characters */
/* max set number */
/* max # of bytes in a message string */
/* default process priority */
/* max # of files a process can have
open */
/* max # of characters in a password */
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*

101

limits (4)
1*
1*
1*
1*

PATH_MAX
PID_MAX
PIPE_BUF
PIPE_MAX

1024
30000
5120
5120

SCHAR_MAX
SCHAR_MIN
SHRT_MAX
SHRT_MIN
SSIZE_MAX
STD_BLK
SYS_NMLN

127
(-128)
32767
(-32768)
INT_MAX
1024
257

1*
1*

1*
1*
1*
1*
/*

17576

by
UCHAR_MAX
UID_MAX
UINT_MAX
ULONG_MAX
USHRT_MAX
USI_MAX
WORD_BIT

1*
1*
1*
1*

255
60000
4294967295
4294967295
65535
4294967295
32

/*
/*
/*

max # of characters in a path name *1
max value for a process ID */
max # bytes atomic in write to a pipe *1
max # bytes written to a pipe
a write *1
max value of a "signed char" *1
min value of a "signed char" *1
max value of a "short int" *1
min value of a "short int" *1
max value of an "int" *1
# bytes in a physical 1/0 block *1
4.0 size of utsname elements */
also defined in sys/utsname.h */
max pid of system processes *1
max # of unique names generated
tmpnam *1
max value of an "unsigned char" *1
max value for a user or group ID *1
max value of an "unsigned int" *1
max value of an "unsigned long int" */
max value of an "unsigned short int" *1
max decimal value of an "unsigned" *1
# of bits in a "word" or "int" *1

The following POSIX definitions are the most restrictive values to be used by a POSIX
conformant application. Conforming implementations shall provide values at least
this large.
_POSIX_ARG_MAX
_POSIX_CHILD_MAX
_POSIX_LINK_MAX
_POSIX_MAX_CANON
_POSIX_MAX_INPUT

4096

1* max length of arguments to exec *1

/* max # of processes per user ID */

8
255
255

1* max # of links to a single file *1
1* max # of bytes in a line of input *1

* max # of bytes in terminal
input queue *1
_POSIX_NAME_MAX
14
1* # of bytes in a filename *1
_POSIX_NGROUPS_MAX 0
/* max # of groups in a process *1
_POSIX_OPEN_MAX
16
1* max # of files a process can have open *1
_POSIX_PATH_MAX
255
/* max # of characters in a pathname *1
_POSIX_PIPE_BUF
512
1* max # of bytes atomic in write
to a pipe *1
32767 1* min value stored in object of
type ssize_t *1
1* min number of streams (stdio)
that one process can have open at a time */
1* max number of bytes supported
for name of a timezone (not the TZ variable) *1

102

Options for the login program can be set or changed with keywords in
fete/default/login. The following keywords are recognized by login.
CONSOLE

If set, a privileged user may log in only on the terminal defined by the
CONSOLE keyword. For example,
CONSOLE=/dev/eonsole

means the privileged user may log in only on the integral display
device attached to /dev/eonsole. If CONSOLE is not in
fete/default/login, a privileged user may log in on any terminal.
ALTSHELL

If the user's shell is defined in /ete/passwd and this keyword is set to
YES, the SHELL environment variable is set to the user's shell. If set to
NO, the names of nonstandard shells are not put in the SHELL environment variable. The default value of this keyword is NO. For increased
security, set it to YES.

PASSREQ

If set to YES, all users must have a password. Any user without a

password is asked for one at the first opportunity permitted by the
password aging set for that user. (That is, users without passwords
may not change their NULL passwords if password aging is enabled
for them and the minimum time before a password can be changed
has not elapsed.)
MANDPASS

When set to YES, this keyword makes passwords mandatory for all
logins (overriding PASSREQ).

TIMEZONE

This keyword sets the TZ variable in the environment of the user. It
must match the format of the timezone set in /ete/TIMEZONE.

This keyword sets the environment variable HZ, the rate of the system
clock, for the user logging in. The default is 100.

PATH

This keyword sets a default path for an unprivileged user. The
default is /usr/bin.

SUPATH

This keyword sets the default path for the privileged user logging in.
Another default path for the privileged user is in /ete/default/su,
which is set for privileged users who did not log in as such. The
default is /sbin: /usr/sbin: /usr/bin: fete.

ULIMIT

This keyword sets the maximum file size for a user. It is in units of
512-byte blocks.

UMASK

This keyword is the default umask for users. The default is 077.

IDLEWEEKS

This keyword is the number of weeks an account may remain idle
before its login is disabled.

TIMEOUT

This keyword is the length of time, in seconds, that login waits for a
password after receiving a user name. The default is 60.

103

This keyword sets the maximum number of login attempts permitted.
The default is 5.

LOGFAILURES

This keyword sets the number of failed login attempts permitted
before a record is made. The default is 5. [See loginlog(4).]
DlSABLETIME

This keyword sets the number of seconds to sleep after MAXTRYS or
LOGFAILURES failed logins. The default is 20.
SLEEPTIME
OPT_FPM

This keyword sets the number of seconds to sleep before printing an
error message. The default is 1.
This keyword is the pathname of a regular, non-executable file containing a site-specific message to a user without a password, asking
that user to pick a password. The default message is Choose one.

DELAYEDEXIT

This keyword is used to delay the exit from the login process, for the
specified number of seconds, so the user logging in has time to read
messages before the screen is cleared. Its value can be set to any
number between 0 and 10; the default value is o. (If you try to assign
a value greater than the default-10-the value will be set to 10.)
FILES

fete/default/login
SEE ALSO

defadm(lM),loginlog(4)

104

loginlog (4)
NAME

loginlog -log of failed login attempts
DESCRIPTION

After LOGFAILURES unsuccessful login attempts, where LOGFAILURES is 5 if not
defined in tete/default/login, all the attempts are logged in the file
/var/adm/loginlog. This file contains one record for each failed attempt. Each
record contains the login name, tty specification, and time.
This is an ASCII file. Each entry is separated from the next by a new-line. Within
each entry, each field is separated from the next by a colon.
By default, loginlog does not exist, so no logging is done. To enable logging, the
log file must be created with read and write permission for owner only. The owner
must be root; the group, sys.
FILES

/var/adm/loginlog
tete/default/login
SEE ALSO

defadm(lM), login(l), login(4), passwd(l)

105

mailcnfg ( 4 )
NAME

mailcnfg - initialization information for mail and nnail
DESCRIPTION
The /etc/mail/mailcnfg file contains initialization information for the mail and
nnail commands. This file must be created initially by the administrator. Each
entry in mai lcnfg consists of a line of the form

Keyword = Value
Leading whitespace, whitespace surrounding the equal sign, and trailing whitespace is ignored. Keyword may not contain embedded whitespace, but whitespace
may appear within Value. Undefined keywords or badly formed entries are silently
ignored. Lines beginning with "#" are ignored.
The mailcnfg file must be world readable.
Keyword Definitions
ADD_DATE

If a message which originated on the local machine does not
have a Date: header, and ADD_DATE has a value, one will be

added.
If a message which originated on the local machine does not
have a From: header, and ADD_FROM has a value, one will be
added.
If a message is received which has no Received: header, and
ADD_RECEIVED has
DEBUG

CLUSTER

RENOTEFROM

FAILSAFE

106

a value, one will be added.
Takes the same values as the -x invocation option of mail.
This provides a way of setting a system-wide debug/tracing
level. Typically DEBUG is set to a value of 2, which provides
minimal diagnostics useful for debugging mail and rmail
failures. The value of the -x mail invocation option will
override any specification of DEBUG in mailcnfg.
To identify a closely coupled set of systems by one name to
all other systems, set Value to the cluster name. This string is
used in place of the rather than the local system nodename
returned by uname(2), such as in the surrogate file processing
or for supplying the ••• remote from •.• information on the
From UNIX postmark header line.
This string may be set in the event that you wish to use a
slightly different string in the ••• remote from ••• information on the From header line UNIX postmark header line than
either the cluster name or system name.
In the event that the /var /mail directory is accessed via RFS
or NFS within a cluster (see CLUSTER above), provisions must
be made to allow for the directory not being available when
local mail is to be delivered (remote system crash, RFS or
NFS problems, etc.). Value is a string that indicates where to
forward the current message for delivery. Typically this is
the remote system that actually owns /var/mail. In this
way, the message is queued for delivery to that system when

mailcnfg ( 4 )
it becomes available. For example, assume a cluster of systems (sysa, sysb, sysc) where Ivar/mail is physically
mounted on sysc and made available to the other machines
via RFS or NFS. If sysc were to crash, the RFS /NFSaccessible Ivar/mail would become unavailable and local
deliveries of mail would go to Ivar lmail on the local system. When Ivar/mail is re-mounted via RFS/NFS, all messages deposited in the local directory would be hidden and
essentially lost. To prevent this, if FAILSAFE is defined in
mailcnfg, mail and rmail check for the existence of
Ivar/mail/:saved, a required subdirectory. If this subdirectory does not exist, mail assumes that the RFS/NFSaccessible lvar/mail is not available and invokes the failsafe
mechanism of automatically forwarding the message to
Value. In this example Value would be sysc! %no The %n keyword is expanded to be the recipient name [see mail(1) for
details] and thus the message would be forwarded to
sysc!recipient_name. Because sysc is not available, the message remains on the local system until sysc is available, and
then sent there for delivery.
DEL_EMPTY_MFILE

If not specified, the default action of mail and rmail is to

delete empty mailfiles if the permissions are 0660 and to
retain empty mailfiles if the permissions are anything else. If
Value is yes, empty mailfiles are always deleted, regardless
of file permissions. If Value is no, empty mailfiles are never
deleted.
DOMAIN
SMARTERHOST

ARG_MAX

BURR_EXPORT

CNFG_EXPORT

This string is used to supply the system domain name in
place of the domain name returned by sysinfo(2).
This string may be set to a smarter host which may be referenced within the mail surrogate file via %X.
The maximum size of the argument list and environment to
be used for surrogate commands. This overrides the kernelsettable ARG_MAX parameter. On most systems, the maximum size will be 5120 bytes.
A comma separated list of environment variables to be
passed through to surrogate commands.
A comma separated list of mail configuration variables to be
passed through to surrogate commands as environment variables.

NOCOMPILEDSURRFILE

Normally, mail will create a compiled version of the surrogate file, named letc/mail/Cmailsurr, whenever the surrogate file or configuration file changes, and then subsequently use the compiled version. If this variable is set to
any value, mail will ignore the compiled surrogate file.

107

mailcnfg ( 4 )
%mailsurrJeyletter

As described in mailsurr(4), certain pre-defined single letter
keywords are textually substituted in surrogate command
fields before they are executed. While none of the predefined
keyletters may be changed in meaning, new ones may be
defined to provide a shorthand notation for long strings
(such as /usr/lib/mail/surrcmd) which may appear
repeatedly within the mailsurr file. Upper case letters are
reserved for future use and will be ignored if encountered
here.

FILES

/etc/mail/mailcnfg
/etc/mail/mailsurr
/etc/mail/Cmailsurr
/var/mail/:saved
/usr/lib/mail/surrcmd
SEE ALSO

mail(l), mailsurr(4), sysconf(3C), sysinfo(2), uname(2)
NOTES

If /var/mail is accessed via RFS or NFS and the subdirectory /var/mail/:saved
is not removed from the local system, the FAILSAFE mechanism will be subverted.

108

mailsurr (4)
NAME

mailsurr - surrogate commands for routing and transport of mail
DESCRIPTION

The mailsurr file contains routing and transport surrogate commands used by the
mail command. Each entry in mailsurr has three (or four) whitespace-separated,
single quote delimited fields:

, sender'
, recipient'
, command'
or a line that begins with either of

[' batch']

Defaults:
Translate-Defaults:

Entries and fields may span multiple lines, but leading whitespace on field continuation lines is ignored. Fields must be less than 1024 characters long after expansion (see below). Case is always ignored for making comparisons.
The sender and recipient fields are regular expressions. If the sender and recipient
fields match those of the message currently being processed, the associated command is invoked.
The command field may have one of the following forms:
A[ccept]
D[eny] [message]
L[ocal]
T[ranslate] [B", ••. ; S"' •.. ;P", •.. ;T", ..• ;L", ... ;] R=[ I]string
< [B", ••• ;s= ••• ;c= ••• ;F= .•• ;] command
> [B= ••• ;w= ••• ;] command
E[rrors] [B= ••• ;w= ••• ;] command
The mailsurr file must be world readable. If a batching specification (B= ••• ;) is
given, then the batch field must also be given; this fourth field is discussed in the
"Batching" section.
Regular Expressions

The sender and recipient fields are composed of regular expressions (REs) which
are digested by the regexp(5) cOIlllile and advance procedures in the C library.
The regular expressions matched are those from ed(l), with simple parentheses ()
playing the role of \ (\) and the addition of the +, ? and I operators from egrep(l).
Any single quotes embedded within the REs must be escaped by prepending them
with a backslash or the RE is not interpreted properly.
The mail command prepends a circumflex (~) to the start and appends a dollar sign
($) to the end of each RE so that it matches the entire string. Therefore it would be
an error to use ~RE$ in the sender and recipient fields. To provide case insensitivity, all REs are converted to lower case before compilation, and all sender and
recipient information is converted to lower case before comparison. This conversion is done only for the purposes of RE pattern matching; the information contained within the message's header is not modified.

109

mailsurr (4)
The sub-expression pattern matching capabilities of regexp may be used in the
command field, that is, \ \n, where 1 :::; n:::; 9. Any occurrences of \ \n in the replacement string are themselves replaced by the corresponding parenthesized ( ... ) substring in the matched pattern. The sub-expression fields from both the sender and
recipient fields are accessible, with the fields numbered 1 to 9 from left to right.
Accept and Deny Commands
Accept instructs rmail to continue its processing with the mailsurr file, but to
ignore any subsequent matching Deny. That is, unconditionally accept this message
for delivery processing. Deny instructs rmail to stop processing the mailsurr file

and to send a negative delivery notification, along with the optional message, to the
originator of the message. Whichever is encountered first takes precedence.

< Delivery command
The intent of a < command is that it is invoked as part of the transport and delivery
mechanism, with the ready-for-delivery message available to the command at its
standard input. As such, there are three conditions possible when the command
exits:
Success
The command successfully delivered the message. What actually constitutes successful delivery may be different within the context of different
surrogates. The rmail process assumes that no more processing is
required for the message for the current recipient.
Continue The command performed some function (logging remote message
traffic, for example) but did not do what would be considered message
delivery. The rmail process continues to scan the mailsurr file looking
for some other delivery mechanism.
Failure
The command encountered some catastrophic failure. The rmail process stops processing the message and sends to the originator of the
message a non-delivery notification that includes any stdout and
stderr output generated by the command.
The semantics of the < command field in the mailsurr file allow the specification of
exit codes that constitute success, continue, and failure for each surrogate command
individually. See the section below on "Exit State Specifications" for details.
Surrogate commands are executed by rmail directly. If any shell syntax is required
(metacharacters, redirection, and so on), then the surrogate command must be of
the form:
sh -c "shell command line . .. "
Special care must be taken to properly escape any embedded back-slashes and other
characters special to the shell as stated in the "Translate" section above.
If there are no matching < commands, or all matching < commands exit with a continue indication, rmail attempts to deliver the message itself by assuming that the
recipient is local and delivering the message to Ivar/maillrecipient.
Translate Command
Translate allows optional on-the-fly translation of recipient address information.

The recipient replacement string is specified as R=string.

110

mailsurr (4)
For example, given a command line of the form
'.+'

'([~!l+)@(.+)\.EUO\.ATT\.cam'

'Translate R=attmail!\\2!\\1'

and a recipient address of rob@sysa.EUO.ATT.COM the resulting recipient address
would be attmail!sysa!rob.
Should the first character after the equal sign be a 'I', the remainder of the string is
taken as a command line to be directly executed by rmail. If any sh(l) syntax is
required (metacharacters, redirection, and so on), then the surrogate command
must be of the form:
sh -c "shell command line . .. "

Special care must be taken to escape properly any embedded back-slashes and single or double quotes, since rmail uses double quoting to group whitespace delimited fields that are meant to be considered as a single argument to execl() [See
exec(2)]. As stated above, any occurrences of \ \n are replaced by the appropriate
substring before the command is executed.
It is assumed that the executed command will write one or more replacement
strings on stdout. The exit code of the command is examined to determine the

outcome of the translation:
Success

Failure

The command successfully translated the address. If the invoked command does not return at least one replacement string (no output or just a
newline), the original address is not modified. If the original address
itself is returned as one of the translations, the translations are added to
the list of addresses and the original address is not modified.
The command encountered some catastrophic failure. Any translations
read from stdout will be used, but the rmail process will send to the
originator of the message a non-delivery notification that includes any
stderr output generated by the command.

The semantics of the Translate command field in the mailsurr file allow the
specification of exit codes that constitute success and failure for each surrogate command individually. See the section below on "Exit State Specifications" for details.
The output of the translation command consists of one or more lines of output containing the new addresses, one or more per line, separated by white space. If batching is enabled (see the section on "Batching" below), the output of the translation
command consists of the new addresses, but each line of output must begin with
the address for which that line of output is the translation.
This mechanism is useful for mailing list expansions. For example, the command
line
'.+'

'(.+)' 'Translate R=lfindpath \\1'

allows local routing decisions to be made.
If the recipient address string is modified, mailsurr is rescanned from the beginning with the new addressees), and any prior determination of Accept (see above)
is discarded.

111

mailsurr (4)
When a recipient has been translated, the new recipient may again be passed
through the translation command for further translation. (Recursive mailing lists
are thus possible.) Some translation commands can guarantee that their output is
fully translated and cannot be further translated. For these commands, the state
specification T=1; should be given. (If the resulting address should not be processed further within the surrogate file, the state specification L=1; should be given.
Local delivery to Ivar/maillrecipient will then be attempted.)
If a recipient address translates into a recipient address previously seen, it will not
be placed onto the recipient list again unless the name was translated recursively
back to itself.
If the returned recipient address begins with an exclamation point "!" and E=1; is
given, then all leading exclamation points will be stripped. Because the default surrogate file treats leading exclamation points as special, careful consideration should
be given as to whether stripping should be performed. If a recipient address is
passed in to the translate command with a leading exclamation point, the exclamation point should not be stripped.
Local Command
Local instructs rmail to stop processing this address within the surrogate file and
attempt local delivery to Ivar/maillrecipient. It is equivalent to a Translate command with the state specification L=1; and a null translation string.
Exit State Specifications

The syntax of the exit state specification is:

[state_id=ec[, ec[,. .. ]]; ][state_id=ec[,ec[,. .. ]]; [... ]]]
Whitespace may precede the exit state specification, but must follow. state_ids can
be specified in any order. exit_state_id can have the value s, C, or F, and are used on
Delivery < and Translation commands. The special state_id of T may be used in
Translation commands, and is described in that section. The special state_id of w
may be used in Postprocessing, > and Errors, commands, and is described in those
sections. The special state_id of B may be used to specify batched processing and is
described in the section "Batching".

eccan be:
any integer 0
and wait(2).}

255 [Negative exit values are not possible. See exit(2)

a range of integers of the form lowerJimit-upper_limit where the limits are ;:::

oand::;; 255, and

*, which implies anything
For example, a command field of the form:
'< S=1-5,99;C=O,12;F=*;

command %R'

indicates that exit values of 1 through 5, and 99, are to be considered success, values
of 0 (zero) and 12 indicate continue, and that anything else implies failure.
It may be possible for ambiguous entries to exist if two exit states have the same
value, for example, S=12, 23;C=* ;F=23, 52; or S=* ;C=9;F=*;. To account for this,
rmail looks for explicit exit values (that is, not "*") in order of success, continue,
failure. Not finding an explicit match, rmail then scans for "*" in the same order.
112

mailsurr (4)
It is possible to eliminate an exit state completely by covering all possible values

with a different default or setting a state's value to an impossible number. (Since
exit values must be between 0 and 255 (inclusive), a value of 256 is a good one to
use.) For example, if you had a surrogate command that was to log all message
traffic, a mailsurr entry of
'(.+)'

'(.+)'

' Postdelivery command
The intent of a > command is that it is invoked after a successful delivery to do any
post-delivery processing that may be required. Matching> commands are executed
only if some < command indicates a successful delivery (see the previous section) or
local delivery processing is successful. The mailsurr file is rescanned and all
matching> commands, not just those following the successful < command, are executed in order. The exit status of an > command is ignored.
Some commands exit quickly, while others may take a while. The rmail command
normally waits for the > command to exit before continuing its processing. If it is
better not to wait for a particular command, the state specification W=1; should be
given.
Errors command
The intent of a Errors command is that it is invoked after an unsuccessful delivery
to do any post-delivery processing that may be required. Matching Errors commands are executed only if some < or Translate command indicates a failed
delivery, or local delivery processing is unsuccessful. The mailsurr file is rescanned and all matching Errors commands, not just those following the failed < or
Translate command, are executed in order. The exit status of an Errors command is ignored. The state specification W=1; may be used just as for the> command.
Batching
Some commands may be combined together for multiple recipients. For example,
the delivery commands

113

mailsurr (4)
uux - sysa!rmail (tony)
uux - sysa!rmail (rob)
may be combined together into the single delivery command
uux - sysa!rmail (tony) (rob)
Note that there are essentially two parts to each of the above commands, the nonvarying left-hand part, and the varying right-hand part. Combining two delivery
lines going to a common system just requires the use of the non-varying left-hand
side paired with all the remaining right-hand sides. Combining the commands
together allows for the more efficient delivery of mail.
Note also that there are two possible limitations to be imposed on such commands:
the maximum size of the command line as limited by the UNIX system, and the
maximum size of buffers used within the command. The first limitation is an
administerable kernel parameter, usually 5120 bytes, for the combination of the
parameters and environment (the command-line length limitation); the second limitation is a function of the command being used and varies from command to command. For example, the internal buffers of most versions of uux limit the command
line to 1024 bytes. (Note also that there are limitations on both sides of the network;
even if the limit for uux were raised on the local side, the limit must remain at 1024
to be portable.)
To specify that a surrogate command is to be batched, the batching specification of
B=number is given along with any exit code specifications. The number is the maximum size of the command line to be used. It may also be specified as *, in which
case the system command-line limitations are used. (The system command-line
limitations may be overridden by using the mailcnfg variable ARG_MAX.)
If batching is specified, then in addition to the command field, a fourth batch field
must also be specified. The command field specifies the non-varying left-hand part,
and the batch field specifies the varying right-hand part. For example, a specification
for uux might be:

'.+' '([A!@]+)!(.+)' '< B=1024; uux - \ \1!rmail' '(\\2)'
All surrogate commands which permit a UNIX command to be executed may be
batched.
Surrogate Command Keyletter Replacement.

Certain special sequences are textually-substituted in surrogate commands before
they are invoked:
'Yoe
value of the Content-Type: header line if present.
%C
"text" or "binary", depending on an actual scan of the content. This is independent of the value of any Content-Type
header line encountered (useful when calling ckbinarsys.)
'Yon
the local domain name. This will be either DOMAIN from
mailcnfg, or the value returned by sysinfo(2).
%H
the size of the message header in bytes.
'YoL
the local system name. This will be either CLUSTER from
mailcnfg or the value returned by uname.

114

mailsurr (4)
%1
~oIl
~oO
~oR

%S
%u
~oX

\ \n

~okeyletters

value of the Content-Length: header line: the size of the message body in bytes.
the recipient's name (address).
the recipient's original address before any translation
the full return path to the originator (useful for sending replies,
delivery failure notifications, and so on)
the value of the Subj ect: header line, if present.
the local system name, as returned by uname.
the value of SMARTERHOST in mailcnfg.
as described above, the corresponding (... ) substring in the
matched patterns. This implies that the regexp limitation of 9
substrings is applied to the sender and recipient REs collectively.
Other
lowercase
keyletters
as
specified
in
/etc/mail/mailcnfg. See mailcnfg(4).

The sequences ~oL, %U, ~oD, and ~okeyletters are permitted within the sender and recipient fields as well as in the command fields.
Mail Surrogate Examples
Some examples of mail surrogates include the distribution of message-waiting
notifications to LAN-based recipients and lighting Message-Waiting Lamps, the
ability to mail output to printers, and the logging of all rmail requests between
remote systems (messages passing through the local system). The following is a
sample mai1surr file:
#
# Same common remote mail surrogates follow. To activate any
# or all of them, remove the '#' (comment indicators) from
# the beginning of the appropriate lines. Remember that they
# will be tried in the order they are encountered in the file,
# so put preferred surrogates first.
#

Prevent all shell meta-characters

, • +'

, • * [ , ; & I ~ <> () ] • *'

Map all names of the form local-machine!user -> user
'~oL! (.+)'
'Translate R=\\l'

'.+'

'Deny'

#
Map all names of the form uname!user -> user
#
Must be turned on when using mail in a cluster environment.
#' .+' '%U! (.+)'
'Translate R=\\l'
#
'.+'

Map all names of the form user@host -> host!user
'([~!@]+)@(.+)'
'Translate R=\\2!\\1'

#
, .+'

Map all names of the form host.uucp!user -> host!user
, ([~ !@]+)\\.uucp! (.+) , 'Translate R=\\l! \\2'

#
#
'.+'

Map all names of the form host.local-domain!user -> host!user
DOMAIN= within /etc/mail/mailcnfg will override sysinfo(2).
'([~!@]+)~oD!(.+)'
'Translate R=\\l!\\2'

115

mailsurr ( 4 )
#
Allow access to 'attmail' from remote system 'sysa'
'sysa!.*'
'attmail! .+'
'Accept'
#
Deny access to 'attmail' from all other remote systems
'.+!.+'
'attmail!.+'
'Deny No access to AT&T Mail'
#
#
'.+'

Send mail for 'laser' to attached laser printer
Make certain that failures are reported via return mail.
'laser'
'< S=O;F=*; lp -dlaser'

Run all local names through the mail alias processor

#
'Translate B=*; R=lmailalias'
#
#
#
#
#
#'.+'

'~on'

If you wish to support a user name space of user@local-domain in
addition to user@host.local-domain, then add the following translation,
where DOMAIN is the local domain, and HOST.DOMAIN is where to send the
mail. Note that ~oD contains a leading dot, so it cannot be used in the
first regular expression.
'!DOMAIN!(.+)'
'Translate R=!HOST"/oD!\1'

For remote mail via nusend
#
#'.+' ,([A!]+)!(.+),
'< nusend -d \\1 -s -e -!"rmail \\2"-'
#
'.+'

For remote mail via usend
,([A!]+)!(.+),
'< usend -s -d\\1 -uNoLogin -!"rmail \\2" - ,

#
'.+'
'.+'

For remote mail via uucp
'( [A!@]+)!.+,
' logger \\1 \\2'

116

mailsurr (4)
Note that invoking mail to read mail does not involve the mailsurr file or any surrogate processing.
Security

Surrogate commands execute with the permissions of rmail (user ID of the invoker,
group ID of mail). This allows surrogate commands to validate themselves, checking that their effective group ID was mail at invocation time. This requires that all
additions to mailsurr be scrutinized before insertion to prevent any unauthorized
access to users' mail files. (Note that some versions of the shell turn off the effective
group ID. If the surrogate command is a shell script and it requires group mail permissions, the shell may be explicitly invoked in the surrogate command with the -p
option: sh -p shell. script.) All surrogate commands are executed with the path
/usr/lib/mail/surrcmd:/usr/bin, and an environment consisting of the
SHELL=/usr/bin/sh, HOME, TZ and LOGNAME variables. Other environment variables may be passed by listing them in the mailcnfg variable SURR_EXPORT as a
comma-separated list (e.g. SURR_EXPORT=TERM,LINES,COLUMNS).
Debugging New mailsurr Entries

To debug mailsurr files, use the -T option of the mail command. The -T option
requires an argument that is taken as the pathname of a test mailsurr file. If null
(as in -T ""), the system mailsurr file is used. Enter
mail -T test yle recipient
The result of using the -T option is displayed on standard output and shows the
inputs and resulting transformations as mailsurr is processed by the mail command for the indicated recipient.
Mail messages will never be sent or delivered when using the -T option.
The -d and -# option may also be used to debug the system surrogate files.
FILES

/etc/mail/mailsurr
/usr/lib/mail/surrcmd/* surrogate commands
/etc/mail/mailcnfg
initialization information for mail
SEE ALSO

ckbinarsys(lM), ed(l), egrep(l), exec(2), exit(2), mail(l), mail (1),
mailalias(l), mailcnfg(4), popen(3S), regexp(5), sh(l), smtpqer(lM),
sysinfo(2), uname(l), uux(lC), wait(2)
NOTES

It would be unwise to install new entries into the system mailsurr file without ver-

ifying at least their syntactical correctness via 'mail -T ... ' as described above.

117

mapchan(4)
NAME

mapchan - format of tty device mapping files
DESCRIPTION

mapchan configures the mapping of information input and output of UNIX.
Each unique channel map requires a 2048-byte buffer for mapping the input and
output of characters. No buffers are required if no channels are mapped.
A method of sharing maps is implemented for channels. that have the same map in
place. Each additional, unique map allocates an additional buffer. The maximum
number of map buffers available on a system is configured in the kernel, and is
adjustable via the link kit NEMAP parameter. Buffers of maps no longer in use are
returned for use by other maps.
EXAMPLES OF A MAP FILE

The internal character set used by UNIX System V /386 is defined by the right
column of the input map, and the first column of the output map in place on that
line. The default internal character set is the 8-bit ISO 8859/1 character set, which is
also known as dpANS X3.4.2 and ISO /TC97 /SC2. It supports the Latin alphabet
and can represent most European languages.
Any character value not given is assumed to be a straight mapping. Only the differences are shown in the mapfile [see mapchan(lM)]. The left hand column must be
unique. More than one occurrence of any entry is an error. Right hand column
characters can appear more than once. This is many to one mapping. Nulls can be
produced with compose sequences or as part of an output string.
It is recommended that no mapping be enabled on the channel used to create or

modify the mapping files. This prevents any confusion of the actual values being
entered due to mapping. It is also recommended that numeric rather than character
representations be used in most cases, as these are not likely to be subject to mapping. Use comments to identify the characters represented. Refer to the ascii(5)
manual page and hardware reference manual of the device being mapped for the
values to assign.
#
#sharp/pound/cross-hatched is the comment character
#however, a quoted # ('#') is Ox23, not a comment
#
#beep, input, output, dead, compose and control
#are special keywords and should appear as shown.
#
beep
#sound bell when errors occur
input

ab
cd
dead p
st

# P followed by q yields r.
# p followed by s yields t.

dead u
vw

# u followed by v yields w.

118

mapchan(4)
compose x

# x is the compose key (only one allowed).

yza
BCD
output

# x followed b¥ B and C yields D.

klmno

# e is mapped to f.
# g is mapped to hij- one to many.
# k is mapped Imno

control

# The control must be last

gh ij

input

# The character E is followed b¥ 1 or more
unmapped character

output
FG2

# The characters FG are followed

b.Y

2 more

unmapped characters

All of the single letters above preceding the control section must be in one of these
formats:

56
045

Oxfa
b'
'\076'

'\x4a'

# decimal
# octal
# hexadecimal
# quoted char
# quoted octal
# quoted hex

All of the above formats are translated to a single byte values.
The control sections (which must be the last in the file) contain specifications of
character sequences which should be passed through to or from the terminal device
without going through the normal mapchan processing. These specifications consist
of two parts: a fixed sequence of one or more defined characters indicating the start
of a no-map sequence, followed by a number of characters of which the actual
values are unspecified.
To illustrate this, consider a cursor-control sequence which should be passed
directly to the terminal without being mapped. Such a sequence would typically
begin with a fixed escape sequence instructing the terminal to interpret the following two characters as a cursor position; the values of the following two characters
are variable, and depend on the cursor position requested. Such a control sequence
would be specified as:
E= 2
# CUrsor control: escape =
There are two subsections under the control section: the input section, which is
used to filter data sent from the terminal to UNIX System V /386, and the output
section, which is used to filter data sent from UNIX System V /386 to the terminal.
The two fields in each control sequence are separated by white space, that is the
SPACE or TAB characters. Also the # (HASH) character introduces a comment,
causing the remainder of the line to be ignored. Therefore, if any of these three
characters are required in the specification itself, they should be entered using one
of alternative means of entering characters, as follows:

119

mapchan(4)
AX

or \
\c

o or On

The character produced by the terminal on pressing the CONTROL and
x keys together.
The ESCAPE character, octal 033.
Where c is one of b, f, 1, n, r or t, produces BACKSPACE, FORMFEED,
LINEFEED, NEWLINE, CARRIAGE RETURN or TAB characters, respectively.
Since the NULL character can not be represented, this sequence is not
stored as the character with octal value 0200, which behaves as a NULL
on most terminals.
Specifies the octal value of the character directly.
Followed by any any other character is interpreted as that character.
This can be used to enter SPACE, TAB, or HASH characters.

DIAGNOSTICS

mapchan performs these error checks when processing the mapfile:
more than one compose key
characters mapped to more than one thing
syntax errors in the byte values
missing input or output keywords
dead or compose keys also occurring in the input section
extra information on a line
mapping a character to null
starting an output control sequence with a character that is already mapped
If characters are displayed as the 7-bit value instead of the 8-bit value, use stty -a
[see stty(l)] to verify that -strip is set. Make sure input is mapping to the 8859
character set. Dead and compose sequences are input mapping and should be
going to 8859.
FILES

/etc/defau1t/mapchan
/usr/1ib/mapchan/*
NOTES

Some non-U.S keyboards and display devices do not support characters commonly
used by UNIX command shells and the C programming language. Do not attempt
to use such devices for system administration tasks.
Not all terminals or printers can display all the characters that can be represented
using this utility. Refer to the device's hardware manual for information on the
capabilities of the peripheral device.
Use of mapping files that specify a different internal character set per-channel, or a
set other than the 8-bit ISO 8859 set supplied by default can cause strange side
effects. It is especially important to retain the 7-bit ASCn portion of the character
set [see ascii(5)] UNIX System V /386 utilities and applications assume these
values. Media transported between machines with different internal code set mappings may not be portable as no mapping is performed on block devices, such as
tape and floppy drives. trchan can be used to translate from one internal character
set to another.

120

mapchan(4)
Do not set ISTRIP [see stty(l)] on channels that have mapping that includes eight
bit character set.

see

ALSO

ascii(5), keyboard(7), lp(7), mapchan(lM), mapkey(lM), stty(l), trchan(l),
tty(7)

121

Master (4)
NAME

Master - generic configuration information for a kernel module
SYNOPSIS

Master
DESCRIPTION

One of the ID /TP kernel configuration files, a Master file describes a kernel module
that can potentially be configured into the system. Configuration information for
the individual kernel modules that are actually to be included in the next system to
be built is described in the System file [see System(4»).
When the Master component of a module's Driver Software Package (DSP) is
installed, idinstall(lM) stores the module's Master file information in
/etc/conf/mdevice.d/module-name, where the file module-name is the name of the
module
being
installed.
Package
scripts
should
never
access
/etc/conf/mdevice.d files directly; only the idinstall and idcheck(lM)
commands should be used.
Master files contain lines of the form:
$version version-number
$entry entry-point-list
$depend module-name-list
$modtype loadable-module-type-name
module-name prefix characteristics order bmaj cmaj
Blank lines and lines beginning with '#' or '*' are considered comments and are
ignored.
The first four types of lines are as follows:
$version
If present in the file, this line must appear as the first noncomment line. The line specifies the version number of the
Master file format. The Master file format being described here
is version 1. If this line is omitted, version 0 (the old Master file
format) is assumed.
Specifies the names of the entry point routines included in the
$entry
module. One or more $entry lines may be used to specify the
entry point names. If a single $entry line specifies more than one
entry point name, the multiple names must be separated by white
space.
The function names are constructed by appending the entry point
name to the module's prefix. Only functions explicitly listed on
$entry lines will be called directly by the kernel. The following
entry points are supported (note that some of the supported entry
points apply only to certain module types):
_init chpoll close core exec halt init intr ioctl
kenter kexit mmap msgio open poll print read segmap
size start strategy write

122

Master (4)
$depend

Used for dynamically loadable kernel modules only, the line
specifies the names of the loadable modules (if any) that contain
symbols referenced by this loadable module. One or more
$depend lines may be used to specify the module names. If a
single $depend line specifies more than one module name, the
multiple names must be separated by white space.

$modtype

This line is used for dynamically loadable kernel modules only.
The line specifies the character string (maximum of 40 characters,
including white space characters) to be used to identify the type
of this module in error messages.

The last line of the Master file contains the follOWing six fields. Each field must be
separated by white space and specify a value.

module-name

Specifies the internal name of the module (maximum of 14 characters). The first character must be alphabetic; the remaining
characters may be letters, digits or underscores.

prefix

Specifies the character string prepended to all entry-point routines and variable names associated with this module (maximum
of 8 characters). During the kernel build process, an all uppercase version of this string will also be used to construct the
#define symbolic constants accessible to the module's Space.c
file [see idbuild(lM)].
If the module has no entry-points or special variables, this field
may contain a dash; in this case, no #define symbols will be generated.

characteristics

Defines a set of flags that indicate the characteristics of the
module. If none of the characteristics listed below apply to the
module, the characteristics field must contain a dash. Valid field
values are:
b

The module is a 'block' device driver.

The module is a (STREAMS or non-STREAMS) character
device driver.

The module is a dispatcher class module.

The module is an exec object-specific module.

The module controls hardware, but is not a device driver;
that is, the module requires hardware I/O resources (for
example, interrupts or bus addresses), but does not
require switch table entries.

Keep majors flag. This flag is intended for device drivers
supplied with the base system only. It indicates that
idinstall should use the major numbers specified by the
bmaj and/or cmaj fields in the module's Master file,
instead of automatically assigning major numbers to the
module. These reserved major numbers must also be
specified in the res_major file [see res_major (4) ].

123

Master (4)
m

o
r

The module is required in all configurations of the kernel.
This flag is intended for device drivers supplied with the
base system only. Note that, once made, a required
module's device nodes (special files in the Idev directory)
are not removed [see idmknod(lM)].

t
u

The module is a non-STREAMS tty driver.
The module is a device driver which requires identical
block major numbers and character major numbers. Note
that both the b and c flags must also be set when using
this flag; if they are not set, the u flag is ignored.
The module is a hardware module which can share its
DMA channel(s) with other drivers.

D
F

o
S

The module is a VFS file system module.
The lOA range of this device may overlap that of another
device.
The module is a STREAMS driver and/or STREAMS
module.

order

Specifies a decimal numeric value used to control the order by
which the module's init and start routines are called, and the
order of execsw entries. Higher-numbered values come first. For
most modules, the order is unimportant, and this field should be
O.

bmaj

Specifies the block major number(s) for this module. This field
should contain either a single decimal number, or two numbers
separated by a dash to indicate an inclusive range of values
("multiple majors"). The (first) value should normally be zero
prior to installation with idinstall(lM). For example, to
request four major numbers, this field would be initialized to
"0-3" in the DSP Master file.
If the b flag is set-and the k flag is not set-in the characteristics
field, idinstall will automatically assign block major numbers
for the device. If the b flag and the k flags are both set, the bmaj
field value will be used.
Specifies the character major number(s) for this module. This
field should contain either a single decimal number, or two
numbers separated by a dash to indicate an inclusive range of
values ("multiple majors"). The (first) value should normally be
zero prior to installation with idinstall(lM). For example, to
request four major numbers, this field would be initialized to
"0-3" in the DSP Master file.

cmaj

124

The module is a STREAMS module.
The module may have only one System file entry.

Master (4)

If the c flag is set-and the k flag is not set-in the characteristics
field, idinstall will automatically assign character major
numbers for the device. If the c flag and the k flags are both set,
the cmaj field value will be used.
NOTES

Specifying STREAMS Devices and Modules
STREAMS modules and drivers are treated in a slightly different way from other
drivers, and their configuration reflects this difference. To specify a STREAMS
device driver, its Master file should specify both an s and a c flag in the characteristics field. This indicates that it is a STREAMS driver and that it requires an entry in
the cdevsw table, where STREAMS drivers are normally configured into the system.
A STREAMS module that is not a device driver, such as a line discipline module,
requires both an s and an m flag in the characteristics field of its Master file; it should
not specify a c flag, as a device driver does.
In cases where a module contains both a STREAMS module and a STREAMS
driver, the s, c and m flags should all be specified.
Compatibility Considerations
For compatibility with existing add-on DSP packages, idinstall also accepts the
old (version 0) mdevice file format, which had a single non-comment line that contained the following nine fields:
name Juncs characteristics prefix bmaj cmaj min_unit max_unit dmachan
When presented with a version 0 mdevice file, idinstall converts the file to
version 1 Master file format. During mdevice file conversion:
The Juncs field is converted into Sentry lines
The following characteristics flags are ignored as obsolete: a, i, n, s, G,
H, M, N, R (the f flag in the version 0 mdevice file will still be recognized,
but should not be used in a version 1 Master file)
The min_unit and max_unit fields are ignored as obsolete
The dmachan field is moved to the System file
Because cross-dependencies exist in the version 0 mdevice and sdevice files for
exec modules, idinstall cannot convert these files to version 1 files. They must be
converted manually before using idinstal1.
Note that idinstall also accepts obsolete mfsys files and converts them to version
1 Master file format.
SEE ALSO

idbuild(lM), idcheck(lM), idinstall(lM),
res_major(4), Space.c(4), system(4)

Master(4),

modadmin(lM),

125

menu (4)
NAME

menu - form description file for menu(l) command
DESCRIPTION

menu is a menu and form generator that creates file-driven, full-screen forms and
menus for accepting user input and displaying information. The form or menu to
be displayed is specified in a form description file that allows text, lists, input fields,
contents of files, and output from commands to be displayed.
The form description file consists of a number of keywords, each denoting the start
of a new section of the form description. Each section of the form description
corresponds to a different part of the menu described. For example, there is a keyword .top which specifies that the text that follows will be placed at the top of the
screen. The text in each section of the form description file can be hard-coded in the
form description file, or it may be redirected from a file or command.
110 Redirection
In the form description file, text may be included from another file. This is handled
by specifying a less than «) character in the first column of the form description
file, followed by the name of a file to include. The text included from the file will be
included verbatim; that is, no keywords will be processed, and no I/O redirection
or command substitution will be performed on the input redirected from a file.
Command Substitution
In the form description file, text may be the output from a shell command. This is
handled by enclosing a command to be executed in backquotes. Note that no more
than one command will be parsed per input line of the form description file, and no
command may span more than one line of the form description file. Again, the text
included from the output of the command will be included verbatim; that is, no
keywords will be processed, and no I/O redirection or command substitution will
be performed on the input given by the output of a command.
Comments
The form description file may contain comments, which will be ignored. Comment
lines are specified by placing a pound sign (#) in the first column.
SEE ALSO

menu(l), menu_colors. sh(l)

126

mkdev(4)
NAME

mkdev - file format for the pdimkdev utility
DESCRIPTION
The pdimkdev

utility is executed when the system transitions from single-user to
multi-user mode to create special device file entries for any newly configured PDI
peripheral hardware. The pdimkdev utility allows for provision of special device
file naming conventions by the application.
The naming convention for a PDI peripheral device is described in a mkdev template file. Additional mkdev template files may be provided for new device types
that require a different naming convention than the one already being used.

Template File Overview

Each device type has a corresponding template file that is, by convention, placed in
the directory /etc/scsi/mkdev.d. The template file allows for special device files
to be created in up to four directories. These are the character and block special
directories and the corresponding simple administration directories. The permissions of the special device files may also be specified.
Device Naming Template Syntax

The following tables show the syntax for the mkdev template files. The lines up to
the separator "DATA" are for user messages that may be device specific.
STRING

MEANING

QUERY

If the QUERY string in the template file is a string other than
"-", then the query will be issued to the user under low inode
conditions. The set of device files to be created will be determined based on the response. The only currently known
application for this feature is to determine whether a disk
device is a boot device.

POSTMSG

The POSTMSG string is printed after the naming of a new
device. For SCSI tape devices, this message is "-", which
mkdev ignores. For disk devices, the message instructs the
user to use sysadm partitioning if necessary.

The next line provides the directory names for the block and character devices as
well as the simple administration equivalents for these. On the remaining lines the
first three fields provide the key, minor number and mode. The fourth and fifth
fields provide, respectively, the block and character device files. The sixth and
seventh fields provide the block and character simple administration names, which
are linked to the files in fields four and five, respectively. Below is a key showing
the use and meaning of characters and keywords in the templates that follow.

127

mkdev(4)
KEY

The key field is a single character from the set "_", "M", or
"Y". The meanings are explained below.

Under low inode conditions (less than 200 available in the root
filesystem) these device files will be created if answer to
QUERY is "yes". For disks, this will denote Logical Unit (LU) is
bootable and files must be created for a bootable LU.

Device file is mandatory and is created in low inode conditions.

Special device file is to be created under normal situations
(that is, more than 200 available inodes on the root filesystem).

Minor Number Calculation
The information available to the pdimkdev utility about each device is host adaptor
slot number (C), target controller number (T), Logical Unit number (L), and major
number. A formula, using the information available to the pdimkdev utility, is provided in the template file and is used to generate the minor number. The major and
minor number are used in calls to mknod(2) to create the special device file.
STRING

MEANING

MINOR

: [constant I ciT I L] [+1 xl *] MINOR The minor field is a
string that may contain any of the characters 'C', 'T', or 'L'.
When calculating the minor number, the values for these variables are substituted in the expression given in the string. The
expression for the minor number is evaluated right to left.
(For example, 3+L*16 is 19 when L=l)

Host adaptor slot number.

Target controller SCSI 10.

Logical Unit number.

REFERENCES
pdimkdev(lM)

128

mnttab(4)
NAME

mnttab - mounted file system table
SYNOPSIS

#include
DESCRIPTION

The file /etc/mnttab contains information about devices that have been mounted
by the mount command. The information is in the following structure, defined in
sys/mnttab.h:
struct mnttab
char
~t_special;
char
*mnt_mountp;
char
*mnt_fstype;
char
*mnt_mntopts;
char
~t_time;
};

The fields in the mount table are space-separated and show the block special device,
the mount point, the file system type of the mounted file system, the mount options,
and the time at which the file system was mounted.
NOTES

Do not store information in the mnttab file other than the fields described above;
fields may be added to this file in future releases and are reserved for future use.
SEE ALSO

getmntent(3C), mount (1M), setmnt(lM)

129

Mtune(4)
NAME

Mtune - tunable parameter definitions
SYNOPSIS

Mtune
DESCRIPTION

One of the ID /TP kernel configuration files, an Mtune file contains definitions of
tunable parameters, including default values, for a kernel module type. Systemspecific tunable values are stored in stune. When the Mtune component of a
module's Driver Software Package (DSP) is installed, idinstall(lM) stores the
module's Mtune file information in /etc/conf/mtune.d/module-name, where the
file module-name is the name of the module being installed. Package scripts should
never access /etc/conf/mtune.d files directly; only the idinstall and idtune
commands should be used.
Each tunable parameter is specified on a separate line of the form:

parameter-name default-value minimum-value maximum-value
All fields are positional and must be separated by white space. Blank lines and
lines beginning with '#' or I.' are considered comments and are ignored.
The Mtune file fields are:

parameter-name

A string (maximum of 20 characters) used to construct the
preprocessor #defines that pass the value for this parameter to
the system when the system is built [see Space. c(4)].

default-value

Specifies the default value for this tunable parameter. If the value
is not overridden by the stune(4) file, this value will be used
when the system is built.
Specifies the minimum allowable value for this tunable parameter. If the parameter is set in the stune(4) file, the configuration
tools will check that the value specified in the stune file is equal
to or greater than this value.

minimum-value

maximum-value

Specifies the maximum allowable value for this tunable parameter. If the parameter is set in the stune(4) file, the configuration
tools will check that the value specified in the stune file is equal
to or less than this value.
For detailed information on Mtune parameters, refer to the advanced features sections on tunable parameters in your system administration documentation.

NOTES

Compatibility Considerations

For compatibility with existing add-on DSP packages, idbuild(lM) maintains a flat
file, /etc/conf/cf .d/mtune, which contains all of the tunable parameters. Packages may read this file to find existing values, and may add new tunables to the file.
This mechanism is discouraged, however; new packages should use the idinstall
and idtune commands.

130

Mtune(4)
SEE ALSO

idbuild(lM), idinstall(lM), idtune(lM), Space. c(4), stune(4)

131

netconfig ( 4)
NAME

netconfig - network configuration database
SYNOPSIS

#include
DESCRIPTION

The network configuration database, /etc/netconfig, is a system file used to store
information about networks connected to the system and available for use. The
netconfig database and the routines that access it [see getnetconfig(3N)] are
part of the UNIX System V Network Selection component. The Network Selection
component also includes the environment variable NETPATH and a group of routines
that access the netconfig database using NETPATH components as links to the
netconfig entries. NETPATH is described in sh(l); the NETPATH access routines are
discussed in getnetpath(3N).
netconfig contains an entry for each network available on the system. Entries are
separated by newlines. Fields are separated by whitespace and occur in the order
in which they are described below. Whitespace can be embedded as "\blank" or
"\tab." Backslashes may be embedded as "\ \". Each field corresponds to an element in the struct netconfig structure. struct netconfig and the identifiers
described on this manual page are defined in lusr I include/netconfig . h.
network ID
A string used to uniquely identify a network. network ID consists of nonnull characters, and has a length of at least 1. No maximum length is
specified. This namespace is locally significant and the local system
administrator is the naming authority. All network IDs on a system must be
unique.
semantics
The semantics field is a string identifying the "semantics" of the network,
that is, the set of services it supports, by identifying the service interface it
provides. The semantics field is mandatory. The following semantics are
recognized.
tpi_clts
Transport Provider Interface, connectionless
tpi_cots
Transport Provider Interface, connection oriented
tpi_cots_ord Transport Provider Interface, connection oriented, supports
orderly release.
tpi_raw
Transport Provider Interface, raw
flag
The flag field records certain two-valued ("true" and "false") attributes of
networks. flag is a string composed of a combination of characters, each of
which indicates the value of the corresponding attribute. If the character is
present, the attribute is "true." If the character is absent, the attribute is
"false." "-" indicates that none of the attributes is present. Two characters
are currently recognized:
v
Visible ("default") network. Used when the environment variable
NETPATH is unset.

132

netconfig ( 4 )
b

Enable RPC broadcast.

protocol family
The protocol family and protocol name fields are provided for protocol-specific
applications.
The protocol family field contains a string that identifies a protocol family.
The protocol family identifier follows the same rules as those for network IDs,
that is, the string consists of non-null characters; it has a length of at least 1;
and there is no maximum length specified. A" -" in the protocol family field
indicates that no protocol family identifier applies, that is, the network is
experimental. The following are examples:
loopback
inet
implink
pup
chaos
ns
nbs
ecma
datakit
ccitt
sna
decnet
dli
lat
hylink
appletalk
nit
ieee802
osi
x25

osinet
gosip

Loopback (local to host).
Internetwork: UDP, TCP, and so on
ARPANET imp addresses
PUP protocols: for example, BSP
MIT CHAOS protocols
XEROX NS protocols
NBS protocols
European Computer Manufacturers Association
DATAKIT protocols
CCITT protocols, X.2S, and so on
IBMSNA
DECNET
Direct data link interface
LAT
NSC Hyperchannel
Apple Talk
Network Interface Tap
IEEE 802.2; also ISO 8802
Umbrella for all families used by OSI (for example,
protosw lookup)
CCITT X.2S in particular
API = 47, IDI = 4
U.S. Government OSI

protocol name
The protocol name field contains a string that identifies a protocol. The protocol name identifier follows the same rules as those for network IDs, that is, the
string consists of non-NULL characters; it has a length of at least 1; and there
is no maximum length specified. The following protocol names are recognized. A" -" indicates that none of the names listed applies.
tcp
Transmission Control Protocol
udp
icmp

User Datagram Protocol
Internet Control Message Protocol

network device
The network device is the full pathname of the device used to connect to the
transport provider. Typically, this device will be in the Idev directory. The

network device must be specified.

133

netconfig ( 4 )
directory lookup libraries
The directory lookup libraries support a "directory service" (a name-toaddress mapping service) for the network. This service is implemented by
the UNIX System V Name-to-Address Mapping feature. If a network is not
provided with such a library, the netdir feature will not work. A" -" in this
field indicates the absence of any lookup libraries, in which case name-toaddress mapping for the network is non-functional. The directory lookup
library field consists of a comma-separated list of full pathnames to dynamically linked libraries. Commas may be embedded as "\, "; backslashs as
"\ \".
Lines in /etc/netconfig that begin with a sharp sign (#) in column 1 are treated as
comments.
The struct netconfig structure includes the following members corresponding
to the fields in in the netconfig database entries:
char * nc_netid

Network rD, including NULL terminator

unsigned long nc_semantics

Semantics

unsigned long nc_flag

Flags

char

nc-protofmly

Protocol family

char * nc-proto

Protocol name

char * nc_device
unsigned long nc_nlookups

Full pathname of the network device

char ** nc_lookups

Full pathnames of the directory lookup
libraries themselves

unsigned long nc_unused[9]

Reserved for future expansion (not advertised
to user level)

Number of directory lookup libraries

The nc_semantics field takes the following values, corresponding to the semantics
identified above:
NC_TPI_CLTS
NC_TPI_COTS
NC_TPI_COTS_ORD
NC_TPI_RAW

The nc_flag field is a bitfield. The following bit, corresponding to the attribute
identified above, is currently recognized. NC_NOFLAG indicates the absence of any
attributes.
NC_VISIBLE
FILES

/etc/netconfig
/usr/include/netconfig.h
SEE ALSO

getnetconfig(3N), getnetpath(3N), icmp(7), ip(7), netconfig(4),
netdir_getbynameO [see netdir (3N) 1

134

netdrivers (4 )
NAME

netdri vers - data file for networking boards to protocols mappings
SYNOPSIS

/etc/confnet.d/netdrivers
DESCRIPTION

The netdrivers file contains a list of hardware devices installed on the system and
the protocols mapped to each board. The format of the file is:

where is the name of the device in /dev and is a string matching
the directory name in / etc / confnet . d where the conf igure script for the protocol can be found. Multiple lines will exist for any board that is being used for multiple protocols. Lines starting with "#" will be ignored.
Manipulation of the netdrivers file should be via the net info command.
Files

/etc/confnet.d/netdrivers
REFERENCES

generic configure(lM),INET-specific configure(lM), protocol-specific
configure(lM), interface(4), netdrivers(4), netinfo(lM)

135

netmasks ( 4 )
NAME

netmasks - network mask data base
DESCRIPTION

The netmasks file contains network masks used to implement IP standard subnetting. For each network that is subnetted, a single line should exist in this file with
the network number, any number of SPACE or TAB characters, and the network
mask to use on that network. Network numbers and masks may be specified in the
conventional IP '.' notation (like IP host addresses, but with zeroes for the host
part). For example,
128.32.0.0 255.255.255.0

can be used to specify that the Class B network 128.32.0.0 should have eight bits of
subnet field and eight bits of host field, in addition to the standard sixteen bits in
the network field.
SEE ALSO

ifconfig(lM)

136

netrc(4)
NAME

netrc - file for ftp remote login data
DESCRIPTION

The . netrc file contains data for logging in to a remote host over the network for
file transfers by ftp(l). This file resides in the user's home directory on the
machine initiating the file transfer. Its permissions should be set to disallow read
access by group and others [see clunod(l)].
The following tokens are recognized; they may be separated by SPACE, TAB, or NEWLINE characters:
machine name

Identify a remote machine name. The auto-login process searches the
. netrc file for a machine token that matches the remote machine specified
on the ftp command line or as an open command argument. Once a match
is made, the subsequent . netrc tokens are processed, stopping when the
EOF is reached or another machine token is encountered.
login name

Identify a user on the remote machine. If this token is present, the autologin process will initiate a login using the specified name.
password string

Supply a password. If this token is present, the auto-login process will supply the specified string if the remote server requires a password as part of
the login process. Note: if this token is present in the . netrc file, ftp will
abort the auto-login process if the .netrc is readable by anyone besides the
user.
account string

Supply an additional account password. If this token is present, the autologin process will supply the specified string if the remote server requires an
additional account password, or the auto-login process will initiate an ACCT
command if it does not.
macdef name

Define a macro. This token functions as the ftp macdef command functions. A macro is defined with the specified name; its contents begin with
the next .netrc line and continue until a NULL line (consecutive NEWLINE
characters) is encountered. If a macro named init is defined, it is automatically executed as the last step in the auto-login process.
EXAMPLE

A . netrc file containing the following line:
machine ray login demo password mypassword

allows an autologin to the machine ray using the login name demo with password
mypassword.
FILES

- / .netrc

137

netrc(4)
SEE ALSO

chmod(l), ftp(l), ftpd(lM)

138

networks ( 4 )
NAME

networks - network name data base
DESCRIPTION

The networks 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 SPACE 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. This file is normally created from the official network data base maintained at the Network Information Control Center (NrC),
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 (for example,
193.4.56.0) using the inet_network routine from the Internet address manipulation library, inet(7). Network names may contain any printable character other
than a field delimiter, NEWLINE, or comment character.
The networks file allows the usage of symbolic names instead of an IP address in
the output of networking commands (for example, netstat -r).
FILES

/etc/networks
SEE ALSO

getnetent(3N), inet(7), netstat(lM)
NOTES

A name server should be used instead of a static file. A binary indexed file format
should be available for fast access.

139

Node(4)
NAME

Node - device node definitions for a device driver
SYNOPSIS
Node
DESCRIPTION

One of the kernel configuration files, a Node file contains definitions used by the
idmknod(lM) command to create the device nodes (block and character special
files) associated with a device driver module. When the Node component of a
module's Driver Software Package (DSP) is installed, idinstall(lM) stores the
driver's Node me information in /ete/eonf/node.d/module-name, where modulename is the name of the driver being installed. Package scripts should never access
/ete/eonf/node.d files directly; the idinstall command should be used instead.
Each device node for the driver is specified on a separate line of the form:

module-name node-name type minor user group permissions
All fields are positional and must be separated by white space. The first four fields
are required; the last three fields are optional. Blank lines and lines beginning with
'#' or '*' are considered comments and are ignored.
The node file fields are:
module-name
Identifies the device to which this node applies. The name must
match the name specified for the device in the module-name field
of the Master(4) me. The device must be defined as a block
and/ or character device (Master file characteristics flag set to b or
e). When the device node is created, the Master file bmaj or cmaj
field values will be used as the major number for the created
node.
node-name
Specifies the name of the Node file to be created, relative to /dev.
If this field specifies a pathname containing subdirectories, idmknod will automatically create these subdirectories.
Identifies the type of node to be created. The character b inditype
cates that the node is a block device; the character e indicates
character device. The value for this field must match one of the
flags specified for the device in the mdeviee me characteristics
field.
In cases where a device has multiple major numbers, the Node file
type field must provide additional information used to identify
which device nodes belong to which major. To do this, you
specify a value of the form:

type:offset
where type is the type of node (b,or e) and offset gives the offset to
this particular device within the range of major numbers specified
for this device type in the Master me. For example, the value
"e: 2" refers to a character major offset 2, which, given a major
device type specification of "15-18", would translate to a character major number of 17.

140

Node (4)
minor

Specifies the minor device number. This field can be coded in one
of three ways:
If this field specifies a (decimal) numeric value, the value
is used as the minor device number for the created node.
If this field specifies a non-numeric value, the value is
assumed to be a request for a clone node, and the minor
number will be set to the major number of the device
whose module-name is the value of the field.
If this field specifies a non-numeric value and the Node file
type field specifies an offset value, the offset will be
applied to the minor number instead of the major number
when the node is created.

user

This field is optional. If used, it specifies the user ID of the user
that will own the node to be created. The user ID must be
specified as decimal integer value.

group

This field is optional. If used, it specifies the group ID of the
group that will own the node to be created. The group ID must
be specified as decimal integer value.

permissions

This field is optional. If used, it specifies, in octal form, tye permissions for the node to be created, as given to the chmod(l) command (example: 0777).

USAGE

Examples
The following sample Node file entries are provided as coding examples:
iasy ttyOO c 0
Makes Idev/ttyOO for character device asy using minor device O.
clone net/nau/clone c nau
Makes ldev/net/nau/clone for character device clone. The minor
device number is set to the major device number of device nau.
clone imx586_l c:l imx586
Makes Idev/imx:586_l for character device clone. The minor device
number is set to the major device number of device imx586 plus 1.
SEE ALSO

idinstall(lM), idmknod(lM)

141

OllcValues (4)
NAME

OlIcValues - Input Context attribute names and value pairs
SYNOPSIS

#include
typedef OlICValues *OlICV~~q~SList;
typedef void (*OlImProc)();
typedef void *OlImValue;
DESCRIPTION

OlIcValuesList contains a list qf Input Context attribute names and value pairs.
It is used for getting and setting various Input Context attributes.
The OlIcValues structure includeli/ the follOWing members:
char *attr_name;
void *attr_value;
The OlImCallback structure incllJ.qes the following members:
01 ImValues client_data;
OlImProc
callbac~;
The supported Input Context attributes are shown in the table below. The end of
the list is indicated by a NULL vaille in the attribute name.
InPlJ.t Context Attributes
Attribute Value Type
Attribute N,nne
OlNclientwinCiow
Window*
OlNClientAre/il,
XRectangle*
OlImStyle*
OlNinputSty+\!!
OlNfocusWindow
Window*
XRectangle*
OlNPreedit:~efL
OlNstatusArea
XRectangle*
OlNspotLocat;ioQ
XPoint*
OlNresource~~~se
xrmDatabase*
OlNPreeditAttributes OlIcWindowAttr*
OlNstatusAttr~butes
01 IcWindowAttr*

142

OllcValues (4)
Attributes for Preedit artd Status Windows
Attribute Value Type
Attribute Name
Colormap
OlNcolormap
Colormap
OlNstdColormap
Pixel
OlNbackground
OlNforeground
Pixel
OlNbackgroundPixmap Pixmap
OlNfontset
OlFontList
OlNlineSpacing
int
OlNcursor
Cursor
OlImcallback
Callbacks
OlNclientWindow
specifies the client window in which the Input Method may display data
or create subwindows. Dynamic changes of client window are not supported; this argument must be set at the Input Context creation time and
cannot be changed later. It is a static attribute required by OlCreatelc.
The value is a pointer to a window.
OlNClientArea
specifies the client area in which the Input Method may display data or
create subwindows. The Input Method will establish its own pre-edit and
status geometry accordingly. When this attribute is left unspecified, The
Input Method will default usable client area to actual client window
geometry. This is a dynamic attribute that can be modified via calls to
OlSetlcYalues. The value is a pointer to an XRectangle.
OlNinputStyle
specifies the input style to be used. The value of this argument must be
one of the supported styles returned by the OlGetlmValues function, otherwise OlCreatlc will fail. If this attribute is unspecified, the Input
Method uses an implementation defined default style. MooLIT does not
support Dynamic changes of Input Method style. This argument must be
set at the Input Context creation time and cannot be changed later. The
value is a pointer to OlImStyle.
OlNfocusWindow
specifies to the Input Method the window XID of the focus window. The
input method may affect that window: select events on it, send events to it,
modify its properties, and grab the keyboard within that window.
When this attribute is unspecified, the Input Method will default from the
focus window to the client window. Explicitly setting this attribute from a
non NULL value to NULL, forces the Input Method to clear any displayed
data in the status area corresponding to the focus window. This is a
dynamic attribute that can be modified via calls to OlSetlcValues. The
value is a pointer to a window.

143

OllcValues (4)
OlNpreeditArea
the area where pre-edit data should be displayed. The value of this argument is a pointer to XRectangle, relative to the client window. The Input
Method may create a preedit window in this area, using the specified
geometry, as a child of a client window.
When OlNpreeditArea is unspecified, the Input Method will default from
the preedit area to an implementation defined area. This area is contained
within the client area.
If you specify this attribute for root or XimPreEditCallbacks Input
Method, it is ignored.
If you specify this attribute for an XimPreEditArea Input Method, the
width and height determine the size of the area within the "over-the-spot"
window now available for pre-edit.

OlNstatusArea
specifies to the Input Method the usable area to display Input Context
state information. The value of this argument is a pointer to XRectangle,
relative to the client window.
The Input Method mayor not create a status window in this area, using
the specified geometry, as a child of the client window.
When OlNstatusArea is unspecified, the Input Method defaults to the
status area defined by the Input Method implementation. The status area
is contained within the client area. This is a dynamic attribute that can be
modified via calls to OlSetlcValues.
Note that if a client leaves all areas unspecified, the Input Method may not
be able to run properly. Some implementations will generate errors if
none of the focus window, focus area, client area, preedit area, and status
area are defined. At best, it may behave randomly using any area in the
client window, possibly clearing the whole window or erasing any region.
OlNspotLocation
specifies the coordinates of the "spot" (the current cursor position in the
text insertion window), to be used by the "over-the-spot" or "on-the-spot"
Input Methods. The type is a pointer to Xpoint. The x coordinate
specifies the position where the next character would be inserted. The y
coordinate is the position of the baseline used by current text line in the
focus window.
SEE ALSO

Olcreatelc(30lit), OlDestroylc(30lit), OlGetIcValues(30lit), OlImOfIc(30Iit),
OlImValues(4), OlSetICFocus(30Iit), OlSetlcValues(30Iit),
OlunsetlcFocus(30Iit),OlResetlc(30lit)

144

OllmValues (4)
NAME

OlImValues - a list of 1M attributes
SYNOPSIS

#include
DESCRIPTION

OlImValues contains a list of Input Method values or attributes returned by the
OlImStyles structure. The OlImStyles structure includes the following members:
unsigned short count_styles; /* the number of input styles
supported */ OlImStyle *supported_styles;
count_styles is also the size of the array in the supported_styles field. Each
element in the array represents a different input style supported by this Input
Method. It is a bitmask in which the Input Method indicates its requirements,
should this style be selected. These requirements fall into the following categories:
OlImPreEditArea

require the client to provide some area values for
preediting. Refer to the Input Context attribute
OlNpreedi tArea.

OlIMPreditPosition

require the client to provide positional values. Refer to
Input Context attributes OlNspotLocation and OlNfocusWindow.

OlImPreEditCallbacks require the client to define the set of preedit callbacks.
Refer to Input Context attributes OlNPreEditStartCallbac~
OlNPreEditDoneCallbac~
OlNPreEditDrawCallback, and OlNPreEdi tCaretCallback.
OlImNeedNothing

function without any preedit values.

OlImStatusArea

require the client to provide some area values for status
feedback. Refer to OlNArea and OlNAreaNeeded.

OlImStatusCallbacks

require the client to define the set of status callbacks.

SEE ALSO

OlCreateIc(30Iit), OlDestroyIc(30Iit), OlGetIcValues(30lit), OlIcValues(4),
OlImOfIc(30lit), OlSetIcFocus(30Iit), OlSetIcValues(30lit),
OlUnsetICFocus(30lit), OlResetIc(30lit)

145

ott(4)
NAME

.ott -FACE object architecture information
DESCRIPTION

The FACE object architecture stores information about object-types in an ASCII file
named .ott (object type table) that is contained in each directory. This file
describes all of the objects in that directory. Each line of the .ott file contains
information about one object in pipe-separated fields. The fields are (in order):
name
the name of the actual UNIX System file.
dname
the name that should be displayed to the user, or a dot if it is
the same as the name of the file.

description

the description of the object, or a dot if the description is the
default (the same as object-type).

object-type
flags
mod time

the FACE internal object type name.

object information

object specific flags.
the time that FACE last modified the object. The time is given
as number of seconds since 1/1/1970, and is in hexadecimal
notation.
an optional field, contains a set of semi-colon separated
name=value fields that can be used by FACE to store any other
information necessary to describe this object.

FILES

.ott is created in any directory opened by FACE.

146

passwd(4)
NAME

passwd - password file
SYNOPSIS

/ete/passwd
DESCRIPTION

/ete/passwd is an ASCII file that contains basic information about each user's
account. This file contains a one-line entry, for each authorized user, of the form:

login_name: password: uid : gid : comment: home_dir : login _shell
where:
login_name

password

uid
gid
comment

is the name specified by the user when logging in. This field contains no uppercase characters, should not be more than eight characters long, and should begin with a non-numeric character (that
is, any alphabetic or special character except colon).
contains the character x. This field remains only for compatibility
reasons. Password information is contained in the file
fete/shadow [see shadow(4)].
is the user's numerical ill for the system, which should be unique.

is the numerical ID of the group to which the user belongs.
is any information you think might be useful to a user of this file
which is not included elsewhere in the file.
is the pathname of the directory in which the user is initially posihome dir
tioned upon logging in.
is the user's initial shell program. If this field is empty, the default
login_shell
shell is /usr /bin/ sh.
Fields are separated by a colon; entries, by a new-line. Comment lines (lines preceded by the # (pound) character) are not allowed in the /ete/passwd file.
/ete/passwd has general read permission on all systems, and can be used by
routines that map numerical user IDs to names.

FILES

/ete/passwd
fete/shadow
/usr/lib/loeale/locale/LC_MESSAGES/uxeore.abi
language-specific message file [See LANG on environ(5).]
SEE ALSO

getpwent(3C), group(4), login(l), passwd(l), putpwent(3C),
shadow(4), unistd(4), useradd(lM), userdel(lM), usermod(lM)

pwconv(lM),

147

pathalias ( 4 )
NAME

pathalias - alias file for FACE
DESCRIPTION

The pathalias files contain lines of the form alias=path where path can be one or
more colon-separated directories. Whenever a FACE user references a path not
beginning with a "I," this file is checked. If the first component of the pathname
matches the left-hand side of the equals sign, the right-hand side is searched much
like $PATH variable in the UNIX System. This allows Users to reference the folder
$HOME/FILECABlNET by typing filecabinet.
There is a system-wide pathalias file called $VMSYS/pathalias, and each user
can also have local alias file called $HOME/pref Ipathalias. Settings in the user
alias file override settings in the system-wide file. The system-wide file is shipped
with several standard FACE aliases, such as filecabinet, wastebasket, preferences, other_users, and so on.
NOTES

Unlike command keywords, partial matching of a path alias is not permitted, however, path aliases are case insensitive. The name of an alias should be alphabetic,
and in no case can it contain special characters like" I," "\," or "=." There is no
particular limit on the number of aliases allowed. Alias files are read once, at login,
and are held in core until logout. Thus, if an alias file is modified during a session,
the change will not take effect until the next session.
FILES

$HOME/pref/pathalias
$VMSYS/pathalias

148

pkginfo(4)
NAME

pkginfo - package characteristics file
DESCRIPTION
pkginfo is an ASCII file that describes the characteristics of the package along with

information that helps control the flow of installation. It is created by the software
packag developer.
Each entry in the pkginfo file is a line that establishes the value of a parameter in
the following form:
PARAM="value"

There is no required order in which the parameters must be specified within the
file. Each parameter is described below. Only fields marked with an asterisk are
mandatory.
PKG is the parameter to which you assign an abbreviation for the
PKG*
name of the package being installed. The abbreviation must be a
short string (no more than nine characters long) and it must conform to file naming rules. All characters in the abbreviation must
be alphanumeric and the first may not be numeric. install, new,
and all are reserved abbreviations.
NAME *
ARCH

VERSION*

CATEGORY*

Text that specifies the package name (maximum length of 256
ASCII characters).
A comma-separated list of alphanumeric tokens that indicate the
architecture (for example, ARCH=m68k, i386) associated with the
package. The pkgmk tool may be used to create or modify this
value when actually building the package. The maximum length
of a token is 16 characters and it cannot include a comma. ARCH is
not a mandatory field. Therefore, if it is not specified or if it is
specified as NULL, it is ignored.
Text that specifies the current version associated with the
software package. The maximum length is 256 ASCII characters
and the first character cannot be a left parenthesis. The pkgmk
tool may be used to create or modify this value when actually
building the package.
A comma-separated list of categories under which a package may
be displayed. There are six categories: "application", "graphics",
"system", "utilities", "set", and "patch." If you choose, you can
also assign a package to one or more categories that you define.
Categories are case-insensitive and may contain only
alphanumerics. Each category is limited in length to 16 characters.
For a Set Installation Package (SIP), this field must have the value
"set". A SIP is a special purpose package that controls the installation of a set of packages.

149

pkginfo(4)
DESC

Text that describes the package (maximum length of 256 ASCII
characters).

VENDOR

Used to identify the vendor that holds the software copyright
(maximum length of 256 ASCII characters).

HOTLINE

Phone number and/ or mailing address where further information may be received or bugs may be reported (maximum length
of 256 ASCII characters).
An electronic address where further information is available or
bugs may be reported (maximum length of 256 ASCII characters).

EMAIL
VSTOCK
CLASSES

I STATES
RSTATES
BASEDIR

ULIMIT

ORDER

MAXINST

PSTAMP

150

The vendor stock number, if any, that identifies this product
(maximum length of 256 ASCII characters).
A space-separated list of classes defined for a package. The order
of the list determines the order in which the classes are installed.
Classes listed first will be installed first (on a medium-by-medium
basis). This parameter may be modified by the request script. In
this way, the request script may be used to select which classes in
the package get installed on the system.
A list of allowable run states for package installation (for example, "S s 1").
A list of allowable run states for package removal (for example,
"S s 1").
The pathname to a default directory where "relocatable" files
may be installed. If BASEDIR is not specified and basedir in the
admin(4) file (lvarisadm/install/admin/default) is set to
default, then BASEDIR is set to I by default. An administrator
can override the value of BASEDIR by setting basedir in the admin
file.
If set, this parameter is passed as an argument to the ulimit
command, which establishes the maximum size of a file during
installation.
A list of classes defining the order in which they should be put on
the medium. Used by pkgmk in creating the package. Classes not
defined in this field are placed on the medium using the standard
ordering procedures.
The maximum number of package instances that should be
allowed on a machine at the same time. By default, only one
instance of a package is allowed. This parameter must be set in
order to have multiple instances of a package.
Production stamp used to mark the pkgmap file on the output
volumes. Provides a means for distinguishing between production copies of a version if more than one is in use at a time. If
PSTAMP is not defined, the default is used. The default consists of
the UNIX system machine name followed by the string
"YYMMDDHHmm" (year, month, date, hour, minutes).

pkginfo(4)
INTONLY

Indicates that the package should be installed interactively only
when set to any non-NULL value.

PREDEPEND

Used to maintain compatibility with dependency checking on
packages delivered earlier than System V Release 4. Pre-Release 4
dependency checks were based on whether or not the name file
for the required package existed in the /usr/options directory.
This directory is not maintained for Release 4 and later packages
because the depend file is used for checking dependencies. However, entries can be created in this directory to maintain compatibility. This is done automatically by pkgmk. This field is to be
assigned the package instance name of the package.
A serial number, if any, that uniquely identifies this copy of the
package (maximum length of 256 ASCII characters).

SERIALNUM
EXAMPLES

Here is a sample pkginfo file:
PKG="oam"
NAME="OAM Installation Utilities"
VERSION="3"
VENDOR= "AT&T"

HOTLINE="1-800-ATT-BUGS"
EMAIL="attunix!olsen"

VSTOCK="0122c3f5566"
CATEGORY="system.essential"
ISTATES="S 2"
RSTATES="S 2"
NOTES

Developers may define their own installation parameters by adding a definition to
this file. A developer-defined parameter should begin with a capital letter.
SEE ALSO

admin(4), pkgmk(l)

151

pkgmap(4)
NAME

pkgmap - package contents description file
DESCRIPTION

pkgmap is an ASCII file that provides a complete listing of the package contents. It is
automatically generated by pkgmk(l) using the information in the prototype file.

Each entry in pkgmap describes a single "deliverable object file." A deliverable
object file includes shell scripts, executable objects, data files, directories, and so on.
The entry consists of several fields of information, each field separated by a space.
The fields are described below and must appear in the order shown.
part
A field designating the part number in which the object resides. A part
is a collection of files, and is the atomic unit by which a package is processed. A developer can choose the criteria for grouping files into a part
(for example, based on class). If no value is defined in this field, part 1 is
assumed.
Jtype
A one-character field that indicates the file type. Valid values are:
a standard executable or data file
a file to be edited upon installation or removal
volatile file (one whose contents are expected to change)
directory
an exclusive directory (See NOTES)
linked file
p
named pipe
c character special device
b block special device
i
installation script or information file
a symbolic link
Once a file has the file type attribute v, it will always
be volatile. For example, if a file being installed already exists and has
the file type attribute v, then even if the version of the file being installed
is not specified as volatile, the file type attribute will remain volatile.
f

e
v
d
x
1

class

pathname

The installation class to which the file belongs. This name must contain
only alphanumeric characters and be no longer than 12 characters. It is
not specified if the ftype is i (information file).
The pathname where the object will reside on the target machine, such
as /uar /bin/mail. Relative pathnames (those that do not begin with a
slash) indicate that the file is relocatable.
For linked files (ftype is either 1 or a), pathname must be in the form of
path1=path2, with pathl specifying the destination of the link and path2
specifying the source of the link.
For symbolically linked files, when path2 is a relative pathname starting
with • / or •• /, path2 is not considered relocatable. For example, if you
enter a line such as
a /foo/bar/etc/mount= •• /uar/abin/mount

pathl

(lfoo/bar/etc/mount)
•. /uar/abin/mount.

152

will

symbolic

link

pkgmap(4)
pathname may contain variables which support relocation of the file. A
$parameter may be embedded in the pathname structure. $BASEDIR can

major
minor
mode

owner

group

size
cksum
modtime

be used to identify the parent directories of the path hierarchy, making
the entire package easily relocatable. Default values for parameter and
BASEDIR must be supplied in the pkginfo ille and may be overridden at
installation.
Special characters, such as an equal sign (=), are included in pathnames
by surrounding the entire pathname in single quotes (as in, for example,
, lusr/libr=').
The major device number. The field is only specified for block or character special devices.
The minor device number. The field is only specified for block or character special devices.
The octal mode of the file (for example, 0664). A question mark (?) indicates that the mode will be left unchanged, implying that the file already
exists on the target machine. This field is not used for linked illes, packaging information illes or non-installable files.
The owner of the ille (for example, bin or root). The field is limited to
14 characters in length. A question mark (?) indicates that the owner
will be left unchanged, implying that the ille already exists on the target
machine. This field is not used for linked illes or non-installable files. It
is used optionally with a package information ille. If used, it indicates
with what owner an installation script will be executed.
Can be a variable specification in the form of $ [A-Z]. Will be resolved
at installation time (see NOTES).
The group to which the ille belongs (for example, "bin" or "sys"). The
field is limited to 14 characters in length. A question mark (?) indicates
that the group will be left unchanged, implying that the file already
exists on the target machine. This field is not used for linked files or
non-installable files. It is used optionally with a package information
file. If used, it indicates with what group an installation script will be
executed.
Can be a variable assignment in the form of $ [A-Z]. Will be resolved at
installation time (see NOTES).
The actual size of the file in bytes. This field is not specified for named
pipes, special devices, directories or linked illes.
The checksum of the file contents. This field is not specified for named
pipes, special devices, directories or linked files.
The time of last modification, as reported by the stat(2) function call.
This field is not specified for named pipes, special devices, directories or
linkedilles.

153

pkgmap(4)
Each pkgmap must have one line that provides information about the number and
maximum size (in 512-byte blocks) of parts that make up the package. This line is
in the following format:

: number_ofyarts maximum yart_size
Lines that begin with "#" are comment lines and are ignored.
When files are saved during installation before they are overwritten, they are normally just copied to a temporary pathname. However, for files whose mode
includes execute permission (but which are not editable), the existing version is
linked to a temporary pathname and the original file is removed. This allows
processes which are executing during installation to be overwritten.
EXAMPLES

The following is an example of a pkgmap file.
:2 500
1 i pkginfo 237 1179 541296672
1 b class1 /dev/diskette 17 134 0644 root other
1 c class1 /dev/rdiskette 17 134 0644 root other
1 d none bin 0755 root bin
1 f none bin/INSTALL 0755 root bin 11103 17954 541295535
1 f none bin/REMOVE 0755 root bin 3214 50237 541295541
1 1 none bin/UNINSTALL=bin/REMOVE
1 f none bin/cmda 0755 root bin 3580 60325 541295567
1 f none bin/cmdb 0755 root bin 49107 51255 541438368
1 f class1 bin/cmdc 0755 root bin 45599 26048 541295599
1 f class1 bin/cmdd 0755 root bin 4648 8473 541461238
1 f none bin/cmde 0755 root bin 40501 1264 541295622
1 f class2 bin/cmdf 0755 root bin 2345 35889 541295574
1 f none bin/cmdg 0755 root bin 41185 47653 541461242
2 d class2 data 0755 root bin
2 p class1 data/apipe 0755 root other
2 d none log 0755 root bin 1 NULL NULL
2 v none log/logfile 0755 root bin 41815 47563 541461333
2 d none save 0755 root bin
2 d none spool 0755 root bin
2 d none tmp 0755 root bin
NOTES

The pkgmap file may contain only one entry per unique pathname.

An exclusive directory type (file) type x) specifies directories that are constrained to
contain only files that appear in the installation software database
(lvar/sadm/install/contents). If there are other files in the directory, they will
be removed by pkgchk -fx as described on the pkgchk(lM) manual page.
Variable specifications for the owner and group fields are defined in the pkginfo file.
For example, owner could be $OWNER in the pkgmap file; if OWNER is defined as root
in the pkginfo file, $OWNER will get the value root when the file is installed.

154

pnch(4)
NAME

pnch - file format for card images
DESCRIPTION

The PNCH format is a convenient representation for files consisting of card images
in an arbitrary code.
A PNCH file is a simple concatenation of card records. A card record consists of a
single control byte followed by a variable number of data bytes. The control byte
specifies the number (which must lie in the range 0-80) of data bytes that follow.
The data bytes are 8-bit codes that constitute the card image. If there are fewer than
80 data bytes, it is understood that the remainder of the card image consists of trailingblanks.

155

priv(4)
NAME

pri v - privilege data file
DESCRIPTION

A privilege data file entry has the following format:

dev: fid : valid: %fixed privs : pathname
Each field in the entry is separated by a colon (:) character. The dev (see stat(2»
and fid are, respectively, the ID of the device containing a directory entry for this
file, and a unique.file identification number for this file. These are stored as decimal
strings. The valid field is the last file status change time (see stat(2» contained in
the inode of the named file and stored as a decimal string. The fixed privileges field
begins with a (%) delimiter and contains character strings which have comma (,)
separated privilege names for each field. The pathname is the absolute path name of
the privileged file.
The privilege data file is /etc/security/tcb/privs.
SEE ALSO

filepriv(lM), initprivs(lM), intro(2), stat(2)

156

PrivTable (4)
NAME

PrivTable - privilege table
DESCRIPTION

PrivTable is a list of permissions that can be granted users through the desktop
User_Setup client. Each entry includes a list of commands a user with permission
will be able to execute with privilege, along with specific granted privileges. These
privileges are granted the user using TFM (Trusted Facilities Management).
The privilege table contains lines of the format:
[CatalogFile: Index: ]CheckboxStringEntryListHelpFile
CheckboxString
label to use for the checkbox in User_Setup. If the checkbox is checked,
EntryList will be registered with TFM
[CatalogFile:Index: ]
translate CheckboxString. CatalogFile is the file of locale specific translations.
index is the line number of the translation.
EntryList
comma seperated list of entries. This takes the form

entrynamel :fullpath :privl :priv2: . .. , entryname2 ...
HelpFile
help file to use with this privilege checkbox. This may be a full path name
or a locale-specific file in /usr/X/lib/locale/locale/help/LoginMgr.
Files

/ etc / securi ty /tfm/users / user
/usr/X/desktop/LoginMgr/PrivTable
SEE ALSO

dtprivilege(lM), make-owner(lM), tfadmin(lM)

157

proc(4)
NAME

proc - process file system
DESCRIPTION

/proc is a file system that provides access to the image of each active process in the
system. The name of each entry in the /proc directory is a decimal number
corresponding to the process ID. The owner of each "file" is determined by. the
process's user-ID.
Standard system call interfaces are used to access /proc files: open, close, read,
write, and ioctl. An open for reading and writing enables process control; a
read-only open allows inspection but not control. As with ordinary files, more than
one process can open the same /proc file at the same time. Exclusive open is provided to allow controlling processes to avoid collisions: an open for writing that
specifies O_EXCL fails if the file is already open for writing; if such an exclusive open
succeeds, subsequent attempts to open the file for writing, with or without the
O_EXCL flag, fail until the exclusively-opened file descriptor is closed. (Exception: a
super-user open that does not specify O_EXCL succeeds even if the file is exclusively
opened.) There can be any number of read-only opens, even when an exclusive
write open is in effect on the file.
Data may be transferred from or to any locations in the traced process's address
space by applying Iseek to position the file at the virtual address of interest followed by read or write. The PIOCMAP operation can be applied to determine the
accessible areas (mappings) of the address space. A contiguous area of the address
space may appear as multiple mappings due to varying read/write/execute permissions. I/O transfers may span contiguous mappings. An I/O request extending
into an unmapped area is truncated at the boundary.
Information and control operations are provided through ioctl. These have the
form:
#include
#include
#include
#include
#include
void *p;
retval = ioctl(fildes, code, p);
The argument p is a generic pointer whose type depends on the specific ioctl code.
Where not specifically mentioned below, its value should be zero. sys/procfs.h
contains definitions of ioctl codes and data structures used by the operations.
Certain operations can be performed only if the process file is open for writing;
these include all operations that affect process control.
Process information and control operations involve the use of sets of flags. The set
types sigset_t, fltset_t, and sysset_t correspond, respectively, to signal, fault,
and system call enumerations defined in sys/signa1.h, sys/fault .h, and
sys/ syscall. h. Each set type is large enough to hold flags for its own enumeration. Although they are of different sizes, they have a common structure and can be
manipulated by these macros:

158

proc(4)
prfillset(&set);
premptyset(&set);
praddset(&set, flag) ;
prdelset(&set, flag) ;
r = prismember(&set, flag) ;

/*
/*
/*
/*
/*

turn
turn
turn
turn
!= 0

on all flags in set */
off all flags in set */
on the specified flag */
off the specified flag */
iff flag is turned on */

One of prfiHset or premptyset must be used to initialize set before it is used in
any other operation. flag must be a member of the enumeration corresponding to
set.
The allowable ioctl codes follow. Those requiring write access are marked with
an asterisk (*). Except where noted, an ioctl to a process that has terminated elicits the error ENOENT.
PIOCSTATUS
This returns status information for the process; p is a pointer to a prstatus structure:
typedef struct prstatus
long
pr_flags;
/* Process flags */
short
pr_why;
/* Reason for process stop (if stopped) */
short
pr_what;
/* More detailed reason */
struct siginfo pr_info; /* Info associated with signal or fault *1
short
pr_cursig;
/* Current signal */
sigset_t pr_sigpend;
/* Set of other pending signals */
sigset_t pr_sighold;
/* Set of held signals */
struct sigaltstack pr_altstack; /* Alternate signal stack info */
struct sigaction pr_action; /* Signal action for current signal */
pid_t
pr-pid;
/* Process id */
pid_t
pr-ppid;
/* Parent process id */
pid_t
pr-pgrp;
/* Process group id */
pid_t
pr_sid;
/* Session id */
timestruc_t pr_utime;
/* Process user cpu time */
timestruc_t pr_stime;
/* Process system cpu time *1
timestruc_t pr_cutime; /* Sum of children's user times */
timestruc_t pr_cstime; /* Sum of children's system times */
char
pr_clname[8]; /* Scheduling class name */
long
pr_filler[20];/* Filler area for future expansion *1
long
pr_instr;
/* Current instruction */
gregset_t pr_reg;
/* General registers */
prstatus_t;
pr_flags is a bit-mask holding these flags:
PR_STOPPED
PR_ISTOP
PR_DSTOP
PR_ASLEEP
PR_FORK
PR_RLC

process is stopped
process is stopped on an event of interest (see PIOCSTOP)
process has a stop directive in effect (see PIOCSTOP)
process is in an interruptible sleep within a system call
process has its inherit-on-fork flag set (see PIOCSFORK)
process has its run-on-last-close flag set (see PIOCSRLC)

159

proc(4)
PR_PTRACE
PR_PCINVAL
PR_ISSYS

process is being traced via ptrace
process program counter refers to an invalid address
process is a system process (see PIOCSTOP)
pr_why and pr_what together describe, for a stopped process, the reason that the
process is stopped. Possible values of pr_why are:
PR_REQUESTED indicates that the process stopped because PIOCSTOP was
applied; pr_what is unused in this case.
PR_SIGNALLED indicates that the process stopped on receipt of a signal (see
PIOCSTRACE); pr_what holds the signal number that caused the stop (for a
newly-stopped process, the same value is in pr_cursig).
PR_FAULTED indicates that the process stopped on incurring a hardware
fault (see PIOCSFAULT); pr_what holds the fault number that caused the
stop.
PR_SYSENTRYand PR_SYSEXIT indicate a stop on entry to or exit from a system call (see PIOCSENTRY and PIOCSEXIT); pr_what holds the system call
number.
PR_JOBCONTROL indicates that the process stopped due to the default action
of a job control stop signal (see sigaction); pr_what holds the stopping
signal number.
pr_info, when the process is in a PR_SIGNALLED or PR_FAULTED stop, contains
additional information pertinent to the particular signal or fault (see
sys/siginfo.h).
pr_cursig names the current signal-that is, the next signal to be delivered to the
process. pr_sigpend identifies any other pending signals. pr_sighold identifies
those signals whose delivery is being delayed if sent to the process.
pr_altstack contains the alternate signal stack information for the process (see
sigaltstack). pr_action contains the signal action information pertaining to the
current signal (see sigaction); it is undefined if pr_cursig is zero.
pr-pid, pr-ppid, pr-P9rp, and pr_sid are, respectively, the process ID, the ID of
the process's parent, the process's process group ID, and the process's session ID.
pr_utime, pr_stime, pr_cutime, and pr_cstime are, respectively, the user CPU
and system CPU time consumed by the process, and the cumulative user CPU and
system CPU time consumed by the process's children, in seconds and nanoseconds.
pr_clname contains the name of the process's scheduling class.
The pr_filler area is reserved for future use.
pr_instr contains the machine instruction to which the program counter refers.
The amount of data retrieved from the process is machine-dependent. In general,
the size is that of the machine's smallest instruction. If the program counter refers
to an invalid address, PR_PCINVAL is set and pr_instr is undefined.
pr_reg is an array holding the contents of the general registers. The constants
defined in sys/regset.h can be used as indices to refer to the general registers.

160

proc(4)
PIOCSTOP*,PIOCWSTOP
PIOCSTOP directs the process to stop and waits until it has stopped; PIOCWSTOP
simply waits for the process to stop. These operations complete when the process
stops on an event of interest, immediately if already so stopped. If p is non-zero it
points to an instance of prstatus_t to be filled with status information for the
stopped process.
An "event of interest" is either a PR_REQUESTED stop or a stop that has been
specified in the process's tracing flags (set by PIOCSTRACE, PIOCSFAULT,
PIOCSENTRY, and PIOCSEXIT). A PR_JOBCONTROL stop is specifically not an event
of interest. (A process may stop twice due to a stop Signal, first showing
PlLSIGNALLED if the signal is traced and again showing PR_JOBCONTROL if the process is set running without clearing the signal.) If the process is controlled by
ptrace, it comes to a PR_SIGNALLED stop on receipt of any signal; this is an event
of interest only if the signal is in the traced signal set. If PIOCSTOP is applied to a
process that is stopped, but not on an event of interest, the stop directive takes
effect when the process is restarted by the competing mechanism; at that time the
process enters a PR_REQUESTED stop before executing any user-level code.
ioctls are interruptible by signals so that, for example, an alann can be set to
avoid waiting forever for a process that may never stop on an event of interest. If
PIOCSTOP is interrupted, the stop directive remains in effect even though the ioctl
returns an error.
A system process (indicated by the PR_ISSYS flag) never executes at user level, has
no user-level address space visible through Iproc, and cannot be stopped. Applying PIOCSTOP or PIOCWSTOP to a system process elicits the error EBUSY.
PIOCRUN*
The traced process is made runnable again after a stop. If p is non-zero it points to a
prrun structure describing additional actions to be performed:
typedef struct prrun {
long
pr_flags;
1* Flags *1
sigset_t pr_trace;
1* Set of signals to be traced *1
sigset_t pr_sighold;
1* Set of signals to be held *1
fltset_t pr_fault;
1* Set of faults to be traced *1
pr_vaddr;
1* Virtual address at which to resume *1
pr_filler[8]; 1* Filler area for future expansion *1
} PrrllD_t;
pr_flags is a bit-mask describing optional actions; the remainder of the entries are
meaningful only if the appropriate bits are set in pr_flags. pr_filler is reserved
for future use; this area must be IDled with zeros by the user's program.
Flag definitions:
PRCSIG clears the current signal, if any (see PIOCSSIG).
PRCFAULT clears the current fault, if any (see PIOCCFAULT).
PRSTRACE sets the traced signal set to pr_trace (see PIOCSTRACE).

161

proc(4)
PRSHOLD sets the held signal set to pr_sighold (see PIOCSHOLD).
PRSFAULT sets the traced fault set to pr_fault (see PIOCSFAULT).
PRSVADDR sets the address at which execution resumes to pr_vaddr.
PRSTEP directs the process to single-step-i.e., to run and to execute a single
machine instruction. On completion of the instruction, a hardware trace
trap occurs. If FLTTRACE is being traced, the process stops, otherwise it is
sent SIGTRAP; if SIGTRAP is being traced and not held, the process stops.
This operation requires hardware support and may not be implemented on
all processors.
PRSABORT is meaningful only if the process is in a PR_SYSENTRY stop or is
marked PR_ASLEEP; it instructs the process to abort execution of the system
call (see PIOCSENTRY, PIOCSEXIT).
PRSTOP directs the process to stop again as soon as possible after resuming
execution (see PIOCSTOP). In particular if the process is stopped on
PR_SIGNALLEDor PR_FAULTED, the next stop will show PR_REQUESTED, no
other stop will have intervened, and the process will not have executed any
user-level code.
PIOCRUN fails (EBUSY) if applied to a process that is not stopped on an event of
interest. Once PIOCRUN has been applied, the process is no longer stopped on an
event of interest even if, due to a competing mechanism, it remains stopped.
PIOCSTRACE*
This defines a set of signals to be traced: the receipt of one of these signals causes
the traced process to stop. The set of signals is defined via an instance of sigset_t
addressed by p. Receipt of SIGKILL cannot be traced.
If a signal that is included in the held signal set is sent to the traced process, the
signal is not received and does not cause a process stop until it is removed from the
held signal set, either by the process itself or by setting the held signal set with
PIOCSHOLD or the PRSHOLD option of PIOCRUN.

PIOCGTRACE
The current traced signal set is returned in an instance of sigset_t addressed by p.
PIOCSSIG*
The current signal and its associated signal information are set according to the contents of the siginfo structure addressed by p (see sys/siginfo.h). If the
specified signal number is zero or if p is zero, the current signal is cleared. The
semantics of this operation are different from those of kill or PIOCKILL in that the
signal is delivered to the process immediately after execution is resumed (even if it
is being held) and an additional PR_SIGNALLED stop does not intervene even if the
signal is traced. Setting the current signal to SIGKILL terminates the process
immediately, even if it is stopped.
PIOCKILL*
A signal is sent to the process with semantics identical to those of kill; p points to
an int naming the signal. Sending SIGKILL terminates the process immediately.

162

proc(4)
PIOCUNKILL*

A signal is deleted, i. e. it is removed from the set of pending signals; the current
signal (if any) is unaffected. p points to an int naming the signal. It is an error to
attempt to delete SIGKILL.
PIOCGHOLD,PIOCSHOLD*
PIOCGHOLD returns the set of held signals (signals whose delivery will be delayed if
sent to the process) in an instance of sigset_t addressed by p. PIOCSHOLD
correspondingly sets the held signal set but does not allow SIGKILL or SIGSTOP to

beheld.
PIOCMAXSIG,PIOCACTION

These operations provide information about the signal actions associated with the
traced process (see sigaction). PIOCMAXSIG returns, in the int addressed by p,
the maximum signal number understood by the system. This can be used to allocate storage for use with the PIOCACTION operation, which returns the traced
process's signal actions in an array of sigaction structures addressed by p. Signal
numbers are displaced by 1 from array indices, so that the action for signal number
n appears in position n-l of the array.
PIOCSFAULT*

This defines a set of hardware faults to be traced: on incurring one of these faults
the traced process stops. The set is defined via an instance of fltset_t addressed
by p. Fault names are defined in sys/fault.h and include the following. Some of
these may not occur on all processors; there may be processor-specific faults in
addition to these.
illegal instruction
privileged instruction
breakpoint trap
trace trap
memory access fault
memory bounds violation
integer overflow
integer zero divide
floating-point exception
unrecoverable stack fault
recoverable page fault
When not traced, a fault normally results in the posting of a signal to the process
that incurred the fault. If the process stops on a fault, the signal is posted to the
process when execution is resumed unless the fault is cleared by PIOCCFAULT or by
the PRCFAULT option of PIOCRUN. FLTPAGE is an exception; no signal is posted.
There may be additional processor-specific faults like this. pr_info in the
prstatus structure identifies the signal to be sent and contains machine-specific
information about the fault.
FLTILL
FLTPRIV
FLTBPT
FLTTRACE
FLTACCESS
FLTBOUNDS
FLTIOVF
FLTIZDIV
FLTFPE
FLTSTACK
FLTPAGE

PIOCGFAULT

The current traced fault set is returned in an instance of fltset_t addressed by p.

163

proc(4)
PIOCCFAULT*

The current fault (if any) is cleared; the associated signal is not sent to the process.
PIOCSENTRY*,PIOCSEXIT*

These operations instruct the process to stop on entry to or exit from specified system calls. The set of syscalls to be traced is defined via an instance of sysset_t
addressed by p.
When entry to a system call is being traced, the traced process stops after having
begun the call to the system but before the system call arguments have been fetched
from the process. When exit from a system call is being traced, the traced process
stops on completion of the system call just prior to checking for signals and returning to user level. At this point all return values have been stored into the traced
process's saved registers.
If the traced process is stopped on entry to a system call (PR_SYSENTRY) or when
sleeping in an interruptible system call (PR_ASLEEP is set), it may be instructed to
go directly to system call exit by specifying the PRSABORT flag in a PIOCRUN request.
Unless exit from the system call is being traced the process returns to user level
shoWing error EINTR.
PIOCGENTRY,PIOCGEXIT

These return the current traced system call entry or exit set in an instance of
sysset_t addressed by p.
PIOCSFORK*,PIOCRFORK*
PIOCSFORK sets the inherit-an-fork flag in the traced process: the process's tracing
flags are inherited by the child of a fork. PIOCRFORK turns this flag off: child

processes start with all tracing flags cleared.
PIOCSRLC*,PIOCRRLC*
PIOCSRLC sets the run-on-last-close flag in the traced process: when the last writable /proc file descriptor referring to the traced process is closed, all of the

process's tracing flags are cleared, any outstanding stop directive is canceled, and if
the process is stopped, it is set running as though PIOCRUN had been applied to it.
PIOCRRLC turns this flag off: the process's tracing flags are retained and the process
is not set running when the process file is closed.
PIOCGREG,PIOCSREG*

These operations respectively get and set the saved process registers into or out of
an array addressed by p; the array has type gregset_t. Register contents are accessible using a set of predefined indices (see PIOCSTATUS). For security, certain bits of
the processor-status word cannot be modified by PIOCSREG. There may be other
privileged registers that cannot be modified at all. PIOCSREG fails (EBusy) if
applied to a process that is not stopped on an event of interest.
PIOCGFPREG,PIOCSFPREG*

These operations respectively get and set the saved process floating-point registers
into or out of a structure addressed by p; the structure has type fpregset_t. An
error (EINVAL) is returned if there is no floating-point hardware on the machine.
PIOCSFPREG fails (EBUSY) if applied to a process that is not stopped on an event of
interest.

164

proc(4)
PIOCNlCE*
The traced process's nice priority is incremented by the amount contained in the
int addressed by p. Only the super-user may better a process's priority in this
way, but any user may make the priority worse.
PIOCPSINFO
This returns miscellaneous process information such as that reported by ps(l). pis
a pointer to a prpsinfo structure containing at least the following fields:
typedef struct prpsinfo {
char
pr_state; /* numeric process state (see pr_sname) */
char
pr_sname; /* printable character representing pr_state * /
char
pr_zomb;
/* !=O: process terminated but not waited for */
char
pr_nice;
/* nice for cpu usage */
u_long pr_flag;
/* process flags */
uid_t
pr_uid;
/* real user id */
gid_t
pr~id;
/* real group id */
pid_t
pr-pid;
/* unique process id */
pid_t
pr-ppid;
/* process id of parent */
pid_t
pr-Pgrp;
/* pid of process group leader */
pid_t
pr_sid;
/* session id */
caddr_t pr_addr;
/* physical address of process */
long
pr_size;
/* size of process image in pages */
long
pr_rssize; /* resident set size in pages */
caddr_t pr_wchan; /* wait addr for sleeping process */
timestruc_t pr_start; /* process start time, sec+nsec since epoch */
timestruc_t pr_time;
/* usr+sys cpu time for this process */
long
pr-pri;
/* priority, high value is high priority */
char
pr_oldpri; /* pre-SVR4, low value is high priority */
char
pr_cpu;
/* pre-SVR4, cpu usage for scheduling */
dev_t
pr_ttydev; /* controlling tty device (PRNODEV if none) */
char
pr_clname[8]; /* Scheduling class name */
char
pr_fname [16] ; /* last c~t of execed patbname * /
char
pr-psargs[PRARGSZ]; /* initial characters of arg list */
long
pr_filler[20]; /* for future expansion */
} prpsinfo_t;
Some of the entries in prpsinfo, such as pr_state and pr_flag, are systemspecific and should not be expected to retain their meanings across different versions of the operating system. pr_addr is a vestige of the past and has no real
meaning in current systems.
PIOCPSINFO can be applied to a zombie process (one that has terminated but whose
parent has not yet performed a wait on it).
PIOCNMAP, PIOCMAP
These operations provide information about the memory mappings (virtual address
ranges) associated with the traced process. PIOCNMAP returns, in the int addressed
by p, the number of mappings that are currently active. This can be used to allocate
storage for use with the PIOCMAP operation, which returns the list of currently
active mappings. For PIOCMAP, p addresses an array of elements of type prmap_t;
one array element (one structure) is returned for each mapping, plus an additional

165

proc(4}
element containing all zeros to mark the end of the list.
typedef struct prmap {
caddr_t pr_vaddr;
1* Virtual address base *1
pr_size;
1* Size of mapping in bytes *1
pr_off;
1* Offset into mapped object, if any *1
pr_mflags;
long
1* Protection and attribute flags *1
pr_filler [4] ; 1* Filler for future expansion *1
long
prmap_t;
pr_vaddr is the virtual address base (the lower limit) of the mapping within the
traced process and pr_size is its size in bytes. pr_off is the offset within the
mapped object (if any) to which the address base is mapped.
pr_mflags is a bit-mask of protection and attribute flags:
MA_READ
MA_WRITE
MA_EXEC
MA_SHARED
MA_BREAK
MA_STACK

mapping is readable by the traced process
mapping is writable by the traced process
mapping is executable by the traced process
mapping changes are shared by the mapped object
mapping is grown by the brk system call
mapping is grown automatically on stack faults

PIOCOPENM
The return value retval provides a read-only file descriptor for a mapped object
associated with the traced process. If p is zero the traced process's execed file (its
a.out file) is found. This enables a debugger to find the object file symbol table
without having to know the path name of the executable file. If p is non-zero it
points to a caddr_t containing a virtual address within the traced process and the
mapped object, if any, associated with that address is found; this can be used to get
a file descriptor for a shared .library that is attached to the process. On error
(invalid address or no mapped object for the designated address), -1 is returned.
PIOCCRED
Fetch the set of credentials associated with the process. P points to an instance of
prcred_t, which is filled by the operation:
typedef struct prcred {
uid_t
pr_euid;
uid_t
pr_ruid;
uid_t
pr_suid;
uid_t
pr_egid;
uid_t
pr_rgid;
uid_t
pr_sgid;

1*
1*
1*
1*
1*
1*
1*

Effective user id *1
Real user id *1
Saved user id (from exec) *1
Effective group id *1
Real group id *1
Saved group id (from exec) *1
Number of supplementary groups *1

} prcred_t;
PIOCGROUPS
Fetch the set of supplementary group IDs associated with the process. p points to
an array of elements of type uid_t, which will be filled by the operation. PIOCCRED
can be applied beforehand to determine the number of groups (pr_ngrOUPs) that
will be returned and the amount of storage that should be allocated to hold them.

166

proc(4)
PIOCGETP~PIOCGETU

These operations copy, respectively, the traced process's proc structure and user
area into the buffer addressed by p. They are provided for completeness but it
should be unnecessary to access either of these structures directly since relevant
status information is available through other control operations. Their use is
discouraged because a program making use of them is tied to a particular version of
the operating system.
PIOCGETPR can be applied to a zombie process (see PIOCPSINFO).
NOTES

Each operation (ioctl or I/O) is guaranteed to be atomic with respect to the traced
process, except when applied to a system process.
For security reasons, except for the super-user, an open of a /proc file fails unless
both the user-ID and group-ID of the caller match those of the traced process and
the process's object file is readable by the caller. Files corresponding to setuid and
setgid processes can be opened only by the super-user. Even if held by the superuser, an open process file descriptor becomes invalid if the traced process performs
an exec of a setuid/ setgid object file or an object file that it cannot read. Any
operation performed on an invalid file descriptor, except close, fails with EAGAIN.
In this situation, if any tracing flags are set and the process file is open for writing,
the process will have been directed to stop and its run-on-Iast-close flag will have
been set (see PIOCSRLC). This enables a controlling process (if it has permission) to
reopen the process file to get a new valid file descriptor, close the invalid file
descriptor, and proceed. Just closing the invalid file descriptor causes the traced
process to resume execution with no tracing flags set. Any process not currently
open for writing via /proc but that has left-over tracing flags from a previous open
and that execs a setuid/setgid or unreadable object file will not be stopped but will
have all its tracing flags cleared.
For reasons of symmetry and efficiency there are more control operations than
strictly necessary.
FILES

/proc
/proc/nnnnn

directory (list of active processes)
process image

SEE ALSO

open(2), ptrace(2), sigaction(2), signal(2)
DIAGNOSTICS

Errors that can occur in addition to the errors normally associated with file system
access:
The traced process has exited after being opened.
ENOENT
EIO

1/0 was attempted at an illegal address in the traced process.

EBADF

An I/O or ioctl operation requiring write access was attempted on a
file descriptor not open for writing.
PIOCSTOP or PIOCWSTOP was applied to a system process; an exclusive
open was attempted on a process file already already open for writing; an open for writing was attempted and an exclusive open is in
effect on the process file; PIOCRUN, PIOCSREG or PIOCSFPREG was

EBUSY

167

proc(4)

ENOSYS

DAULT

EINVAL

EIN'l'R
EAGAIN

168

applied to a process not stopped on an event of interest; an attempt
was made to mount /proc when it is already mounted.
Someone other than the super-user attempted to better a process's
priority by issuing PIOCNICE.
An attempt was made to perform an unsupported operation (such as
create, remove, link, or unlink) on an entry in /proc.
An I/O or ioctl request referred to an invalid address in the controlling process.
In general this means that some invalid argument was supplied to a
system call. The list of conditions eliciting this error includes: the
ioctl code is undefined; an ioctl operation was issued on a file
descriptor referring to the /proc directory; an out-of-range signal
number was specified with PIOCSSIG, PIOCKILL, or PIOCtJNKILL;
SIGKILL was specified with PIOCtJNKILL; an illegal virtual address
was specified in a PIOCOPENM request; PIOCGPPREG or PIOCSFPREG
was issued on a machine without floating-point hardware.
A signal was received by the controlling process while waiting for the
traced process to stop via PIOCS'l'OP or PIOCWS'1'OP.
The traced process has performed an exec of a setuid/ setgid object
file or of an object file that it cannot read; all further operations on the
process file descriptor (except close) elicit this error.

profile (4)
NAME

profile - setting up an environment at login time
SYNOPSIS

/etc/profile
$HOME/ . profile
DESCRIPTION

All users who have the shell, sh(l), as their login command have the commands in
these files executed as part of their login sequence.
/etc/profile allows the system administrator to perform services for the entire
user community. Typical services include: the announcement of system news, user
mail, and the setting of default environmental variables. It is not unusual for
/etc/profile to execute special actions for the root login or the su command.
Computers running outside the U.S. Eastern time zone should have the line
. /etc/TlMEZONE
included early in /etc/profile [see timezone(4)].
The file $HOME/ .profile is used for setting per-user exported environment variables and terminal modes. The following example is typical (except for the comments):
# Make some environment variables global
export MAIL PATH TERM
# Set file creation mask
UllIask 022
# Tell me when new mail comes in
MAIL=/var/mail/$LOGNAME
# Add my bin directory to the shell search sequence
PATH=$PATH:$HOME/bin
# Set termdnal type
TERM=${LO:-u/n/k/n/o/w/n}
while :
do
if [ -f ${TERMINFO:-/usr/share/lib/termdnfo}/?/$TERM
then break
elif [ -f /usr/share/lib/termdnfo/?/$TERM
then break
else echo "invalid term $TERM" 1>&2
fi
echo "termdnal: \c"
read TERM
done
# Set the erase character to backspace
stty erase '~H' echoe

169

profile (4)
FILES

/ete/TIMEZONE
$HOME/ . profile
fete/profile

timezone environment
user-specific environment
system-wide environment

SEE ALSO

env(l), environ(5), login(l), mail(l),
tenninfo(4), timezone(4), tput(l)

sh(l),

stty(l),

su(lM),

term(5),

NOTES

Care must be taken in providing system-wide services in fete/profile. Personal
.profile files are better for serving all but the most global needs.

170

protocols ( 4 )
NAME

protocols - protocol name data base
SYNOPSIS

/etc/protocols
DESCRIPTION

The protocols 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:
officml-protocol-name protocol-number

almses

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.
The protocols file is used to initialize commands and protocols with these
reserved values.
EXAMPLE

The following is a sample database:

#
# Internet (IP) protocols
#
ip
0
IP
# internet protocol, pseudo protocol number
1
ICMP
# internet control message protocol
iClll>
ggp
3
GGP
# gateway-gateway protocol
tcp
TCP
6
# transmission control protocol
pup
12
PUP
# PARe universal packet protocol
udp
17
UDP
# user datagram protocol
FILES

/etc/protocols
SEE ALSO

getprotoent(3N)
NOTES

A name server should be used instead of a static file. A binary indexed file format
should be available for fast access.

171

prototype ( 4 )
NAME

prototype - package information file
DESCRIPTION

prototype is an ASCII file used to specify package information. Each entry in the

file describes a single deliverable object. An object may be a data file, directory,
source file, executable object, etc. This file is generated by the package developer.
Entries in a prototype file consist of several fields of information separated by
white space. Comment lines begin with a //#// and are ignored. The fields are
described below and must appear in the order shown.

An optional field designating the part number in which the object
resides. A part is a collection of files, and is the atomic unit by which a
package is processed. A developer can choose criteria for grouping files
into a part (for example, based on class). If this field is not used, part 1 is
assumed.
ftype
A one·character field which indicates the file type. Valid values are:
f
a standard executable or data file
e a file to be edited upon installation or removal
v volatile file (one whose contents are expected to change)
d directory
x an exclusive directory (See NOTES)
1
linked file
p
named pipe
c character special device
b block special device
i
installation script or information file
s symbolic link
Once a file has the file type attribute v, it will always be volatile. For
example, if a file being installed already exists and has the file type attri·
bute v, then even if the version of the file being installed is not specified
as volatile, the file type attribute will remain volatile.
class
The installation class to which the file belongs. This name must contain
only alphanumeric characters and be no longer than 12 characters. The
field is not specified for installation scripts. (admin and all classes beginning with capital letters are reserved class names.)
pathname The pathname where the file will reside on the target machine, for example, /usr/bin/mail or bin/ras'-"proc. Relative pathnames (those that
do not begin with a slash) indicate that the file is relocatable. The form
pathl=path2 may be used for two purposes: to define a link and to define
local pathnames.
For linked files, pathl indicates the destination of the link and path2 indicates the source file. (This format is mandatory for linked files.)
For symbolically linked files, when path2 is a relative pathname starting
with . / or .• /, path2 is not considered relocatable. For example, if you
enter a line such as

part

s /foo/bar/etc/mount= .. /usr/sbin/mount

172

prototype ( 4 )
pathl

(lfoo/bar/etc/mount)
.. /usr/sbin/mount.

will

symbolic

link

For local pathnames, pathl indicates the pathname an object should have
on the machine where the entry is to be installed and path2 indicates
either a relative or fixed pathname to a file on the host machine which
contains the actual contents.
A pathname may contain a variable specification, which will be resolved
at the time of installation. This specification should have the form
$ [A-Z] (see NOTES).
Special characters, such as an equal sign (=), are included in pathnames
by surrounding the entire pathname in single quotes (as in, for example,
, /usr/libr=').

major
minor
mode

owner

group

The major device number. The field is only specified for block or character special devices.
The minor device number. The field is only specified for block or character special devices.
The octal mode of the file (for example, 0664). A question mark (?) indicates that the mode will be left unchanged, implying that the file already
exists on the target machine. If the directory doesn't exist, the default is
0755. If it's a file, the default is 0644. This field is not used for linked files
or packaging information files.
The owner of the file (for example, bin or root). The field is limited to
14 characters in length. A question mark (?) indicates that the owner
will be left unchanged, implying that the file already exists on the target
machine. If it doesn't exist, owner defaults to root. This field is not used
for linked files or packaging information files.
Can be a variable specification in the form of $ [A-Z] (see NOTES). Will
be resolved at installation time.
The group to which the file belongs (for example, bin or sys). The field
is limited to 14 characters in length. A question mark (?) indicates that
the group will be left unchanged, implying that the file already exists on
the target machine. If it doesn't exist, group defaults to other. This field
is not used for linked files or packaging information files.

Can be a variable specification in the form of $ [A-Z] (see NOTES). Will
be resolved at installation time.
An exclamation point (!) at the beginning of a line indicates that the line contains a
command. These commands are used to incorporate files in other directories, to
locate objects on a host machine, and to set permanent defaults. The following
commands are available:
search

Specifies a list of directories (separated by white space) to search
for when looking for file contents on the host machine. The
basename of the path field is appended to each directory in the
ordered list until the file is located. This command should not be

173

prototype ( 4 )
specified in prototype files for packages that are to be
compressed.
include
default

Specifies a pathname which points to another prototype file to
include. Note that search requests do not span include files.
Specifies a list of attributes (mode, owner, group, mac, fixed, and
inherited) to be used by default if attribute information is not provided for prototype entries which require the information. If
either the mode, owner, or group attribute is supplied, all three of
these attributes must be supplied.

The defaults do not apply to entries in include prototype files.
param=va[ue
Places the indicated parameter in the current environment.
The above commands may have variable substitutions embedded within them, as
demonstrated in the two example prototype files below.
Before files are overwritten during installation, they are copied to a temporary
pathname. The exception to this rule is files whose mode includes execute permission, unless the file is editable (that is, ftype is e). For files which meet this exception, the existing version is linked to a temporary pathname, and the original file is
removed. This allows processes which are executing during installation to be
overwritten.
EXAMPLES

Example 1:
IPROJDIR=/usr/proj
lBIN=$PROJDIR/bin
lCFG=$PROJDIR/cfg
lLIB=$PROJDIR/lib
lHDRS=$PROJDIR/hdrs
lsearch /usr/m¥Qame/usr/bin /usr/myname/src /usr/myname/hdrs
i pkginfo=/usr/myname/wrap/pkginfo
i depend=/usr/m¥Qame/wrap/depend
i version=/usr/~/wrap/version
d none /usr/wrap 0755 root bin
d none /usr/wrap/bin 0755 root bin
search $BIN
f none /usr/wrap/bin/INSTALL 0755 root bin
f none /usr/wrap/bin/REMOVE 0755 root bin
f none /usr/wrap/bin/addpkg 0755 root bin
ldefault 755 root bin
f none /usr/wrap/bin/audit
f none /usr/wrap/bin/listpkg
f none /usr/wrap/bin/pkgmk
# The logfile starts as a zero length file, since the source
# file has zero length. Later, the size of logfile grows.
v none /usr/wrap/logfile=/usr/wrap/log/zero_length 0644 root bin
# the following specifies a link (dest=src)
1 none /usr/wrap/src/addpkg=/usr/wrap/bin/rmpkg
search $SRC

174

prototype ( 4 )
!default 644 root other
f src /usr/wrap/src/INSTALL.sh
f src /usr/wrap/src/REMOVE.sh
f src /usr/wrap/src/addpkg.c
f src /usr/wrap/src/audit.c
f src /usr/wrap/src/listpkg.c
f src /usr/wrap/src/pkgmk.c
d none /usr/wrap/data 0755 root bin
d none /usr/wrap/save 0755 root bin
d none /usr/wrap/spool 0755 root bin
d none /usr/wrap/tmp 0755 root bin
d src /usr/wrap/src 0755 root bin

Example 2:
# this prototype is generated by 'pkgproto' to refer
# to all prototypes in my src directory
!PROJDIR=/usr/dew/projx
!include $PROJDIR/src/cmd/prototype
!include $PROJDIR/src/cmd/audmerg/protofile
!include $PROJDIR/src/lib/proto
SEE ALSO

pkginfo(4), pkgmk(l)
NOTES

Normally, if a file is defined in the prototype file but does not exist, that file is
created at the time of package installation. However, if the file pathname includes a
directory that does not exist, the file will not be created. For example, if the prototype file has the following entry:
f none /usr/dev/bin/command
and that file does not exist, it will be created if the directory /usr/dev/bin already
exists or if the prototype also has an entry defining the directory:
d none /usr/dev/bin
An exclusive directory type (file) type x) specifies directories that are constrained to
contain only files that appear in the software installation database
(lvar/sadm/install/contents). If there are other files in the directory, they will
be removed by pkgchk -fx as described on the pkgchk(lM) man page.
Variable specifications for the patlmame, owner, and group fields are defined in the
pkginfo file. For example, owner could be $OWNER in the pkgmap file; if OWNER is
defined as root in the pkginfo file, $OWNER will get the value root when the file
gets installed.

175

publickey(4)
NAME

publickey - public key database
SYNOPSIS

/etc/publickey
DESCRIPTION

/etc/publickey is the public key database used for secure RPc. Each entry in the
database consists of a network user name (which may either refer to a user or a
hostname), followed by the user's public key (in hex notation), a colon, and then the
user's secret key encrypted with a password (also in hex notation).
This file is altered either by the user through the chkey(l) command or by the system administrator through the newkey(lM) command.
SEE ALSO

chkey(l), newkey(lM), publickey(3N)

176

Rc(4)
NAME
Rc - system startup script

SYNOPSIS
Rc

DESCRIPTION

One of the kernel configuration files, an Rc file is an optional file that executes when
the system is booted to initialize an installed kernel module. [Normally, this is a
shell script (see sh(l).]
When the Rc component of a module's Driver Software Package (DSP) is installed,
idinstall(lM) stores the module's Rc file in /etc/conf/rc.d/module-name,
where module-name is the name of the module being installed. Package scripts
should never access /etc/conf/rc.d files directly; the idinstall command
should be used instead.
The contents of the /etc/conf/rc.d directory are linked to /etc/idrc.d whenever a new configuration of the kernel is first booted. On this initial reboot, and on
all subsequent reboots, the module's Rc file is invoked upon entering init level 2
[see init(lM)].
SEE ALSO

idinstall(lM), init(lM), Sd(4)

res major ( 4 )
NAME

res_major - reserved major numbers for base system device drivers
SYNOPSIS

res_major
DESCRIPTION

One of the ID/TP kernel configuration files, the res_major file defines the major
numbers that are reserved for use by device drivers supplied with the base system.
When the idinstall(lM) command allocates major numbers for an add-on driver,
it examines the contents of the file /etc/conf/cf.d/res_major to make sure the
major number it intends to allocate to the add-on driver is not already reserved for
allocation to a base system driver. This file should not be used by add-on drivers.
Any base system driver that sets a k (keep majors) flag in the characteristics field of
its Master(4) file must add its major numbers to the res_major file. Each
res_major file entry provides information about one type of base system driver,
specified on a line of the form:

device-type major-number module-name
All fields are positional and must be separated by tabs.
The res_major file fields are:

device-type

Identifies the type of base system device driver. The character b
indicates that the driver is a block device driver; the character c
indicates that the driver is a character device driver. If the driver
is both a block device driver and a character device driver, the
driver must define two separate res_major entries, with one
entry for each device type.

major-number

Specifies the major number(s) reserved by the base system device
driver. If the device has multiple major numbers, this field
should be specified as two numbers separated by a dash to indicate an inclusive range of reserved values. The value for this field
must match the value specified in the bmaj or cmaj field in the
driver's Master file.

module-name

Identifies the base system device driver for which the major
number(s) are reserved. The name must match the name
specified for the driver in the module-name field of the Master file.

SEE ALSO

idinstall(lM), Master(4)

178

resolv.conf ( 4)
NAME

resolv . conf - configuration file for name server routines
DESCRIPTION

'The resolver configuration file contains information that is read by the resolver routines the first time they are invoked in a process. 'The file is designed to be human
readable and contains a list of keyword-value pairs that provide various types of
resolver information.

keyword

value

'The different configuration options are:
nameserver address

'The Internet address (in dot notation) of a name server that
the resolver should query. At least one name server should
be listed. Up to MAXNS (currently 3) name servers may be
listed, in that case the resolver library queries tries them in
the order listed. 'The algorithm used is to try a name server,
and if the query times out, try the next, until out of name
servers, then repeat trying all the name servers until a maximum number of retries are made.

domain name

'The default domain to append to names that do not have a
dot in them.

address address

An Internet address (in dot notation) of any preferred networks. 'The list of addresses returned by the resolver will be
sorted to put any addresses on this network before any others.

'The keyword-value pair must appear on a single line, and the keyword (for
instance, nameserver) must start the line. 'The value follows the keyword,
separated by white space.
FILES

letc/resolv.conf
SEE ALSO

gethostent(3N), named(lM), resolver(3N)

179

rfmaster ( 4 )
NAME

rfmaster - Remote File Sharing name server master file
DESCRIPTION

Each transport provider used by Remote File Sharing has an associated rfmaster
file that identifies the primary and secondary name servers for that transport provider. The rfmaster file Ascn contains a series of records, each terminated by a
newline; a record may be extended over more than one line by escaping the newline
character with a backslash ("\"). The fields in each record are separated by one or
more tabs or spaces. Each record has three fields:

name type

data

The type field, which defines the meaning of the name and data fields, has three possible values. These values can appear in upper case or lower case:
p
The p type defines the primary domain name server. For this type, name is
the domain name and data is the full host name of the machine that is the primary name server. The full host name is specified as domain.nodename. There
can be only one primary name server per domain.
s
The s type defines a secondary name server for a domain. name and data are
the same as for the p type. The order of the s entries in the rfmaster file
determines the order in which secondary name servers take over when the
current domain name server fails.
a
The a type defines a network address for a machine. name is the full domain
name for the machine and data is the network address of the machine. The
network address can be in plain AScn text or it can be preceded by a \x or \X
to be interpreted as hexadecimal notation. (See the documentation for the
particular network you are using to determine the network addresses you
need.)
If a line in the rfmaster file begins with a # character, the entire line is treated as a
comment.
There are at least two lines in the rfmaster file per domain name server: one p and
one a line, to define the primary and its network address.
This file is created and maintained on the primary domain name server. When a
machine other than the primary tries to start Remote File Sharing, this file is read to
determine the address of the primary. If the associated rfmaster for a transport
provider is missing, use
rfstart -p primary_name_server_address

to identify the primary name server's address for that transport provider. After
that, a copy of the primary's rfma.ster file is automatically placed on the machine.
Domains not served by the primary can also be listed in the rfmaster file. By
adding primary, secondary, and address information for other domains on a network, machines served by the primary will be able to share resources with
machines in other domains.

180

rfmaster ( 4 )
A primary name server may be a primary for more than one domain. However, the
secondaries must then also be the same for each domain served by the primary.
There is an rfmaster file for each transport provider.
Files
/ etc/ rf s / / rfmaster

USAGE
Examples

An example of an rfmaster file, using TCP lIP addresses, is shown below. (The
network address shown are for illustration purposes only. Do not use these in your
rfmaster file.)
ccs
p
ccs.cOIIIi>l
ccs
s
ccs.c0IIIi>2
ccs.c0IIQ;)2 a
\x00020ACEAE026E380000000000000000
\x00020ACEAE026E480000000000000000
ccs • cOIIIi>l a

REFERENCES
rfstart(lM)

181

routing (4)
NAME

routing - system supporting for packet network routing
DESCRIPTION

The network facilities provide general packet routing. Routing table maintenance
may be implemented in applications processes.
A simple set of data structures compose a routing table used in selecting the
appropriate network interface when transmitting packets. This table contains a single entry for each route to a specific network or host. The routing table was
designed to support routing for the Internet Protocol (IP), but its implementation is
protocol independent and thus it may serve other protocols as well. User programs
may manipulate this data base with the aid of two ioctl(2) commands, SIOCADDRT
and SIOCDELRT. These commands allow the addition and deletion of a single routing table entry, respectively. Routing table manipulations may only be carried out
by privileged user.
A routing table entry has the following form, as defined in
/usr/include/net/route.h:
struct rtentry {
u_long rt_hash;
struct sockaddr rt_dst;
struct sockaddr rt_gateway;
short
rt_flags;
short
rt_refcnt;
u_long rt_use;
#ifdef STRNET
struct ip-provider *rt-prov;
#else
struct ifnet *rt_ifp;
#endif 1* STRNET *1

1*
1*
1*
1*
1*
1*

to speed lookups *1
key *1
value *1
up/down?, host/net *1
# held references *1
raw # packets forwarded *1

1* the answer: provider to use *1
1* the answer: interface to use *1

};

with rtJlags defined from:
#define
#define
#define

RTF_UP
RTF_GATEWAY
RTF_HOST

Oxl
Ox2
Ox4

1* route usable *1
1* destination is a gateway *1
1* host entry (net otherwise) *1

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). Each network interface installs a routing table entry when it it is
initialized. 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 (that is, the packet is forwarded).
Routing table entries installed by a user process may not specify the hash, reference
count, use, or interface fields; these are filled in by the routing routines. If a route is
in use when it is deleted (rt_refcnt is non-zero), the resources associated with it
will not be reclaimed until all references to it are removed.

182

routing (4)
User processes read the routing tables through the /dev/kmem device.
'The rt_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 traffic.
FILES

/dev/kmem
SEE ALSO

ioctl(2), route(lM), routed(lM)
DIAGNOSTICS

EEXIST
ESRCH
ENOBUFS

A request was made to duplicate an existing entry.
A request was made to delete a non-existent entry.
Insufficient resources were available to install a new route.

183

rpc(4)
NAME

rpc - rpc program number data base
SYNOPSIS
rpc
DESCRIPTION

The rpc program number database contains user readable names that can be used
in place of RPC program numbers. Each line has the following information:
name of server for the RPC program
RPC program 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.
Below is an example of an RPC database:

184

#
#
#

rpc

rpcbind
rusersd
nfs
mountd
walld
sprayd
llockmgr
nlockmgr
status
bootparam
keyserv

100000
100002
100003
100005
100008
100012
100020
100021
100024
100026
100029

portmap sunrpc portmapper
rusers
nfsprog
mount showmount

rwall shutdown
spray

keyserver

NAME

rt_dptbl- real-time dispatcher parameter table
DESCRIPTION

The process scheduler (or dispatcher) is the portion of the kernel that controls allocation of the CPU to processes. The scheduler supports the notion of scheduling
classes where each class defines a scheduling policy, used to schedule processes
within that class. Associated with each scheduling class is a set of priority queues
on which ready to run processes are linked. These priority queues are mapped by
the system configuration into a set of global scheduling priorities which are available to processes within the class. (The dispatcher always selects for execution the
process with the highest global scheduling priority in the system.) The priority
queues associated with a given class are viewed by that class as a contiguous set of
priority levels numbered from 0 (lowest priority) to n (highest priority-a
configuration dependent value). The set of global scheduling priorities that the
queues for a given class are mapped into might not start at zero and might not be
contiguous (depending on the configuration).
The real-time class maintains an in-core table, with an entry for each priority level,
giving the properties of that level. This table is called the real-time dispatcher
parameter table (rt_dptbl). The rt_dptbl consists of an array of parameter structures (struct rt_dpent), one for each of the n priority levels. The properties of a
given priority level i are specified by the ith parameter structure in this array
(rt_dptbli).
A parameter structure consists of the following members. These are also described
in the /usr/include/sys/rt.hheader file.
rt~lobpri

The global scheduling priority associated with this priority level.
The mapping between real-time priority levels and global
scheduling priorities is determined at boot time by the system
configuration. The rt_globpri values cannot be changed with
dispadmin(lM).
rt_quantum
The length of the time quantum allocated to processes at this level
in ticks (HZ). The time quantum value is only a default or starting value for processes at a particular level as the time quantum
of a real-time process can be changed by the user with the
priocntl command or the priocntl system call.
An administrator can affect the behavior of the real-time portion of the scheduler by
reconfiguring the rt_dptbl. There are two methods available for doing this.
DISPADMIN CONFIGURATION FILE

The rt_quantum values in the rt_dptbl can be examined and modified on a running system using the dispadmin(lM) command. Invoking dispadmin for the
real-time class allows the administrator to retrieve the current rt_dptbl
configuration from the kernel's in-core table, or overwrite the in-core table with
values from a configuration file. The configuration file used for input to dispadmin
must conform to the specific format described below.

185

rt_dptbl (4)
Blank lines are ignored and any part of a line to the right of a # symbol is treated as
a comment. The first non-blank, non-comment line must indicate the resolution to
be used for interpreting the time quantum values. The resolution is specified as

RES=res
where res is a positive integer between 1 and 1,000,000,000 inclusive and the resolution used is the reciprocal of res in seconds. (For example, RES=1000 specifies millisecond resolution.) Although very fine (nanosecond) resolution may be specified,
the time quantum lengths are rounded up to the next integral multiple of the system clock's resolution. The system clock's resolution is hardware-dependent; this
resolution can be calculated from the value of HZ, which is defined in the file
/usr/include/sys/param.h. HZ gives the number of clock ticks per second of the
system clock. For example, an HZ of 100 specifies 100 clock ticks per second, or one
tick every 10 milliseconds (that is, this system clock has a resolution of 10 milliseconds). If the -t and -r options are used to specify a time quantum of 34 milliseconds, it is rounded up to 4 ticks (40 milliseconds) on a machine with an HZ of
100.
The remaining lines in the file are used to specify the rt_quantum values for each of
the real-time priority levels. The first line specifies the quantum for real-time level
0, the second line specifies the quantum for real-time levell, etc. There must be
exactly one line for each configured real-time priority level. Each rt_quantum
entry must be either a positive integer specifying the desired time quantum (in the
resolution given by res), or the symbol RT_TQINF indicating an infinite time quantum for that level.
EXAMPLE

The following excerpt from a dispadmin configuration file illustrates the format.
Note that for each line specifying a time quantum there is a comment indicating the
corresponding priority level. These level numbers indicate priority within the realtime class, and the mapping between these real-time priorities and the corresponding global scheduling priorities is determined by the configuration specified in the
rt master file. The level numbers are strictly for the convenience of the administrator reading the file and, as with any comment, they are ignored by dispadmin on
input. dispadmin assumes that the lines in the file are ordered by consecutive,
increasing priority level (from 0 to the maximum configured real-time priority).
The level numbers in the comments should normally agree with this ordering; if for
some reason they don't, however, dispadmin is unaffected.

186

# Real-Time Dispatcher Configuration File
RES=1000

#
#

PRIORITY

TIME QUANTUM
(rt_quantum)

LEVEL

100
100
100
100
100
100
90
90

#
#
#
#
#
#
#
#

0
1
2
3
4
5
6

10
10

#
#

FILES

/usr/include/sys/rt.h
SEE ALSO

dispadmin(lM), priocntl(l), priocntl(2)

187

Sassign(4)
NAME

Sassign - configurable device variables
SYNOPSIS

Sassign
DESCRIPTION

One of the kernel configuration files, the Sassign file gives system administrators
the ability to assign specific actual devices to logical device names used by the kernel. One example is rootdev, which is the device that contains the root file system.
At present, the Sassign file only supports block devices.
If the system administrator wants to assign a different actual device to perform a
function, the administrator remaps the logical device name for that function to
specify another configured device in the sassign file. Note that the kernel must be
rebuilt and rebooted for the new assignment to take affect.
Each logical device name in the Sassign file is specified (in
/ete/eonf/sassign.d) on a separate line of the form:

device-variable-prefix device-module-name minor node-name
All fields are positional and must be separated by white space. Blank lines and
lines beginning with '#' or '.' are considered comments and are ignored.
The Sassign file fields are:

device-variable-prefix
Specifies a prefix identifier to be used to construct the logical name by which
the device is known. When the kernel is rebuilt, the suffix deY will be
appended to this identifier to form the full logical device name.
The logical device name will be used to create a global variable of type
dev_t during the kernel rebuild process. Any module that needs to reference the logical device should include an extern dev_t declaration for the
logical device name variable.

device-module-name
Identifies the name of actual device that is to perform the function associated with this logical device name. The name must match the name defined
for the device in the module-name field of its Master(4) file.
minor Specifies the minor device number which is to be assigned to this logical
device name. The major number for the logical device is the major number
defined for the device identified in the device-module-name field.

node-name
This field is used for the swap device only. The field specifies the full pathname of the block special file for the swap device.
NOTES

To create a variable which is intended to always refer to the same device, define it
as a variable in the device's Spaee.e file, using the PRFX_BMAJOR_X symbol from
/ete/eonf/ef .d/eonfig .h, instead of using an Sassign file.

188

Sassign(4)
SEE ALSO

idbuild(lM), Master(4), space.c(4)

189

sccsfile ( 4 )
NAME

sccsfile - format of sees file
DESCRIPTION

An sees (Source Code Control System) file is an ASen file. It consists of six logical
parts: the checksum, the delta table (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 body (contains the actual text
lines intermixed with control lines).
Throughout an sees file there are lines which begin with the AseII SOH (start of
heading) character (octal 001). This character is hereafter referred to as the control
character and will be represented graphically as @. Any line described below that is
not depicted as 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@hprovides a magic number of (octal) 064001, depending on byte order.
Delta Table
The delta table consists of a variable number of entries of one of the following
forms:
@sDDDDD/DDDDD/DDDDD

@d yr/mo/da hr:mi:se DDDDD DDDDD
@iDDDDD ...
@xDDDDD •••
@gDDDDD •••
@In

...

The first line (@s) contains the number of lines inserted/deleted/unchanged,
respectively. The second line (@d) contains the type of the delta (normal: D or
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 @i, @x, and @g lines contain the serial numbers of deltas included, excluded,
and ignored, respectively. These lines are optional.

190

sccsfile (4)
The @m lines (optional) each contain one MR number associated with the delta; the
@c lines contain comments associated with the delta. The @e line ends the delta
table entry.
User Names

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 @u. An empty
list allows anyone to make a delta. Any line starting with a ! prohibits the
succeeding group or user from making deltas.
Flags

Keywords used internally. See admin(l) for more information on their use. Each
flag line takes the form:
@f

The following flags are defined:
@f t
@f
@f
@f
@f

@f f
@f

v
i

@f d

n
@f j
@f 1
@f

@f q
@f

The t flag defines the replacement for the %Y"-f, 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
causes a fatal error (the file will not be "gotten", or the delta will not be made).
When the b flag is present the -b keyletter 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 'YoM% ,identification keyword. The f flag defines the floor release; the
release below which no deltas may be added. The c flag defines 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 n 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 n flag 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. The q flag defines the replacement

191

sccsfile ( 4 )
for the %Q% identification keyword. The z flag is used in specialized interface programs.
Comments

Arbitrary text is surrounded by the bracketing lines @t and @T. The comments section typically will contain a description of the file's purpose.
Body

The body consists of text lines and control lines. Text lines do not begin with the
control character, control lines do. There are three kinds of control lines: insert,
delete, and end, represented by:
@IDDDDD
@DDDDDD
@EDDDDD

respectively. The digit string is the serial number corresponding to the delta for the
control line.
SEE ALSO

admin(l), delta(l), get(l), prs(l)

192

Sd(4)
NAME

Sd - kernel module system shutdown script
SYNOPSIS
Sd
DESCRIPTION

One of the kernel configuration files, a Sd file is an optional file that executes when
the system is shut down to perform any cleanup required for an installed kernel
module. Normally, this is a shell script [see sh(l)].
When the Sd component of a module's Driver Software Package (DSP) is installed,
idinstall(lM) stores the driver's Sd file information in /etc/conf/sd.d/modulename, where module-name is the name of the module being installed. Package scripts
should never access /etc/conf/sd.d files directly; only the idinstall command
should be used.
The contents of the /etc/conf/sd.d directory are linked to /etc/idsd.d whenever a new configuration of the kernel is first booted. On the next system
shutdown-and all subsequent system shutdowns-the module's Sd file is executed
upon entering init level 0, 5, or 6 [see init(lM)].
SEE ALSO

idinstall(lM), init(lM), shutdown(lM), Rc(4)

193

services ( 4 )
NAME

services - Internet services and aliases
DESCRIPTION

The services file contains an entry for each service available through the DARPA
Internet. Each entry consists of a line of the form:

service-name port / protocol aliases
service-name
This is the official Internet service name.
port / protocol
This field is composed of the port number and protocol
through which the service is provided (for instance,
Sl2/tcp).

aliases

This is a list of alternate names by which the service might be
requested.

Fields can be separated by any number of SPACE and/or TAB characters. A 'I'
(pound-sign) 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.
The services file is used to initialize commands and protocols with these traditional and reserved values.
FILES

/etc/services
SEE ALSO

getservent(3N), inetd. conf(4), RFC 1060

194

setinfo (4)
NAME

setinfo - set characteristics file
DESCRIPTION

set info is an ASCII file that describes the characteristics of the set along with information that helps control the flow of installation. It is created by the software set
developer and is included in the Set Installation Package (SIP). A SIP is a special
purpose package that controls the installation and removal of a set of packages.
Each entry in the set info file is a line that consists of predefined fields. Each entry
corresponds to a package belonging to the set and must contain the following
-separated fields:

1. Package Abbr

This field contains the abbreviated name of the package. The abbreviation must be a short string (no more than nine characters long) and
must conform to the file naming rules. All characters in the abbreviation must be alphanumeric and the first character cannot be numeric.
install, new, and all are reserved.
This abbreviated name must be the same as the one used in pkginfo(4).

2. Parts
This field specifies the number of parts this package consists of.
3. Default This field contains the character 'y' indicating that the package is to be
installed as a default. Conversely, an 'n' indicates that the package will
not be installed.
4. Category
The category under which the package belongs. Release 4 defines four
categories: "application," "graphics," "system" and "utilities." All
packages must be assigned to one of these categories. If you choose,
you can also assign a package to a category you defined. Categories are
case-insensitive and may contain only alphanumerics. Each category is
limited to 16 characters.
5. Package Full-Name
Text that specifies the package name (maximum length of 256 ASCII characters). This field must be the same as NAME in pkginfo(4).
EXAMPLES

set info file for set admin:
#ident
#ident

"@(#)set:cmn/set/admin/setinfo
"$Header: $"

# Format for the set info file.
# pkg parts default
category
# abbr
yin
oam
4
bkrs 1
face 1

y
y
y

application
system
application

1.2"

Field separator is:
pkg full-name

OA&M

Extended Backup and Restore
FACE

195

setinfo(4)
NOTES

The order of the packages listed in the setinfo file must reflect any package dependencies (if any) and must represent the order in which the packages will occur on
the media (in the case of datastream). Any package for which there exists a dependency must be listed prior to the package(s) that depends on it.
SEE ALSO
pkginfo(4)

196

setsize (4)
NAME

setsize - disk space requirements file
DESCRIPTION

This set information file defines disk space requirements for the target environment.
It contains information about all of the packages in the set. This file describes the

disk space taken up by installed files as well as extra space needed for dynamically
created files, as described in each package's space(4) file.
The generic format of a line in this file is:

pathname blocks inodes
Definitions for each field are as follows:
pkg
The short, or abbreviated, name of a package in the set. This name
describes which package of the set requires the amount of space
described by the rest of the data on this line in the setsize file.
pathname Names a directory in which there are objects that will be installed or that
will require additional space. The name may be the mountpoint for a
filesystem. Names that do not begin with a slash (/) indicate relocatable
directories.
blocks
Defines the number of 512 byte disk blocks required for installation of
the files and directory entries contained in the pathname. (Do not
include filesystem-dependent disk usage).
inodes
Defines the number of inodes required for the installation of the files
and directory entries contained in the pathname.
At installation time, the set installation calls setsizecvt(l), which reduces the
setsize file for a set to a space(4) file containing entries for only the packages that
are selected. It is this resulting space(4) file against which space checking for the
set is performed.
EXAMPLE

# space required by packages in the Networking Set
inet:/usr/adm
46
2
nfs:/etc
197 17
SEE ALSO

setsizecvt(l), space(4)

197

shadow (4)
NAME

shadow - shadow password file
DESCRIPTION

letc/shadow is an access-restricted ASCII system file that contains an entry for each
user on the system. The fields within each entry are separated by colons; each entry
is separated from the next by a new-line. Unlike the letc/passwd file,
letc/shadow does not have general read permission.
Here are the fields in letc/shadow:

login_name
password

lastchanged
minimum
maximum
warn
inactive
expire

The name by which a user identifies himself or herself when logging in.
A 13-character encrypted password for the user, a lock string to
indicate the login is not accessible, or no string to show that there
is no password for the login.
The number of days between January I, 1970, and the date that the
password was last modified.
The minimum number of days required between password
changes.
The maximum number of days the password is valid.
The number of days before password expires that the user is
warned.
The number of days of inactivity allowed for that user.
An absolute date specifying when the login may no longer be
used.

flag
A character identifying a password generator.
The encrypted password consists of 13 characters chosen from a 64-character alphabet (., I, 0-9,A-Z, a-z).
To update this file, use the passwd, useradd, usermod, or userdel command.
FILES

letc/shadow
SEE ALSO

get spent (3C), login(I), passwd(I), passwd(4), putspent(3C), useradd(IM),
userdel(IM), usermod(IM)

198

sharetab ( 4 )
NAME

sharetab - shared file system table
DESCRIPTION

share tab resides in directory /ete/dfs and contains a table of local resources
shared by the share command.

Each line of the file consists of the following fields:

pathname resource fstype specific_options description
where

pathname
resource

Indicates the pathname of the shared resource.

fstype
specific _options

Indicates the file system type of the shared resource.

description

Is a description of the shared resource provided by the system administrator when the resource was shared.

Indicates the symbolic name by which remote systems can
access the resource.
Indicates file-system-type-specific options that were given to
the share command when the resource was shared.

SEE ALSO

share(lM)

199

space (4)
NAME

space - disk space requirement file
DESCRIPTION
space is an Ascn file that gives information about disk space requirements for the

target environment. It defines space needed beyond that which is used by objects
defined in the prototype file-for example, files which will be installed with the
installf command. It should define the maximum amount of additional space
which a package will require.
The generic format of a line in this file is:

pathname blocks inodes
Definitions for the fields are as follows:
path name Specifies a directory name which mayor may not be the mount point for
a filesystem. Names that do not begin with a slash (I) indicate relocatable directories.
blocks
Defines the number of disk blocks required for installation of the files
and directory entries contained in the pathname (using a 512-byte block
size).
inodes
Defines the number of inodes required for installation of the files and
directory entries contained in the pathname.
EXAMPLE
# extra space required by config data which is
# dynamically loaded onto the system
data 500 1
SEE ALSO

installf(lM), prototype(4)

200

Space.c(4)
NAME

Space. c - configuration-dependent kernel module data structure initializations
SYNOPSIS

Space.c
DESCRIPTION

One of the kernel configuration files, the Space. c file contains storage allocations
and initializations for data structures associated with a kernel module, when the
size or initial value of the data structures depend on configurable parameters, such
as the number of subdevices configured for a particular device or a tunable parameter. For example, the Space.c file gives a driver the ability to allocate storage only
for the subdevices actually being configured, by referencing symbolic constants
defined in the conf ig . h file.
When the Space.c component of a module's Driver Software Package (DSP) is
installed, idinstall(lM) stores the module's Space.c file information in
/etc/conf/pack.d/module-name/space.c, where module-name is the name of the
module being installed.
Package scripts should never access Space. c files directly; only the idinstall
command should be used.
The config.h file is a temporary file created in /etc/conf/cf.d during the system
reconfiguration process. The file contains #define statements that can be used to
specify the following information about the module:
Per module #defines:
#define
#define
#define
#define
#define

PRFX

PRFX_CNTLS
PRFX_UNITS
PRFX_CMAJORS
PRFX_CMAJOR_O

Set to 1 i f module is configured
NUmber of configured entries in System file
NUmber of subdevices (sum of unit fields)
Number of character major numbers supported
Character major numbers supported; the first
major is PRFX_CKAJOR_O, the second
PRFX_CMAJOR_1, and so forth

Per instance #defines (PRFX_o represents the first configured
instance, followed by PRFX_1, and so on if more than one
instance is configured):
#define
#define
#define
#define
#define
#define
#define
#define
#define

PRFX_O

PRFX_O_VECT
PRFX_O_T'iPE
PRFX_O_IPL
PRFX_O_SIOA
PRFX_O_EIOA
PRFX_O_SCMA
PRFX_O_ECMA
PRFX_O_CHAN

Unit field value
Interrupt vector used
Interrupt vector type
Interrupt priority level
Starting input/output address
Ending input/output address
Starting controller memory address
Ending controller memory address
DMA channel used (-1 i f none)

201

Space.c(4)
Since the module is installed as an object file, the module itself can not reference the
#defines for the configurable device parameters in config.h. However, the
module's Space.c is a C language source file, and as such, can define variables
which can take on the values of the #defines in config.h. When the next system
configuration is built, the idbuild(lM) command uses the list of arguments to
cc(l) defined in letclconf/cf .d/deflist to compile the module's Space.c file
before linking the module to the kernel.
NOTES

The following two #defines are generated for the Space. c file only if their values
are identical for all instances:
#define PRFX_CHAN
DMA channel used (-1 if none)
#define PRFX_TYPE
Interrupt vector type used
SEE ALSO

idbuild(lM). Master(4), System(4)
EXAMPLES

#include

1* tty structs for each device *1
1* output char watchdog timeout *1

struct strtty lp_tty[LP_CNTLS];
time_t last_time[LP_CNTLS];

struct lpcfg lpcfg[LP_CNTLS]
0,

LP_O_SIOA+O,
LP_0_SIOA+1,
LP_0_SIOA+2,
LP_O_VECT
#ifdef LP_1

{

1*
1*
1*
1*
1*

state *1
data register port address *1
status register port address *1
control register port address *1
interrupt vector *1

1* next structure *1
0,

LP_1_SIOA+O,
LP_1_SIOA+1,
LP_1_SIOA+2,
LP_1_VECT
#endif
1* LP_1 *1
#ifdef LP_2

202

Space.c(4)
/* next structure */
0,
LP_2_SIOA+O,
LP_2_SIOA+l,
LP_2_SIOA+2,
LP_2_VECT

#endif
} ;

203

stat(4)

(XENIX System Compatibility)

NAME

stat - (XENIX) data returned by stat system call
SYNOPSIS

#include
#include
DESCRIPTION

The system calls stat, lstat and fstat return data in a stat structure, which is
defined in stat. h:
struct

stat

{

dev_t
ioo_t
mode_t
nlink_t
uid_t
gid_t
dev_t
off_t
time_t
time_t
t~t

st_dev;
st_ioo;
st_mode;
st_nlink.;
st_uid;
st-9id;
st_Mev;
st_size;
st_atime;
st_mtime;
st_ctime;

};

The constants used in the st_mode field are also defined in this file:
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define

204

S_IFMT
S_IAMB
S_IFlFO
S_IFCHR
S_IFDIR
S_IFNAM
S_INSEH
S_INSBM
S_IFBLK
S_IFREG
S_IFLNK
S_ISUID
S_ISGID
S_ISVTX
S_IREAD
S_rwRlTE
S_IEXEC

OxFOOO
OxlFF
Oxl000
Ox2000
Ox4000
OxSOOO
Oxl

S_BNFMT

S_ISGID

S_IRWXU
S_IRUSR

00700
00400
00200
00100

S_IWOSR
S_IXUSR

0x2

Ox6000
Ox8000
OxAOOO
04000
02000
01000
00400
00200
00100

/* type of file */

/ * access mode bits */

/* fiio */

/ * character special */
/ * directory */
/ * XENIX special named file */
/ * XENIX semaphore subtype of IFNAM */
/ * XENIX shared data subtype of IFNAM */

/ * block special */

/ * regular */
/ * symbolic link */
/ * set user id on execution */
/ * set group id on execution */
/ * save swapped text even after use */
/ * read permission, owner */
/ * write permission, owner */

/ * execute / search permission, owner */

/ * record locking enforcement flag */
/ * read, write, execute: owner */
/ * read permission: owner */
/ * write permission: owner */
/ * execute permission: owner */

(XENIX System Compatibility)

#define
#define
#define
#define
#define
#define
#define
#define

S_IRWXG
S_IRGRP
S_IWGRP
S_IXGRP
S_IRWXO
S_IROTH
S_IWOTH
S_IXOTH

00070
00040
00020
00010
00007
00004
00002
00001

stat (4)

/ * read, write, execute: group */
/ * read permission: group */
/ * write permission: group */
/* execute permission: group */
/* read, write, execute: other */
/* read permission: other */
/* write permission: other */
/* execute permission: other */

SEE ALSO

stat(2), types(S)

205

stref (4)
NAME

strcf - STREAMS Configuration File for STREAMS TCP lIP
DESCRIPTION

/etc/strcf contains the script that is executed by slink(lM) to perform the
STREAMS configuration operations required for STREAMS Tep lIP.

The standard /etc/strcf file contains several functions that perform various
configuration operations, along with a sample boot function. Normally, only the
boot function must be modified to customize the configuration for a given installation. In some cases, however, it may be necessary to change existing functions or
add new functions.
The following functions perform basic linking operations:
The tp function is used to set up the link between a transport provider, such as Tep,
andIP.
#
# tp - configure transport provider (that is, tcp, udp, icmp)
# usage: tp devname
#

tp {

p = open $1
ip = open /dev/ip
link p ip

The linkint function links the specified streams and does a sifname operation
with the given name.
#
# linkint - link interface to ip or arp
# usage: linkint top bottom ifname
#

linkint {
x = link $1 $2
sifname $1 x $3
The aplinkint function performs the same function as linkint for an interface
that uses the app module.
#

# aplinkint - like linkint, but app is pushed on dev
# usage: aplinkint top bottom ifname
#
aplinkint {
push $2 app
linkint $1 $2 $3
}

206

strcf(4)
The following functions are used to configure different types of Ethernet interfaces:
The uenet function is used to configure an Ethernet interface for a cloning device
driver that uses the unit select ioctl to select the desired interface. The interface
name is constructed by concatenating the supplied prefix and the unit number.
#
# uenet - configure ethernet-type interface for cloning driver using
#
unit select
# usage: uenet ip-fd devname ifprefix unit
#

uenet {
ifname = strcat $3 $4
dev = open $2
unitsel dev $4
aplinkint $1 dev ifname
dev = open $2
unitsel dev $4
arp = open /dev/arp
linkint arp dev ifname
The denet function performs the same function as uenet, except that DL_ATTACH is
used instead of unit select.
#
# denet - configure ethernet-type interface for cloning driver using
DL_ATTACH
#
# usage: denet ip-fd devname ifprefix unit
#
denet {
ifname = strcat $3 $4
dev = open $2
dlattach dev $4
aplinkint $1 dev ifname
dev = open $2
dlattach dev $4
arp = open /dev/arp
linkint arp dev ifname

The cenet function is used to configure an Ethernet interface for a cloning device
driver that uses a different major number for each interface. The device name is
formed by concatenating the supplied device name prefix and the unit number.
The interface name is formed in a similar manner using the interface name prefix.
#
# cenet - configure ethernet-type interface for cloning driver with

one major per interface

# usage: cenet ip-fd devprefix ifprefix unit
#

cenet {
devname

strcat $2 $4
207

strcf(4)
ifname = strcat $3 $4
dey = open devname
aplinkint $1 dey ifname
dey = open devname
arp = open /dev/arp
linkint arp dey ifname
}

The senet function is used to configure an Ethernet interface for a non-cloning
device driver. Two different device nodes must be specified for IP and ARP.
#
# senet - configure ethernet-type interface for non-cloning driver
# usage: senet ip-fd ipdevname arpdevname ifname

#
senet {
dey = open $2
aplinkint $1 dey $4
dey = open $3
arp = open /dev/arp
linkint arp dey $4
}

The senetc function is like senet, except that it allows the specification of a convergence module to be used with the Ethernet driver (such as, for the 3B2 emd
driver).
#
# senetc - configure ethernet-type interface for non-cloning driver
#
using convergence module
# usage: senetc ip-fd convergence ipdevname arpdevname ifname
#

senetc {
dey = open $3
push dey $2
aplinkint $1 dey $5
dey = open $4
push deY $2
arp = open /dev / arp
linkint arp dey $5
}

The loopback function is used to configure the loopback interface.
#
# loopback - configure loopback device

# usage: loopback ip-fd
#
loopback
dey = open /dev/loop
linkint $1 dey 100
}

208

strcf(4)
The slip function is used to configure a SLIP interface. This function is not normally executed at boot time.

#
# slip - configure slip interface
# usage: slip unit
#

slip
ip = open /dev/ip
s = open /dev/slip
ifname = strcat sl $1
unitsel s $1
linkint ip s ifname
}

The boot function is called by default when slink is executed. Normally, only the
interfaces section and possibly the queue params section will have to be customized
for a given installation. Examples are provided for the various Ethernet driver
types.
#

# boot - boot time configuration
#

boot {
#

# queue params
#
#

initqp /dev/udp rq 8192 40960
initqp /dev/ip muxrq 8192 40960 rq 8192 40960
#

# transport
#
tp /dev/tcp
tp /dev/udp
tp /dev/icnq;>
tp /dev/rawip
FILES

/etc/strcf
SEE ALSO

slink(lM)

209

strftime (4)
NAME

strftime - language-specific strings
DESCRIPTION

There can exist one printable file per locale to specify its date and time formatting
information.
These
files
must
be
kept
in
the
directory
/usr/lib/locale//LC_TIME. The contents of these files are:
1. abbreviated month names (in order)
2. month names (in order)
3. abbreviated weekday names (in order)
4. weekday names (in order)
5. default strings that specify formats for locale time (%X) and locale date (%x)
6. default format for cftime, if the argument for cftime is zero or null
7. ante meridian string
8. post meridian string
9. default format for date command output
Each string is on a line by itself. All white space is significant. The order of the
strings in the above list is the same order in which they must appear in the file.
EXAMPLE

Here are the contents of /usr/lib/locale/C/LC_TIME:
Jan

Feb
January

February
Sun
Mon

Sunday
Monday
%H:'%M:%S
%m/%d/%y
%a %b %d %T %Z %Y
AM
PM

%a %b %d %T %Z %Y

FILES

/usr /lib/locale/ /LC_TIME
SEE ALSO

ctime(3C), setlocale(3C), strftime(3C)

210

Stubs.c (4)
NAME

Stubs. c - stubs for kernel module symbols
SYNOPSIS

Stubs.c
DESCRIPTION

One of the kernel configuration files, a Stubs. c file is an optional C language
source file that can be installed and compiled into the system as a "place holder"
for a kernel module that will not be installed in the system. Its purpose is to enable
the kernel to resolve references to the absent module's symbols.
When the Stubs.c component of a module's Driver Software Package (DSP) is
installed, idinstal1(lM) stores the module's Stubs. c file information in
/etc/conf/pack.d/module-name/stubs.c where module-name is the name of the
module being installed. Package scripts should never access Stubs. c files directly;
only the idinstall command should be used.
A module's Stubs.c file contains function name and variable definition stubs for
symbols defined in the module that can be referenced by other kernel modules
being configured into the system. At compile time, the definitions in the Stubs. c
file give the kernel the ability to resolve references made to the absent module's
symbols.
SEE ALSO

idinstal1(lM)

211

stune(4)
NAME

stune -local system settings for tunable parameters
SYNOPSIS
stune
stune. current
DESCRIPTION
The /etc/conf/cf .d/stune file contains tunable parameters for the kernel
modules to be configured into the next system to be built [see idbuild(lM)]. The
parameter settings in the stune file are used to override the default values specified
in the Mtune file.

The cohtents of the stune file will only affect the next kernel rebuild. Once the new
kernel has been installed to / stand and booted, the stune file is copied to
stune. current. Any change made to the stune. current file using the
idtune(lM) command with the -c option will affect all the loadable kernel
modules subsequently configured into the running system.
Package
scripts
should
never
access
/etc/conf/cf.d/stune
or
/etc/conf/cf.d/stune.current files directly; only the idtune(lM) command
should be used.
The stune and stune. current files contain one line for each parameter to be set.
Each line contains two positional fields separated by white space:

parameter-name new-value
Blank lines and lines beginning with 'I' or '.' are considered comments and are
ignored.
The stune and stune. current fields are:
parameter-name The name of the tunable parameter, as defined in the Mtune file.
new-value
Specifies the new value to be used to override the default value
specified for this tunable parameter in the Mtune file. This value
must fall within the valid range of values specified for this parameter in the Mtune file.
For detailed information on stune parameters, refer to the advanced features sections on tunable parameters in your system administration documentation.
SEE ALSO

idbuild(lM), idtune(lM), Mtune(4)

212

su(4)
NAME

su - su options file
DESCRIPTION

Options for the su command [see su(lM)] can be set or changed with keywords in
Jete/default/suo The following keywords are recognized by su:

SOLOG=filename

Log (in filename) successful and unsuccessful attempts to execute su.

CONSOLE=device

If a user executes su to become a privileged user on a device
other than device, a printed message will appear on device to
inform the administrator of that fact.

PATH=path Jist

When a user executes su to become an unprivileged user, the
user's path will be set to pathJist. The default is
/usr/bin:/usr/ees/bin.

SOPATH=path Jist

When a user executes su to become a privileged user, the
user's path will be set to path_list. The default is
/sbin:/usr/sbin:/usr/bin:/ete:/usr/ees/bin.

PROMPT:

If this parameter exists and is set to No, the su command does
not prompt for a password (even if one is defined for
login_name). The invoking user, however, must still have
appropriate privilege to execute su successfully. If this
parameter does not exist, or is set to anything other than No
(including NULL), su prompts for a password when invoked
and validates the password (if one is defined for login_name).

FILES

/ete/default/su
SEE ALSO

su(lM)

213

syslog.conf (4)

(BSO System Compatibility)

NAME

syslog. conf - (BSD) configuration file for syslogd system log daemon
SYNOPSIS

/etc/syslog.conf
DESCRIPTION

The file /etc/syslog.conf contains information used by the system log daemon,
syslogd(lM), to forward a system message to approp~iate log files and/or users.
syslog preprocesses this file through m4(1) to obtain the correct information for
certain log files.
A configuration entry is composed of two TAB-separated fields:

"selector
action"
The selector field contains a semicolon-separated list of priority specifications of the
form:

facility •level [ i facility .level]
where facility is a system facility, or comma-separated list of facilities, and level is an
indication of the severity of the condition being logged. Recognized values for facility include:
user

Messages generated by user processes. This is the default priority for
messages from programs or facilities not listed in this file.

kern
mail

Messages generated by the kernel.
The mail system.

daemon

System daemons, such as ftpd(lM), routed(lM), and so on.

auth

The authorization system: login(l), su(lM), getty(lM), and so on.

lpr

The line printer spooling system: lpr(l), lpc(lM), and so on.

news

Reserved for the USENET network news system.

uucp

Reserved for the UUCP system; it does not currently use the syslog
mechanism.

cron

The cron/at facility; crontab(l), at(l), cron(lM), and so on.

localO-7 Reserved for local use.
mark

For timestamp messages produced internally by syslogd.

An asterisk indicates all facilities except for the mark facility.

Recognized values for level are (in descending order of severity):

214

emerg

For panic conditions that would normally be broadcast to all users.

alert

For conditions that should be corrected immediately, such as a
corrupted system database.

crit

For warnings about critical conditions, such as hard device errors.

err

For other errors.

(BSD System Compatibility)

warning
notice
info
debug
none

syslog.conf (4)

For warning messages.
For conditions that are not error conditions, but may require special
handling.
Informational messages.
For messages that are normally used only when debugging a program.
Do not send messages from the indicated facility to the selected file. For
example, a selector of
*.debug;mail.none

will send all messages except mail messages to the selected file.
The action field indicates where to forward the message. Values for this field can
have one of four forms:
A filename, beginning with a leading slash, which indicates that messages
specified by the selector are to be written to the specified file. The file will be
opened in append mode.
The name of a remote host, prefixed with an @, as with: @server, which indicates that messages specified by the selector are to be forwarded to the
syslogd on the named host.
A comma-separated list of usernames, which indicates that messages
specified by the selector are to be written to the named users if they are
logged in.
An asterisk, which indicates that messages specified by the selector are to be
written to all logged-in users.
Blank lines are ignored. Lines for which the first nonwhite character is a '#' are
treated as comments.
EXAMPLE

With the following configuration file:
*.notice;mail.info
*.crit
kern, mark. debug
kern. err
*.emerg
*.alert
*.alert;auth.warning

/var/log/notice
/var/log/critical
/dev/console
@server
*
root, operator
/var/log/auth

syslogd will log all mail system messages except debug messages and all notice
(or higher) messages into a file named /var/log/notice. It logs all critical
messages into /var/log/critical, and all kernel messages and 20-minute marks
onto the system console.

Kernel messages of err (error) severity or higher are forwarded to the machine
named server. Emergency messages are forwarded to all users. The users root and
operator are informed of any alert messages. All messages from the authorization
system of warning level or higher are logged in the file /var/log/auth.

215

syslog.conf ( 4 )

(BSD System Compatibility)

FILES

/etc/syslog.conf
SEE ALSO

at{l), cron{lM), crontab{l), getty(lM), login{l), lp{l), m4(1), syslog(3),
syslogd{lM), su{lM)

216

System(4)
NAME

System - system-specific configuration information for a kernel module
SYNOPSIS

System
DESCRIPTION

One of the ID jTP kernel configuration files, a System file contains information
needed to incorporate a particular kernel module into the next system
configuration. General configuration information about the module type is
described in the Master file. When the System component of a module's Driver
Software Package (DSP) is installed, idinstall(lM) stores the module's System
file information in /etc/conf/sdevice.d/module-name, where the file module-name
is the name of the module being installed. Package scripts should never access
System files directly; only the idinstall and idcheck(lM) commands should be
used.
System files typically contain data in the following format:
$version version-number
$loadable module-name

module-name configure unit ipl itype ivec sioa eioa scma ecma dmachan
Blank lines and lines beginning with
ignored.

'fj:'

or '.' are considered comments and are

The first two entries are described as follows:
$version

If present in the file, this line must appear as the first noncomment line. The line specifies the version number of the System file format. The System file format being described here is
version 1. If this line is omitted, version 0 (the old sdevice file
format) is assumed.

$loadable

Indicates that the module is to be configured as a loadable
module [see modadmin(lM)].
This line is used for dynamically loadable kernel modules only.
When the line is present in the file:
The module-name specified on the $loadable line must
match the module-name specified in the first field of each
instance line of this file.
At least one instance of the module must specify the value
"y" in the configure field.
The module must be coded in loadable form (requires
creation of speCial initialization "wrapper" code for loadable modules).
To statically link a loadable module to the base kernel, the
module's $loadable line should be commented out by inserting
the character fj: in column one.

217

System (4)
The third type of entry in the System file contains configuration information for
each instance of the module. For example, if two instances of a device were to be
configured, the device would require two lines of System file definitions.
The third entry type contains the following 11 fields. Each field must be delimited
by white space and specify a value. Note that, except for the first two fields
(module-name and configure), the remaining fields on this line are used for
hardware-related modules only. That is, these fields apply to modules that have b,
c, or h chiJracteristics flags set in their Master files (one exception to this is exec
modules, described below). In cases where a field does not apply to the moduleregardless of the module type-the unused field must contain the value 0 (an
unused dmachan field must contain the value -1).

218

module-name

Identifies the internal name of the module. The field value must
match the module name specified in the module's Master file.

configure

Indicates (Y or N) whether idbuild(lM) should configure this
instance of the module into the system. Note that this field can be
used to configure statically linked modules or to configure
dynamically loadable modules.

unit

This field can be used to encode an arbitrary, module-dependent
numeric value. The field is typically used to specify the number
of subdevices attached to a controller or pseudo device. If this
field is not used it should contain the value O.

ipl

This field specifies the interrupt priority level for the device controlled by this module, and the priority at which the module's
interrupt handler will run. Valid values are 1 (lowest priority) to
7 (highest priority); priority 8 is reserved for the clock tick interrupt. If the module is not a hardware module or does not have
an interrupt handler, this field should contain the value O.

itype

Indicates the type of interrupt sharing (if any) this hardware
module supports. Note that if a module supports a number of
interrupt schemes, it will require multiple system lines, with each
line specifying a different itype field value.
Valid values are:

This instance of the device does not use interrupts.

This instance of the device uses an interrupt vector which
cannot be shared, not even with another instance of the
same module.

This instance of the device uses an interrupt vector which
can be shared with another instance of the same module,
but can not be shared with other modules.

This instance of the device uses an interrupt vector which
can be shared with any instance of any hardware
modules.

System (4)
4

This instance of the device uses an EISA level-sensitive
interrupt vector which can be shared with any instance of
any hardware module.

If this field is not used it should contain the value

vector

Specifies the interrupt vector number used by this instance of the
device. Valid values are a decimal number from 0 through the
value of the highest interrupt vector number supported by the
system. If the itype field specifies 0 (no interrupts used), this field
should also specify o.
Note that more than one device can share an interrupt vector
number if the devices use the same itype interrupt, and that interrupt is of a type that can be shared. Note also that every instance
of every module that shares an interrupt vector number must
specify the same ipl values. If this field is not used it should contain the value o.

sioa

The start I/O address field. Specifies the lowest I/O port address
through which the device communicates. Valid values are a hexadecimal number from 0 through FFFF. For non-hardware
modules or devices without I/O ports, this field should contain
the value o.

eioa

The end I/O address field. Specifies the highest (inclusive) I/O
port address through which the device communicates. Valid
values are a hexadecimal number from 1 through FFFF. Note
that the value of the eioa field must be greater than or equal to the
value of the sioa field. For non-hardware modules or devices
without I/O ports, this field should contain the value o.
The start memory controller address field. Specifies the lowest
address in memory through which the device communicates.
Valid values are a hexadecimal number from 10000 through
FFFFFFFF. For non-hardware drivers or devices without controller memory, this field should contain the value O.

sema

eema

The end memory controller address field. Specifies the highest
(inclusive) address in memory through which the device communicates. Valid values are a hexadecimal number from 10000
through FFFFFFFF. Note that the value of the eema field must be
greater than or equal to the value of the sema field. For nonhardware modules or devices without controller memory, this
field should contain the value O.

dmaehan

For hardware modules that use DMA channels, this field specifies
the DMA channel number. Valid values are a decimal number
from 0 through 7. For non-hardware modules or devices that
don't use DMA, this field should contain the value-1.

219

System (4)
NOTES

Specifying exec Modules

For exec object-specific modules used to support various executable file formats
(modules with e characteristic flags set in their Master files, two System file fields
have special meanings:
The unit field specifies the number of magic numbers supported by the
module. Magic numbers are the first two bytes of an executable file, which
are used to dispatch to the appropriate exec module. The module is responsible for defining an array of type short to hold the magic numbers. This
array must be called xxxmagic, where xxx is the module's prefix, as defined
in the Master(4) file. All of the execsw entries are processed in order,
according to the order field of the Master file, calling the appropriate
handlers if the magic number matches, until one returns 0 for success or an
error other than ENOEXEC.
The itype field controls whether a wild card execsw entry should be generated for the module. If itype is non-zero, an additional entry will be generated for the module, following the entries for the explicit magic numbers.
This additional entry will have a NULL magic number pointer. This tells
the system to call the handler no matter what the magic number is.
Compatibility Considerations

For compatibility with existing add-on DSP packages, idinstall also accepts the
old (version 0) sdevice file format, which it converts to version 1 format before installing the file in /etc/conf/sdevice.d. Since the version 1 System file format
now includes the dmachan field that formerly appeared in the version 0 mdevice
file, version 0 sdevice files and version 0 mdevice files must be installed together,
using a single invocation of the idinstall command. This allows idinstall to
move the dmachan field from the module's mdevice file to its System file during
conversion.
Because cross-dependencies exist in the version 0 mdevice and sdevice files for
exec modules, idinstall cannot convert these files to version 1 files. They must be
converted manually before using idinstall.
Note that idinstall also accepts obsolete sfsys files and converts them to version
1 System file format.
SEE ALSO

idbuild(lM), idcheck(lM), idinstall(lM), Master(4)

220

tc.index (4)
NAME

tc. index - configuration index file for mass-storage devices
DESCRIPTION

The tc. index file provides the correlation between device-specific inquiry strings
and the files used by pdimkdev, pdimkdtab, and disksetup to control their execution. If no matching inquiry string is found in tc. index, generic entries found at
the end of the file are used.
The generic entries should be sufficient for most types of mass-storage devices.
Before spending time to generate a device-specific entry for a new mass-storage
device, you should try the existing generic entry. If the generic entry works, no
device-specific entry is required.
File Format
tc. index is a plain-text file consisting of keywords/value pairs. Keywords start in
column 1. The value of a keyword is the rest of the text line after the keyword and
any white space. A keyword/value pair must be separated by white space, either
spaces or tabs. By convention, the value is separated from the keyword by a single
tab. The device-specific entries in this file must be first, before any generic entries.

Keywords

The following keywords are recognized in tc. index:
TCINQ

MKDEV

Marks the beginning of a device-specific entry in the tc. index file.
The remainder of this entry consists of the lines in the file after this
keyword, up to the next TCINQ or GENERIC keyword.
The inquiry string for the device in question must be duplicated
character-by-character as the value of this keyword. Embedded
spaces, special characters and the case of letters are all significant.
The first 8 characters of the inquiry string represent the vendor
identification string. The next 16 characters represent the product
name. Taken together, these 24 characters are considered the inquiry
string.
Used by pdimkdev and pdimkdtab, the name of the template file to
use to create device nodes and device table entries for this device.

FORMAT

Used by disksetup and diskformat, the name of the format
specification file to use when preparing this device for use by the
system.

GENERIC

Marks the beginning of an entry that will be used for a given type of
device if no device-specific entry is found. Generic entries are
currently provided for random, sequential, CD-ROM and WORM
devices. The keyword values for each of these device types are,
respectively, RANDOM, TAPE, ROM, and WORM. This remainder of this
entry consists of the lines in the file after this keyword up to the next
GENERIC keyword or until the end-of-file.

Used to imbed comments in the tc. index file.

221

tc.index (4 )
REFERENCES
diskadd(lM), disksetup(lM), pdimkdev(lM), pdimkdtab(lM)

222

term (4)
NAME

term - format of compiled term file
SYNOPSIS

/usr/lib/share/terminfo
DESCRIPTION

Compiled terminfo(4) descriptions are placed under the directory
/usr/share/lib/terminfo. In order to avoid a linear search of a huge UNIX system directory, a two-level scheme is used: /usr/share/lib/terminfo/c/name
where name is the name of the terminal, and c is the first character of name. Thus,
att4425 can be found in the file /usr/share/lib/terminfo/a/att4425.
Synonyms for the same terminal are implemented by multiple links to the same
compiled file.
The format has been chosen so that it is the same on all hardware. An 8-bit byte is
assumed, but no assumptions about byte ordering or sign extension are made.
Thus, these binary terminfo files can be transported to other hardware with 8-bit
bytes.
Short integers are stored in two 8-bit bytes. The first byte contains the least
significant 8 bits of the value, and the second byte contains the most significant 8
bits. (Thus, the value represented is 256*second+first.) The value -1 is represented
by 0377,0377, and the value -2 is represented by 0376,0377; other negative
values are invalid. The -1 generally means that a capability is missing from this terminal. The -2 means that the capability has been canceled in the terminfo source
and also is to be considered missing.
The compiled file is created from the source file descriptions of the terminals (see
the -I option of infocmp) by using the terminfo compiler, tic, and read by the
routine setupterm [see curses(3curses).] The file is divided into six parts in the
following order: the header, terminal names, boolean flags, numbers, strings, and
string table.
The header section begins the file. This section contains six short integers in the format described below. These integers are (1) the magic number (octal 0432);
(2) the size, in bytes, of the names section; (3) the number of bytes in the boolean
section; (4) the number of short integers in the numbers section; (5) the number of
offsets (short integers) in the strings section; (6) the size, in bytes, of the string table.
The terminal names section comes next. It contains the first line of the terminfo
description, listing the various names for the terminal, separated by the bar ( I )
character (see term(5)). The section is terminated with an ASCII NUL character.
The boolean flags have one byte for each flag. This byte is either 0 or 1 as the flag is
present or absent. The value of 2 means that the flag has been canceled. The capabilities are in the same order as the file .
Between the boolean section and the number section, a null byte is inserted, if
necessary, to ensure that the number section begins on an even byte offset. All
short integers are aligned on a short word boundary.

223

term (4)
The numbers section is similar to the boolean flags section. Each capability takes up
two bytes, and is stored as a short integer. If the value represented is -1 or -2, the
capability is taken to be missing.
The strings section is also similar. Each capability is stored as a short integer, in the
format above. A value of -lor -2 means the capability is missing. Otherwise, the
value is taken as an offset from the beginning of the string table. Special characters
in AX or \c notation are stored in their interpreted form, not the printing representation. Padding information ($ am, lines #24,
home=\Eeh,
The first line, commonly referred to as the header line, must begin in column one
and must contain at least two aliases separated by vertical bars. The last field in the
header line must be the long name of the device and it may contain any string.
Alias names must be unique in the terminfo database and they must conform to
UNIX system file naming conventions [see tic(lM)]; they cannot, for example, contain white space or slashes.
Every device must be assigned a name, such as "vt100". Device names (except the
long name) should be chosen using the following conventions. The name should
not contain hyphens because hyphens are reserved for use when adding suffixes
that indicate special modes.
These special modes may be modes that the hardware can be in, or user preferences. To assign a special mode to a particular device, append a suffix consisting of
a hyphen and an indicator of the mode to the device name. For example, the -w
suffix means "wide mode"; when specified, it allows for a width of 132 columns
instead of the standard 80 columns. Therefore, if you want to use a vt100 device set
to wide mode, name the device "vt100-w." Use the following suffixes where possible.

226

terminfo (4)
Suffix

Meaning

-w
-am
-nam

Wide mode (more than 80 columns)
With auto. margins (usually default)
Without automatic margins
Number of lines on the screen
No arrow keys (leave them in local)
Number of pages of memory
Reverse video

-n
-na
-np
-rv

Example
5410-w
vt100-am
vt100-nam
2300-40
c100-na
c100-4p
4415-rv

The terminfo reference manual page is organized in two sections: "DEVICE
CAPABILITIES" and "PRINTER CAP ABILITIES."
PART 1: DEVICE CAPABILITIES
Capabilities in terminfo are of three types: Boolean capabilities (which show that a

device has or does not have a particular feature), numeric capabilities (which quantify particular features of a device), and string capabilities (which provide
sequences that can be used to perform particular operations on devices).
In the following table, a Variable is the name by which d c programmer accesses a
capability (at the terminfo level). A Capname is the short name for a capability
specified in the terminfo source file. It is used by a person updating the source file
and by the tput command. A Termcap Code is a two-letter sequence that
corresponds to the te:r:mcap capability name. (Note that te:r:mcap is no longer
supported.)
Capability names have no real length limit, but an informal limit of five characters
has been adopted to keep them short. Whenever possible, capability names are
chosen to be the same as or similar to those specified by the ANSI X3.64-1979
standard. Semantics are also intended to match those of the ANSI standard.
All string capabilities listed below may have padding specified, with the exception
of those used for input. Input capabilities, listed under the Strings section in the
following tables, have names beginning with key_. The #i symbol in the description field of the following tables refers to the ith parameter.
Booleans
Variable

Capname

Termcap
Code

auto_left_margin

auto_right_margin
back_color_erase
can_change

eeol_standout~liteh

bee
cce
xhp

ec
xs

eol_addr~liteh

xhpa

cpi_changes_res

cpix

cr_cancels_mdcro_mode

enan

Description
cubl wraps from column 0 to
last column
Terminal has automatic margins
Screen erased with background color
Terminal can re-define existing color
Standout not erased by overwriting (hp)
Only positive motion for hpa/mhpa caps
Changing character pitch changes
resolution
Using er turns off micro mode

227

terminfo ( 4)

Variable

Capname

Termcap
Code

eat_newline~litch

xenl

XII

erase_overstrike
generic_type
hard_copy
hard_cursor
has_meta_key
has-print_wheel

hc
chts

hc
HC

kin

daisy

has_status_Iine
hue_Iightness_saturation

hs
hI

insert_null~litch

in
lpix
da

hls

lpi_changes_res
memo:ty_above
memo:ty_below
move_insert_mcde
move_standout_mode
needs_xon_xcff
no_esc_ctlc
non_rev_=p
no-.psd_char
over_strike

mir
msgr
nxon
xsb

mi
ms
rue
xb

nrllllC

npc

prtr_silent

mcSi

row_addr~litch

xvpa

semi_auto_right_margin
status_Iine_esc_ok
dest_tabs_magic_SDlSo

sam
eslok

tilde~litch

transparent_underline
xcn_xoff

ul
xon

ul
xc

Description
Newline ignored after 80 columns
(Concept)
Can erase overstrikes with a blank
Generic line type (e.g., dialup, switch)
Hardcopy terminal
Cursor is hard to see
Has a meta key (shift, sets parity bit)
Printer needs operator to change
character set
Has extra "status line"
Terminal uses only HLS color
notation (Tektronix)
Insert mode distinguishes nulls
Changing line pitch changes resolution
Display may be retained above the screen
Display may be retained below the screen
Safe to move while in insert mode
Safe to move in standout modes
Padding won't work, xon/xoff required
Beehive (£1 =escape, f2=ctrl C)
smcup does not reverse llIICUP
Pad character doesn't exist
Terminal overstrikes on hard-copy
terminal
Printer won't echo on screen
Only positive motion for vpa/lIIIIP'l caps
Printing in last column causes cr
Escape can be used on the status line
Destructive tabs, magic SDlSO char (tl061)
Hazeltine; can't print tilde
Underline character overstrikes
Terminal uses xon/xoff handshaking

Numbers

228

Variable

Capname

Termcap
Code

buffer_capacity
buttons
columns
dot_vert_spacing
dot_horz_spacing
init_tabs
label_height
label_width

bufsz
btns
cols
spinv
spinh
it
lh
lw

Ya
BT

co
Yb

Yc
it
lh
lw

Description
Number of bytes buffered before printing
Number of buttons on the mouse
Number of columns in a line
Spacing of pins vertically in pins per inch
Spacing of dots horizontally in dots per inch
Tabs inltially every # spaces
Number of rows in each label
Number of columns in each label

terminfo (4)

Variable
lines
lines_of_memory
magic_cookie-91itch

Capname

Termcap
Code

lines

XlIIC

colors
maddr
mjump
pairs

Co
Yd
Ye
pa

mes
mls

yf
Yg

ncv

Description
Number of lines on a screen or a page
Lines of memory if> lines; 0 means varies
Number of blank characters left by
smso or rmso

max_colors
max_micro_address
max_micro--.:jump
max-Pairs
micro col_size

micro_line_size
no_color_video

number_ofJ>ins
nUlILlahels
output_res_char
output_res_line
output_res_horz_inch
output~es_vert_inch

padding_baud_rate
virtual_terminal
wide_char_size

npins

nlab
orc
orl
orhi
orvi

Maximum number of colors on the screen
Maximum value in micro_ ., ._address
Maximum value in parnL ... _micro
Maximum number of color-pairs on the
screen
Character step size when in micro mode
Line step size when in micro mode
Video attributes that can't be used
with colors
Number of pins in print-head
Number of labels on screen (start at 1)
Horizontal resolution in units per character
Vertical resolution in units per line
Horizontal resolution in units per inch
Vertical resolution in units per inch
Lowest baud rate where padding needed
Virtual terminal number (UNIX system)
Character step size when in double
wide mode
Number of columns in status line

Yi
Yj
Yk

Yl
pb

widcs

wel

Strings
Capname

Termcap
Code

acs_chars
alt_scancode_esc

acsc

scesca

back_tab
bell

cbt
bel
birep
binel
bicr
cr
cpi
Ipi
chr

bt
bl
Zy
Zz
Yv
cr

Variable

bit_image~epeat

bit_image_newline
bit_image_carriage_return
carriage_return
change_charJ>itch
change_lineJ>itch
change_res_horz
change_res_vert
change_scroll_region
charJ)adding
char_set_names

cvr

csr
DIP

csnm

ZB
ZC
ZD
cs
rP
Zy

Description
Graphic charset pairs aAbBcC
Alternate escape for scancode emulation
(default is for vt100)
Back tab
Audible signal (bell)
Repeat bit-image cell #1 #2 times (use tparm)
Move to next row of the bit image (use tparm)
Move to beginning of same row (use tparm)
Carriage return
Change number of characters per inch
Change number of lines per inch
Change horizontal resolution
Change vertical resolution
Change to lines #1 through #2 (vt100)
Like ip but when in replace mode
List of character set names

229

terminfo (4 )

Variable

Capname

Termcap
Code

clear all_tabs
clear_margins

tbc
mgc

clear_screen
clr_bol
clr_eol
cIr_6os
code set_init
color_names
column_address
command_character

clear
ell
el
ed

cursor_address
cursor_down
cursor_home
cursor_invisible
cursor_left
cursor_mem_address
cursor_nonnal

cup
cud1
home

civis
cub1
mrcup

cl
cb
ce
cd
ci
Yw

ch
CC

em
do
ho
vi
Ie
CM

cnonn

cursor_right

cufl

cursor_to_11
cursor_up
cursor_visible
define_bit_image_region

cuu1
cvvis
defbi

11
up
vs

define_char
delete_character
delete_line
device_type
dis_status_line
display-pc_char
down_half_line
ena_aes
end_bit_image_region
enter_alt_charset_mode
enter_am_mode
enter_blink_mode
enter_bold_mode
enter_ca_mode
enter_delete_mode
enter_dim_mode
enter_doublewide_mode
enter_draft_quality

230

cain

colo=
hpa
cmdch

defc
dch1
dll
devt
dsl
dispc
hd
enacs
endbi
emacs

dc
dl
dv
ds
Sl
hd
eA

Yy
as

SlIlallI

blink
bold
smcup
smdc
dim
swidIn
sdrfq

mb
rod

ti
dIn
mh

ZF
ZG

Description
Clear all tab stops
Clear all margins (top, bOllom,
and sides)
Clear screen and home cursor
Clear to beginning of line, inclusive
Clear to end of line
Clear to end of display
!nit sequence for multiple codesets
Give name for color #1
Horizontal position absolute
Terminal sellable cmd character
in prototype
Move to row #1 col #2
Down one line
Home cursor (if no cup)
Make cursor invisible
Move left one space.
Memory relative cursor addressing
Make cursor appear normal
(undo vs/vi)
Non-destructive space (cursor or
carriage right)
Last line, first column (if no cup)
Upline (cursor up)
Make cursor very visible
Define rectangular bit-image region
(use tpann)
Define a character in a character set t
Delete character
Delete line
Indicate language/ codeset support
Disable status line
Display PC character
Half-line down (forward 1I2linefeed)
Enable alternate character set
End a bit-image region (use tpann)
Start alternate character set
Turn on automatic margins
Turn on blinking
Turn on bold (extra bright) mode
String to begin programs that use cup
Delete mode (enter)
Turn on half-bright mode
Enable double wide printing
Set draft quality print

terminfo (4)

Variable
enter_insert_mode
enter_italics_mode
enter_leftward_mode
enter_micro_mode
enter_near_letter_~lity
enter_normal_~lity

enter-pc_charset_mode
enter-protected_mode
enter_reverse_mode
enter_scancode_mode
enter_secure_mode
enter_shadow_mode
enter_standout_mode
enter_subscript_mode
enter_superscript_mode
enter_UDderline_mode
enter_upward_mode
enter_xon_mode
erase_chars
exit_alt_cbarset_mode
exit_am_mode
exit_attribute_mode
exit_ca_mode
exit_delete_mode
exit_douhlewide_mode
exit_insert_mode
exit_italics_mode
exit_leftward_mode
exit_micro_mode
exit-pc_charset_mode
exit_scancode_mode
exit_shadow_mode
exit_standout_mode
exit~Ubscript_mode

exit_superscript_mode
exit_UDderline_mode
exit_upward_mode
exit---""",_mode
flash_screen
form_feed
from~tatus_line

get_mouse

Capname

Termcap
Code

smir
sitm
s1m
smicm
snlq
snrmq
smpch
prot
rev
smsc
invis

ZI
ZJ
ZK

sa
mp

mr
S4
mk

ssbIn
smso
ssutm
ssupm
SIIlUl
sum

zo
us
zp

smxon

ech
rmacs

ec
ae

so
ZN

rmam

sgrO
rmcup
nndc
rwidm
rmir
ritm
rlm

rmicm
rmpch
:mISC

rsbIn
rmso
rsubm
rsupm

te
ed
ZQ

ei
ZR
ZS
ZT
S3
S5
ZU

rum

rmxon

flash
ff
fsl
getm

vb
ff
fs
GIn

Description
Insert mode (enter)
Enable italics
Enable leftward carriage motion
Enable micro motion capabilities
Set near-letter quality print
Set normal quality print
Enter PC character display mode
Tum on protected mode
Tum on reverse video mode
Enter PC scancode mode
Turn on blank mode
(characters invisible)
Enable shadow printing
Begin standout mode
Enable subscript printing
Enable superscript printing
Start underscore mode
Enable upward carriage motion
Tum on xon/xoff handshaking
Erase #1 characters
End altemate character set
Tum off automatic margins
Tum off all attributes
String to end programs that use cup
End delete mode
Disable double wide printing
End insert mode
Disable italics
Enable rightward (normal)
carriage motion
Disable micro motion capabilities
Disable PC character display mode
Disable PC scancode mode
Disable shadow printing
End standout mode
Disable subscript printing
Disable superscript printing
End underscore mode
Enable downward (normal)
carriage motion
Tum off xon/xoff handshaking
Visible bell (may not move cursor)
Hardcopy terminal page eject
Retum from status line
Curses should get button events

231

terminfo(4)

Variable

Capname

Termcap
Code

init_lstricg

isl

init_2stricg
init_3stricg

is2

is3

init_file
init-prog

if
iprog

if
iP

initialize_color

initc
initp

ielll
ill
ip

ic
al
ip

initialize-.Pair
insert_character
insert_line
insert~

Description
Terminal or printer initialization string
Terminal or printer initialization string
Terminal or printer initialization string
Name of initialization file
Path name of program for initialization
Initialize the definition of color
Initialize color-pair
Insert character
Add new blank line
Insert pad after character inserted

The "key_" strings are sent by specific keys. The "key-" descriptions include the
macro, defined in curses.h, for the code returned by the curses routine getch
when the key is pressed [see curs--9"etch(3curses)].
key_al

kal

key_a3
key_b2

ka3

KEY_Al, upper left of keypad
KEY_A3, upper right of keypad

kb2

KEY_52, center of keypad

key_backspace

kbs

KEY_BACKSPACE, sent by backspace key

key-beg
key_btab

kbeg

kb
@l

KEY_BEG, sent by beg(inning) key
KEY_BTAB, sent by back-tab key

kcbt
kcl

kc3

KEY_Cl, lower left of keypad
KEY_C3, lower right of keypad

key_cancel
key_catab

kcan
ktbc

KEY_CANCEL, sent by cancel key

key_clear

kclr

KEY_CATAB, sent by clear-ail-tabs key
KEY_CLEAR, sent by clear-screen or

key_close
key_cCllll1alld

kclo

kcxnd

KEY_CLOSE, sent by close key
KEY_COMMl\ND, sent by cmd (command)

key_copy

kcpy

KEY_COPY, sent by copy key

key_create

kcrt

key_ctab
key_de

kctab

KEY_CREATE, sent by create key
KEY_CTAB, sent by clear-tab key

kdchl.

KEY_DC, sent by delete-character key

key_dl

kdll

key_down

kcudl

ltd

KEY_DL, sent by delete-line key
KEY_DONN, sent by terminal

key_eic

krmir

key_Blld

kBlld
kent

key_enter
key_eol

kel

key_eos

ked

key_cl
key_c3

erase key

key

232

down-arrow key
KEY_EIC, sent by nair or smir in
insert mode
KEY_END, sent by end key
KEY_ENTER, sent by enter/send key
KEY_EOL, sent by clear-to-end-of-line
key
KEY_EOS, sent by clear-to-end-of-screen
key

terminfo ( 4)

Variable

Capname

Termcap
Code

Description

key_exit

kext

KEY_EXIT, sent by exit key

key_fO

kfO

KEY_F (0) , sent by function key fa

key_fl

kfl

KEY_F (1) , sent by function key fl

key_f2

kf2

KEY_F (2) , sent by function key f2

key_f3

kf3

KEY_F (3) , sent by function key f3

key_f4

kf4

KEY_F (4) , sent by function key f4

key_fs

kfs

KEY] (5) , sent by function key f5

key_f6

kf6

KEY] (6) , sent by function key f6

key_f7

kf7

KEY_F (7) , sent by function key f7

key_fS

kf8

KEY] (8) , sent by function key f8

key_f9

kf9

KEY_F (9), sent by function key f9

key_flO

kflO

KEY_F (10) , sent by function key flO

key_fll

kfl1

KEY_F (11) , sent by function key f11

key_fl2

kfl2

KEY] (12) , sent by function key £12

key_fl3

kfl3

KEY_F (13) , sent by function key £13

key_fl4

kfl4

KEY] (14) , sent by function key £14

key_fls

kf1s

KEY_F (15) , sent by function key £15

key_fl6

kf16

KEY_F(16), sent by function key £16

key_fl7

kf17

KEY_F(17) , sent by function key £17

key318

kf18

KEY_F (18), sent by function key £18

key_fl9

kfl9

KEY_F (19) , sent by function key £19

key_f20

kf20

KEY_F (20) , sent by function key f20

key_f21

kf21

KEY_F(21), sent by function key f21

key_f22

kf22

KEY_F (22) , sent by function key f22

key_f23

kf23

KEY_F (23) , sent by function key f23

key_f24

kf24

KEY_F (24) , sent by function key f24

key_f2s

kf25

KEY_F (25), sent by function key f25

key_f26

kf26

KEY_F(26), sent by function key f26

key_f27

kf27

KEY_F (27) , sent by function key f27

key_f28

kf28

KEY_F(28) , sent by function key f28

key_f29

kf29

KEY_F (29) , sent by function key f29

key_f30

kf30

KEY_F(30) , sent by function key f30

key_f31

kf31

KEY_F(31), sent by function key f31

key_f32

kf32

KEY_F(32), sent by function key f32

key_f33

kf33

KEY] (13) , sent by function key fl3

key_f34

kf34

KEY] (34) , sent by function key f34

key_f35

kf35

KEY] (35) , sent by function key f35

key_f36

kf36

KEY_F(36), sent by function key f36

key_f37

kf37

KEY] (37) , sent by function key f37

key_f38

kf38

KEY_F(38), sent by function key f38

key_f39

kf39

KEY_F(39), sent by function key f39

key_f40

kf40

KEY_F(40), sent by function key f40

key_f41

kf41

KEY_F(41), sent by function key f41

key_f42

kf42

KEY_F (42) , sent by function key f42

key_f43

kf43

KEY_F(43), sent by function key f43

233

terminfo (4 )

Variable

Capname

key_f44
key_f45
key_f46
key_f47
key_f48
key_f49
key_f50
key_f51
key_f52
key_f53
key_f54
key_f55
key_f56
key_f57
key_f58
key_f59
key_f60
key_f61
key362
key_f63
key_find
key_help
key_home
key_ic

kf44
kf45
kf46
kf47
kf48
kf49
kf50
kf51
kf52
kf53
kf54
kf55
kf56
kf57
kf58
kf59
kf60
kf61
kf62
kf63
kfnd
khlp

Termcap
Code
FY

FZ
Fa
Fb

Fc
Fd
Fe
Ff
Fg
Fh

Fi
Fj
Fk

Fl
FIn

Fo
Fp

Fq
Fr
@O
'1--01

khome

kich1

key_il
key_left

kill
kcub1

key_ll
key_mark
key_message
key_mouse
key_move
key_next
key_npage
key_open
key_options
key-'-ppage
key-previous

kll
kmrk
kmsg
kmous

Description
KEY] (44) , sent by function key f44
KEY_F (45) , sent by function key f45
KEY_F (46), sent by function key f46
KEY] (47), sent by function key f47
KEY] (48), sent by function key f48
KEY] (49), sent by function key f49
KEY] (50) , sent by function key f50
KEY] (51) , sent by function key f51
KEY] (52), sent by function key f52
KEY] (53), sent by function key f53
KEY] (54) , sent by function key f54
KEY] (55), sent by function key f55
KEY] (56) , sent by function key f56
KEY] (57) , sent by function key f57
KEY] (58) , sent by function key f58
KEY_F (59) , sent by function key f59
KEY_F (60) , sent by function key f60
KEY_F(61), sent by function key f61
KEY_F(62) , sent by function key f62
KEY_F (63) , sent by function key f63
KEY_FIND, sent by find key
KEY_HELP, sent by help key
KEY_HOME, sent by home key
KEY_Ie, sent by ins-char I enter

ins-mode key
kl

KEY_IL, sent by insert-line key
KEY_LEFT, sent by terminal left-arrow

key

key-print
key_redo
key_reference
key_refresh
key_replace

234

'1--.,2

%3
KIn

kmov

'1--04

knxt

knp

kopn
kopt

%6
%7

kpp

kprv

kprt
krdo
kref
krfr
krpl

%0
&1
&2
&3

KEY_LL, sent by home-down key
KEY_MARK, sent by mark key
KEY_MESSAGE, sent by message key

Mouse event has occurred
KEY_MOVE, sent by move key
KEY_NEXT, sent by next-object key
KEY_NPAGE, sent by next-page key
KEY_OPEN, sent by open key
KEY_OPTIONS, sent by options key
KEY_PPAGE, sent by previous-page key
KEY_PREVIOUS, sent by previous-object
key
KEY_PRINT, sent by print or copy key
KEY_REDO, sent by redo key
KEY_REFERENCE, sent by ref(erence) key
KEY_REFRESH, sent by refresh key
KEY_REPLACE, sent by replace key

terminfo (4)

Variable

Capname

Termcap
Code

Description

key_restart

krst

KEY_RESTART, sent by restart key

key_resume

kres

KEY_RESIJME, sent by resume key

key_right

kcufl

KEY_RIGHT, sent by terminal

key_save

ksav

KEY_SAVE, sent by save key

key_sbeg

kBEG

key_scancel

kCAN

keyjlcomnand

kCMD

&6
&9
&0
*1

key_scopy

kCPY

key_screate

kCRT

key_sdc

kDC

key_sdl

kDL

right-arrow key
KEY_SBEG, sent by shifted beginning key
KEY_SCANCEL, sent by shifted cancel key
KEY_SCOMMAND, sent by shifted

command key
KEY_SCOPY, sent by shifted copy key

keyjlelect

kslt

key_send

kENO

keyjleol

kEOL

key_sexit

kEXT

*2
*3
*4
*5
*6
*7
*8
*9

key_sf

kind

KEY_SF, sent by scroll-forward/ down

key_sfiDd

kFND

KEY_SFINO, sent by shifted find key

key_shelp

kHLP

key_shane

k:I!<»4

keyjlic

kIC

key_sleft

kLFT

*0
#1
#2
#3
#4

key_Sl\1essage

kMSG

%a.

KEY_BMESSAGE, sent by shifted message

key_amove

kKW

KEY_S!«JVE, sent by shifted move key

keyjllleXt

kNXT

KEY_SNEXT, sent by shifted next key

keyJIOPtions

kePT

KEY_SOPTIONS, sent by shifted options

key_sprevious

kPRV

KEY_SPREVIOUS, sent by shifted prev

key_sprint

kPRT

KEY_SPRINT, sent by shifted print key

key_sr

kri

KEY_SR, sent by scroll-backward/up

key_srede

kRDO

KEY_SREDO, sent by shifted redo key

keyjlreplace

kRPL

KEY--.-BREPLACE, sent by shifted replace

keyjlright

kRIT

KEY_BRIGHT, sent by shifted

key_srsume

kRES

KEY_SRSUME, sent by shifted resume

keyjlsave

kSAV

KEY_SSAVE, sent by shifted save key

key_ssuspend

kSPD

KEY_SSUSPEND, sent by shifted suspend

KEY_SCREATE, sent by shifted create key
KEY_SDC, sent by shifted delete-char key
KEY_SDL, sent by shifted delete-line key
KEY_SELECT, sent by select key
KEY_SEND, sent by shifted end key
KEY_SEOL, sent by shifted clear-line key
KEY_SEXIT, sent by shifted exit key

key
KEY_SHELP, sent by shifted help key
KEY_SHOMB, sent by shifted home key
KEY_SIC, sent by shifted input key
KEY_SLEFT, sent by shifted left-arrow

key
key

key

key
right-arrow key
key

235

terminfo(4)

Variable
key_stab
key_sUDdo
key_suspend

236

Capname

Termcap
Code

khts

ItT

kUND

!3
&7

kspd

key_undo
key_up
keypad_local
keypacLxmit
lab_fO
lab_fl
lab32
lab_f3
lab_f4
lab_fs
lab36
lab_f7
lab_f8
lab_f9
lab_flO
label_off
label_on
meta_off
meta_OIl
micro_colUIIIILaddress
micro_down
micro_left
micro_right

mcud1
mcub1
mcuf1

micro_ro",,-address
micro_lIP
mouse_info
newline

mvpa

mcuu1
minfo
nel

iii

order_of-llins
orig_colors
orig-.l)air

porder
oc

Ze
oc

pad_char

pad

op
pc

doh

panluich
pa%m_delete_line
pa%DLdown_cursor
parDI_dawn_micro
parDI_iob

kund

kcuu1

:tmkx

smkx

lfO
lf1
lf2
lf3
If4
lfs
lf6
lf7
If8
lf9
lf10

10
11
12
13
14
15
16
17
18

rmln

smln

D1III.

1110

SlIm

II1II

mbpa.

ZZ
Zb

or.

cud

mcud

iob

Description
key
KEY_STAB, sent by set-tab key
KEY_SUNDO, sent by shifted undo key
KEY_suSPEND,sentby
suspend key
KEY_tlNOO, sent by undo key
KEY_UP, sent by terminal up-arrow key
Out of "keypad-transmit" mode
Put terminal in "keypad-transmit" mode
Labels on function key fO if not fO
Labels on function key fl if not fl
Labels on function key f2 if not f2
Labels on function key f3 if not f3
Labels on function key f4 if not f4
Labels on function key f5 if not f5
Labels on function key f6 if not f6
Labels on function key f7 if not f7
Labels on function key f8 if not f8
Labels on function key f9 if not f9
Labels on function key flO if not flO
Turn off soft labels
Turn on soft labels
Turn off "meta mode"
Tum on "meta mode" (8th bit)
Like colUllDl_address for micro
adjustment
like cursor_dawn for micro adjustment
like cursor_left for micro adjustment
Like cursor_right for micro
adjustment
Like row_address for micro adjustment
like cursor_lIP for micro adjustment
Mouse status information
Newline (behaves like cr followed
bylf)
Matches software bits to print-head pins
Set all color(-pair)s to the original ones
Set default color-pair to the original one
Pad character (rather than nUll)
Delete #1 chars
Delete #1 lines
Move down #1 lines.
Like pa%m_down_cursor for micro
adjust.
Insert #1 blank chars

terminfo (4)

Variable

Capname

Termcap
Code

indn

cub

meub

paJ:1ILindex
pa=_insert_Iine
pa=_left_cursor
P8J:lU_Ieft_micro
P8J:lU_right_cursor
parm_right_micro

cuf
mcuf

parm_rindex
P8J:lU_up_cursor
P8J:lU_up_micro
pc_term_optians
pkey_key
pkey_Iocal
pkey...plab
pkey_xmit
plab_no=
print_screen
prtr_non
prtr_off
prtr_an
repeat_char
re9'len_inch
set_right_margin
set_right_margin~

set_tab
set_tb_margin
set_tap_margin
set_tap_margin--P8.rm
set_window
start_bit_image
start_char_set_def
stop_bit_image
stap_char_set_def
subscript_characters
superscriPt_characters
tab
these_cause_cr
to_status_line
underline_char
up_half_line
xoff_character
xon_character
zero_motion

Capname

Termcap
Code

setcolorYz
sop
sp
Sf
setf
engl
ML
smglp
Zln
englr
ML
slines YZ
slength YI
engr
MR
engrp
zn
hts
st
engtb
MT
sngt
zo
smgtp
zp
wind
wi
shim
Zq
scsd
Zr
rbim
zs
zt
=sd
sllbcs
Zu
supcs
Zv
ht
ta
zw
doer
tsl
ts
uc
uc
hu
hu
xoffc
XF
xonc

zerom

Description
lines from bottom
Change to ribbon color #1
Set current color-pair
Set current foreground color1
Set left margin at current line
Set left (right) margin at column #1 (#2)
Sets both left and right margins
Set page length to #1 lines (use tpazm)
Set page length to #1 hundredths of an inch (use tpazm)
Set right margin at current column
Set right margin at column #1
Set a tab in all rows, current column
Sets both top and bottom margins
Set top margin at current line
Set top (bottom) margin at line #1 (#2)
Current window is lines #1-#2 cols #3-#4
Start printing bit image graphics
Start definition of a character set
End printing bit image graphics
End definition of a character set
List of "subscript-able" characters
List of "superscript-able" characters
Tab to next 8-space hardware tab stop
Printing any of these chars causes cr
Go to status line, col #1
Underscore one char and move past it
Half-line up (reverse 1/2linefeed)
X-off character
X-on character
No motion for the subsequent character

Sample Entry
The following entry, which describes the AT&T 610 terminal, is among the more
complex entries in the terminfo file as of this writing.
610 I 610bct I ATT610 I att610 I AT&T 610; 80 column; 98key keyboard
am, eslok, hs, mir, msgr, xenl, xon,
cols#80, it#8, lh#2, lines#24, lW#8, nlab#8, wsl#80,
acsc="aaffggjjkkllmmnnooppqqrrssttuuvvww.xxyyzz{{II}}--,
bel=AG, blink=\E[Sm, bold=\E[lm, cbt=\E[Z,
civis=\E[?2S1, clear=\E [H\E [J, cnorm=\E[?2Sh\E[?121,
cr=\r, csr=\E[%i%p1%d;%p2%dr, cub=\E[%p1%dD, cub1=\b,
cud=\E[%P1%dB, cud1=\E[B, cuf=\E[%p1%dC, cuf1=\E[C,
cup=\E[%i%p1%d;%p2%dH, cuu=\E[%p1%dA, cuu1=\E[A,
cvvis=\E[?12;2Sh, dch=\E[%p1%dP, dch1=\E[P, d~\E[2m,
dl=\E[%p1%dM, dl1=\E[M, ed=\E[J, el=\E[K, el1=\E[lK,
flash=\E[?Sh$<200>\E[?Sl, fsl=\E8, hame=\E[H, ht=\t,

238

terminfo(4)
ich=\E[%pl%d@, il=\E[%pl~odL, ill=\E[L, ind=\ED, .ind=\ED$<9>,
invis=\E[8m,
isl=\E[8;0 I \E[?3;4;5;13;15l\E[13;20l\E[?7h\E[12h\E(B\E}0,
is2=\E[Om AO, is3=\E(B\E}0, kLFT=\E[\s@, kRIT=\E[\SA,
kbS=AH, kcbt=\E[Z, kclr=\E[2J, kcubl=\E[D, kcudl=\E[B,
kcufl=\E[C, kcuul=\E[A, kfl=\EOc, kflO=\ENp,
kfll=\ENq, kf12=\ENr, kf13=\ENs, kf14=\ENt, kf2=\EOd,
kf3=\EOe, kf4=\EOf, kf5=\EOg, kf6=\EOh, kf7=\EOi,
kf8=\EOj, kf9=\ENo, khame=\E[H, kind=\E[S, kri=\E[T,
11=\E[24H, mc4=\E[?4i, mc5=\E[?5i, nel=\EE,
pfxl=\E[%Pl~od;%P2%1%02dq%?%pl%{9}%<%t\s\s\s~~1%ld\s\s\s\s\s

\s\s\s\s\s\s%;%p2%s,
pln=\E[%pl%d;0;0;0q%p2%:-16.16s, rc=\E8, rev=\E[7m,
ri=\EM, rmacs=AO, rmdr=\E[4l, rmln=\E[2p, rmso=\E[m,
r.mul=\E[m, rs2=\Ec\E[?3l, sc=\E7,
sgr=\E [0%?%p6%t; 1%;%?%p5%t;2%;%?%p2%t;4%;%?%p4%t; 5%;
%?%p3%Pl% I %t;7%;%?%p7%t;8%;m%?%p9%tA~~AQP~;,
sgrO=\E[mAO, smacS=AN, smir=\E[4h, smln=\E[p,
smso=\E[7m, smul=\E[4m, tsl=\E7\E[25;%i%pl%dx,
Types of Capabilities in the Sample Entry

The sample entry shows the formats for the three types of terminfo capabilities
listed: Boolean, numeric, and string. All capabilities specified in the termdnfo
source file must be followed by commas, including the last capability in the source
file. In termdnfo source files, capabilities are referenced by their capability names
(as shown in the previous tables).
Boolean capabilities are specified simply by their comma separated cap names.
Numeric capabilities are followed by the character '#' and then a positive integer
value. Thus, in the sample, cols (which shows the number of columns available on
a device) is assigned the value 80 for the AT&T 610. (Values for numeric capabilities may be specified in decimal, octal, or hexadecimal, using normal C programming language conventions.)
Finally, string-valued capabilities such as el (clear to end of line sequence) are
listed by a two- to five-character capname, an '=', and a string ended by the next
occurrence of a comma. A delay in milliseconds may appear anywhere in such a
capability, preceded by $ and enclosed in angle brackets, as in el=\EK$<3>. Padding characters are supplied by tput. The delay can be any of the following: a
number, a number followed by an asterisk, such as 5*, a number followed by a
slash, such as 5/, or a number followed by both, such as 5 * /. A' *, shows 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. (In the case of
insert characters, the factor is still the number of lines affected. This is always 1
unless the device has in and the software uses it.) 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. (Only one decimal place is allowed.)

239

terminfo (4)
A '/' indicates that the padding is mandatory. If a device has xon defined, the padding information is advisory and will only be used for cost estimates or when the
device is in raw mode. Mandatory padding will be transmitted regardless of the
setting of xon. If padding (whether advisory or mandatory) is specified for bel or
flash, however, it will always be used, regardless of whether xon is specified.
terminfo offers notation for encoding special characters. Both \E and \e map to
an ESCAPE character, AX maps to a control x for any appropriate x, and the
sequences \n, \1, \r, \t, \h, \f, and \s give a newline, linefeed, return, tab,
backspace, formfeed, and space, respectively. Other escapes include: \ ~ for caret
0; \ \ for backslash (\); \, for comma (,); \: for colon (:); and \0 for null. (\0 will
actually produce \200, which does not terminate a string but behaves as a null
character on most devices, providing CS7 is specified. [See stty(l).] Finally, characters may be given as three octal digits after a backslash (for example, \ 123).
Sometimes individual capabilities must be commented out. To do this, put a period
before the capability name. For example, see the second ind in the example above.
Note that capabilities are defined in a left-to-right order and, therefore, a prior
definition will override a later definition.
Preparing Descriptions

The most effective way to prepare a device description is by imitating the description of a similar device in terminfo and building up a description gradually, using
partial descriptions with vi to check that they are correct. Be aware that a very
unusual device may expose deficiencies in the ability of the terminfo file to
describe it or the inability of vi to work with that device. To test a new device
description, set the environment variable TERMINFO to the pathname of a directory
containing the compiled description you are working on and programs will look
there rather than in /usr/share/lih/terminfo. To get the padding for insert-line
correct (if the device manufacturer did not document it) a severe test is to comment
out xon, edit a large file at 9600 baud with vi, delete 16 or so lines from the middle
of the screen, and then press the u key several times quickly. If the display is
corrupted, more padding is usually needed. A similar test can be used for
insert-character.
Section 1-1: Basic Capabilities

The number of columns on each line for the device is given by the cols numeric
capability. If the device has a screen, then the number of lines on the screen is given
by the lines capability. If the device 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, leaving the cursor in the home position, then this is
given by the clear string capability. If the terminal overstrikes (rather than clearing a position when a character is struck over) then it should have the os capability.
If the device is a printing terminal, with no soft copy unit, specify both hc and os.
If there is a way to move the cursor to the left edge of the current row, specify this
as cr. (Normally this will be carriage return, control M.) If there is a way to produce an audible signal (such as a bell or a beep), specify it as bel. If, like most
devices, the device uses the xon-xoff flow-control protocol, specify xon.

240

terminfo (4)
If there is a way to move the cursor one position to the left (such as backspace), that
capability should be given as cool. Similarly, sequences to move to the right, up,
and down should be given as cufl, cuul, and cudl, respectively. These local
cursor motions must not alter the text they pass over; for example, you would not
normally use" cufl= \s" because the space would erase the character moved over.

A very important point here is that the local cursor motions encoded in terminfo
are undefined at the left and top edges of a screen terminal. Programs should never
attempt to backspace around the left edge, unless bw is specified, and should never
attempt to go up locally off the top. To scroll text up, a program goes to the bottom
left comer of the screen and sends the ind (index) string.
To scroll text down, a program goes to the top left comer of the screen and sends
the ri (reverse index) string. The strings ind and ri are undefined when not on
their respective comers of the screen.
Parameterized versions of the scrolling sequences are indn and rin. These versions
have the same semantics as ind and ri, except that they take one parameter and
scroll the number of lines specified by that parameter. They are also undefined
except at the appropriate edge of the screen.
The am capability tells whether the cursor sticks at the right edge of the screen when
text is output, but this does not necessarily apply to a cufl from the last column.
Backward motion from the left edge of the screen is pOSSible only when bw is
specified. In this case, cool will move to the right edge of the previous row. If bw
is not given, the effect is undefined. This is useful for drawing a box around the
edge of the screen, for example. If the device has switch selectable automatic margins, am should be specified in the terminfo source file. In this case, initialization
strings should tum on this option, if possible. If the device has a command that
moves to the first column of the next line, that command can be given as nel (newline). It does not matter if the command clears the remainder of the current line, so
if the device has no cr and If it may still be possible to craft a working nel out of
one or both of them.
These capabilities suffice to describe hardcopy and screen terminals. Thus the
AT&T 5320 hardcopy terminal is described as follows:
53201att53201AT&T 5320 hardcopy terminal,
am, hc, os,
cols#132,
bel=AG, cr=\r, cOOl=\b, cndl=\n,
dchl=\E[P, dll=\E[M,
ind=\n,
while the Lear Siegler ADM-3 is described as
adm3 I lsi adm3,
am, bel=AG, clear=A Z, cols#80, cr=AM, cOOl=AH,
cUdl=AJ, ind=AJ, lines#24,
Section 1-2: Parameterized Strings

Cursor addressing and other strings requmng parameters are described by a
parameterized string capability, with printf-like escapes ('YoX) in it. For example, to
address the cursor, the cup capability is given, using two parameters: the row and
column to address to. (Rows and columns are numbered from zero and refer to the
241

terminfo(4)
physical screen visible to the user, not to any unseen memory.) If the terminal has
memory relative cursor addressing, that can be indicated by mrcup.
The parameter mechanism uses a stack and special % codes to manipulate the stack
in the manner of Reverse Polish Notation (postfix). Typically a sequence will push
one of the parameters onto the stack and then print it in some format. Often more
complex operations are necessary. Operations are in postfix form with the
operands in the usual order. That is, to subtract 5 from the first parameter, one
would use %pl%{5}%-.
The % encodings have the following meanings:
outputs '%'

%[ [:

]j1ags][width[.precision]][doxXs]
as in printf, flags are [-+#] and space
print pop gives %c

%P[1-9]

push ith parm
%P[a-z]

set dynamic variable [a-z] to pop
%g[a-z]

get dynamic variable [a-z] and push it
%P[A-Z]

set static variable [a-zl to pop
%g[A-Z]
%I C I

get static variable [a-zl and push it
push char constant c

%{nn} push decimal constant nn
push strlen(pop)

%+ %- %* %/ %m

arithmetic (%In is mod): push(pop integer2 op pop integerl) where integer I is
the top of the stack
%& %1 %A

bit operations: push(pop integer2 op pop integerl)
%= %> %<

logical operations: push(pop integer2 op pop integerl)
%A %0 logical operations: and, or
%! %-

unary operations: push(op pop)

(for ANSI terminals) add 1 to first parm, if one parm present, or first two
parms, if more than one parm present

expr %t thenpart

elsepart %;

if-then-else, %e elsepart is optional; else-if's are possible ala Algol 68: %? c 1
%t b 1 %e

%t b 2 %e c 3 . %t b 3

ci are condItions, b i are bOGIes.

242

'Y.,e

c 4 %t b 4 %e b 5%;

terminfo (4)
If the "-" flag is used with "%[doxXs]", then a colon (:) must be placed between the
"%" and the "-" to differentiate the flag from the binary "%-" operator, for example, "%: -16 .16s".
Consider the Hewlett-Packard 2645, which, to get to row 3 and column 12, needs to
be sent \E&a12c03Y padded for 6 milliseconds. Note that the order of the rows and
columns is inverted here, and that the row and column are zero-padded as two
digits. Thus its cup capability is:
cup=\E&a%p2%2.2dc%p1%2.2dY$<6>

The Micro-Term ACT-IV needs the current row and column sent preceded by a -T,
with the row and column simply encoded in binary, "cup=-T%p1%c%p2%e".
Devices that use "%e" need to be able to backspace the cursor (cubl), and to move
the cursor up one line on the screen (cuu1). This is necessary because it is not
always safe to transmit \n, -D, and \r, as the system may change or discard them.
(The library routines dealing with terminfo set tty modes so that tabs are never
expanded, so \ t is safe to send. This turns out to be essential for the Ann Arbor
4080.)
A final example is the LSI ADM-3a, which uses row and column offset by a blank
character, thus "cup=\E=%P1%'\s'%+%e%p2%'\s'%+%e". After sending "\E=", this
pushes the first parameter, pushes the ASCII value for a space (32), adds them
(pushing the sum on the stack in place of the two previous values), and outputs that
value as a character. Then the same is done for the second parameter. More complex arithmetic is possible using the stack.
Section 1-3: Cursor Motions

If the terminal has a fast way to home the cursor (to very upper left corner of
screen) then this can be given as home; similarly a fast way of getting to the lower
left-hand comer can be given as 11; this may involve going up with cuu1 from the
home position, but a program should never do this itself (unless 11 does) because it
can make no assumption about the effect of moving up from the home position.
Note that the home position is the same as addressing to (0,0): to the top left corner
of the screen, not of memory. (Thus, the \EH sequence on Hewlett-Packard terminals cannot be used for home without losing some of the other features on the terminal.)
If the device has row or column absolute-cursor addressing, these can be given as
single parameter capabilities hpa (horizontal position absolute) and vpa (vertical
position absolute). Sometimes these are shorter than the more general twoparameter sequence (as with the Hewlett-Packard 2645) and can be used in preference to cup. If there are parameterized local motions (for example, move n spaces
to the right) these can be given as cud, cub, cuf, and cuu with a single parameter
indicating how many spaces to move. These are primarily useful if the device does
not have cup, such as the Tektronix 4025.
If the device needs to be in a special mode when running a program that uses these

capabilities, the codes to enter and exit this mode can be given as smcup and nncup.
This arises, for example, from terminals, such as the Concept, with more than one
page of memory. If the device has only memory relative cursor addressing and not
screen relative cursor addressing, a one screen-sized window must be fixed into the
device for cursor addressing to work properly. This is also used for the Tektronix

243

terminfo(4)
4025, where smcup sets the command character to be the one used by terminfo. H
the smcup sequence will not restore the screen after an :rmcup sequence is output (to
the state prior to outputting rmcup), specify nrDIIC.
Section 1-4: Area Clears

If the terminal can clear from the current position to the end of the line, leaving the
cursor where it is, this should be given as el. If the terminal can clear from the
beginning of the line to the current position inclusive, leaving the cursor where it is,
this should be given as ell. If the terminal can clear from the current position to
the end of the display, then this should be given as ed. ed is only defined from the
first column of a line. (Thus, it can be simulated by a request to delete a large
number of lines, if a true ed is not available.)
Section 1-5: Insert/Delete Line

If the terminal can open a new blank line before the line where the cursor is, this
should be given as ill; this is done only from the first position of a line. The cursor
must then appear on the newly blank line. H the terminal can delete the line which
the cursor is on, then this should be given as dll; this is done only from the first
position on the line to be deleted. Versions of ill and dll which take a single
parameter and insert or delete that many lines can be given as i l and dl.
If the terminal has a settable destructive scrolling region (like the VT100) the command to set this can be described with the esr capability, which takes two parameters: the top and bottom lines of the scrolling region. The cursor position is, alas,
undefined after using this command. It is possible to get the effect of insert or
delete line using this command - the se and re (save and restore cursor) commands are also useful. Inserting lines at the top or bottom of the screen can also be
done using ri or ind on many terminals without a true insert/delete line, and is
often faster even on terminals with those features.·

To determine whether a terminal has destructive scrolling regions or nondestructive scrolling regions, create a scrolling region in the middle of the screen,
place data on the bottom line of the scrolling region, move the cursor to the top line
of the scrolling region, and do a reverse index (ri) followed by a delete line (dll) or
index (ind). If the data that was originally on the bottom line of the scrolling region
was restored into the scrolling region by the dll or ind, then the terminal has nondestructive scrolling regions. Otherwise, it has destructive scrolling regions. Do
not specify esr if the terminal has non-destructive scrolling regions, unless ind, ri,
indn, rin, dl, and dll all simulate destructive scrolling.
If the terminal has the ability to define a window as part of memory, which all commands affect, it should be given as the parameterized string wind. The four parameters are the starting and ending lines in memory and the starting and ending
columns in memory, in that order.
H the terminal can retain display memory above, then the da capability should be
given; if display memory can be retained below, then db should be given. These
indicate that deleting a line or scrolling a full screen may bring non-blank lines up
from below or that scrolling back with ri may bring down non-blank lines.

244

terminfo (4)
Section 1-6: Insert/Delete Character

There are two basic kinds of intelligent terminals with respect to insert/ delete character operations which can be described using tenninfo. 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
determine the kind of terminal you have by clearing the screen and then typing text
separated by cursor motions. Type "abc def" using local cursor motions (not
spaces) between the abc and the def. Then position the cursor before the abc and
put the terminal in insert mode. If typing characters causes the rest of the line to
shift rigidly and characters to fall off the end, then your terminal does not distinguish between blanks and untyped positions. If the abc shifts over to the def
which then move together around the end of the current line and onto the next as
you insert, you have the second type of terminal, and should give the capability in,
which stands for "insert null." While these are two logically separate attributes
(one line versus multiline insert mode, and special treatment of untyped spaces) we
have seen no terminals whose insert mode cannot be described with the single attribute.
tenninfo can describe both terminals that have an insert mode and terminals
which send a simple sequence to open a blank position on the current line. Give as
smir the sequence to get into insert mode. Give as nnir the sequence to leave
insert mode. Now give as iehl any sequence needed to be sent just before sending
the character to be inserted. Most terminals with a true insert mode will not give
iehl; terminals that send a sequence to open a screen position should give it here.
(If your terminal has both, insert mode is usually preferable to iehl. Do not give
both unless the terminal actually requires both to be used in combination.) If postinsert padding is needed, give this as a number of milliseconds padding 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. If your terminal needs both to be placed
into an 'insert mode' and a special code to precede each inserted character, then
both smir/rmir and iehl can be given, and both will be used. The ieh capability,
with one parameter, n, will insert n blanks.
If padding is necessary between characters typed while not in insert mode, give this
as a number of milliseconds padding in nnp.
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). If

your terminal allows motion while in insert mode you can give the capability mir to
speed up inserting in this case. Omitting mir will affect only speed. Some terminals (notably Datamedia's) must not have mir because of the way their insert mode
works.
Finally, you can specify dehl to delete a single character, deh with one parameter,

n, to delete n characters, and delete mode by giving smde and rmde to enter and exit
delete mode (any mode the terminal needs to be placed in for dehl to work).

245

terminfo (4)
A command to erase n characters (equivalent to outputting n blanks without moving the cursor) can be given as ech with one parameter.
Section 1-7: Highlighting, Underlining, and Visible Bells

Your device may have one or more kinds of display attributes that allow you to
highlight selected characters when they appear on the screen. The following
display modes (shown with the names by which they are set) may be available: a
blinking screen (blink), bold or extra-bright characters (bold), dim or half-bright
characters (dim), blanking or invisible text (invis), protected text (prot), a reversevideo screen (rev), and an alternate character set (smacs to enter this mode and
rmacs to exit it). (If a command is necessary before you can enter alternate character set mode, give the sequence in enacs or "enable alternate-character-set" mode.)
Turning on any of these modes singly mayor may not turn off other modes.
sgrO should be used to turn off all video enhancement capabilities. It should
always be specified because it represents the only way to turn off some capabilities,
such as dim or blink.
You should choose one display method as standout mode [see curses(3curses)] and
use it to highlight error messages and other kinds of text to which you want to
draw attention. Choose a form of display that provides strong contrast but that is
easy on the eyes. (We recommend reverse-video plus half-bright or reverse-video
alone.) The sequences to enter and exit standout mode are given as smso and rmso,
respectively. 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 xmc
should be given to tell how many spaces are left.
Sequences to begin underlining and end underlining can be specified as smul and
rmul ,respectively. If the device has a sequence to underline the current character
and to move the cursor one space to the right (such as the Micro-Term MIME), this
sequence can be specified as uc.
Terminals with the "magic cookie" glitch (xmc) deposit special "cookies" when
they receive mode-setting sequences, which affect the display algorithm rather than
having extra bits for each character. Some terminals, such as the Hewlett-Packard
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, unless the msgr capability, asserting that it
is safe to move in standout mode, is present.
If the terminal has a way of flashing the screen to indicate an error quietly (a bell
replacement), then this can be given as flash; it must not move the cursor. A good
flash can be done by changing the screen into reverse video, pad for 200 ms, then
return the screen to normal video.
If the cursor needs to be made more visible than normal when it is not on the bottom line (to make, for example, a non-blinking underline into an easier to find block
or blinking underline) give this sequence as cvvis. The boolean chts should also
be given. If there is a way to make the cursor completely invisible, give that as
civis. The capability cnorm should be given which undoes the effects of either of
these modes.

246

terminfo (4)
If your terminal generates underlined characters by using the underline character
(with no special sequences needed) even though it does not otherwise overstrike
characters, then you should specify the capability ul. For devices on which a character overstriking another leaves both characters on the screen, specify the capability os. If overstrikes are erasable with a blank, then this should be indicated by
specifying eo.
If there is a sequence to set arbitrary combinations of modes, this should be given as

sgr (set attributes), taking nine parameters. Each parameter is either 0 or non-zero,
as the corresponding attribute is on or off. The nine parameters are, in order: standout, underline, reverse, blink, dim, bold, blank, protect, alternate character set.
Not all modes need to be supported by sgr; only those for which corresponding
separate attribute commands exist should be supported. For example, let's assume
that the terminal in question needs the following escape sequences to turn on
various modes.
tparm
parameter

attribute

escape sequence

pI
p2
p3
p4
p5
p6
p7
p8
p9

none
standout
underline
reverse
blink
dim
bold
invis
protect
altcharset

\E[Om
\E[O;4;7m
\E[O;3m
\E[O;4m
\E[O;5m
\E[O;7m
\E[O;3;4m
\E[O;8m
not available
AQ (off) AN (on)

Note that each escape sequence requires a 0 to turn off other modes before turning
on its own mode. Also note that, as suggested above, standout is set up to be the
combination of reverse and dim. Also, because this terminal has no bold mode, bold is
set up as the combination of reverse and underline. In addition, to allow combinations, such as underline+blink, the sequence to use would be \E [0; 3; 5m. The terminal doesn't have protect mode, either, but that cannot be simulated in any way, so
p8 is ignored. The altcharset mode is different in that it is either AQ or AN, depending
on whether it is off or on. If all modes were to be turned on, the sequence would be
\E[O;3;4;5;7;8m N.
A

Now look at when different sequences are output. For example, ; 3 is output when
either p2 or p6 is true, that is, if either underline or bold modes are turned on. Writing out the above sequences, along with their dependencies, gives the following:
sequence

when to output

terminfo translation

\E[O

always
ifp2 or p6
if pI or p3 or p6
ifp4
ifpI or p5

%?%p2%p6%I%ti3%i
%?%pl%p3%I%p6%I%t;4%;
%?%p4%ti5%;
%?%pl%p5%I%t;7%;

;3
;4
;5
;7

\E[O

247

terminfo (4)
;8

ifp7

always
if p9 ~N, else

%?%p7%ti8%;
m
~o

%?%p9%t~W-oe~0%;

Putting this all together into the sgr sequence gives:
sgr=\E[O%?%p2%p6%I%t;3%;%?%pl%p3%I%p6%
l%t;4%;%?%p5%t;5%;%?%pl%p5%
l%ti7%;%?%p7%t;8%im%?%p9%tA~oeAO%i,

Remember that sgr and sgrO must always be specified.
Section 1-8: Keypad
If the device has a keypad that transmits sequences when the keys are pressed, this
information can also be specified. Note that it is not possible to handle devices
where the keypad only works in local (this applies, for example, to the unshifted
Hewlett-Packard 2621 keys). If the keypad can be set to transmit or not transmit,
specify these sequences as smkx and:nnkx. Otherwise the keypad is assumed to
always transmit.
The sequences sent by the left arrow, right arrow, up arrow, down arrow, and
home keys can be given as kcubl, kcufl, kcuul, kcudl, and khome, respectively. If there are function keys such as £0, fl, ... , f63, the sequences they send can
be specified as kfO, kfl, ••• , kf63. If the first 11 keys have labels other than
the default £0 through flO, the labels can be given as lfO, lfl, ••. , lflO. The
codes transmitted by certain other special keys can be given: kll (home down), kbs
(backspace), ktbc (clear all tabs), kctab (clear the tab stop in this column), kcir
(clear screen or erase key), kdchl (delete character), kdll (delete line), krmir (exit
insert mode), kei (clear to end of line), ked (clear to end of screen), kichl (insert
character or enter insert mode), kill (insert line), knp (next page), kpp (previous
page), kind (scroll forward/down), kri (scroll backward/up), khts (set a tab stop
in this column). In addition, if the keypad has a 3 by 3 array of keys including the
four arrow keys, the other five keys can be given as kal, ka3, kb2, kcl, and kc3.
These keys are useful when the effects of a 3 by 3 directional pad are needed.
Further keys are defined above in the capabilities list.
Strings to program function keys can be specified as pfkey, pfioc, and pfx. A
string to program screen labels should be specified as pin. Each of these strings
takes two parameters: a function key identifier and a string to program it with.
pfkey causes pressing the given key to be the same as the user typing the given
string; pfloc causes the string to be executed by the terminal in local mode; and
pfx causes the string to be transmitted to the computer. The capabilities niab, iw
and ih define the number of programmable screen labels and their width and
height. If there are commands to turn the labels on and off, give them in smln
and rmin. smin is normally output after one or more pin sequences to make sure
that the change becomes visible.
Section 1-9: Tabs and Initialization
If the device has hardware tabs, the command to advance to the next tab stop can
be given as ht (usually control I). A "backtab" command that moves leftward to
the next tab stop can be given as cbt. By convention, if tty modes show that tabs
are being expanded by the computer rather than being sent to the device, programs
should not use ht or cbt (even if they are present) because the user may not have
248

terminfo (4)
the tab stops properly set. If the device has hardware tabs that are initially set
every n spaces when the device is powered up, the numeric parameter it is given,
showing the number of spaces the tabs are set to. This is normally used by tput
init [see tput(l)] to determine whether to set the mode for hardware tab expansion and whether to set the tab stops. If the device has tab stops that can be saved
in nonvolatile memory, the terminfo description can assume that they are properly
set. If there are commands to set and clear tab stops, they can be given as tbe (clear
all tab stops) and hts (set a tab stop in the current column of every row).
Other capabilities include: isi, is2, and is3, initialization strings for the device;
iprog, the path name of a program to be run to initialize the device; and if, the
name of a file containing long initialization strings. These strings are expected to
set the device into modes consistent with the rest of the terminfo description.
They must be sent to the device each time the user logs in and be output in the following order: run the program iprog; output isi; output is2; set the margins
using mge, smgl and smgr; set the tabs using too and hts; print the file if; and
finally output is3. This is usually done using the init option of tput.
Most initialization is done with is2. Special device modes can be set up without
duplicating strings by putting the common sequences in is2 and special cases in
isi and is3. Sequences that do a reset from a totally unknown state can be given
as rsi, rs2, rf, and rs3, analogous to isi, is2, is3, and if. (The method using
files, if and rf, is used for a few terminals, from /usr/share/lib/tabset/*;
however, the recommended method is to use the initialization and reset strings.)
These strings are output by tput reset, which is used when the terminal gets into a
wedged state. Commands are normally placed in rsi, rs2, rs3, and rf only if they
produce annoying effects on the screen and are not necessary when logging in. For
example, the command to set a terminal into 80-column mode would normally be
part of is2, but on some terminals it causes an annoying glitch on the screen and is
not normally needed because the terminal is usually already in 80-column mode.
If a more complex sequence is needed to set the tabs than can be described by using
tbe and hts, the sequence can be placed in is2 or if.
Any margin can be cleared with mge. (For instructions on how to specify
commands to set and clear margins, see "Margins" below under "PRINTER
CAPABILITIES.")
Section 1-10: Delays

Certain capabilities control padding in the tty driver. These are primarily needed
by hard-copy terminals, and are used by tput init to set tty modes appropriately.
Delays embedded in the capabilities er, ind, eubi, ff, and tab can be used to set
the appropriate delay bits to be set in the tty driver. If pb (padding baud rate) is
given, these values can be ignored at baud rates below the value of pb.
Section 1-11: Status Lines
If the terminal has an extra "status line" that is not normally used by software, this

fact can be indicated. If the status line is viewed as an extra line below the bottom
line, into which one can cursor address normally (such as the Heathkit h19's 25th
line, or the 24th line of a VT100 which is set to a 23-line scrolling region), the capability hs should be given. Special strings that go to a given column of the status line
and return from the status line can be given as tsl and fsl. (fsl must leave the
cursor position in the same place it was before tsl. If necessary, the se and re
249

terminfo ( 4)
strings can be included in tsl and fsl to get this effect.} The capability tsl takes
one parameter, which is the column number of the status line the cursor is to be
moved to.
If escape sequences and other special commands, such as tab, work while in the
status line, the flag eslok can be given. A string which turns off the status line (or
otherwise erases its contents) should be given as dsl. If the terminal has commands to save and restore the position of the cursor, give them as sc and rc. The
status line is normally assumed to be the same width as the rest of the screen, for
example, cols. If the status line is a different width (possibly because the terminal
does not allow an entire line to be loaded) the width, in columns, can be indicated
with the numeric parameter wsl.

Section 1-12: Line Graphics
If the device has a line drawing alternate character set, the mapping of glyph to
character would be given in acsc. The definition of this string is based on the alternate character set used in the DEC VT100 terminal, extended slightly with some
characters from the AT&T 44lOvl terminal.
glyph name
arrow pointing right
arrow pointing left
arrow pointing down
solid square block
lantern symbol
arrow pointing up
diamond
checker board (stipple)
degree symbol
plus/minus
board of squares
lower right comer
upper right comer
upper left comer
lower left comer
plus
scan line 1
horizontal line
scan line 9
left tee (~)
right tee ( -I)
bottom tee ( 1)
top tee ( I) vertical line
bullet

vtloo+
character
+

0
I

a
f
g

h
j
k
1
m

n
0

s
t
u
v
w

The best way to describe a new device's line graphics set is to add a third column to
the above table with the characters for the new device that produce the appropriate
glyph when the device is in the alternate character set mode. For example,

250

terminfo (4)

glyph name
upper left corner
lower left corner
upper right corner
lower right corner
horizontal line
vertical line

vtloo+
char

new tty
char

I
m
k

Now write down the characters left to right, as in "acsc=IRmFkTjGq\,x.".
In addition, terminfo allows you to define multiple character sets. See Section 2-5
for details.
Section 1·13: Color Manipulation

Let us define two methods of color manipulation: the Tektronix method and the HP
method. The Tektronix method uses a set of N predefined colors (usually 8) from
which a user can select "current" foreground and background colors. Thus a terminal can support up to N colors mixed into N*N color-pairs to be displayed on the
screen at the same time. When using an HP method the user cannot define the foreground independently of the background, or vice-versa. Instead, the user must
define an entire color-pair at once. Up to M color-pairs, made from 2*M different
colors, can be defined this way. Most existing color terminals belong to one of these
two classes of terminals.
The numeric variables colors and pairs define the number of colors and colorpairs that can be displayed on the screen at the same time. If a terminal can change
the definition of a color (for example, the Tektronix 4100 and 4200 series terminals),
this should be specified with ccc (can change color). To change the definition of a
color (Tektronix 4200 method), use initc (initialize color). It requires four arguments: color number (ranging from 0 to colors-I) and three RGB (red, green, and
blue) values or three HLS colors (Hue, Lightness, Saturation). Ranges of RGB and
HLS values are terminal dependent.
Tektronix 4100 series terminals only use HLS color notation. For such terminals (or
dual-mode terminals to be operated in HLS mode) one must define a boolean variable hIs; that would instruct the curses init_color routine to convert its RGB
arguments to HLS before sending them to the terminal. The last three arguments to
the initc string would then be HLS values.
If a terminal can change the definitions of colors, but uses a color notation different
from RGB and HLS, a mapping to either RGB or HLS must be developed.
To set current foreground or background to a given color, use setaf (set ANSI
foreground) and setab (set ANSI background). They require one parameter: the
number of the color. To initialize a color-pair (HP method), use initp (initialize
pair). It requires seven parameters: the number of a color-pair (range=O to
pairs-I), and six RGB values: three for the foreground followed by three for the
background. (Each of these groups of three should be in the order RGB.) When
initc or initp are used, RGB or HLS arguments should be in the order "red,
green, blue" or "hue, lightness, saturation"), respectively. To make a color-pair
current, use scp (set color-pair). It takes one parameter, the number of a color-pair.

251

terminfo(4)
Some terminals (for example, most color terminal emulators for pes) erase areas of
the screen with current background color. In such cases, bee (background color
erase) should be defined. The variable op (original pair) contains a sequence for setting the foreground and the background colors to what they were at the terminal
start-up time. Similarly, oc (original colors) contains a control sequence for setting
all colors (for the Tektronix method) or color-pairs (for the HP method) to the
values they had at the terminal start-up time.
Some color terminals substitute color for video attributes. Such video attributes
should not be combined with colors. Information about these video attributes
should be packed into the ncv (no color video) variable. There is a one-ta-one
correspondence between the nine least significant bits of that variable and the video
attributes. The following table depicts this correspondence.
Bit
Decimal
Position
Value
Attribute
A_STANDOUT
0
1
A_UNDERLINE
1
2
A_REVERSE
4
2
A_BLINK
3
8
A_DIM
4
16
A_BOLD
5
32
A_INVIS
64
6
A_PROTECT
7
128
A_ALTCHARSET
256
8
When a particular video attribute should not be used with colors, the corresponding ncv bit should be set to 1; otherwise it should be set to zero. To determine the
information to pack into the ncv variable, you must add together the decimal
values corresponding to those attributes that cannot coexist with colors. For example, if the terminal uses colors to simulate reverse video (bit number 2 and decimal
value 4) and bold (bit number 5 and decimal value 32), the resulting value for ncv
will be 36 (4 + 32).

Section 1-14: Miscellaneous
If the terminal requires other than a null (zero) character as a pad, then this can be
given as pad. Only the first character of the pad string is used. If the terminal does
not have a pad character, specify Dpc.
If the terminal can move up or down half a line, this can be indicated with hu (halfline up) and hd (half-line down). This is primarily useful for superscripts and subscripts on hardcopy terminals. If a hardcopy terminal can eject to the next page
(form feed), give this as ff (usually control L).
If there is a command to repeat a given character a given number of times (to save
time transmitting a large number of identical characters) this can be indicated with
the parameterized string rep. The first parameter is the character to be repeated
and the second is the number of times to repeat it. Thus, tparm(repeat_char,
'x', 10) is the same as xxxxxxxxxx.

252

terminfo (4)
If the terminal has a settable command character, such as the Tektronix 4025, this
can be indicated with cmdch. A prototype command character is chosen which is
used in all capabilities. This character is given in the cmdch capability to identify it.
The following convention is supported on some UNIX systems: If the environment
variable CC exists, all occurrences of the prototype character are replaced with the
character in CC.

Terminal descriptions that do not represent a specific kind of known terminal, such
as switch, dialup, patch, and network, should include the gn (generic) capability so
that programs can complain that they do not know how to talk to the terminal.
(This capability does not apply to virtual terminal descriptions for which the escape
sequences are known.) If the terminal is one of those supported by the UNIX system virtual terminal protocol, the terminal number can be given as vt. A line-turnaround sequence to be transmitted before doing reads should be specified in rf i.
If the device uses xon/xoff handshaking for flow control, give xon. Padding information should still be included so that routines can make better decisions about
costs, but actual pad characters will not be transmitted. Sequences to turn on and
off xon/xoff handshaking may be given in SIllXon and rmxon. If the characters used
for handshaking are not ~s and ~Q, they may be specified with xonc and xoffc.
If the terminal has a "meta key" which acts as a shift key, setting the 8th bit of any
character transmitted, this fact can be indicated with kIn. Otherwise, software will
assume that the 8th bit is parity and it will usually be cleared. If strings exist to turn
this "meta mode" on and off, they can be given as smm and rmm.
If the terminal has more lines of memory than will fit on the screen at once, the
number of lines of memory can be indicated with 1m. A value of lm#O indicates that
the number of lines is not fixed, but that there is still more memory than fits on the
screen.

Media copy strings which control an auxiliary printer connected to the terminal can
be given as meO: print the contents of the screen, me4: turn off the printer, and me5:
turn on the printer. When the printer is on, all text sent to the terminal will be sent
to the printer. A variation, mc5p, takes one parameter, and leaves the printer on for
as many characters as the value of the parameter, then turns the printer off. The
parameter should not exceed 255. If the text is not displayed on the terminal screen
when the printer is on, specify mc5i (silent printer). All text, including mc4, is transparently passed to the printer while an me5p is in effect.
Section 1-15: Special Cases

The working model used by terminfo fits most terminals reasonably well. However, some terminals do not completely match that model, requiring special support
by terminfo. These are not meant to be construed as deficiencies in the terminals;
they are just differences between the working model and the actual hardware. They
may be unusual devices or, for some reason, do not have all the features of the terminfo model implemented.
Terminals that cannot display tilde
nals, should indicate hz.

n characters, such as certain Hazeltine termi-

253

term info (4)
Terminals that ignore a linefeed immediately after an am wrap, such as the Concept
100, should indicate xenl. Those terminals whose cursor remains on the right-most
column until another character has been received, rather than wrapping immediately upon receiving the right-most character, such as the VT100, should also indicate xenl.
If el is required to get rid of standout (instead of writing normal text on top of it),
xhp should be given.

Those Teleray terminals whose tabs turn all characters moved over to blanks,
should indicate xt (destructive tabs). This capability is also taken to mean that it is
not possible to position the cursor on top of a "magic cookie." Therefore, to erase
standout mode, it is necessary, instead, to use delete and insert line.
Those Beehive Superbee terminals which do not transmit the escape or control-C
characters, should specify xsb, indicating that the f1 key is to be used for escape
and the f2 key for control C.
Section 1-16: Similar Terminals
If there are two very similar terminals, one can be defined as being just like the
other with certain exceptions. The string capability use can be given with the name
of the similar terminal. The capabilities given before use override those in the terminal type invoked by use. A capability can be canceled by placing xx@ to the left
of the capability definition, where xx is the capability. For example, the entry
att4424-2lTeletype 4424 in display function group ii,
reV@, sgr@, smul@, use=att4424,

defines an AT&T 4424 terminal that does not have the rev, sgr, and smul capabilities, and hence cannot do highlighting. This is useful for different modes for a terminal, or for different user preferences. More than one use capability may be
given.
PART 2: PRINTER CAPABILITIES
The terminfo database allows you to define capabilities of printers as well as terminals. To find out what capabilities are available for printers as well as for terminals, see the two lists under "DEVICE CAPABILITIES" that list capabilities by variable and by capability name.
Section 2-1: Rounding Values
Because parameterized string capabilities work only with integer values, we recommend that terminfo deSigners create strings that expect numeric values that have
been rounded. Application designers should note this and should always round
values to the nearest integer before using them with a parameterized string capability.
Section 2-2: Printer Resolution
A printer's resolution is defined to be the smallest spacing of characters it can
achieve. In general printers have independent resolution horizontally and vertically. Thus the vertical resolution of a printer can be determined by measuring the
smallest achievable distance between consecutive printing baselines, while the horizontal resolution can be determined by measuring the smallest achievable distance
between the left-most edges of consecutive printed, identical, characters.

254

terminfo (4)
All printers are assumed to be capable of printing with a uniform horizontal and
vertical resolution. The view of printing that terminfo currently presents is one of
printing inside a uniform matrix: All characters are printed at fixed positions relative to each "cell" in the matrix; furthermore, each cell has the same size given by
the smallest horizontal and vertical step sizes dictated by the resolution. (The cell
size can be changed as will be seen later.)
Many printers are capable of "proportional printing," where the horizontal spacing
depends on the size of the character last printed. terminfo does not make use of
this capability, although it does provide enough capability definitions to allow an
application to simulate proportional printing.
A printer must not only be able to print characters as close together as the horizontal and vertical resolutions suggest, but also of "moving" to a position an integral
multiple of the smallest distance away from a previous position. Thus printed characters can be spaced apart a distance that is an integral multiple of the smallest distance, up to the length or width of a single page.
Some printers can have different resolutions depending on different "modes." In
"normal mode," the existing terminfo capabilities are assumed to work on
columns and lines, just like a video terminal. Thus the old lines capability would
give the length of a page in lines, and the eols capability would give the width of a
page in columns. In "micro mode," many tenninfo capabilities work on increments of lines and columns. With some printers the micro mode may be concomitant with normal mode, so that all the capabilities work at the same time.
Section 2-3: Specifying Printer Resolution

The printing resolution of a printer is given in several ways. Each specifies the resolution as the number of smallest steps per distance:
Specification of Printer Resolution
Characteristic Number of Smallest Steps
orhi
Steps per inch horizontally
orvi
Steps per inch vertically
ore
Steps per column
orl
Steps per line
When printing in normal mode, each character printed causes movement to the
next column, except in special cases described later; the distance moved is the same
as the per-column resolution. Some printers cause an automatic movement to the
next line when a character is printed in the rightmost position; the distance moved
vertically is the same as the per-line resolution. When printing in micro mode,
these distances can be different, and may be zero for some printers.
Specification of Printer Resolution
Automatic Motion after Printing
Normal Mode:
ore
Steps moved horizontally
orl
Steps moved vertically

255

terminfo (4)
Micro Mode:
Steps moved horizontally
mls
Steps moved vertically
mes

Some printers are capable of printing wide characters. The distance moved when a
wide character is printed in normal mode may be different from when a regular
width character is printed. The distance moved when a wide character is printed in
micro mode may also be different from when a regular character is printed in micro
mode, but the differences are assumed to be related: If the distance moved for a regular character is the same whether in normal mode or micro mode (mes=ore), then
the distance moved for a wide character is also the same whether in normal mode
or micro mode. This doesn't mean the normal character distance is necessarily the
same as the wide character distance, just that the distances don't change with a
change in normal to micro mode. However, if the distance moved for a regular
character is different in micro mode from the distance moved in normal mode
(mes
DESCRIPTION

The unistd. h header file defines the symbolic constants and structures not already
defined or declared in some other header file. The contents of this file are shown
below.
The following symbolic constants are defined for the access function [see
access(2)]:
R_OK
Test for read permission.
W_OK
Test for write permission.
X_OK
Test for execute (search) permission.
F_OK
Test for existence of file.
The constants F _OK, R_OK, W_OK and X_OK and the expressions R_OK I W_OK,
R_OK I X_OK and R_OK I W_OK I X_OK all have distinct values.
Declares the constant
NULL
null pointer
The following symbolic constants are defined for the lockf function [see
lockf(3C)]:
F_ULOCK
Unlock a previously locked region.
F_LOCK
Lock a region for exclusive use.
F_TLOCK
Test and lock a region for exclusive use.
F_TEST
Test a region for other processes locks.
The following symbolic constants are defined for the lseek [see Iseek(2)] and
fcntl [see fcntl(2)] functions (they have distinct values):

Set file offset to offset.
Set file offset to current plus offset.
Set file offset to EOF plus offset.
The following symbolic constants are defined (with fixed values):
Integer value indicating version of the POSIX
standard.
Integer value indicating version of the XPG to
which system is compliant.
SEEK_SET
SEEK_CUR
SEEK_END

The follOWing symbolic constants are defined to indicate that the option is present:
_POSIX_JOB_CONTROL
Implementation supports job control.
_POSIX_BAVED_IDS
The exec functions [see exec(2)] save the effective user and group.
in
Terminal special characters defined
tennios.h [see tennio(7)] can be disabled using
this character.

275

unistd(4)
The following symbolic constants are defined for sysconf [see sysconf(3C)]:
_SC_ARG_MAX
_SC_CHILO_MAX
_SC_CLK_TCK
_SC_JOB_CONTROL
_SC_LOGNAME_MAX
_SC_NGROUPS_MAX
_SC_OPEN_MAX
_SC_PAGESIZE
_SC_PASS_MAX
_SC_SAVED_IDS
_SC_VERSION
_SC_XOPEN_VERSION

The following symbolic constants are defined for pathconf [see fpathconf(2)]:
_PC_CHOWN_RESTRICTED
_PC_LINK_MAX
_PC_MAX_CANON
_PC_MAX_INPUT
_PC_NAME_MAX
_PC_NO_TRUNC
_PC_PATH_MAX
_PC_PIPE_BUF
_PC_VDISABLE

The following symbolic constants are defined for file streams:
STDIN_FILENO
File number of stdin. It is O.
STDOUT_FILENO
File number of stout. It is 1.
STDERR_FILENO
File number of stderr. It is 2.
The following pathnames are defined:
GF_PATH
Pathname of the group file.
PF_PATH
Pathname of the passwd file.
SEE ALSO

access(2), exec(2), fcnt1(2), fpathconf(2), group(4), lseek(2), passwd(4),
sysconf(3C), tennio(7), tennios(2)
NOTES

The following values for constants are defined for this release of System V:
_POSIX_VERSION
198808L
_XOPEN_VERSION
3

276

updaters (4)
NAME

updaters - configuration file for Network Information Service (NIS) updating
SYNOPSIS

/var/yp/updaters
DESCRIPTION

The file /var/yp/updaters is a makefile [see make(l)] which is used for updating
NIS databases. Databases can only be updated in a secure network, that is, one that
has a publickey(4) database. Each entry in the file is a make target for a particular
NIS database. For example, if there is a NIS database named publickey.byname
that can be updated, there should be a make target named publickey. byname in
the updaters file with the command to update the file.
The information necessary to make the update is passed to the update command
through standard input. The information passed is described below (all items are
followed by a NEWLINE, except for the actual bytes of key and actual bytes of date).
network name of client wishing to make the update (a string)
kind of update (an integer)
number of bytes in key (an integer)
actual bytes of key
number of bytes in data (an integer)
actual bytes of data
After getting this information through standard input, the command to update the
particular database should decide whether the user is allowed to make the change.
If not, it should exit with the status YPERR_ACCESS. If the user is allowed to make
the change, the command should make the change and exit with a status of zero. If
there are any errors that may prevent the updater from making the change, it
should exit with the status that matches a valid NIS error code described in
.
FILES

/var/yp/updaters
SEE ALSO

make(l), publickey(4), ypupdate(3N), ypupdated(lM)

277

utmp(4)
NAME
ut~,

wtII\P - utmp and wtmp entry formats

SYNOPSIS

#include
DESCRIPTION

These files, which hold user and accounting information for such commands as who,
write, and login, have the following structure, defined in utmp.h:
#define UTMP_FILE
#define WTMP_FILE
#define ut_name

"/var/adm/utmp"
"/var/adm/wtmp"
ut_user

The utmp structure includes the following members:
char
char

ut_user[81;
ut_id[41;

char
short
ut-pid;
short
ut_type;
struct exit_status
short e_termination;
short e_exit;
} ut_exit;

Definitions for ut_type

#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
/*
/*
/*
/*

RUN_LVL
BOOT_TIME
OLD_TIME
NEW_TIME
INIT_PROCESS
LOGIN_PROCESS
USER_PROCESS
DEAD_PROCESS
ACCOUNTING
UTMAXTYPE

/* process termination status */
/* process exit status */
/* exit status of a process
* marked as DEAD_PROCESS */
/* time entry was made */
*/

0
1
2
3

4
5
6
7

/* process spawned by "init" */
/* a "getty" process waiting for login */
/* a user process */

8
9

ACCOUNTING

/* max legal value of ut_type */

Below are special strings or formats used in the "ut_line" */
field when accounting for something other than a process. */
No string for the ut_line field should be no more than 11 chars +
a null character in length. */

#define
#define
#define
#define

278

EMPTY

user login name */
/etc/inittab id (created by */
process that puts entry in utmp) */
device name (console, lnxx) */
/* process id * /
/ * type of entry * /
/*
/*
/*
/*

RUNLVL_MSG
BOOT_MSG
OTIME_MSG
NTIME_MSG

"run-level %e"
"system boot"
"old time"
"new time"

utmp(4)
FILES

/var/adm/utmp
/var/adm/wtmp
SEE ALSO

getut(3C), login(l), utmpx(4), who(l), write(l)

279

utmpx(4)
NAME

utmpx, wtllIpx - utmpx and wtmpx entry formats
SYNOPSIS

#include
DESCRIPTION

utmpx(4) is an extended version of utDi>(4).

These files, which hold user and accounting information for such commands as who,
wri te, and login, have the following structure as defined by ut!lpX. h:
#define
#define
#define
#define

UTMPX_FILE
"/var/adm!utmpx"
WTMPX_FILE
"/var/adm/wtmpx"
ut_name
ut_user
ut_xtime
ut_tv.tv_sec

The utmpx structure includes the following members:
char
ut_user[32];
1* user login name *1
char
ut_id[4];
1* inittab id *1
char
ut_line[32];
1* device name (console, lnxx) *1
pid_t ut-pid;
1* process id *1
short ut_type;
1* type of entry *1
struct exit_status {
short e_termination;
1* termination status *1
short e_exit;
1* exit status *1
} ut_exit;
1* process terminationlexit status *1
struct timeval {
long tv_sec;
1* seconds *1
long tv_usee;
1* and microseconds *1
ut_tv;
1* time entry was made *1
long
ut_session;
1* session ID, used for windowing *1
long
pad[S] ;
1* reserved for future use *1
short ut_syslen;
1* significant length of ut_host *1
1* including terminating null *1
char
1* remote host name *1

1* Definitions for ut_type *1

280

#define
#define
#define
#define
#define
#define
#define
#define
#define
#define

EMPTY

RUN_LVL
BOOT_TIME
OLD_TIME
NEW_TIME
INIT_PROCESS
LOGIN_PROCESS
USER_PROCESS
DEAD_PROCESS
ACCOUNTING

#define

UTMAXTYPE

2
3
4
5
6
7
8
9

1* Process spawned by "init" *1
1* A "getty" process waiting for login *1
1* A user process *1

ACCOUNTING

1* Largest legal value of ut_type *1

utmpx(4)
/*
/*
/*
/*

Below are special strings or formats used in the "ut_Iine" */
field when accounting for something other than a process. */
No string for the ut_Iine field should be more than 31 chars + */
a null character in length. */

#define
#define
#define
#define
#define

RUNLVL_MSG
BOOT_MSG
OTIME_MSG
NTIME_MSG
MOD_WIN

"run-level %e"
"system boot"
"old tilDe"
"new tilDe"
10

FILES
/var/adm/u~
/var/adm/~

SEE ALSO

getutx(3C), login(l), utmp(4), who(l), write(l)

281

uuencode(4)

(Basic Networking Utilities)

NAME

uuencode - format of an encoded uuencode file
DESCRIPTION

Files output by uuencode consist of a header line, followed by a number of body
lines, and a trailer line. uudecode ignores any lines preceding the header or
following 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 followed by a space). 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, followed by encoded
characters, followed 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 from 0 to 63 and can be determined by subtracting the character space (octal 40) from the character.
Groups of 3 bytes are stored in 4 characters, 6 bits per character. All 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 characters will be included to make the character
count a multiple of 4. The body is terminated by a line with a count of zero. This
line consists of one ASCII space.
The trailer line consists of end on a line by itself.
SEE ALSO

mail(l), uucp(lC), uuencode(lC)

282

vfstab (4)
NAME

vfstab - table of file system defaults
SYNOPSIS

#include
#include
#include
DESCRIPTION

The file /etc/vfstab describes defaults for each file system. The information is in
the following structure, defined in sys/vfstab.h:
struct vfstab {
char
*vfs_special;
char
*vfs_fsckdev;
char
*vfs_mountp;
char
*vfs_fstype;
char
*vfs_fsckpass;
char
*vfs_automnt;
char
*vfs_mntopts;
char
*vfs_macceiling;
};

The fields in the table are space-separated and show the block special or resource
name, the raw device to fsck, the default mount directory, the name of the file system type, the number used by fsck to decide whether to check the file system
automatically, whether the file system should be mounted automatically by
mountall, the mount options, and the default file system level ceiling. If Enhanced
Security is not installed, the field that displays the default file system level ceiling is
not used. A' -' is used to indicate no entry in a field.
The getvfsent(3C) family of routines are used to read and write to /etc/vfstab.
NOTES

Do not store information in the vfstab file other than the fields described above;
fields may be added to this file in future releases and are reserved for future use.
SEE ALSO

fsck(lM), getvfsent(3C), mount(lM), setmnt(lM)

283

Xwincmaps (4)
NAME

Xwincmaps - XWIN color map file
DESCRIPTION

The server reads the /usr/X/defaults/Xwincmaps file to fill up the static color
map. Each line has 'R', 'G', and 'B' values. There are several colormaps in the
default Xwincmaps file, but custom colormaps can be created and added to this file.
The server takes the first uncommented colormap (without '#' in the first column)
as the valid colormap data.
The format of the colormap data is:
colormap type screen_num num_colors

RED VAL, BLUE VAL, GREEN VAL,
RED=VAL , BLUE=VAL , GREEN=VAL ,

Where
colormap

key word. This is the same for all entries.
type of colormap. This can be PseudOColor, StaticColor, or

type

GrayScale.

screen num

screen number

num colors

number of colors

RED VAL
red value
GREEN VAL green value
BLUE VAL blue value
The number of RED VAL BLUE_VAL GREEN_VAL lines should be the same as
I

num colors.

USAGE

To use the colormap of your choice, add a # to the current definition and remove
the # sign in front of the new definition line, for example,
colormap

StaticColor

o. 0

To use a private copy of your color map, either of the following commands can be
used.
olinit -- -cmap $HOME/mycmap
X -cmap $HOME/mycmap &

284

Xwincmaps (4)
EXAMPLES
The following is equivalent to the default colormap on the XWIN server.

colonnap
OxOOOO,
OxFFFF,
OxAAAA,
OxOOOO,
OxOOOO,
OxOOOO,
OxOOOO,
OxOOOO,
OxOOOO,
OxAAAA,
OxAAAA,
OxFFFF,
OxFFFF,
OxAAAA,
OxFFFF,
OxFFFF,

StaticColor
OxOOOO,
OxFFFF,
OxAAAA,
OxOOOO,
OxOOOO,
OxAAAA,
OxFFFF,
OxAAAA,
OxFFFF,
OxFFFF,
Ox5555,
OxAAAA,
OxFFFF,
OxOOOO,
OxOOOO,
OxOOOO,

0.0
OxOOOO,
OxFFFF,
OxAAAA,
OxAAAA,
OxFFFF,
OxFFFF,
OxFFFF,
OxOOOO,
OxOOOO,
Ox5555,
OxOOOO,
OxOOOO,
OxOOOO,
OxAAAA,
OxFFFF,
OxOOOO,

#colonnap
OxOOOO,
Oxffff,
Oxa699,
OxOOOO,
OxOOOO,
OxOOOO,
OxOOOO,
OxOOOO,
OxOOOO,
Ox2081,
Oxaaaa,
Oxf3ce,
Oxffff,
Oxaaaa,
Ox9248,
Oxffff,

StaticColor
OxOOOO,
Oxffff,
Oxa699,
OxOOOO,
Ox5144,
Oxaaaa,
Oxe79d,
Oxaaaa,
Oxdf7d,
Ox8e38,
Ox5555,
Oxge79,
Oxffff,
OxOOOO,
Oxcb2b,
OxOOOO,

0.0
OxOOOO,
Oxffff,
Oxa699 ,
Oxaaaa,
Oxffff,
Oxffff,
Oxe79d,
OxOOOO,
OxOOOO,
Ox69a6,
OxOOOO,
OxOOOO,
OxOOOO,
Oxaaaa,
Ox9248,
OxOOOO,

16
#
#
#
#
#
#
#
#
#
#
#
#
#
#

a bit darker than openlook gray
navy

a bit less saturated than blue
sky blue
a bit darker than openlook cyan
lime green (openlook forestgreen)
a bit darker than green
sea green
brown
a bit darker than openlook orange
yellow
violet
wheat-like color
red

NOTES

PseudoColor is not recommended for 16 colors.
SEE ALSO

Xwinconf ig(4)

285

Xwinconfig (4)
NAME

xwinconfig - XWIN configuration file
DESCRIPTION

The server reads the first uncommented line in the Xwinconfig file for information
about the display, colormap, and the information needed by the display driver. All
the required data is on one line.
To change the current configuration, use the setvgamode command. To change
modes manually, see the section "Editing the Xwinconfig File" below. In either
case, the user must have appropriate privileges.
The format of the data of the first line in xwinconfig file is:
display class cmap "INFO for SDD" scr_num tty display_lib
Where
display

device

display class, for example, VGA16, VGA256, EGA, 8514, XGA, and
soon.
cmap
type of colormap, for example, StaticColor or PseudoColor
INFO_for_SDD
information passed to SDD, for example, info passed to
libvga16 . so. See USAGE for a detailed description of this
field.
scr_num screen number

class

tty

tty, for example, /dev/console

display_lib
display library to link at run time, for example, libvga16. so or
libvga256.so
USAGE

The following two sample entries in the Xwinconfig file illustrate the file format.
Each line has been split in two (with a \ at the end of the first line) for display here,
in the Xwinconfig file, each is one line.
display VGA16 StaticColor "VGA STDVGA 640x480 16 9.75x7.32" \
o /dev/console /usr/X/lib/libvga16.so
display VGA256 StaticColor "ET4000 MULTISYNC 1024x768 9.75x7.32" \
o /dev/console /usr/X/lib/libvga16.so

Description of the various fields:
1st field
type of device (currently, always display)
2nd field
3rd field

286

video class (for example, VGA16, VGA256, XGA, 8514, and so on)
color class (always StaticColor for VGA16, PseudoColor for 256
and other high performance boards, and GrayScale for monochrome)

Xwinconfig (4)
4th field

information passed to the "display driver" which is linked at run
time. The format of this string is dependent on the display driver
and varies for different display boards. Entries for both 16 and 256
colors can reside in the same configuration file. For example:
"ET4000 MULTISYNC 800x600 16 10.0x9.0"
ET4000

vendor or chipset identification.

MULTI SYNC
800x600
16

type of monitor
resolution (width x height) in pixels
number of colors. For a 256 color driver, this field is
omitted, because it supports only 256 colors. For a 16
color driver, this field may be 2, 4, or 16. For monochrome, this field must be 2.

10. Ox9 • 0 monitor size (width x height) in inches

5th field

display number

6th field

the actual device (in most cases /dev/console)

7th field

the display driver

Editing the Xwinconfig file

For the advance user, editing the Xwinconfig file manually may be more flexible.
The first uncommented line (without a # in the first column) is treated as a valid
entry in the file.
To use a private copy of a configuration file, either of the following commands can
be used:
olinit
-config $HOME/mycfg
X -config $HOME/mycfg &

To return to the default mode (640x480, 16 colors), run the setvgamode command
with the -default option.
Examples

This example illustrates how to manually set up files for a particular mode. The
display is a Tseng Labs ET4000 based board and the mode is 1024x768 mode with
256 colors.
cp /usr/X/lib/vgainit/et4k_256i.so /usr/X/lib/libv256i.so.1
cp /usr/X/lib/vgainit/et4k.256cfg /usr/X/defaults/xwinconfig

Edit the /usr/X/defaults/Xwinconfig file and remove the # sign in the first
column of the line that has the 1024x768 entry. Make sure that all lines in the file
before this entry are commented, as the first line without a # in the 1st column is
treated as the active entry.

287

Xwinconfig (4)
The procedure is the same for 16 modes. (that is, copy the et4k_16i. so and
et4k.16cfg files).
The following example demonstrates creating a private copy of the config files,
(avoids editing the system Xwinconfig file):
cp /usr/X/lib/vgainit/et4k.16cfg $HOME/cfg16
cp /usr/X/lib/vgainit/et4k.256cfg $HOME/cfg256
Now to run the server, either command can be used.
X -config $HOME/cfg16
X -config $HOME/cfg256
The standard VGA 640x480 mode is supported by all the 16 color SDDs. To find
out the various entries provided by a particular SDD, follow the instructions above
and give an invalid entry for the first field of the SDD information (for example, foo
rather than ET4000). The following example prints out all the modes supported by
thatSDD.
display VGA16 StaticColor "foo STDVGA 640x480 16 10.0x9.0" \
o /dev/console /usr/X/lib/libvga16.so
Files
/usr/X/adm/setvgamode
/usr/X/defaults/Xwinconfig
/usr/X/defaults/Xwinconfig.ini
SEE ALSO

setvgamode(lM), xwincmaps(4)

288

Xwinfont (4)
NAME

Xwinfont - XWIN font configuration and defaults file (scalable and bitmapped)
SYNOPSIS

lusr/X/defaults/Xwinfont
DESCRIPTION

The Xwinfont file specifies options concerning font rendering to the X server and
allows several different font renders, both bitmapped and scalable, to be used. For
example, it contains font configuration information showing the library to use for a
renderer, the filename suffix for the renderer's font files, and the default pointsize to
use for a scalable font if none is specified by an application.
The design of the font interface in XWIN provides the flexibility to add renderers to
the X server without any code changes if the renderer uses the interface described in
the document Porting the XWIN Server; this is done using dynamic shared libraries.
This configuration file contains the information needed to use any such rendererno changes to the server are required.
This file can also be used to tune font rendering in the server by allowing certain
runtime combinations to be easily changed-for example, tuning for memory
versus speed tradeoffs.
The format of the entries in the xwinfont file is a simple keyword-value pair, with
each element separated by an =. This is the same format as the XllR5 Font Server
configuration file. The following types of values are supported:
cardinal
a non-negative number; generally used for specifying sizes
boolean
I, y, or t shows a feature present, 0, n, or f shows a feature absent; used
for yes/no or true/false possibilities.
string
an ASCII string
list
a list of cardinals or strings separated by commas
Comments can be inserted in the file with lines that start with a #. Invalid options
are logged to stderr ($HOME/.oliniterr) and are skipped. Some options are general options and affect all renderers; others are renderer-specific.
Renderer-specific options begin with a line containing startrenderer=suffix, followed by a variable number of lines containing information specific to that
renderer, and ended by either another line containing startrenderer=suffix or the
end of the file. Suffix is the font filename suffix the renderer uses to recognize files
that it can render. Valid suffixes and their meanings are bitmap distribution format
(bdf), server natural format (snf), portable compiled format (pef), PostScript™
Type 1 format (pfa and pfb), Bitstream Speedo format (spd), and Folio
(TypeScalerTM) F3 format (f3b).
1£ several suffixes are valid for a renderer, as when the font files might have several
valid styles of names, multiple start renderer lines should be supplied, each with
a valid suffix; the same options can be defined for each suffix. For example, the
Type 1 outline font files for use with the Adobe Type ManagerTM renderer can have,
among others, suffixes of pfa or pfb.

289

Xwinfont (4)
The snf format is the default supported bitmap renderer and need not be explicitly
defined. Its shared library is libbitmap. so in /usr/x/lib.
General Font Configuration Options

The options that apply to all renderers or to the X server appear first in the file,
before the renderer-specific options.
fontpath=listojstring

The X server's default font path. This is a list of font path elements that
the server will use in resolving OpenFont and ListFonts requests. It
contains a comma separated list of string entries. If a full pathname is
not given, the server will check the XWINHOME environment variable for
the location of the default installed tree, and will prep end that path to
each partial path. Font server names for fontpaths contain a colon
separating the font server name from the path within the font server.
The environment variable XWINFONTPATH or a server command line
option (-fp) will override this option.
cachesi ze=cardinal
The cachesize option is the maximum value that the font cache can
grow to without causing a font to be freed from the cache before inserting a new font. This value is expressed in K bytes and defaults to 800; it
cannot be set lower than 256. The space is not preallocated for the
cache. The cache will be allowed to grow to this value; if the maximum
value is never reached, the freeing of fonts from the cache will not take
place. Fonts are freed from the cache when they have been closed by all
processes and users that had them open, or when a font is selected by
the cache free routines to keep the maximum cache allocated for fonts
within a maximum size. This maximum size can temporarily be
exceeded if a font is open and more space is needed for the font glyphs;
however, the space will be reduced to below the maximum cachesize at
the first available opportunity. The font that caused the cache to
overflow its maximum value will be chosen to free first, provided it is
not the current font in use.
mincachesize=cardinal

This value is the low water mark for the cache. The value is expressed
in units of K bytes. The cache starts allocating in non-pagesize chunks
when the low water mark is reached. The default value is 90% of
cachesize. The options
cachesize=500
mincachesize=450
would set a maximum font cache size of 500K bytes of memory and a
low-water mark of 450K bytes of memory.
derived -instance-pointsizes=list
Applications may already exist that do not use scalable names, yet use
the ListFonts protocol request with some pattern and expect to receive
a list of fonts that specify a collection of point and pixel sizes. It was
strongly encouraged by the X Logical Font Description Conventions
that server vendors provide a mechanism for including in each scalable

290

Xwinfont (4)
name a list of specific derived instance names for use by these applications. (A derived instance is the result of replacing scalable fields with
values to yield a font name that could actually be produced from the
font source.)
This option contains a list of cardinal values for point sizes that should
be generated for scalable fonts to satisfy such requests. There is no
default value if this is not specified in the file; the value placed in the file
when outline fonts are installed is 10, 12, 14. This option is not used
directly by the X server; its value can be specified as the value of the
DERIVED_INSTANCE_PS environment variable of the mkfontscale program, which creates the XLFD names in the fonts. scale in directories
containing outline fonts (one XLFD name is created for each specified
size, as well as for size 0, which indicates a scalable name). The Font
Setup application of the UNIX Desktop runs the mkfontscale program,
with the environment variable thus set, when the Actions / Integrity
Check button menu item is chosen. The mkfontdir program creates the
fonts.dir file from the fonts.scale file '(this is also run by the
Integrity Check menu button item); the X server reads the fonts.dir
file to determine what fonts and derived instances are available.

Renderer-Specific Configuration Options
A renderer-specific configuration option is an option that only applies to the
renderer used for font files who suffix was named in the most recent startrenderer option. All renderer-specific options must be specified in the entries
that follow a startrenderer=suffix. Duplicate entries, for the same suffix, later in
the file will override any previous entries; only the last set of renderer options in a
file for any given named renderer are set. All options for a given renderer are
grouped together between the start renderer and the next startrenderer in the
file (or the end of the file).
There are both public and private renderer options allowed. Renderer public
options are defined below. Renderer private options are options that are unique to
a specific renderer that might be added to the X server by OEMs and are defined
and checked by the renderering library. Any unrecognized renderer options are
assumed to be private options and are not parsed directly by the configuration file
initialization routines (other than to set a flag to the renderer that private options
were encountered). The renderer must check this flag for possible private options
and for parsing these options. An example of an option that might be useful and
private to a given renderer would be a list of glyphs to preallocate or prerender for
a given font or for all fonts. How to specify the list would be renderer-specific.
startrenderer=suffix

Start defining renderer-specific options for a renderer whose font files
have the file name suffix suffix.

use-renderer=boolean
The use-renderer option shows if this particular renderer should be
used by the X server. The default, if the renderer is specified, and the
use-renderer field is missing, is to include the rendering library. The
server command line option -renderer +suffix or -renderer -suffix
will override this option.

291

Xwinfont (4)
font -type=string
The font-type option denotes the type of rendering supported by this
renderer. Valid values are bitmap, scalable and both. If both bitmap
and scalable are valid, then the value both should be used. The
default type is scalable.
sharedlib-filename=string

Contains the name and location of the font rendering library to load for
this font format type. If the name is not a complete pathname, then the
library will be searched for using the lib directory of the XWINHOME
environment variable. This field will be used when the rendering
library needs to be loaded. If the library is not found, an error will be
returned when a font from that library is needed. This is a mandatory
field. It is reqUired since a renderer could be added after the Desktop
product is released, and a full library specification in this field will
enable the server to handle new font rendering libraries that conform to
the specification outlined in Porting the XWIN Server. If more than one
suffix applies to a single library, then multiple startrenderer entries
and sharedlib-filename entries should be used.
defaul tpoint=cardinal
Contains the default point size to be used in resolving scalable names
that do not specify a point size or a pixel size in the request. This will
be used to generate a derived instance of the font, if no other derived
instance point sizes are given. If not specified, a compiled in default
point size will be used (12).
preallocate-glyphs=cardinal

Rendering all the glyphs at open time requires that space be allocated at
open as well. This will have a longer initialization time for the font as
the glyphs are scaled. The other approach scales the character the first
time it is accessed for display.
If glyphs are preallocated but not prerendered, this ensures enough
space exists to render the entire font, and reserves it even though some
glyphs may never get rendered.
A renderer-specific configuration option (preallocate-glyphs=string),
determines how much space for the glyphs in a font should be preallocated. Value should be a cardinal value that specifies a number
reflecting a percentage of the entire font to preallocate (that is, 10 for
10%). If the value is 0, no glyphs should be preallocated. If the value is
100, all the glyphs in each font should be preallocated; otherwise a
value can be given that will represent the percentage of the total font
glyph size that should be preallocated. The default for bitmap fonts, if
not specified, is to preallocate the space for all the glyphs when the font
is read.
prerender-glyphs=boolean

Another option (prerender-glyphs=boolean) specifies whether all the
glyphs in the font should be rendered at open time (y), or as each glyph
is used in a blitting routine (n). The default for bitmap fonts is they are
already rendered. The default for scalable fonts is not to render the
292

Xwinfont ( 4)
glyph until it is needed, unless some renderer-specific private option
overrides this. (For Adobe Type Manager, when it is installed, this
option is set in the file to y, as this has proven to more efficient, given
the information that the X server must get from the font for each character when just a single character is rendered.)
Other Options

Additional renderer-specific options are available. However, they should not be
changed by a user or the owner of the machine, just an expert administrator or
OEM developer who is monitoring font-related server performance.

preload-renderer=boolean
This option will determine when the rendering library should be opened
and the symbols resolved. If preload-renderer is set to false, the loading
of the font renderer's library will be deferred until a font is needed. This
will conserve the memory required by the library until it is needed, and will
be the default for scalable renderers. If preload-renderer is true, the
library will be loaded at server start up. This is the default for the bitmap
based library containing the default cursor and text fonts.
free- renderer=boolean
This option will determine when the rendering library will be closed and
consequently when the memory used by the library is released. If set to
true, the library will be closed when the last font is closed. This will free the
space, but if another font from the library is opened later, it might cause a
delay to reload the library. This is a performance/memory tradeoff option
and will be helpful in doing internal performance evaluations. The default
is set to false.
alloe-units=cardinal
Indicates the minimum pagesize chunks that should be allocated for this
renderer when allocating space for font glyphs. The default value is one
pagesize chunk.
The alloe-units are saved in the font structure. This will allow renderers
who wish to supply alloe-units by using renderer private options to
override any general value.
download-glyphs=string
Indicates if glyphs of this renderer should be downloaded to device dependent code. Possible values are none, fixed or all. The value fixed indicates only fixed width fonts should be downloaded. If download-glyphs is
none, fonts for this renderer will not be downloaded. If set to all, then all
fonts for this renderer will be downloaded.
download-height=cardinal
This is the maximum height for glyphs in fonts that can be downloaded.
Fonts containing any glyphs larger than height will not be downloaded.
download -width=cardinal
This is the maximum width for glyphs in fonts that can be downloaded.
Fonts containing any glyphs wider than width will not be downloaded.

293

Xwinfont (4)
download-maxchars=cardinal

If fonts are downloadable, then this is the maximum number of glyphs in
fonts that can be downloaded. Fonts containing more characters than
download -maxchars will not be downloaded.
EXAMPLES

The following options allow the Adobe Type Manager renderer to be used:
derived-instance-pointsizes=lO,12,14
#

fontpath= lib/fonts/misc/,lib/fonts/Xol/,lib/fonts/75dpi/, \
lib/fonts/100dpi,lib/fonts/typel,lib/fonts/mitTypel
#
startrenderer=pfa
prerender-glyphs=t
sharedlib-filename=libatm.so
#

startrenderer=pfb
use-renderer=t
prerender-glyphs=t
sharedlib-filename=libatm.so

The \ at the end of the font path line is just notation showing this line is longer than
can be printed here; the \ is not parsed.
NOTES

Partial names that contain a colon are reserved for future font server names.
SEE ALSO

mkfontscale(l), mkfontdir(l)

294

ypfiles (4)
NAME

ypfiles - the Network Information Service (NIS) database and directory structure
DESCRIPTION

The NIS network lookup service uses a distributed, replicated database of dbm files
contained in the /var /yp directory hierarchy on each NIS server. A dbm database
consists of two files, one has the filename extension .pag and the other has the
filename extension .dir. For instance, the database named publickey, is implemented by the pair of files publickey . pag and publickey . dir.
A dbm database served by the NIS is called a NIS map. A NIS ypdomain is a subdirectory of /var/yp containing a set of NIS maps. Any number of NIS domains can
exist. Each may contain any number of maps.
No maps are required by the NIS lookup service itself, although they may be
required for the normal operation of other parts of the system. There is no list of
maps which NIS serves - if the map exists in a given domain, and a client asks
about it, the NIS will serve it. For a map to be accessible consistently, it must exist
on all NIS servers that serve the domain. To provide data consistency between the
replicated maps, an entry to run ypxfr periodically should be made in the
privileged user's crontab file on each server. More information on this topic is in
ypxfr(lM).
NIS maps should contain two distinguished key-value pairs. The first is the key
YP_LAST_MODIFIED, having as a value a ten-character ASCII order number. The

order number should be the system time in seconds when the map was built. The
second key is YP_MASTER_NAME, with the name of the NIS master server as a value.
makedbm(lM) generates both key-value pairs automatically. A map that does not
contain both key-value pairs can be served by the NIS, but the ypserv process will
not be able to return values for "Get order number" or "Get master name"
requests. See ypserv(lM). In addition, values of these two keys are used by ypxfr
when it transfers a map from a master NIS server to a slave. If ypxfr cannot figure
out where to get the map, or if it is unable to determine whether the local copy is
more recent than the copy at the master, extra command line switches must be set
when it is run.
NIS maps must be generated and modified only at the master server. They are

copied to the slaves using ypxfr(lM) to avoid potential byte-ordering problems
among NIS servers running on machines with different architectures, and to minimize the amount of disk space required for the dbm files. The NIS database can be initially set up for both masters and slaves by using ypinit(lM).
All NIS maps have entries in /var/yp/aliases. Each entry includes the map
name and map nickname. The map name and nickname may be the same depending on the filesystem limitation of the length of filenames.
After the server databases are set up, it is probable that the contents of some maps
will change. In general, some ASCII source version of the database exists on the
master, and it is changed with a standard text editor. The update is incorporated
into the NIS map and is propagated from the master to the slaves by running
/Var/yp/Makefile, see ypmake(lM). All Sun-supplied maps have entries in
/var/yp/Makefile; if a NIS map is added, edit this file to support the new map.
The makefile uses makedbm(lM) to generate the NIS map on the master, and

295

ypfiles (4)
yppush(lM) to propagate the changed map to the slaves. yppush is a client of the
map ypservers, which lists all the NIS servers. For more information on this topic,
see yppush(lM).
FILES

/var/yp
/var/yp/aliases
/var/yp/Makefile
SEE ALSO

dbm(3), makedbm(lM), publickey(4), ypinit(lM), ypmake(lM), yppoll(lM),
yppush(lM), ypserv(lM), ypxfr(lM)

296

intro (5)
NAME

intro - introduction to miscellany
DESCRIPTION

This section describes miscellaneous facilities such as macro packages, character set
tables, and so forth.

297

ascii (5)
NAME

ascii - map of ASCII character set
DESCRIPTION

This is a map of the ASCII character set, giving both octal and hexadecimal
equivalents of each character.
1000
1010
1020
1030
1040
1050
1060
1070
1100
1110
1120
1130
1140
1150
1160
1170

00
08
10
18
20
28
30
38
40
48
50
58
60
68
70
78

298

null001
bs 1011
dlel021
can 031
sp 041
(
051
0 061
8 071
@
101
H 111
p
121
X 131
141
h 151
p 161
x 171

soh
ht
dc1
em

null
bs I
dIe'
can
sp

soh
ht
dc1
em

(

0
8
@

H
P
X

h
P

01
09
11
19
21
29
31
39
41
49
51
59
61
69
71
79

)

1
9
A
I

Q
y
a
i
q
y

1
9
A
I

Q
y
a
i
q
y

002
012
022
032
042
052
062
072
102
112
122
132
142
152
162
172

02
Oa
12
1a
22
2a
32
3a
42
4a
52
Sa
62
6a
72
7a

stxl003
nl 1013
dc21023
sub 033
043
* 053
2 063
073
B 103
113
J
R 123
Z 133
b 143
j
153
r
163
z 173

stx
nl
dc2
sub

J
R
Z

b
j

03
Ob
13
1b
23
2b
33
3b
43
4b
53
5b
63
6b
73
7b

etx 004 eotl005
014 np 1015
dc3 024 dc41025
esc 034 fs 1035
# 044 $ 1045
1055
+ 054
3 064 4 1065
074 < 1075
C 104 D 1105
K
114 L 1115
S 124 T 1125
[
134 \ 1135
c 144 d 1145
k 154 1 1155
s 1164 t 1165
1174 I 1175

enql006
cr 1016
nak 026
gs 036
% 046
056
5 066
076
E 106
M 116
U 126
]
136
e 146
m 156
u 166
}
176

ackl007
so 1017
synl027
rs 037
&
047
057
6 067
> 077
F
107
N 117
V
127
137
f 147
n 157
v 167
177

w
dell

etx
vt
dc3
esc

enql
cr ,
nak
gs

ack
so
syn
rs

bell
si ,
etb
us

#
+
3
C
K

S
[

c
k
s
{

04
Oc
14
1c
24
2c
34
3c
44
4c
54
5c
64
6c
74
7c

eotl
np ,
dc4
fs

$
4
<
D
L

\
d
1

05
Od
15
1d
25
2d
35
3d
45
4d
55
5d
65
6d
75
7d

5
E
M
U
]

m
u

06
Oe
16
1e
26
2e
36
3e
46
4e
56
5e
66
6e
76
7e

6
>
F

N
V

f
n
v

07
Of
17
1f
27
2f
37
3f
47
4f
57
Sf
67
6f
77
7f

bell
si I
etbl
us
I

/
7
?
G

0
W

g
0

/
7
?
G

0
W

g
0

w
del

environ (5)
NAME

environ - user environment
DESCRIPTION

When a process begins execution, exec routines make available an array of strings
called the environment [see exec(2)]. By convention, these strings have the form
variable=value, for example, PATH=/sbin: /usr/sbin. These environmental variables provide a way to make information about a program's environment available
to programs. The following environmental variables can be used by applications
and are expected to be set in the target runtime environment.
HOME
The name of the user's login directory, set by login{l) from the password file [see passwd(4)].
The program's locale. Locales consist of files that describe the convenLANG
tions appropriate to some nationality, culture, and language. Generally, users determine which files are selected by manipulating the
environment variables described below. For background, see
set1oca1e{3C).
Locales are partitioned into categories LC_COLLATE, LC_CTYPE,
LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and LC_TIME (see below
for what the categories control). Each category has a corresponding
environment variable that the user can set to specify that category's
locale:
LC_CTYPE=fr[ancais]
The LANG environment variable is searched if the environment variable for a category is unset or empty:
LANG=fr
LC_COLLATE=de[utsche]
sets all the categories but LC_COLLATE to French. If LANG is unset or
empty, the default C locale is used.
specifies the collation order used. The information
for this category is stored in a database created by
the colltb1{lM) command. This environment variable affects sort{l), strcoll{3C), and strxf:rm{3C).
specifies character classification, character conversion, and widths of multibyte characters. The information for this category is stored in a database
created by the chrtb1{lM) or wchrtb1{lM) commands. The default C locale uses the 7-bit US ASCn
character set. This environment variable affects many
commands and functions, among them, cat{l), ed{l),
ls{l), vi{l), ctype{3C), and mbchar{3C),
LC_MESSAGES

specifies the message database used. A command or
application may have French and German message
databases, for example. Message databases are
created by the mkmsgs{l) or gencat{l) commands.
This environment variable affects gettxt{l),
299

environ (5)

LC_MONETARY

LC_NtlMERIC

LC_TlME

300

srchtxt(l), catgets(3C), and gettxt(3C), and
every command that generates locale-specific output
messages.
specifies the monetary symbols and delimiters used.
The information for this category is stored in a database created by the montbl(lM) command. This
environment variable affects localeconv(3C).
specifies the decimal and thousands delimiters. The
information for this category is stored in a database
created by the chrtbl(lM) or wchrtbl(lM) commands. The default C locale uses a period (.) as the
decimal delimiter and no thousands delimiter. This
environment variable affects localeconv(3C),
printf(3S), scanf(3S), and strtod(3C).
specifies date and time formats. The information for
this category is stored in a database specified in
strftilne(4). The default C locale uses US date and
time formats. This environment variable affects
many commands and functions, among them, at(l),
calendar(l),
date(l),
getdate(3C),
and
strftilne(3C).

MSGVERB

Controls which standard format message components fmtmsg selects
when messages are displayed to stderr [see fmtmsg(l) and
fmtmsg(3C)].

SEV_LEVEL

Defines severity levels and associates and prints strings with them in
standard format error messages [see addseverity(3C), fmtmsg(l),
and fmtmsg(3C)].

NETPATH

A colon-separated list of network identifiers. A network identifier is a
character string used by the Network Selection component of the system to provide application-specific default network search paths. A
network identifier must consist of non-NULL characters and must
have a length of at least 1. No maximum length is specified. Network
identifiers are normally chosen by the system administrator. A network identifier is also the first field in any /etc/netconfig file entry.
NETPATH thus provides a link into the /etc/netconfig file and the
information about a network contained in that network's entry.
/etc/netconfig is maintained by the system administrator. The
library routines described in getnetpath(3N) access the NETPATH
environment variable.

NLSPATH

Contains a sequence of templates which catopen(3C) uses when
attempting to locate message catalogs. Each template consists of an
optional prefix, one or more substitution fields, a filename, and an
optional suffix.

environ (5)
For example:
NLSPATH="/system/n1s1ib/%N.cat"
defines that catopen should look for all message catalogs in the directory /system/nls1ib, where the catalog name should be constructed
from the name parameter passed to catopen, CYaN, with the suffix • cat.
Substitution fields consist of a % symbol, followed by a single-letter
keyword. The following keywords are currently defined:
%N
%L
%1
%t
%c
%%

The value of the name parameter passed to catopan.
The value of LANG.
The language element from LANG.
The territory element from LANG.
The codeset element from LANG.
A single %character.

An empty string is substituted if the specified value is not currently
defined. The separators "":' and "." are not included in %t and %c
substitutions.

Templates defined in NLSPATH are separated by colons (:). A leading
colon or two adjacent colons (: :) is equivalent to specifying %N.
For example:
NLSPATH=I:%N.cat:/n1s1ib/%L/%N.cat"
indicates to catopen that it should look for the requested message
catalog in name, name •cat, and /n1s1ib/$LANG/name • cat.
PATH

The sequence of directory prefixes that sh(l), time(l), nice(l),
nohup(l), and so on apply in searching for a file known by an incomplete path name. The prefixes are separated by colons (:). login(l)
sets PATH=/usr/bin. [For more detail, see sh(l).]

SHELL

When the shell is invoked, it scans the environment for this name. If it
is found and rsh is the filename part of its value, the shell becomes a
restricted shell. The value of this variable should be specified with an
absolute pathname. The variable is used by make(l), ksh(l), sh(l),
and vi(l), among other commands.
The kind of terminal for which output is to be prepared. This information is used by commands, such as vi(l), which may exploit special
capabilities of that terminal.

Time zone information. The contents of the environment variable
named TZ are used by the functions ctime(3C), loca1time [see
ctime(3C)], strftime(3C), and mktime(3C) to override the default
time zone. If the first character of TZ is a colon (:), the behavior is
implementation-defined, otherwise TZ has the form:

std offset [dst [ offset ], [start [ / time] , end [ / time] ] ]

301

environ (5)
std and dst
Three or more bytes that are the designation for the standard
(std) and daylight savings time (dst) time zones. Only std is
required, if dst is missing, then daylight savings time does not
apply in this locale. Upper- and lowercase letters are allowed.
Any characters except a leading colon (:), digits, a comma (,),
a minus (-), or a plus (+) are allowed.
offset Indicates the value one must add to the local time to arrive at
Coordinated Universal Time. The offset has the form:
hh [ : mm [ : ss 1 1
The minutes (mm) and seconds (55) are optional. The hour
(hh) is required and may be a single digit. The offset following
std is required. If no offset follows dst , daylight savings time is
assumed to be one hour ahead of standard time. One or more
digits may be used; the value is always interpreted as a
decimal number. The hour must be between 0 and 24, and the
minutes (and seconds) if present between 0 and 59. Out of
range values may cause unpredictable behavior. If preceded
by a "-", the time zone is east of the Prime Meridian; otherwise it is west (which may be indicated by an optional preceding "+" sign).
start / time, end / time
Indicates when to change to and back from daylight savings
time, where start/time describes when the change from standard time to daylight savings time occurs, and end/time
describes when the change back happens. Each time field
describes when, in current local time, the change is made.
The formats of start and end are one of the following:
In
The Julian day n (1 ~ n ~ 365). Leap days are
not counted. That is, in all years, February 28 is
day 59 and March 1 is day 60. It is impossible
to refer to the occasional February 29.
n
The zero-based Julian day (0 ~ n ~ 365). Leap
days are counted, and it is possible to refer to
February 29.
Mm.n.d The d th day, (0 ~ d ~ 6) of week n of month m of
the year (1 ~ n ~ 5, 1 ~ m ~ 12), where week 5
means "the last d-day in month m" which may
occur in either the fourth or the fifth ~eek).
Week 1 is the first week in which the d day
occurs. Day zero is Sunday.
Implementation-specific defaults are used for start and end if
these optional fields are not given.
The time has the same format as offset except that no leading
sign ("-" or "+") is allowed. The default, if time is not given is
02:00:00.
302

environ (5)
Further names may be placed in the environment by the export command and

name=value arguments in sh(l), or by exec(2). It is unwise to conflict with certain
shell variables that are frequently exported by .profile files: MAIL, PSi, PS2, IFS
[see profile(4)].
SEE ALSO

addseverity(3C), cat(l), catgets(3C), catopen(3C), chrtb1(lM), colltb1(lM),
ctime(3C), ctype(3C), date(l), ed(l), exec(2), fmtmsg(l), fmtmsg(3C), gencat(l),
getdate(3C), getnetpath(3N), gettxt(l), gettxt(3C), 1oca1econv(3C), 1ogin(1),
1s(1), mbchar(3C), mkmsgs(l), mktime(3C), montb1(lM), netconfig(4), nice(l),
nohup(l), passwd(4), printf(3S), profile(4) scanf(3S), setloca1e(3C), sh(l),
sort(l), srchtxt(l), strcoll(3C), strftime(3C), strftime(4), strtod(3C),
strxfrm(3C), time(l), timezone(4) vi(l), wchrtb1(lM)

303

eqnchar(5)

(BSO System Compatibility)

NAME

eqnchar - (BSD) special character definitions for eqn
SYNOPSIS

eqn /usr/ucblib/pub/eqnchar [file]

I troff [options]
I nroff [options]

neqn /usr/ucblib/pub/eqnchar [file]
DESCRIPTION

The eqnchar command contains troff(l) and nroff(l) character definitions for
constructing characters that are not available on the Graphic Systems typesetter.
These definitions are primarily intended for use with eqn(l) and neqn. It contains
definitions for the following characters:
ciplus
citimes

square

langle

circle

blot

bullet

•

wig

rangle

-wig

hbar

\
\
I

>wig

ppd

empty

=wig

<=>

member

star

nomem

fi.

bigstar

II>

cup

=dot

ang

cap

orsign

rang

incl

andsign

3dot

subset

=del

L'1

thf

supset

::)

oppA

\;/

quarter

!subset

oppE

::3

3quarter

!supset

angstrom

FILES

/usr/ucblib/pub/eqnchar
SEE ALSO

eqn(l), nroff(l), troff(l)

304

degree

prop

eucioctl ( 5)
NAME

eucioctl - generic interface to EVC handling tty drivers and modules
SYNOPSIS

#include
ioctl(int fd,

I_STR,

struct strioctl *sb);

DESCRIPTION

This interface is implemented in tty drivers and pushable STREAMS modules that
handle EVC codes. It is intended as a generic interface for EVC handling, to eliminate an explosion of module-specific ioctl calls that would otherwise be necessary, and to provide uniformity in dealing with EVC code sets in the tty subsystem.
Several calls are defined. The first two calls take an argument, which is expected to
be a pointer to an eucioc structure, defined in the header file sys/ eucioctl. h:
struct eucioc {
unsigned char eucw[4];
unsigned char scrw[4];
};

typedef struct eucioceucioc_t;
In all cases, these calls return non-zero on failure. Failure should be usually taken
as an indication that the current driver, or line discipline module, does not support
EVC, in which case errno will be set to EINVAL. For the EUC_WSET or EUC_WGET
calls, errno will be set to EPROTO if struct eucioc argument is invalid.
EUC_WSET
This call takes a pointer to an eucioc structure, and uses it to
set the EVC line discipline's local definition for the code set
widths to be used for subsequent operations. Within the
stream, the line discipline may optionally notify other modules
of this setting via M_CTL messages.
EUC_WGET
This call takes a pointer to an eucioc structure, and returns in
it the EVC code set widths currently in use by the EVC line discipline. It needs to be recognized only by line diScipline
modules.
The following calls take no arguments. They should only fail if the driver (at the
bottom of the tty stream) does not recognize EVC codes. Drivers that support EVC,
whether the stream contains modules that respond to the calls or not, will recognize
the calls and acknowledge them. These calls are normally only interpreted by
modules that have modes other than ASCII, and/or do some form of I/O conversion
that normally prevents a program from receiving non-EVC characters in its byte
stream. All of these calls, when received by modules, are passed down the tty
stream, to be ultimately acknowledged by the tty driver.
This call has no effect on modules that are currently in ASCII
mode. Otherwise (Le., for modules not in ASCII mode), the following actions are taken by all modules that recognize this call:
(1) the current mode status is saved, (2) the mode is changed to
ASCII mode immediately.

305

eucioctl (5)
If a mode was saved via a previous EUC_MSAVE call, the saved
mode is restored, and the saved state flag is cleared. If the

mode was not previously saved, this call has no effect. (The
exact semantics are somewhat dependent on the module, since
some modules may respond to specific user requests to switch
modes, even while a mode is being saved via EUC_MSAVE.)
If a module is currently in a state where input conversion is
being performed on the incoming byte stream, then input
conversion is turned off, and the module's mode status is
saved. If no input conversion is being performed, there is no
effect on the module. The purpose of this call is to provide a
way of insuring a pure byte stream to the program. The byte
stream while input conversion is off is, of course, not
guaranteed to be a stream of EUC characters. Turning off input
conversion is roughly equivalent to the old concept of raw
mode, if used in conjunction with ICANON off. It should normally not be used by applications.
If a module previously saved its state and turned off input
conversion, then input conversion is restored (i.e., turned back
on); otherwise, there is no effect.
In a manner similar to EUC_IXLOFF, any output conversion is

turned off and the current mode status saved.
In a manner similar to EUC_IXLON, any saved output conversion status is restored (i.e., output conversion is turned back on
if previously turned off via EUC_OXLOFF).
FILES

/usr/include/sys/eucioctl.h
NOTES

Drivers and modules that support EUC should all respond appropriately to these
calls, depending on their type. Line disciplines must respond to EUC_WSET and
EUC_WGET, changing their current code set sizes to match EUC_WSET requests. All
tty STREAMS modules that do any input or output conversion should recognize the
other calls; modules that do no code set conversion are not required to recognize
the calls, but must pass them through. Drivers that support EUC tty streams must
all acknowledge the ON/OFF calls, whether the drivers themselves are affected or
not, since these calls are purposely not acknowledged by modules which receive
them; they are intended to be made available for affecting all modules in the whole
stream.
Adherence to this protocol for all EUC handling modules is strongly encouraged in
order to increase portability and language-independence of applications. These
calls are intended as a small set of primitives to help reduce an anticipated plethora
of module- and language-dependent operations.

306

fcntl (5)
NAME

fcntl - file control options
SYNOPSIS

#include
DESCRIPTION

The fcntl.h header defines the following requests and arguments for use by the
functions fcntl [see fcntl(2)] and open [see open(2)].
Values for cmd used by fcntl (the following values are unique):
F _DUPFD
Duplicate file descriptor
F _GETFD
Get file descriptor flags
F _SETFD
Set file descriptor flags
F _GETFL
Get file status flags
F _SETFL
Set file status flags
F _GETLK
Get record locking information
F _SETLK
Set record locking information
F _SETLKW
Set record locking information;
wait if blocked
File descriptor flags used for fcntl:
FD_CLOEXEC
Close the file descriptor upon
execution of an exec function [see exec(2)]
Values for l_type used for record locking with fcntl
(the following values are unique):
F _RDLCK
Shared or read lock
F_UNLCK
Unlock
F _WRLCK
Exclusive or write lock
The following three sets of values are bitwise distinct:
Values for oflag used by open:
O_CREAT
Create file if it does not exist
OJ:XCL
Exclusive use flag
O_NOCTTY
Do not assign controlling tty
O_TRUNC
Truncate flag
File status flags used for open and fcntl:
O_APPEND
Set append mode
O_NDELAY
Non-blocking mode
O_NONBLOCK
Non-blocking mode (POSIX)
O_SYNC
Synchronous writes
Mask for use with file access modes:
O_ACCMODE
Mask for file access modes
File access modes used for open and fcntl:
O_RDONLY
Open for reading only
O_RDWR
Open for reading and writing
O_WRONLY
Open for writing only

307

fentl (5)
The structure flock describes a file lock. It includes the following members:
l_type;
short
1* Type of lock * 1
short
l_whence;
1* Flag for starting offset *1
off_t
l_start;
1* Relative offset in b¥tes *1
off_t
l_len;
1* Size; if 0 then until EOF *1
long
l_sysid;
1* Returned with F_GETLK *1
pid_t
l-pid;
1* Returned with F_GETLK *1
long
l-Pad
1* reserve area *1
SEE ALSO

creat(2), exec(2), fcntl(2), open(2)

308

font(5)
NAME

font - font description files for troff and dpost
SYNOPSIS

troff -T ptty . ..
DESCRIPTION

For each typesetter or printer type supported by troff(l) and available on this system, there is a directory containing files describing the device and its fonts. This
directory is named /usr/lib/font/devptty where ptty is the abbreviated name of
the typesetter or printer type. Currently supported devices are aps for the Autologic APS-5, post for PostScript printers, and ilO for the Imagen Imprint 10 laser
printer.
For a particular phototypesetter, ptty, the ASCII file DESC in the directory
/usr/lib/font/devptty describes its characteristics. Each line starts with a word
identifying the characteristic which is followed by appropriate specifiers. Blank
lines and lines beginning with a # are ignored.
The legal lines for DESC are:
res num

resolution of device in basic increments per inch

hor num

smallest unit of horizontal motion

vert num

smallest unit of vertical motion

unitwidth num

pointsize in which widths are specified

sizescale num

scaling for fractional pointsizes

paperwidth num

width of paper in basic increments

paperlength num

length of paper in basic increments

biggest font num

maximum size of a font

spare2 num

available for use

sizes num num . . .

list of pointsizes available on typesetter

fonts num name. ..

number of initial fonts followed by the names of the
fonts. For example:
fonts 4 RI B S

charset

this always comes last in the file and is on a line by
itself. Following it is the list of special character
names for this device. Names are separated by a
space or a newline. The list can be as long as necessary. Names not in this list are not allowed in the
font description files.

Res is the basic resolution of the device in increments per inch. Hor and vert

describe the relationships between motions in the horizontal and vertical directions.
If the device is capable of moving in single basic increments in both directions, both
hor and vert would have values of 1. If the vertical motions only take place in

multiples of two basic units while the horizontal motions take place in the basic
increments, then hor would be 1, while vert would be 2. The unitwidth is the
pointsize in which all width tables in the font description files are given. troff

309

font(5)
automatically scales the widths from the unitwidth size to the pointsize it is working with. Sizescale is not currently used and is 1. paperwidth is the width of the
paper in basic increments. The APS-5 is 6120 increments wide. paperlength is the
length of a sheet of paper in the basic increments. biggest font is the maximum
number of characters on a font.
For each font supported by the phototypesetter, there is also an ASCII file with the
same name as the font (e.g., R, I4). The format for a font description file is:
name name
name of the font, such as R or' 4
internalname name internal name of font
special

sets flag indicating that the font is special

ligatures name. .. 0

Sets flag indicating font has ligatures. The list of ligatures follows and is terminated by a zero. Accepted ligatures are: ff fi f l ffi f f l .
available for use
width of space if something other than 1/3 of - is
desired as a space.
charset
The character set must come at the end. Each line following the word charset describes one character in the
font. Each line has one of two formats:
name width kerning code
name"
where name is either a single ASCII character or a special
character name from the list found in DESC. The width
is in basic increments. The kerning information is 1 if
the character descends below the line, 2 if it rises above
the letter 'a', and 3 if it both rises and descends. The
kerning information for special characters is not used
and so may be o. The code is the number sent to the
typesetter to produce the character. The second format
is used to indicate that the character has more than one
name. The double quote indicates that this name has the
same values as the preceding line. The kerning and code
fields are not used if the width field is a double quote
character. The total number of different characters in
this list should not be greater than the value of biggestfont in the DESC file (see above).
troff and its postprocessors like dpost read this information from binary files produced from the ASCII files by a program distributed with troff called makedev.
For those with a need to know, a description of the format of these files follows:
spare 1

spacewidth num

The file DESC.out starts with the dev structure, defined by dev.h:

310

font(5)
/*

dev.h: characteristics of a typesetter

* /
struct dev {
unsigned short
short
short
short
short
short
short
short
short
short
short
short
short
short

res;
hor;

filesize; /* number of bytes in file, */
/* excluding dev part */
/* basic resolution in goobies/inch */
/* goobies horizontally */

vert;

unitwidth;
nfonts;
nsizesi
sizescale;
paperwidth;
paperlength;
nchtab;
lchname;
biggest font;
spare2;

/* size at which widths are given*/
/* number fonts physically available */
/* number of pointsizes */
/* scaling for fractional pointsizes */
/* max line length in units */
/* max paper length in units */
/* number of funny names in chtab */
/* length of chname table */
/* max # of chars in a font */

Filesize is just the size of everything in DESC.out excluding the dev structure. Nfonts
is the number of different font positions available. Nsizes is the number of different
pointsizes supported by this typesetter. Nchtab is the number of special character
names. Lchname is the total number of characters, including nulls, needed to list all
the special character names. At the end of the structure are two spares for later
expansions.
Immediately following the dev structure are a number of tables. First is the sizes
table, which contains nsizes + 1 shorts(a null at the end), describing the pointsizes of
text available on this device. The second table is the funny-char_index_table. It contains indices into the table which follows it, the funny_char_strings. The indices
point to the beginning of each special character name which is stored in the
funny_char _strings table. The funny_char _strings table is lchname characters long,
while the funny_char _index_table is nchtab shorts long.
Following the dev structure will occur nfonts {fontl.out files, which are used to initialize the font positions. These {fontl.out files, which also exist as separate files, begin
with a font structure and then are followed by four character arrays:
struct
char
char
char
char
char
char

font {
nwfont;
specfont;
ligfont;
spare1;
namefont [10];
intname [10];

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

characteristics of a font */
number of width entries */
1 == special font */
1 == ligatures exist on this font */
unused for now */
name of this font, e.g., R */
internal name of font, in ASCII */

311

font(5)
The font structure tells how many defined characters there are in the font, whether
the font is a "special" font and if it contains ligatures. It also has the ASCII name of
the font, which should match the name of the file it appears in, and the internal
name of the font on the typesetting device (intname). The internal name is independent of the font position and name that troff knows about. For example, you
might say mount R in position 4, but when asking the typesetter to actually produce
a character from the R font, the postprocessor which instructs the typesetter would
use intname.
The first three character arrays are specific for the font and run in parallel. The first
array, widths, contains the width of each character relative to unitwidth. unitwidth is
defined in DESC. The second array, kerning, contains kerning information. If a
character rises above the letter 'a', 02 is set. If it descends below the line, 01 is set.
The third array, codes, contains the code that is sent to the typesetter to produce the
character.
The fourth array is defined by the device description in DESC. It is the
font _index_table. This table contains indices into the width, kerning, and code tables
for each character. The order that characters appear in these three tables is arbitrary
and changes from one font to the next. In order for troff to be able to translate
from ASCII and the special character names to these arbitrary tables, the
font _index_table is created with an order which is constant for each device. The
number of entries in this table is 96 plus the number of special character names for
this device. The value 96 is 128 - 32, the number of printable characters in the ASCII
alphabet. To determine whether a normal ASCII character exists, troff takes the
ASCII value of the character, subtracts 32, and looks in the font _index_table. If it
finds a 0, the character is not defined in this font. If it finds anything else, that is the
index into widths, kerning, and codes that describe that character.
To look up a special character name, for example \ (pI, the mathematical plus sign,
and determine whether it appears in a particular font or not, the following procedure is followed. A counter is set to 0 and an index to a special character name is
picked out of the counter'th position in thefunny_char_index_table. A string comparison is performed between funny-char _strings [ funny _char_index_table [ counter ]
] and the special character name, in our example pI, and if it matches, then troff
refers to this character as ( 96 + counter). When it wants to determine whether a
specific font supports this character, it looks in font_index_table[(96 + counter)], (see
below), to see whether there is a 0, meaning the character does not appear in this
font, or a number, which is the index into the widths, kerning, and codes tables.
Notice that since a value of 0 in the font _index_table indicates that a character does
not exist, the Oth element of the width, kerning, and codes arrays are not used. For
this reason the Oth element of the width array can be used for a special purpose,
defining the width of a space for a font. Normally a space is defined by troff to be
1/3 of the width of the \(em character, but if the Oth element of the width array is
non-zero, then that value is used for the width of a space.
SEE ALSO

dpost(l), troff(l), troff(5)

312

font(5)
FILES

/usr/lib/font/devX/DESC.out description file for phototypesetter X

/usr/lib/font/devX/font . out

font description files for phototypesetter X

313

iconv(5)
NAME

iconv - code set conversion tables
DESCRIPTION

The following code set conversions are supported:
Code
ISO 646
ISO 646de
ISO 646da
ISO 646en
ISO 646es
ISO 646fr
ISO 646it
ISO 646sv
ISO 8859-1
ISO 8859-1
ISO 8859-1
ISO 8859-1
ISO 8859-1
ISO 8859-1
ISO 8859-1
ISO 8859-1

Code Set Conversions Supported
Symbol Target Code Symbol
646
ISO 8859-1
8859
646de
ISO 8859-1
8859
646da
ISO 8859-1
8859
ISO 8859-1
8859
646en
646es
ISO 8859-1
8859
ISO 8859-1
8859
646fr
ISO 8859-1
8859
646it
ISO 8859-1
8859
646sv
ISO 646
646
8859
646de
ISO 646de
8859
8859
ISO 646da
646da
8859
ISO 646en
646en
8859
ISO 646es
646es
646fr
8859
IS0646fr
8859
IS0646it
646it
ISO 646sv
646sv
8859

comment
US ASCII
German
Danish
English ASCII
Spanish
French
Italian
Swedish
7 bit ASCII
German
Danish
English ASCII
Spanish
French
Italian
Swedish

The conversions are performed according to the tables following. All values in the
tables are given in octal.
ISO 646 (US ASCII) to ISO 8859·1

For the conversion of ISO 646 to ISO 8859-1 all characters in ISO 646 can be mapped
unchanged to ISO 8859-1
ISO 646de (GERMAN) to ISO 8859·1

For the conversion of ISO 646de to ISO 8859-1 all characters not in the following
table are mapped unchanged.
Conversions Performed
ISO 646de ISO 8859-1
247
100
133
304
134
326
135
334
173
344
174
366
175
374
176
337

314

iconv (5)
ISO 646da (DANISH) to ISO 8859-1

For the conversion of ISO 646da to ISO 8859-1 all characters not in the following
table are mapped unchanged.
Conversions Performed
ISO 646da ISO 8859-1
133
306
134
330
135
305
173
346
370
174
175
345
ISO 646en (ENGLISH ASCII) to ISO 8859-1

For the conversion of ISO 646en to ISO 8859-1 all characters not in the following
table are mapped unchanged.
Conversions Performed
ISO 646en [ ISO 8859-1
043
I 243
ISO 646fr (FRENCH) to ISO 8859-1

For the conversion of ISO 646fr to ISO 8859-1 all characters not in the following
table are mapped unchanged.
Conversions Performed
ISO 646fr
ISO 8859-1
043
243
100
340
133
260
134
347
135
247
173
351
174
371
175
350
176
250

315

iconv(5)
ISO 646it (ITALIAN) to ISO 8859-1

For the conversion of ISO 646it to ISO 8859-1 all characters not in the following
table are mapped unchanged.
Conversions Performed
ISO 646it
ISO 8859-1
043
243
100
247
133
260
134
347
135
351
140
371
173
340
174
362
175
350
176
354
ISO 646es (SPANISH) to ISO 8859-1

For the conversion of ISO 646es to ISO 8859-1 all characters not in the following
table are mapped unchanged.
Conversions Performed
ISO 646es ISO 8859-1
247
100
133
241
134
321
135
277
173
260
174
361
175
347

316

iconv (5)
ISO 646sv (SWEDISH) to ISO 8859-1

For the conversion of ISO 646sv to ISO 8859-1 all characters not in the following
table are mapped unchanged.
Conversions Performed
ISO 646sv ISO 8859-1
311
100
133
304
134
326
135
305
136
334
140
351
173
344
174
366
175
345
176
374
ISO 8859-1 to ISO 646 (ASCII)

For the conversion of ISO 8859-1 to ISO 646 all characters not in the following table
are mapped unchanged.

200
210
220
230
240
250
260
270
300
310
320
330
340
350
360
370

Converted to Underscore' '(137)
201 202 203 204 205 206
211 212 213 214 215 216
221 222 223 224 225 226
231 232 233 234 235 236
241 242 243 244 245 246
251 252 253 254 255 256
261 262 263 264 265 266
271 272 273 274 275 276
301 302 303 304 305 306
311 312 313 314 315 316
321 322 323 324 325 326
331 332 333 334 335 336
341 342 343 344 345 346
351 352 353 354 355 356
361 362 363 364 365 366
371 372 373 374 375 376

207
217
227
237
247
257
267
277
307
317
327
337
347
357
367
377

317

iconv(5)
ISO 8859·1 to ISO 646de (GERMAN)

For the conversion of ISO 8859-1 to ISO 646de all characters not in the following
tables are mapped unchanged.
Conversions Performed
ISO 8859-1 ISO 646de
247
100
304
133
326
134
334
135
337
176
344
173
174
366
374
175

318

100

Converted to Underscore' , (137)
133 134 135 173 174 175

200
210
220
230
240
250
260
270
300
310
320
330
340
350
360
370

201
211
221
231
241
251
261
271
301
311
321
331
341
351
361
371

202
212
222
232
242
252
262
272
302
312
322
332
342
352
362
372

203
213
223
233
243
253
263
273
303
313
323
333
343
353
363
373

204
214
224
234
244
254
264
274
314
324
354
364

205
215
225
235
245
255
265
275
305
315
325
335
345
355
365
375

206
216
226
236
246
256
266
276
306
316
336
346
356
376

176
207
217
227
237
257
267
277
307
317
327
337
347
357
367
377

iconv (5)
ISO 8859-1 to ISO 646da (DANISH)

For the conversion of ISO 8859-1 to ISO 646da all characters not in the following
tables are mapped unchanged.
Conversions Performed
ISO 8859-1 ISO 646da
305
135
133
306
330
134
345
175
346
173
370
174

133
200
210
220
230
240
250
260
270
300
310
320
340
350
360

Converted to Underscore' '(137)
134 135 173 174 175
201
211
221
231
241
251
261
271
301
311
321
331
341
351
361
371

202
212
222
232
242
252
262
272
302
312
322
332
342
352
362
372

203
213
223
233
243
253
263
273
303
313
323
333
343
353
363
373

204
214
224
234
244
254
264
274
304
314
324
334
344
354
364
374

205
215
225
235
245
255
265
275

206
216
226
236
246
256
266
276

315
325
335

316
326
336

355
365

356
366
376

319

iconv(5)
ISO 8859-1 to ISO 646en (ENGLISH ASCII)

For the conversion of ISO 8859-1 to ISO 646en all characters not in the following
tables are mapped unchanged.
Conversions Performed
ISO 8859-1 I ISO 646en
243
I 043
Converted to Underscore' '(137)
043
200
210
220
230
240
250
260
270
300
310
320
330
340
350
360
370

320

201
211
221
231
241
251
261
271
301
311
321
331
341
351
361
371

202
212
222
232
242
252
262
272
302
312
322
332
342
352
362
372

203
213
223
233
253
263
273
303
313
323
333
343
353
363
373

204
214
224
234
244
254
264
274
304
314
324
334
344

354
364
374

205
215
225
235
245
255
265
275
305
315
325
335
345
355
365
375

206
216
226
236
246
256
266
276
306
316
326
336
346
356
366
376

207
217
227
237
247
257
267
277
307
317
327
337
347
357
367
377

iconv(5)
ISO 8859-1 to ISO 646fr (FRENCH)

For the conversion of ISO 8859-1 to ISO 646fr all characters not in the following
tables are mapped unchanged.
Conversions Performed
ISO 8859-1 ISO 646fr
243
043
247
135
250
176
260
133
340
100
347
134
350
175
351
173
371
174
Converted to Underscore' '(137)
043
100
200
210
220
230
240
270
300
310
320
330
360
370

133

134

135

173

174

175

176

201
211
221
231
241
251
261
271
301
311
321
331
341

202
212
222
232
242
252
262
272
302
312
322
332

203
213
223
233

204
214
224
234
244
254
264
274
304
314
324
334

361

206
216
226
236
246
256
266
276
306
316
326
336
346
356
366
376

207
217
227
237

352
362
372

205
215
225
235
245
255
265
275
305
315
325
335
345
355
365
375

342

253
263
273
303
313
323
333
343
353
363
373

344

354
364
374

257
267
277
307
317
327
337
357
367
377

321

iconv(5)
ISO 8859-1 to ISO 646it (ITALIAN)

For the conversion of ISO 8859-1 to ISO 646it all characters not in the following
tables are mapped unchanged.
Conversions Performed
ISO 8859-1
ISO 646it
243
043
247
100
260
133
173
340
347
134
350
175
351
135
354
176
362
174
371
140
Converted to Underscore' '(137)
043
100
200
210
220
230
240
250
270
300
310
320
330
360
370

322

133

134

135

173

174

175

176

201
211
221
231
241
251
261
271
301
311
321
331
341

202
212
222
232
242
252
262
272
302
312
322
332
342
352

203
213
223
233

204
214
224
234
244
254
264
274
304
314
324
334
344
354
364
374

205
215
225
235
245
255
265
275
305
315
325
335
345
355
365
375

206
216
226
236
246
256
266
276
306
316
326
336
346
356
366
376

207
217
227
237

361
372

253
263
273
303
313
323
333
343
353
363
373

257
267
277
307
317
327
337
357
367
377

iconv (5)
ISO 8859-1 to ISO 646e5 (SPANISH)

For the conversion of ISO 8859-1 to ISO 646es all characters not in the following
tables are mapped unchanged.
Conversions Performed
ISO 8859-1 ISO 646es
241
133
247
100
260
173
277
135
321
134
347
175
174
361

100
200
210
220
230
240
250
270
300
310
320
330
340
350
360
370

Converted to Underscore' '(137)
133 134 135 173 174 175
201
211
221
231
251
261
271
301
311
331
341
351
371

202
212
222
232
242
252
262
272
302
312
322
332
342
352
362
372

203
213
223
233
243
253
263
273
303
313
323
333
343
353
363
373

204
214
224
234
244
254
264
274
304
314
324
334
344
354
364
374

205
215
225
235
245
255
265
275
305
315
325
335
345
355
365
375

206
216
226
236
246
256
266
276
306
316
326
336
346
356
366
376

207
217
227
237
257
267
307
317
327
337
357
367
377

323

iconv(5)
ISO 8859-1 to ISO 646sv (SWEDISH)

For the conversion of ISO 8859-1 to ISO 646sv all characters not in the following
tables are mapped unchanged.
Conversions Performed
ISO 8859-1 ISO 646sv
304
133
135
305
311
100
326
134
334
136
173
344
345
175
351
140
174
366
374
176
100
173
200
210
220
230
240
250
260
270
300
310
320
330
340
350
360
370

324

Converted to Underscore' '(137)
133 134 135 136 140
174 175 176
201
211
221
231
241
251
261
271
301
321
331
341
361
371

202
212
222
232
242
252
262
272
302
312
322
332
342

352
362
372

203
213
223
233
243
253
263
273
303
313
323
333
343
353
363
373

204
214
224
234
244
254
264
274

205
215
225
235
245
255
265
275

314
324

315
325
335

354
364

355
365
375

206
216
226
236
246
256
266
276
306
316
336
346
356
376

207
217
227
237
247
257
267
277
307
317
327
337
347
357
367
377

iconv (5)
FILES

/usr/lib/iconv/iconv_data
lists the conversions supported
/usr/lib/iconv/*
conversion tables
/usr/lib/locale/locale/LC_MESSAGES/uxmesg
language-specific message file [See LANG on
environ(5).J
SEE ALSO

iconv(l)

325

langinfo(5)
NAME

langinfo -language information constants
SYNOPSIS

#include
DESCRIPTION

This header file contains the constants used to identify items of lang info data. The
mode of items is given in nl_types(5).

326

DAY_I

Locale's equivalent of "sunday"

DAY_2

Locale's equivalent of "monday"

DAY_3

Locale's equivalent of "tuesday"

DAY_4

Locale's equivalent of "wednesday"

DAY_5

Locale's equivalent of "thursday"

DAY_6

Locale's equivalent of "friday"

DAY_7

Locale's equivalent of "saturday"

ABDAY_1

Locale's equivalent of "sun"

ABDAY_2

Locale's equivalent of "mon"

ABDAY_3

Locale's equivalent of "tue"

ABDAY_4

Locale's equivalent of "wed"

ABDAY_5

Locale's equivalent of "thur"

ABDAY_6

Locale's equivalent of "fri"

ABDAY_7

Locale's equivalent of "sat"

MON_I

Locale's equivalent of "january"

MON_2

Locale's equivalent of "february"

MON_3

Locale's equivalent of "march"

MON_4

Locale's equivalent of "april"

MON_5

Locale's equivalent of "may"

MON_6

Locale's equivalent of "june"

MON_7

Locale's equivalent of "july"

MON_8

Locale's equivalent of "august"

MON_9

Locale's equivalent of "september"

MON_IO

Locale's equivalent of "october"

MON_II

Locale's equivalent of "november"

MON_12

Locale's equivalent of "december"

ABMON_I

Locale's equivalent of "jan"

langinfo (5)

ABMON_3

Locale's equivalent of "feb"
Locale's equivalent of "mar"

ABMON_4

Locale's equivalent of "apr"

ABMON_S

Locale's equivalent of "may"
Locale's equivalent of "jun"
Locale's equivalent of "jul"

ABMON_2

ABMON_6
ABMON_7
ABMON_8
ABMON_9

Locale's equivalent of "aug"
Locale's equivalent of "sep"

ABMON_12

Locale's equivalent of "oct"
Locale's equivalent of "nov"
Locale's equivalent of "dec"

RADIXCHAR

Locale's equivalent of "."

THOUSEP

ABMON_10
ABMON_ll

YESSTR

Locale's equivalent of ","
Locale's equivalent of "yes"

NOSTR

Locale's equivalent of "no"

CRNCYSTR

Locale's currency symbol
Locale's default format for date and time
Locale's default format for the date

D_T_FMT
D_FMT
T_FMT
AM_STR

Locale's default format for the time
Locale's equivalent of "AM"

Locale's eqUivalent of "PM"
This information is retrieved by nl_langinfo(3C).
The items CRNCYSTR, RADIXCHAR, and THOUSEP are extracted from the fields
currency_symbol, decimal-point, and thousands_sep in the structure returned
by localeconv(3C).
The items T_FMT, D_FMT, D_T_FMT, YESSTR, and NOSTR are retrieved from a special
message catalog named Xopen_info which should be generated for each locale
supported and installed in the appropriate directory [see mkmsgs(l) and
gettxt(3C)]. This catalog should have the messages in the order T_FMT, D_FMT,
D_T_FMT, YESSTR, and NOSTR.
PM_STR

All other items are as returned by strftllne(3C).
SEE ALSO

cftime(3C), gettxt(3C),
nl_types(5), strftime(3C)

localeconv(3C),

mkmsgs(l),

nl_langinfo(3C),

327

maneS)

(BSO System Compatibility)

NAME

man - macros to format Reference Manual pages
SYNOPSIS

nroff -man filename . . .
troff -manfilename .. .
DESCRIPTION

These macros are used to layout the reference pages in this manual. Note: if
filename contains format input for a preprocessor, the commands shown above must
be piped through the appropriate preprocessor. This is handled automatically by
man(I). See the "Conventions" section.
Any text argument t may be zero to six words. Quotes may be used to include
SPACE characters in a word. If text is empty, the special treatment is applied to the
next input line with text to be printed. In this way . I may be used to italicize a
whole line, or • SB may be used to make small bold letters.
A prevailing indent distance is remembered between successive indented paragraphs, and is reset to default value upon reaching a non-indented paragraph.
Default units for indents i are ens.
Type font and size are reset to default values before each paragraph, and after processing font and size setting macros.
These strings are predefined by -man:
\ *R
'®', '(Reg)' in nroff.
\ *S
Change to default type size.
Requests

* n.t.1. = next text line; pj. = prevailing indent

Request
.B t

.BI

.BR t
• DT

.HP i
.I

.IB
.IP
.IR

t
xi

• IX t
.LP

. PD d
• PP

328

Cause
Break
no
no
no
no
yes

If no
Argument

no
no
yes
no
no
yes

t=n.t.l.

no
yes

d=.4v

t=n.t.l.*
t=n.t.l.
t=n.t.l.

.5i Ii. ..
i=p.i.*

t=n.t.l.
X="11

t=n.t.l.

Explanation
Text is in bold font.
Join words, alternating bold and italic.
Join words, alternating bold and roman.
Restore default tabs .
Begin paragraph with hanging indent. Set
prevailing indent to i.
Text is italic.
Join words, alternating italic and bold.
Same as •TP with tag x.
Join words, alternating italic and roman.
Index macro .
Begin left-aligned paragraph. Set prevailing
indent to .5i.
Set vertical distance between paragraphs .
Same as .LP.

man(5}

(BSO System Compatibility)

Request

Cause
Break

.RE

yes

.RB

no
no
yes

.RI
• RS

. SB
• SH
.SM

.SS t
.TH

nsdfm

no
yes
no
yes
yes

yes

. TP

If no
Argument

t=n.t.l.
t=n.t.l.

i=p.i .

t=n.t.l.
t=n.t.l.

i=p.i .

Explanation
End of relative indent. Restores prevailing
indent.
Join words, alternating roman and bold.
Join words, alternating roman and italic.
Start relative indent, increase indent by i. Sets
prevailing indent to .5i for nested indents.
Reduce size of text by 1 point, make text bold .
Section Heading .
Reduce size of text by 1 point.
Section Subheading.
Begin reference page n, of of section s; d is the
date of the most recent change. If present, f is
the left page footer; m is the main page
(center) header. Sets prevailing indent and
tabs to .5i.
Begin indented paragraph, with the tag given
on the next text line. Set prevailing indent to i.

Conventions
When formatting a manual page, man examines the first line to determine whether it
requires special processing. For example a first line consisting of:
'\" t

indicates that the manual page must be run through the tbl(l) preprocessor.
A typical manual page for a command or function is laid out as follows:
• TH

title [1-8]
The name of the command or function, which serves as the title of the
manual page. This is followed by the number of the section in which it
appears .

• SH NAME

The name, or list of names, by which the command is called, followed by a
dash and then a one-line summary of the action performed. All in roman
font, this section contains no troff(l) commands or escapes, and no macro
requests. It is used to generate the whatis(l) database .
. SH SYNOPSIS
Commands:

The syntax of the command and its arguments, as typed on the command line. When in boldface, a word must be typed exactly as
printed. When in italics, a word can be replaced with an argument
that you supply. References to bold or italicized items are not capitalized in other sections, even when they begin a sentence.

329

man(5)

(BSO System Compatibility)

Syntactic symbols appear in roman face:
[1
An argument, when surrounded by brackets is optional.

Arguments separated by a vertical bar are exclusive. You
can supply only one item from such a list.
Arguments followed by an ellipsis can be repeated. When an
ellipsis follows a bracketed set, the expression within the
brackets can be repeated.

Functions:
If required, the data declaration, or #include directive, is shown
first, followed by the function declaration. Otherwise, the function
declaration is shown.
. SH DESCRIPTION

A narrative overview of the command or function's external behavior. This
includes how it interacts with files or data, and how it handles the standard
input, standard output and standard error. Internals and implementation
details are normally omitted. This section attempts to provide a succinct
overview in answer to the question, "what does it do?"
Literal text from the synopsis appears in constant width, as do literal
filenames and references to items that appear elsewhere in the reference
manuals. Arguments are italicized.
If a command interprets either subcommands or an input grammar, its command interface or input grammar is normally described in a USAGE section,
which follows the OPTIONS section. The DESCRIPTION section only
describes the behavior of the command, not that of subcommands .
. SH OPTIONS

The list of options along with a description of how each affects the
command's operation .
. SH FILES

A list of files associated with the command or function .
• SH SEE ALSO

A comma-separated list of related manual pages, followed by references to
other published materials .
. SH DIAGNOSTICS

A list of diagnostic messages and an explanation of each.
. SH NOTES

A description of limitations, known defects, and possible problems associated with the command or function.
FILES

/usr/ucblib/doctools/tmac/an
SEE ALSO

man(l), nroff(l), troff(l), whatis(l)

330

math (5)
NAME

math - math functions and constants
SYNOPSIS

#include
DESCRIPTION

This file contains declarations of all the functions in the Math Library (described in
Section 3M), as well as various functions in the C Library (Section 3C) that return
floating-point values.
It defines the structure and constants used by the matherr(3M) error-handling
mechanisms, including the following constant used as a error-return value:
HUGE

The maximum value of a single-precision floating-point number.

The following mathematical constants are defined for user convenience:
M_E

The base of natural logarithms (c).

M_LOG2E

The base-2logarithm of c.

M_LOG10E

The base-10 logarithm of c.

M_LN2

The natural logarithm of 2.

M_LN10

The natural logarithm of 10.

M_PI

M_2_SQRTPI

n, the ratio of the circumference of a circle to its diameter.
n/2.
n/4.
l/n.
2/n.
2f'.1n.

M_SQRT2

The positive square root of 2.

M_SQRT1_2

The positive square root of 1/2.

M_PI_2
M_P:L4
M_l_PI
M_2_PI

The following mathematical constants are also defined in this header file:
MAXFLOAT

The maximum value of a non-infinite single-precision floating
point number.
positive infinity.

For the definitions of various machine-dependent constants, see values(5).
SEE ALSO

intro(3), matherr(3M), values(5)

331

me(5)

(BSD System Compatibility)

NAME

me - (BSD) macros for formatting papers
SYNOPSIS

nroff -me [optionsljile .. .
troff -me [optionsljile .. .
DESCRIPTION

This package of nroff and troff macro definitions provides a canned formatting
facility for technical papers in various formats. When producing 2-column output
on a terminal, filter the output through co1(1).
The macro requests are defined below. Many nroff and troff requests are unsafe
in conjunction with this package, however, these requests may be used with impunity after the first .pp:
· bp
· br
· sp n
.1s n
· na
· ce n
• u1 n
• sz +n

begin new page
break output line here
insert n spacing lines
(line spacing) n=l single, n=2 double space
no alignment of right margin
center next n lines
underline next n lines
add n to point size

Output of the eqn, neqn, refer, and tb1(1) preprocessors for equations and
tables is acceptable as input.
Requests
In the following list, initialization refers to the first .pp, .1p, . ip, .np, . sh, or . uh

macro. This list is incomplete.
Request
• {c
• {d
• {f
• {I
• (q
• (xx
• (z
• }c
• }d

.) f

.} 1
• }q
• }x

.} z

332

Initial
Value

Cause
Break

Explanation

yes
no
no
yes
yes
no
no
yes
yes
yes
yes
yes
yes
yes

Begin centered block
Begin delayed text
Begin footnote
Begin list
Begin major quote
Begin indexed item in index x
Begin floating keep
End centered block
End delayed text
End footnote
End list
End major quote
End index item
End floating keep

(BSD System Compatibility)

Request

Initial
Value

Cause
Break

.++mH

.+e T

yes

.le
.2e

1
1

• EN

• EQxy

yes
yes
yes
no

• TE
• TH

• TSx

.aeAN

.bx
.ba+n

.be
.bi x
• bxx
· ef 'x'y'z
• eh 'x'y'z
• fo 'x'y'z
• hx
.he 'x'y'z

.hI
.i x

yes
yes
yes
yes

yes

no
no
no

yes
no
no
no
no
no
no
no
yes
no

me(5)

Explanation
Define paper section. m defines the part of the
paper, and can be C (chapter), A (appendix), P
(preliminary, for instance, abstract, table of contents, and so on), B (bibliography), RC (chapters
renumbered from page one each chapter), or RA
(appendix renumbered from page one).
Begin chapter (or appendix, and so on, as set by
. ++). T is the chapter title.
One column format on a new page.
Two column format.
Space after equation produced by eqn or meqn .
Precede equation; break out and add space .
Equation number is y. The optional argument x
may be I to indent equation (default), L to leftadjust the equation, or C to center the equation.
End table .
End heading section of table .
Begin table; if x is H table has repeated heading .
Set up for ACM style output. A is the Author's
name(s), N is the total number of pages. Must be
given before the first initialization.
Print x in boldface; if no argument switch to
boldface.
Augments the base indent by n. This indent is
used to set the indent on regular text (like paragraphs).
Begin new column
Print x in bold italics (nofill only)
Print x in a box (nofill only) .
Set even footer to x y z
Set even header to x y z
Set footer to x y z
Suppress headers and footers on next page .
Set header to x y z
Draw a horizontal line
Italicize x; if x missing, italic text follows .

333

me(5)

(BSO System Compatibility)

Request

Initial
Value

Cause
Break

. ipxy

yes

. 1p
. 10

yes

yes
no

yes
no
no
yes
yes
no
no
no

.np
.of 'x'y'z
.oh 'x'y'z
.pd
.pp
.r
.re
.se

no
yes
no

.shnx

yes

.sk

.sz +n
.th

lOp

no
no

. tp

.ux
• uh
• xpx

yes
no
yes
no

Explanation
Start indented paragraph, with hanging tag x .
Indentation is yens (default 5).
Start left-blocked paragraph .
Read in a file of local macros of the form . *x .
Must be given before initialization.
Start numbered paragraph.
Set odd footer to x y z
Set odd header to x y z
Print delayed text.
Begin paragraph. First line indented.
Roman text follows.
Reset tabs to default values.
Read in a file of special characters and diacritical
marks. Must be given before initialization.
Section head follows, font automatically bold. n
is level of section, x is title of section.
Leave the next page blank. Only one page is
remembered ahead.
Augment the point size by n points.
Produce the paper in thesis format. Must be
given before initialization.
Begin title page .
Underline argument (even in troff). (Nofill
only).
Like .sh but unnumbered .
Print index x .

FILES

/usr/ueb1ib/doeto01s/tmae/e
/usr/ueb1ib/doeto01s/tmae/*.me
SEE ALSO

e01(1), eqn(l), nroff(l), troff(l), refer(l), tb1(1)

334

(BSD System Compatibility)

ms(5)

NAME

ms - (BSD) text formatting macros
SYNOPSIS

nroff -rns [options] file . . .
troff -ms [options] file .. .
DESCRIPTION

This package of nroff(l) and troff(l) macro definitions provides a formatting
facility for various styles of articles, theses, and books. When producing 2-column
output on a terminal or lineprinter, or when reverse line motions are needed, filter
the output through col(l). All external-ms macros are defined below.
Many nroff and troff requests are unsafe in conjunction with this package. However, the first four requests below may be used with impunity after initialization,
and the last two may be used even before initialization:
· bp

begin new page

.br

break output line

n
· ce n

insert n spacing lines
center next n lines

.ls n

line spacing: n=l single, n=2 double space

· na

no alignment of right margin

• sp

Font and point size changes with \f and \s are also allowed; for example,
\ fIword\fR will italicize word. Output of the tbl(l), eqn(l) and refer(l) preprocessors for equations, tables, and references is acceptable as input.
Requests
Macro
Name

Initial
Value

.ABx
.AE

y
y
y
n
y
n
y
y

.AI
.AM

.AU
.BX

.Bl
.B2
.BD
.BT

date

.BXx
.CD
.CM

ift

.CT

.DAx
.DE

.DSxy

Break?
Reset?

ifn

n
n
y
n
y,y
n
y
y

Explanation
begin abstract; if x=no do not label abstract
end abstract
author's institution
better accent mark definitions
author's name
embolden x; if no x, switch to boldface
begin text to be enclosed in a box
end boxed text and print it
block display; center entire block
bottom title, printed at foot of page
print word x in a box
centered display with no keep
cut mark between pages
chapter title: page number moved to CF (TM only)
force date x at bottom of page; today if no x
end display (unfilled text) of any kind
begin display with keep; x=I, L, C, B; y=indent

335

ms(5)
Macro
Name

(BSO System Compatibility)

Initial
Value

.EFx
.EHx
.EN
.EQxy
.FE
.FP
.FSx
.HD
.I x

undef

.IDy
.IPXY
.IXx y

8n,.5i

.KE

.KF
.KS
.LD
.LG
. LP
.MCx
.NDx
.NHxy
.NL

itt
lOp

.OFx
.OHx
.pi

.PP
.PT
.PXx
.QP
.R
.RE

.RP x
.RS
.SH
.SM
.TA

ifTM
- %-

on
5n
5n
8n,5n

Break?
Reset?

Explanation

n
n
Y
y
n
n
n
n
n
y
y,y
y
n
n
y
y
n
y,y
y,y
n
y,y
n
n
n
n
y,y
n
y
y,y
n
y,y
n
y,y
y,y
n
n

even page footer x (3 part as for. tl)
even page header x (3 part as for . tl)
end displayed equation produced by eqn
break out equation; x=L,I,C; y=equation number
end footnote to be placed at bottom of page
numbered footnote paragraph; may be redefined
start footnote; x is optional footnote label
optional page header below header margin
italicize x; if no x, switch to italics
indented display with no keep; y=indent
indented paragraph, with hanging tag x; y=indent
index words x y and so on (up to 5 levels)
end keep of any kind
begin floating keep; text fills remainder of page
begin keep; unit kept together on a single page
left display with no keep
larger; increase point size by 2
left (block) paragraph .
multiple columns; x=column width
no date in page footer; x is date on cover
numbered header; x=level, x=o resets, x=S sets to y
set point size back to normal
odd page footer x (3 part as for. tl)
odd page header x (3 part as for . tl)
print header on first page
paragraph with first line indented
page title, printed at head of page
print index (table of contents); x=no suppresses title
quote paragraph (indented and shorter)
return to Roman font
retreat: end level of relative indentation
released paper format; x=no stops title on first page
right shift: start level of relative indentation
section header, in boldface
smaller; decrease point size by 2
set TAB characters to 8n 16n ... (nroff) 5n IOn ...

y
y
y
y
n
y,y
n

print table of contents at end; x=no suppresses title
end of table processed by tbl
end multi-page header of table
title in boldface and two points larger
thesis mode
begin table; if x=H table has multi-page header
underline x, even in troff

(troff)

.TCx
.TE
.TH
.TL
.TM

.TSx
.ULx

336

off

ms(5) .

(BSO System Compatibility)

Macro
Name

Initial
Value

Break?
Reset?

.UXx

.XAxy

y
y
y,y

.XE
.XP

.XSxy

y
on

.1C
.2C
.]

y,y
y,y
n
n

•[0

Explanation
UNIX; trademark message first time; x appended
another index entry; x=page or no for none; y=indent
end index entry (or series of . IX entries)
paragraph with second and subsequent lines indented
begin index entry; x=page or no for none; y=indent
one column format, on a new page
begin two column format
beginning of refer reference
end of unc1assifiable type of reference

Registers

Formatting distances can be controlled in -DIS by means of built-in number registers. For example, this sets the line length to 6.5 inches:
.nr LL 6.5i
Here is a table of number registers and their default values:
Name
PS
VS
LL
LT
FL
PD
DO

PI
QI
FI
PO
HM

Register Controls
point size
vertical spacing
line length
title length
footnote length
paragraph distance
display distance
paragraph indent
quote indent
footnote indent
page offset
header margin
footer margin
footnote format

Takes Effect
paragraph
paragraph
paragraph
next page
next .FS
paragraph
displays
paragraph
next .QP
next .FS
next page
next page
next page
next .FS

Default
10
12
6i
same as LL
5.5i
Iv (if n), .3v (if t)
Iv (if n), .5v (if t)
5n
5n
2n
o(if n), -Ii (if t)
Ii
Ii
o(1,2,3 available)

When resetting these values, make sure to specify the appropriate units. Setting the
line length to 7, for example, will result in output with one character per line. Setting FF to 1 suppresses footnote superscripting; setting it to 2 also suppresses indentation of the first line; and setting it to 3 produces an . IP-like footnote paragraph.
Here is a list of string registers available in -me; they may be used anywhere in the
text:

337

ms(5)

(BSD System Compatibility)

Name
\*Q
\*U
\*-

\*(MO
\*(DY
\**
\*'
\*'
\*~

\* ,
\*:
\*-

String's Function
quote (" in nroff, "in troff)
unquote (" in nroff, "in troff)
dash (-- in nroff, - in troff )
month (month of the year)
day (current date)
automatically numbered footnote
acute accent (before letter)
grave accent (before letter)
circumflex (before letter)
cedilla (before letter)
umlaut (before letter)
tilde (before letter)

When using the extended accent mark definitions available with
should come after, rather than before, the letter to be accented.

.AM,

these strings

FILES

/usr/ucb/1ib/doctoo1s/tmac/s
/usr/ucb1ib/doctoo1s/tmac/ms.???
SEE ALSO

co1(1), eqn(l), nroff(l), refer(l), tb1(1), troff(l)
NOTES

Floating keeps and regular keeps are diverted to the same space, so they cannot be
mixed together with predictable results.

338

nl_types (5)
NAME

nl_types - native language data types
SYNOPSIS

#include
DESCRIPTION

This header file contains the following definitions:
used by the message catalog functions catopen, catgets and catclose to identify a catalog
nl_itern
used by nl_langinfo to identify items of langinfo data. Values
for objects of type nl_i tern are defined in langinfo. h
NL_SETD
used by gencat when no $set directive is specified in a message
text source file. This constant can be used in subsequent calls to
catgets as the value of the set identifier parameter.
nl_catd

NL_MGSMAX

maximum number of messages per set

NL_SE'l'MAX
NL_TEXTMAX

maximum number of sets per catalog
maximum size of a message

DEF_NLSPATH

the default search path for locating catalogs

SEE ALSO

catgets(3C), catopen(3C), gencat(l), langinfo(5), nl_langinfo(3C)

339

priv(5)
NAME

priv - include file for user-level privilege definitions
SYNOPSIS

#include
DESCRIPTION

This header file is used by all user-level privilege commands.
#ifndef
#define

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

*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*

*
*
*
*
*

Header file used b¥ the user-level privilege commands.
Contains several macros used by user-level programs. The
external (user-level) privilege representation consists of:
type I privilege
and is defined in .

Also contained in are the definitions
for the privilege position names used b¥ user-level macros
PllLWOrk() pm_max() pm_fixed() and pm_inher() below.
I

The syntax for privileges are as follows:
: :=
privilege position
P_
string name of privilege ::= lowercase «pname»
It also contains macro definitions for the command arguments
to the filepriv() procpriv() procprivl () and procprivc()
calls in addition to the typedef for the user-level definition
of a privilege type and privilege set.
I

*****************************************************************/
#include

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

* The following macros are used to specify which privilege sets
* are updated with the specified privilege.
*

*****************************************************************/
#define
#define
#define

340

pm_work(p)
pm_max(p)
pm_fixed(p)

(priv_t) «(p) & PS_TYPE) ? -1
(priv_t)«(p) & PS_TYPE) ? -1
(priv_t)«(p) & PS_TYPE) ? -1

«p)
«p)
«p)

PS_WKG) )
PS_MAX) )
PS_FIX) )

priv (5)
#define

PlILinher (p)

(priv_t) ( «p)

PS_TYPE) ? -1 : «p) I PS_INH}}

1***************************************************** ************

*
* The following macros are used to simplify the procprivl(3C} and
* the procprivc(3C} calls for setting/clearing process privileges.
*
****************************************************** ***********1

#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define

OWNER_W
AUDIT_W
COMPAT_W
DACREAD_W
DACWRITE_W
DEV_W
FILESYS_W
MACREAD_W
MACWRITE_W
MOUNT_W
MULTIDIR_W
SETFLEVEL_W
SETPLEVEL_W
SETSPRIV_W
SETUID_W
SYSOPS_W
SETUPRIV_W
DRIVER_W
RTIME_W
MACUPGRADE_W
FSYSRANGE_W
AUDITWR_W
TSHAR_W
PLOCK_W
ALLPRIVS_W

pm_work (P_OWNER)
pm_work (P_AUDIT)
pm_work (P_COMPAT)
pm_work (P_DACREAD)
pm_work (P_DACWRITE)
pm_work (P_DEV)
pm_work (P_FILESYS)
pm_work (P_MACREAD)
pm_work (P_MACWRITE)
pm_work (P_MOUNT)
pm_work (P_MULTIDIR)
pm_work (P_SETFLEVEL)
pm_work (P_SETPLEVEL)
pm_work (P_SETSPRIV)
pm_work (P_SETUID)
pm_work (P_SYSOPS)
pm_work (P_SETUPRIV)
pm_work (P_DRIVER)
pm_work (P_RTIME)
pm_work (P_MACUPGRADE)
pm_work (P_FSYSRANGE)
pm_work (P_AUDITWR)
pm_work (P_TSHAR)
pm_work (P_PLOCK)
pm_work (P_ALLPRIVS)

#define
#define
#define
#define

READ_W
WRITE_W
ACCESS_W
PRIVS_W

DACREAD_W,MACREAD_W
DACWRITE_W,MACWRITE_W
READ_W,WRITE_W
ACCESS_W, SETSPRIV_W, FSYSRANGE_W

1***************************************************** ************

* The following are the definitions for the privilege functions
*

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

extern

int

filepriv(const char *, int, priv_t *, int};

341

priv (5)
int
int
int

procpriv(int, priv_t *, int);
procprivI (int, •.. );
procpri vc (int, ... );

extern
extern
extern
extern

int
int
int
int

filepriv() ;
procpriv() ;
procprivl();
procprivc();

#endif

/* _STDC

#endif

/* _PRIV_H */

extern
extern
extern
#eIse

SEE ALSO

filepriv(2), procpriv(2), privilege(5)

342

privilege ( 5)
NAME

privilege - include file for privilege mechanism definitions
SYNOPSIS

#include
DESCRIPTION

This header file is used by all privilege mechanisms. All privileges are defined here,
as well as certain operations that are necessary for privilege operations.
#ifndef
#define

_ACC_PRIV_PRIVILEGE_H
_ACC_PRIV_PRIVILEGE_H

#ifndef
#include
#endif/* _UTIL_TYPES_H */

/* wrapper symbol for kernel use */
/* subject to change without notice */

REQUIRED

#elif defined(_KERNEL)
#include

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

* The following is the typedef for the user-level privilege
* definition. It is here because kernel routines also need
* to know about this particular type.

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

typedef

unsigned

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

*
* The following are the known privilege sets.
*
PS_FIX
for fixed privilege sets
*

*
*
*

PS_INH
PS_MAX
PS_WKG

for inheritable privilege sets
for maximum privilege sets
for working privilege sets

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

#define
#define
#define
#define
#define

PS_FIX
PS_INH
PS_MAX
PS_WKG
PS_TYPE

Ox66000000
Ox69000000
Ox6dOOOOOO
Ox77000000
OxffOOOOOO

343

privilege (5)
1***************************************************** *****

*
* The following are the supported object types for
* privilege mechanisms.
*

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

#define
#define

PS_FILE_OTYPE
PS_PROC_OTYPE

OxO
Oxl

1***************************************************** *****

*
* The following is the set of all known privileges.
* The define NPRIVS is the number of privileges
* currently in use. It should be modified whenever a
* privilege is added or deleted. Further description
* of each privilege can be found in intro(2).
*

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

344

#define

NPRIVS

#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define

P_OWNER
P_AUDIT
P_COMPAT
P_DACREAD
P_DACWRITE
P_DEV
P_FILESYS
P_MACREAD
P_MACWRITE
P_MOUNT
P_MOLTIDIR
P_SETPLEVEL
P_SETSPRIV
P_SETUID
P_SYSOPS
P_SETUPRIV
P_DRIVER
P_RTIME
P_MACUPGRADE
P_FSYSRANGE
P_SETFLEVEL
P_AUDITWR
P_TSHAR
P_PLOCK
P_CORE
P_LOADMOD
P_ALLPRIVS

26
OxOOOOOOOO
OxOOOOOOOl
OxOOOOOOO2
OxOOOOOOO3
OxOOOOOOO4
OxOOOOOOO5
OxOOOOOOO6
OxOOOOOOO7
OxOOOOOOO8
OxOOOOOOO9
OxOOOOOOOa
OxOOOOOOOb
OxOOOOOOOc
OxOOOOOOOd
OxOOOOOOOe
OxOOOOOOOf
OxOOOOOO1O
OxOOOOOOll
OxOOOOOO12
OxOOOOOO13
OxOOOOOO14
OxOOOOOO15
OxOOOOOO16
OxOOOOOO17
OxOOOOOO18
OxOOOOOO19
OxOOffffff

privilege ( 5)
1***************************************************** *****

*
* The following defines are recognized by the privilege
* mechanisms. They are returned in the argument value of
* the secsys() system call in the form of flags when the

command is ES_PRVINFO.

****************************************************** ·*·*1

#define
#define
#define

PM_UIDBASE
PM_ULVLINIT
PM_PRVMODE

OxOOOOOOOl
Ox00000002
Ox00000004

1***************************************************** *****

* The following are the CMOS recognized
* and filepriv() system calls.
*

by the procpriv()

****************************************************** ·***1

#define
#define
#define
#define
#define

SETPRV
CLRPRV
PUTPRV
GETPRV
CNTPRV

OxO
Oxl
Ox2
Ox3
Ox4

1***************************************************** *****

* Structure definition for the privilege sets supported

* by individual privilege servers. Also same defines
* that are used at user-level related to the privilege
* mechanisms.
*

****************************************************** *·**1

#define
#define

PR~IZ

PRVMAXSETS

32
256

typedef
struct
PIILsetdef
priv_t
sd_mask;
sd_setcnt;
uint
char
sd_name[PR~IZ1;
ulong_t
sd_objtype;
setdef_t;

/*
/*
/*
/*

masked type for this privilege set * /
number of privileges in this set
*/
name of this privilege set
*/
object type of this privilege set */

#if definedLKERNEL) II definedLKMEMUSER)
1***************************************************** *****

*
* The following macros are used by the different privilege
* servers to manipulate privilege bits.
*

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

345

privilege ( 5)
/* Turn on significant bits within kernel privilege vector. */
#define
pm_allon
«1 « NPRIVS) - 1)

/* Mask off type field within privilege descriptor and returns */
/* the privilege */
#define
pm-POs (p)
(pvec_t) «p) & -PS_TYPE)
/* Mask off the privilege field and return the privilege type */
#define
pm_type(p)
(pvec_t) «p) & PS_TYPE)
/* Convert privilege type to ASCII character */
#define
pm-pridc(p)
(pvec_t) «p) » 24)
/* Set the pvec_t bit corresponding to the privilege passed */
#define
pm-privbit(p)
(pvec_t)(1 « (p»
/* Convert an ASCII character to a privilege type */
#define
pm-pridt(p)
(pvec_t) «p) « 24)
/* Validate the privilege descripter passed */
#define
pm_invalid (p)
« (pm-pos «p» < 0 I I pm-pos «p»
> NPRIVS) && pm-POs«p»
!= P_ALLPRIVS) ? 1
/* Turn on privilege passed within vector passed */
#define
pm_setbits (p, v)
(v 1= « (p) == P_ALLPRIVS)
? pm_allon : (l«pm-pos(p»»

*
*

Check the credential(a) passed,
to determine if privilege(b) is on within the working privilege set

*/
#define pm-privon(a, b)

«a)->cr_wkgpriv & (b»

*
*

Check both credentials(a,b) passed,
to determine if the maximum privilege set of (b) is a subset of (a)

*/
«(a)->cr_maxpriv & (b)->cr_maxpriv)
(b)->cr_maxpriv)

#define

If the maximum privileges in the credentials passed are non-zero

* then the process is privileged.
*/
#define

pm-privileged(a)

1***************************************************** ******

*
*
*
*

Structure definitions for the kernel privilege table
data types. Used by any privilege mechanism that stores
the information in the kernel.

****************************************************** *****1

346

privi lege ( 5)
/* least privilege file table */
typedef struct
lpftab {
structlpftab*lpf_next; /* ptr to next file in list
ino_t lpf_nodeid;
/* node id
pvec_tlpf_fixpriv;
/* fixed privileges
pvec_tlpf_inhpriv;
/* inheritable privileges
time_tlpf_validity;
/* validity info for integrity
lpftab_t;
/* least privilege file system id
typedef struct
lpdtab {
structlpdtab*lpd~ext;
/*
lpftab_t
*lpd_list; /*
/*
dev_t lpd_fsid;
/*
lpdtab_t;

*/
*/
*/
*/
*/

table */
ptr to next file system in list */
ptr to a privileged file on
*/
this particular file system
*/
the id number for this file system */

/* least privilege device per file system table */
typedef struct
lpktab {
structlpktab*lpk_next; /* ptr to next device in list
lpdtab_t
*lpk_list; /* ptr to a file system on
/* this particular device
dev_t lpk_dev;
/* the id number for this device
lpktab_t;

*/
*/
*/
*/

#endif / * _KERNEL I I _KMEMOSER * /
#endif/* _ACC_PRIV_PRIVILEGE_H */
SEE ALSO

filepriv(2), procpriv(2), priv(4)

347

prof(S)
NAME

prof - profile within a function
SYNOPSIS

#define MARK
#include
void MARK (name);
DESCRIPTION

MARK introduces a mark called name that is treated the same as a function entry
point. Execution of the mark adds to a counter for that mark, and program-counter
time spent is accounted to the immediately preceding mark or to the function if
there are no preceding marks within the active function.
name may be any combination of letters, numbers, or underscores. Each name in a
single compilation must be unique, but may be the same as any ordinary program
symbol.

For marks to be effective, the symbol MARK must be defined before the header file
prof.h is included, either by a preprocessor directive as in the synopsis, or by a
command line argument:
cc -p -DMARK foo.c
If MARK is not defined, the MARK(name) statements may be left in the source files
containing them and are ignored. prof -g must be used to get information on all
labels.
EXAMPLE
In this example, marks can be used to determine how much time is spent in each

loop. Unless this example is compiled with MARK defined on the command line, the
marks are ignored.
#include
foo( )
{

int i, j;
MARK (loopl) ;

for (i = 0; i < 2000; i++) {
}

MARK(loop2);

for (j = 0; j < 2000; j++) {
}

}

SEE ALSO

monitor(3C) prof(l), profil(2)

348

regexp(5)
NAME

regexp: compile, step, advance - regular expression compile and match routines
SYNOPSIS

#define
#define
#define
#define
#define
#define

INIT declarations
GETC (void) getc code
PEEKC (void) peekc code
UNGETC (void) ungetc code

RETlJRN(ptr) return code
ERROR(val) error code

#include
char *compile (char *instring, char *expbuJ, char *endbuJ, int eoJ)

int step (char *string, char *expbuJ) i
int advance (char *s tring, char *expbuJ)

extern char *loc1, *loc2, *lOCSi
DESCRIPTION

These functions are general purpose regular expression matching routines to be
used in programs that perform regular expression matching. These functions are
defined by the regexp. h header file.
The functions step and advance do pattern matching given a character string and a
compiled regular expression as input.
The function compile takes as input a regular expression as defined below and produces a compiled expression that can be used with step or advance.
A regular expression specifies a set of character strings. A member of this set of
strings is said to be matched by the regular expression. Some characters have special meaning when used in a regular expression; other characters stand for themselves.
The regular expressions available for use with the regexp functions are constructed
as follows:

Expression
c
\c

Meaning
the character c where c is not a special character.
the character c where c is any character, except a digit in the range
1-9.

$
[s]
[~sl

the beginning of the line being compared.
the end of the line being compared.
any character in the input.
any character in the set s, where s is a sequence of characters and/or a
range of characters, for example, [c-cl.
any character not in the set s, where s is defined as above.

349

regexp(5)
r*

zero or more successive occurrences of the regular expression r. The
longest leftmost match is chosen.

the occurrence of regular expression r followed by the occurrence of
regular expression x. (Concatenation)
any number of m through n successive occurrences of the regular
expression r. The regular expression r\{m\} matches exactly m
occurrences; r\ {m, \} matches at least m occurrences.

r\ {m, n \}

\ (r\)

the regular expression r. When \n (where n is a number greater than
zero) appears in a constructed regular expression, it stands for the regular expression x where x is the nth regular expression enclosed in \ (
and \) that appeared earlier in the constructed regular expression.
For example, \ (r\) x\ (y\) z\2 is the concatenation of regular expressions rxyzy.

Characters that have special meaning except when they appear within square brackets ([ 1) or are preceded by \ are: ., *, L \. Other special characters, such as $ have
special meaning in more restricted contexts.
The character ~ at the beginning of an expression permits a successful match only
immediately after a newline, and the character $ at the end of an expression
requires a trailing newline.
Two characters have special meaning only when used within square brackets. The
character - denotes a range, [c-c], unless it is just after the open bracket or before
the closing bracket, [-c] or [c-] in which case it has no special meaning. When
used within brackets, the character ~ has the meaning complement of if it immediately follows the open bracket (example: [~c1); elsewhere between brackets (example: [c~]) it stands for the ordinary character ~.
The special meaning of the \ operator can be escaped only by preceding it with
another \ , for example, \ \.
Programs must have the following five macros declared before the #include
regexp.h statement. These macros are used by the conpile routine. The macros
GETC, PEEKC, and UNGETC operate on the regular expression given as input to compile.
GETC

PEEKC

UNGETC

350

This macro returns the value of the next character (byte) in the regular expression pattern. Successive calls to GETC should return
successive characters of the regular expression.
This macro returns the next character (byte) in the regular expression. Immediately successive calls to PEEKC should return the
same character, which should also be the next character returned
byGETC.
This macro causes the argument c to be returned by the next call to
GETC and PEEKC. No more than one character of pushback is ever
needed and this character is guaranteed to be the last character
read by GETC. The return value of the macro UNGETC(c) is always
ignored.

regexp(5)
RETURN (ptr)

This macro is used on normal exit of the compile routine. The
value of the argument ptr is a pointer to the character after the last
character of the compiled regular expression. This is useful to programs which have memory allocation to manage.

ERROR (val)

This macro is the abnormal return from the compile routine. The
argument val is an error number [see ERRORS below for meanings].
This call should never return.

The syntax of the compile routine is as follows:
compile (instring, expbuf, endbuf, eof)

The first parameter, instring, is never used explicitly by the compile routine but is
useful for programs that pass down different pointers to input characters. It is
sometimes used in the INIT declaration (see below). Programs which call functions
to input characters or have characters in an external array can pass down a value of
(char *) 0 for this parameter.
The next parameter, expbuj, is a character pointer. It points to the place where the
compiled regular expression will be placed.
The parameter endbuf is one more than the highest address where the compiled regular expression may be placed. If the compiled expression cannot fit in
(endbuf-expbuf) bytes, a call to ERROR(SO) is made.
The parameter eof is the character which marks the end of the regular expression.
This character is usually a /.
Each program that includes the regexp.h header file must have a #define statement for INIT. It is used for dependent declarations and initializations. Most often
it is used to set a register variable to point to the beginning of the regular expression
so that this register variable can be used in the declarations for GETC, PEEKC, and
UNGETC. Otherwise it can be used to declare external variables that might be used
by GETC, PEEKC and UNGETC. [See EXAMPLE below.]
The first parameter to the step and advance functions is a pointer to a string of
characters to be checked for a match. This string should be null terminated.
The second parameter, expbuj, is the compiled regular expression which was
obtained by a call to the function compile.
The function step returns non-zero if some substring of string matches the regular
expression in expbuf and zero if there is no match. If there is a match, two external
character pointers are set as a side effect to the call to step. The variable locl
points to the first character that matched the regular expression; the variable loc2
points to the character after the last character that matches the regular expression.
Thus if the regular expression matches the entire input string, locl will point to the
first character of string and loc2 will point to the null at the end of string.
The function advance returns non-zero if the initial substring of string matches the
regular expression in expbuf If there is a match, an external character pointer, loc2,
is set as a side effect. The variable loc2 points to the next character in string after
the last character that matched.

351

regexp(5)
When advance encounters a * or \ { \} sequence in the regular expression, it will
advance its pointer to the string to be matched as far as possible and will recursively call itself trying to match the rest of the string to the rest of the regular
expression. As long as there is no match, advance will back up along the string
until it finds a match or reaches the point in the string that initially matched the *
or \ { \}. It is sometimes desirable to stop this backing up before the initial point in
the string is reached. If the external character pointer locs is equal to the point in
the string at sometime during the backing up process, advance will break out of the
loop that backs up and will return zero.
The external variables circf, sed, and nbra are reserved.
DIAGNOSTICS

The function compile uses the macro RETURN on success and the macro ERROR on
failure (see above). The functions step and advance return non-zero on a successful match and zero if there is no match. Errors are:
11
range endpoint too large.
16
bad number.
25
\ digit out of range.
36
invalid or missing delimiter.
41
no remembered search string.
42
\ ( \) imbalance.
43
too many \ (.
44
more than 2 numbers given in \ { \}.
45
} expected after \.
46
first number exceeds second in \ { \ }.
49
[] imbalance.
50
regular expression overflow.
EXAMPLES

The following is an example of how the regular expression macros and calls might
be defined by an application program:
#define
#define
#define
#define
#define
#define

INIT
GETC
PEEKC
UNGETC(c)
RETURN(*c)
ERROR(c)

= instring;

#include
(void) compile (*argv, expbuf, &expbuf[ESIZE],'\O');
if (step (linebuf, expbuf»
succeed;
SEE ALSO

regexpr(3G)

352

siginfo(5)
NAME

siginfo - signal generation information
SYNOPSIS

#include
DESCRIPTION

If a process is catching a signal, it may request information that tells why the system
generated that signal [see sigaction(2)]. If a process is monitoring its children, it
may receive information that tells why a child changed state [see waitid(2)]. In
either case, the system returns the information in a structure of type siginfo_t,
which includes the following information:
int si_signo
1* signal number *1
int si_ermo
1* error number *1
int si_code
1* signal code *1
si_signe contains the system-generated signal number. (For the waitid(2) function, si_signe is always SIGCHLD.)
If si_errno is non-zero, it contains an error number associated with this signal, as
defined in errno. h.
si_code contains a code identifying the cause of the signal. If the value of si_code
is less than or equal to 0, then the signal was generated by a user process [see
kill(2) and sigsend(2)] and the siginfo structure contains the following additional information:
pid_t si-l)id
1* sending process ID *1
uid_t si_uid
1* sending user ID *1
Otherwise, si_code contains a signal-specific reason why the signal was generated,
as follows:
Code
Reason
Signal
ILL_ILLOPC
SIGILL
illegal opcode
ILL_ILLOPN
illegal operand
ILL_ILLADR
illegal addressing mode
ILL_ILLTRP
illegal trap
ILL_PRVOPC
privileged opcode
ILL_PRVREG
privileged register
ILL_COPROC
co-processor error
ILL_BADSTK
internal stack error
SIGFPE

FPE_INTDIV
FPE_IN'1'OVF
FPE_FLTDIV
FPE_FLTOVF
FPE_FLTUND
FPE_FLTRES
FPE_FLTINV
FPE_FLTSUB

integer divide by zero
integer overflow
floating point divide by zero
floating point overflow
floating point underflow
floating point inexact result
invalid floating point operation
subscript out of range

353

siginfo(5)
Signal

Code

Reason
address not mapped to object
invalid permissions for mapped object

BUS_ADRALN
BUS_ADRERR
BUS_OBJERR

invalid address alignment
non-existent physical address
object specific hardware error

SIGSEGV
SIGBUS

process breakpoint
process trace trap

SIGTRAP
SIGCHLD

eLD_EXITED
eLD_KILLED
eLD_DUMPED
eLD_TRAPPED
eLD_STOPPED
eLD_CONTINUED

child has exited
child was killed
child terminated abnormally
traced child has trapped
child has stopped
stopped child had continued

SIGPOLL

POLL_IN
POLL_OUT
POLL_MSG
POLL_ERR
POLL_PRI
POLL_HOP

data input available
output buffers available
input message available
I/O error
high priority input available
device disconnected

In addition, the following signal-dependent information is available for kemelgenerated signals:
Signal
Field
Value
SIGILL
caddr_t si_addr address of faulting instruction
SIGFPE
SIGSEGV
SIGBUS
SIGCHLD
SIGPOLL

caddr_t si_addr

address of faulting memory reference

pid_t si.....pid
int si_status
long si_band

child process ill
exit value or signal
band event for POLL_IN, POLL_OUT, or
POLL_MSG

SEE ALSO

sigaction(2), signal(5), waitid(2)
NOTES

For SIGCHLD signals, if si_code is equal to eLD_EXITED, then si_status is equal
to the exit value of the process; otherwise, it is equal to the signal that caused the
process to change state. For some implementations, the exact value of si_addr
may not be available; in that case, si_addr is guaranteed to be on the same page as
the faulting instruction or memory reference.

354

signal (5)
NAME

signal - base signals
SYNOPSIS

#include
DESCRIPTION

A signal is an asynchronous notification of an event. A signal is said to be generated for (or sent to) a process when the event associated with that signal first
occurs. Examples of such events include hardware faults, timer expiration and terminal activity, as well as the invocation of the kill or sigsend system calls. In
some circumstances, the same event generates signals for multiple processes. A
process may request a detailed notification of the source of the signal and the reason why it was generated [see siginfo(5)].
Each process may specify a system action to be taken in response to each signal sent
to it, called the signal's disposition. The set of system signal actions for a process is
initialized from that of its parent. Once an action is installed for a specific signal, it
usually remains installed until another disposition is explicitly requested by a call to
either sigaction, signal or sigset, or until the process execs [see sigaction(2)
and signal(2)]. When a process execs, all signals whose disposition has been set to
catch the signal will be set to SIG_DFL. Alternatively, a process may request that
the system automatically reset the disposition of a signal to SIG_DFL after it has
been caught [see sigaction(2) and signal(2)].
A signal is said to be delivered to a process when the appropriate action for the process and signal is taken. During the time between the generation of a signal and its
delivery, the signal is said to be pending [see sigpending(2)]. Ordinarily, this interval cannot be detected by an application. However, a signal can be blocked from
delivery to a process [see signal(2) and sigprocmask(2)]. If the action associated
with a blocked signal is anything other than to ignore the signal, and if that signal is
generated for the process, the signal remains pending until either it is unblocked or
the signal's disposition requests that the signal be ignored. If the signal disposition
of a blocked signal requests that the signal be ignored, and if that signal is generated for the process, the signal is discarded immediately upon generation.
Each process has a signal mask that defines the set of signals currently blocked from
delivery to it [see sigprocmask(2)]. The signal mask for a process is initialized from
that of its parent.
The determination of which action is taken in response to a signal is made at the
time the signal is delivered, allowing for any changes since the time of generation.
This determination is independent of the means by which the signal was originally
generated.
The signals currently defined in sys/ signal. h are as follows:

355

signal (5)
Name
SIGHUP
SIGINT
SIGQUIT
SIGILL
SIGTRAP
SIGABR'I'
SIGEMT
SIGFPE
SIGKILL
SIGBUS
SIGSEGV
SIGSYS
SIGPIPE
SIGALRM
SIGTERM
SIGUSRI
SIGUSR2
SIGCHLD
SIGPWR
SIGWINCH
SIGURG
SIGPOLL
SIGSTOP
SIGTSTP
SIGCONT
SIGTTIN
SIGTTOU
SIGVTALRM
SIGPROF
SIGXCPU
SIGXFSZ

Value
1
2
3
4
5
6
7
8
9
10

1l
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Default
Exit
Exit
Core
Core
Core
Core
Core
Core
Exit
Core
Core
Core
Exit
Exit
Exit
Exit
Exit
Ignore
Ignore
Ignore
Ignore
Ignore
Stop
Stop
Ignore
Stop
Stop
Exit
Exit
Core
Core

Event
Hangup [see termio(7)]
Interrupt [see termio(7)]
Quit [see termio(7)]
illegal Instruction
Trace/Breakpoint Trap
Abort
Emulation Trap
Arithmetic Exception
Killed
Bus Error
Segmentation Fault
Bad System Call
Broken Pipe
Alarm Clock
Terminated
User Signal 1
User Signal 2
Child Status
Power Fail/Restart
Window Size Change
Urgent Socket Condition
Socket I/O Possible
Stopped (signal)
Stopped (user) [see termio(7)]
Continued
Stopped (tty input) [see termio(7)]
Stopped (tty output) [see termio(7)]
Virtual Timer Expired
Profiling Timer Expired
CPU time limit exceeded [see getrlimit(2)]
File size limit exceeded [see getrlimit(2)]

Using the signal, sigset or sigaction system call, a process may specify one of
three dispositions for a signal: take the default action for the signal, ignore the signal, or catch the signal.
Default Action: SIG_DFL
A disposition of SIG_DFL specifies the default action. The default action for each
signal is listed in the table above and is selected from the follOWing:
Exit
When it gets the signal, the receiving process is to be terminated with all
the consequences outlined in exit(2).
Core
When it gets the signal, the receiving process is to be terminated with all
the consequences outlined in exit(2). In addition, a "core image" of the
process is constructed in the current working directory.
Stop
When it gets the signal, the receiving process is to stop.

356

signal (5)
Ignore

When it gets the signal, the receiving process is to ignore it. This is identical to setting the disposition to SIG_IGN.

Ignore Signal: SIG_IGN

A disposition of SIG_IGN specifies that the signal is to be ignored.
Catch Sig nal: function address

A disposition that is a function address specifies that, when it gets the signal, the
receiving process is to execute the signal handler at the specified address. Normally, the signal handler is passed the signal number as its only argument; if the
disposition was set with the sigaction function however, additional arguments
may be requested [see sigaction(2)]. When the signal handler returns, the receiving process resumes execution at the point it was interrupted, unless the signal
handler makes other arrangements. If an invalid function address is specified,
results are undefined.
If the disposition has been set with the sigset or sigaction function, the signal is
automatically blocked by the system while the signal catcher is executing. If a
longjmp [see setjmp(3C)] is used to leave the signal catcher, then the signal must
be explicitly unblocked by the user [see signal(2) and sigprocmask(2)].
If execution of the signal handler interrupts a blocked system call, the handler is
executed and the interrupted system call returns a -1 to the calling process with
errno set to EINTR. However, if the SA_RESTART flag is set the system call will be
transparently restarted.
NOTES

The dispositions of the SIGKILL and SIGSTOP signals cannot be altered from their
default values. The system generates an error if this is attempted.
The SIGKILL and SIGSTOP signals cannot be blocked. The system silently enforces
this restriction.
Whenever a process receives a SIGSTOP, SIGTSTP, SIGTTIN, or SIGTTOU signal,
regardless of its disposition, any pending SIGCONT signal is discarded. A process
stopped by the above four signals is said to be in a job control stop.
Whenever a process receives a SIGCONT signal, regardless of its disposition, any
pending SIGSTOP, SIGTSTP, SIGTTIN, and SIGTTOU signals are discarded. In addition, if the process was stopped, it is continued.
SIGPOLL is issued when a file descriptor corresponding to a STREAMS [see
intro(2)] file has a "selectable" event pending. A process must specifically request
that this signal be sent using the I_SETSIG ioctl call. Otherwise, the process will
never receive SIGPOLL.

If the disposition of the SIGCHLD signal has been set with signal or sigset, or

with sigaction and the SA_NOCLDSTOP flag has been specified, it will only be sent
to the calling process when its children exit; otherwise, it will also be sent when the
calling process's children are stopped or continued due to job control.
For backward compatibility, the names SIGCLD, SIGIOT, and SIGIO are defined in
this header file. SIGCLD identifies the same signal as SIGCHLD. SIGIOT identifies
the same signal as SIGABRT, and SIGIO identifies the same signal as SIGPOLL.
However, new applications should use SIGCHLD, SIGABRT, and SIGPOLL.

357

signal (5)
The disposition of signals that are inherited as SIG_IGN should not be changed.
SEE ALSO

exit(2),
getrlimit(2),
intro(2),
kill(2),
pause(2),
sigaction(2),
sigaltstack(2),
siginfo(5),
signal(2),
sigprocmask(2),
sigsend(2),
sigsetops(3C), sigsuspend(2), ucontext(5), wait(2)

358

stat (5)
NAME

stat - data returned by stat system call
SYNOPSIS

#include
#include
DESCRIPTION

The system calls stat, lstat and fstat return data in a stat structure, which is
defined in stat.h and includes the following members:
dev_t
ino_t
mode_t
nlink_t
uid_t
gid_t
dev_t
off_t
time_t
time_t
time_t
long
long
char
int
level_t st_level;
ulong_t st_flags;

st_dev;
st_ino;
st_mode;
st_nlink;
st_uid;
st_gid;
st_rdev;
st_size;
st_atime;
st_mtime;
st_ctime;
st_blksize;
st_blocks;
st_fstype[_ST_FSTYPSZ];
st_aclcnt;
/* general purpose flag */

The following members are only valid if Enhanced Security is installed:
int st_aclcnt;
level_t st_level;
ulong_t st_flags;

The constants used in the st_mode field are also defined in this file:
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define

S_IFMT
S_IAMB
S_IFIFO
S_IFCHR
S_IFDIR
S_IFNAM
S_INSEM
S_INSHD
S_IFBLK
S_IFREG
S_IFLNK
S_ISUID
S_ISGID
S_ISVTX

/* type of file */
/ * access mode bits */
/* fifo */
/ * character special */
/ * directory */
/ * XENIX special named file */
/* XENIX semaphore subtype of IFNAM * /
/ * XENIX shared data subtype of IFNAM */
/ * block special */
/ * regular */
/ * symbolic link */
/ * set user id on execution */
/ * set group id on execution */
/ * save swapped text even after use */

359

stat (5)
#define
#define
#define
#define
#define
#def ine
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define

/* read permission, owner */

S_IREAD
S_IWRITE
S_IEXEC
S_ENFMT
S_IRWXU
S_IRUSR
S_IWUSR
S_IXUSR
S_IRWXG
S_IRGRP
S_IWGRP
S_IXGRP
S_IRWXO
S_IROTH
S_IWOTH
S_IXOTH

* write permission, owner */

/* execute/search permission, owner */
/* record locking enforcement flag */
/
/
/

* read, write, execute: owner */
* read permission: owner */
* write permission: owner */

/* execute permission: owner */
/
/

* read, write, execute: group */
* read permission: group */

/* write permission: group */
/* execute permission: group */
/* read, write, execute: other */
/* read permission: other */

1* write permission: other */
1* execute permission: other */

The following macros are for POSIX conformance:
#define
#define
#define
#define
#define

S_ISBLK{mode)
S_ISCHR{mode)
S_ISDIR{mode)
S_ISFIFO(mode)
S_ISREG{mode)

block special file
character special file
directory file
pipe or fifo file
regular file

One constant used in the st_flags field is also defined in this file:
#def ine

S_ISMLD

* indicates multilevel directory */

Multilevel directories are only supported if the Enhanced Security Utilities are
installed.
SEE ALSO

stat(2), types(5)

360

stdarg(5)
NAME

stdarg - handle variable argument list
SYNOPSIS

#include
va_list pvar;
void va_start (va_list pvar, parmN);

type va_arg(va_list pvar, type);
void va_end(va_list pvar);
DESCRIPTION

This set of macros allows portable procedures that accept variable numbers of arguments of variable types to be written. Routines that have variable argument lists
(such as printf) but do not use stdarg are inherently non-portable, as different
machines use different argument-passing conventions.
va_list is a type defined for the variable used to traverse the list.
The va_start macro is invoked before any access to the unnamed arguments and
initializes pvar for subsequent use by va_arg and va_end. The parameter parmN is
the identifier of the rightmost parameter in the variable parameter list in the function definition (the one just before the, ••• ). If this parameter is declared with the
register storage class or with a function or array type, or with a type that is not
compatible with the type that results after application of the default argument promotions, the behavior is undefined.
The parameter parmN is required under strict ANSI C compilation. In other compilation modes, parmN need not be supplied and the second parameter to the
va_start macro can be left empty [e.g., va_start
#define MAXARGS 31
void f1(int n-ptrs, .•. )
{

va_list ap;
char *array [MAXARGS] ;
int ptr_no = 0;
if (n.....ptrs > MAXARGS)
n-ptrs = MAXARGS;
va_start(ap, n-ptrs);
while (ptr_DO < ~trs)
array [ptr_DO++] = va_arg(ap, char*);
va_end (ap) ;
f2(n.....ptrs, array);
}

Each call to f1 shall have visible the definition of the function or a declaration such
as
void f1(int, •.• )
SEE ALSO

vprintf(3S)
NOTES

It is up to the calling routine to specify in some manner how many arguments there
are, since it is not always possible to determine the number of arguments from the
stack frame. For example, execl is passed a zero pointer to signal the end of the
list. printf can tell how many arguments there are by the format. It is nonportable to specify a second argument of char, short, or float to va_arg, because
arguments seen by the called function are not char, short, or float. C converts
char and short arguments to int and converts float arguments to double before
passing them to a function.

362

term(5)
NAME

term - conventional names for terminals
DESCRIPTION

Terminal names are maintained as part of the shell environment in the environment
variable TERM [see sh(l), profile(4), and environ(5)]. These names are used by
certain commands [for example, tabs, tput, and vi] and certain functions [for
example, see curses(3curses)].
Files under lusrlshare/lib/terminfo are used to name terminals and describe
their capabilities. These files are in the format described in terminfo(4). Entries in
terminfo source files consist of a number of comma-separated fields. To print a
description of a terminal term, use the command infocnrp -I term [see
infocnp(lM)]. White space after each comma is ignored. The first line of each terminal description in the terminfo database gives the names by which terminfo
knows the terminal, separated by bar (I) characters. The first name given is the
most common abbreviation for the terminal [this is the one to use to set the environment variable TERMINFO in $HOMEI .profile; see profile(4)], the last name given
should be a long name fully identifying the terminal, and all others are understood
as synonyms for the terminal name. All names but the last should contain no
blanks and must be unique in the first 14 characters; the last name may contain
blanks for readability.
Terminal names (except for the last, verbose entry) should be chosen using the following conventions. The particular piece of hardware making up the terminal
should have a root name chosen, for example, for the AT&T 4425 terminal,
att442S. This name should not contain hyphens, except that synonyms may be
chosen that do not conflict with other names. Up to 8 characters, chosen from the
set a through z and 0 through 9, make up a basic terminal name. Names should
generally be based on original vendors rather than local distributors. A terminal
acquired from one vendor should not have more than one distinct basic name. Terminal sub-models, operational modes that the hardware can be in, or user preferences should be indicated by appending a hyphen and an indicator of the mode.
Thus, an AT&T 4425 terminal in 132 column mode is att442S-w. The following
suffixes should be used where possible:
Suffix
Meaning
Example
att442S-w
-w
Wide mode (more than 80 columns)
-am
With auto. margins (usually default) vt100-am
-nam
Without automatic margins
vt 10 O-nam
aaa-60
-n
Number of lines on the screen
-na
No arrow keys (leave them in local)
cl00-na
cl00-4p
-np
Number of pages of memory
-rv
Reverse video
att441S-rv
To avoid conflicts with the naming conventions used in describing the different
modes of a terminal (for example, -w), it is recommended that a terminal's root
name not contain hyphens. Further, it is good practice to make all terminal names
used in the terminfo(4) database unique. Terminal entries that are present only for
inclusion in other entries via the use= facilities should have a '+' in their name, as in
441S+nl.

363

term (5)
Here are some of the known terminal names: (For a complete list, enter the command 1s -C lusrlshare/lib/tenninfol?)
2621,hp2621
Hewlett-Packard 2621 series
2631
Hewlett-Packard 2631 line printer
2631-c
Hewlett-Packard 2631 line printer, compressed
mode
2631-e
Hewlett-Packard 2631 line printer, expanded mode
2640,hp2640
Hewlett-Packard 2640 series
2645,hp2645
Hewlett-Packard 2645 series
3270
mM Model 3270
33,tty33
AT&T Teletype Model 33 KSR
35,tty35
AT&T Teletype Model 35 KSR
37,tty37
AT&T Teletype Model 37 KSR
4000a
Trendata 4000a
4014,tek4014
TEKTRONIX 4014
40,tty40
AT&T Teletype Dataspeed 40/2
43,tty43
AT&T Teletype Model 43 KSR
4410,5410
AT&T 4410/5410 in 8O-column mode, version 2
4410-nfk,5410-nfk
AT&T 4410/5410 without function keys, version 1
4410-nsl,5410-ns1
AT&T 4410/5410 without pIn defined
4410-w,5410-w
AT&T 4410/5410 in 132-column mode
AT&T 4410/5410 in 80-column mode, version 1
4410vl,5410vl
4410vl-w,5410vl~
AT&T 4410/5410 in 132-column mode, version 1
4418,5418
AT&T 5418 in 80-column mode
4418-w,5418-w
AT&T 5418 in 132-column mode
4420
AT&T Teletype Model 4420
4424
AT&T Teletype Mode14424
4424-2
AT&T Teletype Model 4424 in display function
group ii
4425,5425
AT&T 4425/5425
4425-fk,5425-fk
AT&T 4425/5425 without function keys
4425-n1,5425-nl
AT&T 4425/5425 without changing labels in 80column mode
4425-w,5425-w
AT&T 4425/5425 in 132-column mode
4425~fk,5425-~fk
AT&T 4425/5425 without function keys in 132column mode
4425-n1-w,5425-nl~
AT&T 4425/5425 without changing labels in 132column mode
4426
AT&T Teletype Model4426S

364

term (5)
450
450-12
500,att500
510,510a
513bct,att513
5320
5420_2
5420_2-w
610, 610bct
610-w,610bct-w
630, 630M'l'G
735,ti
745
dumb

hp
lp
pt505
pt505-24
sync

DASI450 (same as Diablo 1620)
DASI 450 in 12-pitch mode
AT&T-IS 500 terminal
AT&T 510/51Oa in 80-column mode
AT&T 513 bet terminal
AT&T 5320 hardcopy terminal
AT&T 5420 model 2 in 80-column mode
AT&T 5420 model 2 in 132-column mode
AT&T 610 bct terminal in 80-column mode
AT&T 610 bet terminal in 132-column mode
AT&T 630 Multi-Tasking Graphics terminal
Texas Instruments TI735 and TI725
Texas Instruments TI745
generic name for terminals that lack reverse linefeed and other special escape sequences
Hewlett-Packard (same as 2645)
generic name for a line printer
AT&T Personal Terminal 505 (22 lines)
AT&T Personal Terminal 505 (24-line mode)
generic name for synchronous Teletype Model
4540-compatible terminals

Commands whose behavior depends on the type of terminal should accept arguments of the form -Tterm where term is one of the names given above; if no such
argument is present, such commands should obtain the terminal type from the
environment variable TERM, which, in turn, should contain term.
FILES

/usr/share/lib/terminfo/? /*

compiled terminal description database

SEE ALSO

curses(3curses), environ(5), infocq>(lM), profile(4), sh(l), stty(l), tabs (1),
terminfo(4), tput(l), vi(1)

365

types (5)
NAME

types - primitive system data types
SYNOPSIS

#include
DESCRIPTION

The data types defined in types.h are used in UNIX system code. Some data of
these types are accessible to user code:
typedef struct { int r[l]; } *physadr;
typedef long
clock_t;
typedef long
daddr_t;
typedef char *
caddr_t;
typedef unsigned char
unchar;
typedef unsigned short ushort;
typedef unsigned int
uint;
typedef unsigned long
ulong;
typedef unsigned long
ino_t;
typedef long
uid_t;
typedef long
gid_t;
typedef ulong
nlink_t;
typedef ulong
mode_t;
typedef short
cnt_t;
typedef long
time_t;
typede£ int
label_t[lO];
typedef ulong
dev_t;
typedef long
off_t;
typedef long
pid_t;
typedef ulong
paddr_t;
typedef int
key_t;
typedef unsigned char
use_t;
typedef short
sysid_t;
typedef short
index_t;
typedef short
lock_t;
typedef unsigned int
size_t;
typedef long
clock_t;
typedef long
pid_tf
typedef int
ssize_t;
The form daddr_t is used for disk addresses except in an i-node on disk, see fs(4).
Times are encoded in seconds since 00:00:00 UTe, January 1, 1970. The major and
minor parts of a device code specify kind and unit number of a device and are
installation-dependent. Offsets are measured in bytes from the beginning of a file.
The label_t variables are used to save the processor state while another process is
running.

366

ucontext ( 5)
NAME

ucontext - user context
SYNOPSIS

#include
DESCRIPTION

The ucontext structure defines the context of a thread of control within an executing process.
This structure includes at least the following members:
ucontext_t
sigset_t
stack_t
mcontext_t

*uc_link
uc_sigmask
uc_stack
uc_mcontext

uc_link is a pointer to the context that is to be resumed when this context returns.
If uc_link is equal to 0, then this context is the main context, and the process exits
when this context returns. The uc_link field is only meaningful for contexts
created using makecontext.
uc_sigmask defines the set of Signals that are blocked when this context is active
[see sigprocmask(2)].
uc_stack defines the stack used by this context [see sigaltstack(2)].
uc_mcontext contains the saved set of machine registers and any implementation
specific context data. Portable applications should not modify or access
uc_mcontext.
SEE ALSO

getcontext(2),
sigprocmask(2)

makecontext(3C),

sigaction(2),

sigaltstack(2),

367

values (5)
NAME

values - machine-dependent values
SYNOPSIS

#include
DESCRIPTION

This file contains a set of manifest constants, conditionally defined for particular
processor architectures.
The model assumed for integers is binary representation (one's or two's complement), where the sign is represented by the value of the high-order bit.
BITS (type)
The number of bits in a specified type (for example, int).
HI BITS
The value of a short integer with only the high-order bit set.
HIBITL
The value of a long integer with only the high-order bit set.
HIBITI
The value of a regular integer with only the high-order bit set.
MAXSHORT

The maximum value of a signed short integer.
The maximum value of a signed long integer.
MAXINT
The maximum value of a signed regular integer.
MAXFLOAT, LN_MAXFLOAT
The maximum value of a single-precision floating-point number,
and its natural logarithm.
MAXDOUBLE, LN_MAXDOUBLE
The maximum value of a double-precision floating-point number,
and its natural logarithm.
MAXLONGDOUBLE, LN_MAXLONGDOUBLE
The maximum value of a quad-precision floating-point number, and
its natural logarithm.
MINFLOAT,LN_MINFLOAT
The minimum positive value of a single-precision floating-point
number, and its natural logarithm.
MINDOUBLE,LN_MINDOUBLE
The minimum positive value of a double-precision floating-point
number, and its natural logarithm.
MINLONGDOUBLE, LN_MINLONGDOUBLE
The minimum value of a quad-precision floating-point number, and
its natural logarithm.
FSIGNIF
The number of significant bits in the mantissa of a single-precision
floating-point number.
DSIGNIF
The number of Significant bits in the mantissa of a double-precision
floating-point number.
The number of significant bits in the mantissa of a quad-precision
LDSIGNIF
floating-point number.
MAXLONG

368

values(5)
SEE ALSO

intro(3), math(S)

369

varargs (5)
NAME

varargs - handle variable argument list
SYNOPSIS

#inelude
va_alist
va_del
va_list pvar;
void va_start(va_list pvar);

type va_arg(va_list pvar, type);
void va_end(va_list pvar);
DESCRIPTION

This set of macros allows portable procedures that accept variable argument lists to
be written. Routines that have variable argument lists [such as printf(3S)] but do
not use varargs are inherently non-portable, as different machines use different
argument-passing conventions.
va_alist is used as the parameter list in a function header.
va_del is a declaration for va_alist. No semicolon should follow va_del.
va_list is a type defined for the variable used to traverse the list.
va_start is called to initialize pvar to the beginning of the list.
va_arg will return the next argument in the list pointed to by pvar. type is the type
the argument is expected to be. Different types can be mixed, but it is up to the routine to know what type of argument is expected, as it cannot be determined at runtime.
va_end is used to clean up.

Multiple traversals, each bracketed by va_start and va_end, are possible.
EXAMPLE

This example is a possible implementation of exeel [see exee(2)].
#inelude
#inelude
#define MAXARGS 100
/*

exeel is ealled by
exeel(file, arg1, arg2, . . . , (ehar *)0);

exeel(va_alist)
va_del
{

va_list ap;
ehar *file;
ehar *args[MAXARGS];
int argno = 0;
va_start ( ap) ;

370

/* assumed big enough*/

varargs (5)
file = va_arg(ap, char *);
while «args[argno++] = va_arg(ap, char

*»

va_end (ap) ;
return execv(file, args);
SEE ALSO

exec(2), printf(3S), stdarg(5), vprintf(3S)
NOTES

It is up to the calling routine to specify in some manner how many arguments there
are, since it is not always possible to determine the number of arguments from the
stack frame. For example, execl is passed a zero pointer to signal the end of the
list. printf can tell how many arguments are there by the format.
It is non-portable to specify a second argument of char, short, or float to va_arg,
since arguments seen by the called function are not char, short, or float. C converts char and short arguments to int and converts float arguments to double
before passing them to a function.

stdarg is the preferred interface.

371

wstat(5)
NAME

wstat - wait status
SYNOPSIS

#include
DESCRIPTION

When a process waits for status from its children via either the wait or waitpid
function, the status returned may be evaluated with th~ following macros, defined
in sys/wait.h. These macros evaluate to integral expressions. The stat argument
to these macros is the integer value returned from wait or waitpid.
WIFEXITED(stat)
Evaluates to a non-zero value if status was returned for a
child process that terminated normally.
WEXITSTATUS (stat)
If the value of WIFEXlTED(stat) is non-zero, this macro
evaluates to the exit code that the child process passed to
_exit or exit, or the value that the child process returned
from main.
WIFSIGNAL.ED(stat)
Evaluates to a non-zero value if status was returned for a
child process that terminated due to the receipt of a signal.
WTERMSIG(stat)
If the value of WIFSIGNALED(stat) is non-zero, this macro
evaluates to the number of the signal that caused the termination of the child process.
WIFSTOPPED(stat)
Evaluates to a non-zero value if status was returned for a
child process that is currently stopped.
WSTOPSIG(stat)
If the value of WIFSTOPPED(stat) is non-zero, this macro
evaluates to the number of the signal that caused the child
process to stop.
WIFCONTlNUED(stat) Evaluates to a non-zero value if status was returned for a
child process that has continued.
WCOREDUMI?(stat)
If the value of WIFSIGNALED(stat) is non-zero, this macro
evaluates to a non-zero value if a core image of the terminated child was created.
SEE ALSO

exit(2), wait(2), waitpid(2)

372

intro(7)
NAME

intro - introduction to special files
DESCRIPTION

This section describes various special files that refer to specific hardware peripherals, and UNIX system device drivers. STREAMS [see intro(2)] software drivers,
modules and the STREAMS-generic set of ioctl(2) system calls are also described.
For hardware related files, the names of the entries are generally derived from
names for the hardware, as opposed to the names of the special files themselves.
Characteristics of both the hardware device and the corresponding UNIX system
device driver are discussed where applicable.
Disk device file names are in the follOWing format:
/dev/ {r}dsk/ {lo O}s# For integral disks
/dev/ {r}dsk/c#t#d#s# For SCSI disks

where r indicates a raw interface to the disk, the c# indicates the SCSI host adapter
number, t# indicates the SCSI target ID of the device, d# indicates the device
attached to the controller and s# indicates the section number of the partitioned
device.

373

adsc(7)
NAME

adsc - Adaptec 1542A SCSI host adapter subsystem
DESCRIPTION

The Adaptec 1542A host adapter subsystem enables SCSI target drivers (such as
sd01, st01, and so on) to communicate on the SCSI bus with target controllers and
logical units. This driver implements the Portable Device Interface (PDI) for such
PDI target drivers.
It is also possible to access the SCSI-bus subsystem directly by using the driver's

pass-through interface. This allows you to issue sb control blocks directly to the
target controller. To find the appropriate pass-through device to use, while any
device is being accessed through the target driver (for example,sd01), use the
B_GETDEV ioctl to get the major and minor numbers of the pass-through node.
This node may be created and opened for pass-through use (SDI_SEND ioctl).
ioetl Calls

The following ioctl(2) commands are supported by this driver:
SDI_SEND
Sends a pass-through command (SCSI control block) to a target controller,
bypassing the associated target driver.
SDI_BRESET
Resets the SCSI bus.
B_REDT
Reads the extended Equipped Device Table (EDT) data structure that is
stored in the adsc driver's internal data structure.
B_GETTYPE
Returns the bus name (for example, SCSI) and device driver name of a
specific device.
Files

/usr/include/sys/ad1542.h
/usr/include/sys/scsi.h
/usr/include/sys/sdi.h
/usr/include/sys/sdi_edt.h
/etc/conf/pack.d/adsc/space.c
NOTICES

Adaptec SCSI controllers cannot be used reliably with Emulex SCSI/ESDI bridge
controllers (also known as AT&T DCM/4E). In the future, a hardware and/or
software fix may be implemented.
REFERENCES

dpt(7), ioctl(2), mcis(7), sc01(7), sd01(7), st01(7), sw01(7), wd7000(7)

374

alp(7)
NAME

alp - algorithm pool management module
DESCRIPTION

The STREAMS module alp maintains a pool of algorithms (in the form of STREAMScompatible subroutines) that may be used for processing STREAMS data messages.
Interfaces are defined allowing modules to request and initiate processing by any of
the algorithms maintained in the pool. It is expected to help centralize and standardize the interfaces to algorithms that now represent a proliferation of similarbut-different STREAMS modules. Its major use is envisioned as a central registry of
available code set conversion algorithms or other types of common datamanipulating routines.
An algorithm pool is a registry (or pool) of available functions; in this case, routines
for performing transformations on STREAMS data messages. Registered functions
may keep information on attached users, which means that algorithms need not be
stateless, but may maintain extensive state information related to each connection.
An algorithm from the pool is called by another in-kernel module with arguments
that are a STREAMS data message and a unique identifier. If a message is passed
back to the caller, it is the algorithm's output, otherwise the algorithm may store
partially convertible input until enough input is received to give back output on a
subsequent call.
This pool is one means for providing a consistent and flexible interface for code set
conversion within STREAMS modules, especially kbd, but it may also be used to provide other services that are commonly duplicated by several modules.
The alp module contains some subroutines dealing with its (minor) role as a
module, a data definition for an algorithm list, connection and disconnection routines, and a search routine for finding registered items. The module interface incorporated into alp serves the purpose of providing an ioctl interface, so that users
can find out what algorithms are registered [see alpq(l}].
The programmer of a function for use with alp provides a simple module with a
simple specified interface. The module must have an initialization routine
(xxxinit) which is called at system startup time to register itself with alp, an open
routine, and an interface routine (which actually implements the algOrithm).
The registry method of dynamically building the list of available functions obviates
the need for recompiling modules or otherwise updating a list or reconfiguring
other parts of the system to accommodate additions or deletions. To install a new
function module, one merely links it with the kernel in whatever manner is standard for that system; there is no need for updating or re-configuring any other parts
of the kernel (including alp itself). The remainder of this discussion concerns the
in-kernel operation and use of the module.
Calling Sequence
An algorithm is called from the pool by first requesting a connection via the alp
connection interface. The alp module returns the function address of an interface
routine, and fills in a unique identifier (id) for the connection. The returned function address is NULL on failure (and id is undefined). This is a sample of making a
connection to a function managed by alp:

375

alp (7)
unsigned char *name;
caddr_t id;
mblk_t *(*func)();
mblk_t *(*alp_con(»();

/*
/*
/*
/*

algorithm name */
unique id */
func returns ptr to mblk_t */
returns pointer to mblk_t */

if (func = alp_con(name, (caddr_t) &id»
regular processing;
else
error processing;
Once the connection has been made, the interface routine can be called directly by
the connecting module to process messages:
mblk_t *inp, *outp;
mblk_t *(*func)();
outp = (*func)(mp, id);
mp = NULL;
/* mp cannot be re-used! */
i f (outp)
regular processing;
If the interface routine processed the entire message, then outp is a valid pointer to
the algorithm's output message. If, however, the routine needs more information,
or is buffering something, outp will be a null pointer. In either case, the original
message (mp) may not be subsequently accessed by the caller. The interface routine
takes charge of the message mp, and may free it or otherwise dispose of it (it may
even return the same message). The caller may pass a null message pointer to an
interface routine to cause a flush of any data being held by the routine; this is useful
for end-of-file conditions to insure that all data have been passed through. (Interface routines must thus recognize a null message pointer and deal with it.)
Synchronization between input and output messages is not guaranteed for all items
in the pool. If one message of input does not produce one message of output, this
fact should be documented for that particular module. Many multibyte code set
conversion algorithms, to cite one instance, buffer partial sequences, so that if a
multibyte character happens to be spread across more than one message, it may
take two or more output messages to complete translation; in this case, it is only
possible to synchronize when input message boundaries coincide with character
boundaries.
Building an Algorithm for the Pool

As mentioned, the modules managed by alp are implemented as simple
modules-not STREAMS modules-each with an initialization routine, an open routine, and a user-interface routine. The initialization routine is called when the system is booted and prior to nearly everything else that happens at boot-time. The
routine takes no arguments and its sole purpose is to register the algorithm with the
alp module, so that it may subsequently accessed. Any other required initialization
may also be performed at that time. A generic initialization routine for a module
called GEN, with prefix gen is as follows:

376

alp(7)
geninit()
{

mblk_t *genfunc(); 1* interface routine *1
int rval;
1* return value from registrar *1
rval = alp_register(genfunc, "name", "explanation");
if (rval) emn_err(CE_WARN, "warning message");
}

The registration routine, alp_register takes three arguments and returns zero if
successful. The arguments are (1) a pointer to the algorithm's entry point (in this
case, the function genfunc), (2) a pointer to its name, and (3) a pointer to a character string containing a brief explanation. The name should be limited to under 16
bytes, and the explanation to under 60 bytes, as shown in the following example.
Neither the name nor the explanation need include a newline.
i

= alp_register(sjisfunc,

"stou",
"Shift-JIS to UJIS converter");

It is possible for a single module to contain several different, related algorithms,

which can each be registered separately by a single init routine.

A module's open routine is called by alp_con when a connection is first requested
by a user (that is, a module that wishes to use it). The open routine takes two arguments. The first argument is an integer; if it is non-zero, the request is an open
request, and the second argument is unused. The function should allocate a unique
identifier and return it as a generic address pointer. If the first argument is zero, the
request is a close request, and the second argument is the unique identifier that was
returned by a previous open request, indicating which of (potentially several) connections is to be closed. The routine does any necessary clean-up and closes the
connection; thereafter, any normal interface requests on that identifier will fail. This
use of unique identifiers allows these modules to keep state information relating to
each open connection; no format is imposed upon the unique identifier, so it may
contain any arbitrary type of information, equivalent in size to a core address; alp
and most callers will treat it as being of type caddr_t, in a manner similar to the
private data held by each instantiation of a STREAMS module.
A skeleton for the gen module's open routine is:

genopen(arg, id)
int arg;
caddr_t id;
{

i f (arg){

open processing;
return ( unique-id );
}

close processing for id;
return(O);

alp(7)
Once a connection has been made, users may proceed as in the example in the previous section. When the connection is to be closed (for example, the connecting
module is being popped), a call is made to alp_discon, passing the unique id and
the name:
caddr_t id;
char *name;
mblk_t *alp_discon (), *mp;
mp = alp_discon(name, id);

(mp)

process "left-over" data;
If the disconnect request returns a valid message pointer (mp) then there was unprocessed or partially processed data left in an internal buffer, and it should be dealt
with by the caller (for example, by flushing it or sending it to the neighboring
module).
The ioctl and Query Interfaces

A kernel-level query interface is provided in addition to the query interface supported by the alpq command. The routine alp_query takes a single argument, a
pointer to a name. If the name matches a registered function, alp_query returns a
pointer to the function's explanation string, otherwise it returns a null pointer. A
calling example is:
unsigned char *alp_query(), *name, *expl;
if (expl = alp_query(name»

regular processing;
else

error processing;
The ioctl interface provides calls for querying registered functions (for which the
explanation discussed above is necessary); this is supported by the alpq command,
which may be used whenever user-level programs need the associated information.
Uses

The alp module can be used to replace various kernel-resident code set conversion
functions in international or multi-language environments. The KBD subsystem
(which supplies code set conversion and keyboard mapping) supports the use of
alp algorithms as processing elements.
Since state information may be maintained, functions may also implement processing on larger or more structured data elements, such as transaction records and network packets. Currently, STREAMS CPU priority is assumed by alp or should be set
individually by interface and open routines.
EXAMPLES
/*

* This is a SAMPLE module that registers with ALP and
* performs a one-message delay.
*/
#include
#include

378

alp(7)
#include
#include
#include
static mblk_t *dely();
caddr_t delyopen();
/*
* OUr state structure.
*/
struct dstruct {
caddr_t d_unique;
mblk_t *d_1II>;
};

Keeps its own address and a pointer.

/*
* The name is "Dely". It has an open routine "delyopen"
* and an interface "dely".
*/
static struct algo delyalgo
{

0, (queue_t *) 0, (queue_t *) 0, dely, delyopen,
(unsigned char *) "Dely",
(unsigned char *) "One Message Delay Buffer",
(struct algo *) 0
};
/*
* This is the sysinit routine, called when the system is
* being brought up. It registers "Dely" with ALP.
*/
delyinit()
{

if (alp_register(&delyalgo»
/* then register with ALP */
printf("DELY: register failed\n");
}

/*
* This is the interface routine itself.
* Holds onto "mp" and returns whatever it had before.
*/
static mblk_t *
delY(1II>, id)
mblk_t *mp;
caddr_t id;
{

379

alp(7)
rp = d->d_IIP;
d->d_IIP = lIP;
return(rp);

/* return the previous message */

}

/*
* The open (and. close) routine. Use kmeliLalloc() to get
* a private structure for saving state info.
*/
caddr_t
delyopen(arg, id)
int arg;
/* 1 = open, 0 = close */
caddr_t id; /* ignored on open; unique id on close * /

register struct dstruct *d;
register mblk_t *rp;
if (! arg) {
/* close processing */
d = (struct dstruct *) id;
d->d_unique = (caddr_t) -1;
rp = d->d_IIP;
krnem_free(d, sizeof(struct dstruct»;
return ( (caddr_t) rp);
}

/* otherwise, open processing */
d = (struct dstruct *) kmem_zalloc(sizeof(struct dstruct),
IQCNOSLEEP) ;

d->d_unique = (caddr_t) &:d;
return ( (caddr_t) d);
}

SEE ALSO

alpq(l), kbd,(7)

380

ARP(7}
NAME

ARP - Address Resolution Protocol
SYNOPSIS

#include
#include
#include
s

socket (AF_INET, SOCK_DGRAM, 0);

open ("/dev/arp", O_RDWR);

DESCRIPTION

ARP is a protocol used to map dynamically between Internet Protocol (IP) and
lOMb/s Ethernet addresses. It is used by all the lOMb/s Ethernet datalink providers (interface drivers). It is not specific to the Internet Protocol or to the lOMb/s
Ethernet, but this implementation currently supports only that combination. The
STREAMS device /dev/arp is not a Transport Level Interface (TLI) transport provider and may not be used with the TLI interface.
ARP caches IP-to-Ethernet address mappings. When an interface requests a mapping for an address not in the cache, ARP queues the message that 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
message is 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 facilitate communications with systems which do not use ARP, ioctl requests
are provided to enter and delete entries in the Ip-to-Ethernet tables.
USAGE

#include
#include
#include
#include

struct arpreq arpreq;
ioctl (s, SIOCSARP, (caddr_t) &arpreq) ;
ioctl (s, SIOCGARP, (caddr_t) &arpreq) ;
ioctl(s, SIOCDARP, (caddr_t)&arpreq);

Each ioctl request takes the same structure as an argument. SIOCSARP sets an ARP
entry, SIOCGARP gets an ARP entry, and SIOCDARP deletes an ARP entry. These
ioctl requests may be applied to any Internet family socket descriptor s, or to a
descriptor for the ARP device, but only by the privileged user. The arpreq structure contains:
/*

* ARP ioctl request
*/
struct arpreq {
struct sockaddr arp~a;
struct sockaddr arp_ha;
int
arp_flags;

/* protocol address */
/* hardware address */
/* flags */

381

ARP(7)
};

arp_flags field values */
#define ATF_lNUSE
OxOl
#define ATF_COM
Ox2
#define ATF_PERM
Ox4
#define ATF_PUBL
Ox8
#define ATF_USETRAILERS OxlO
/*

entry in use */
completed entry (arp_ha valid) */
permanent entry */
publish (respond for other host) */
/* send trailer packets to host */

/*
/*
/*
/*

The address family for the arp-pa sockaddr must be AF_INET; for the arp_ha
sockaddr it must be AF_UNSPEC. The only flag bits that may be written are
ATF_PERM, ATF_PUBL and ATF _USETRAILERS. ATF_PERM makes the entry permanent if the ioctl request succeeds. The peculiar nature of the ARP tables may
cause the ioctl request to fail if too many permanent IP addresses hash 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 host to act as an ARP
server, which may be useful in convincing an ARP-only machine to talk to a nonARP machine.
ARP is also used to negotiate the use of trailer IP encapsulations; trailers are an alternate encapsulation used to allow efficient packet alignment for large packets
despite variable-sized headers. Hosts that wish to receive trailer encapsulations so
indicate by sending gratuitous ARP translation replies along with replies to IP
requests; they are also sent in reply to IP translation replies. The negotiation is thus
fully symmetrical, in that either or both hosts may request trailers. The
ATF_USETRAILERS flag is used to record the receipt of such a reply, and enables the
transmission of trailer packets to that host.
ARP watches passively for hosts impersonating the local host (that is, a host which
responds to an ARP mapping request for the local host's address).
SEE ALSO

arp(lM), if(7), ifconfig(lM), inet(7)
Plummer, Dave, " An Ethernet Address Resolution Protocol -or- Converting Network Protocol Addresses to 48.bit Ethernet Addresses for Transmission on Ethernet Hardware ," RFC
826, Network Information Center, SRI International, Menlo Park, Calif., November
1982
Leffler, Sam, and Michael Karels, "Trailer Encapsulations," RFC 893, Network Information Center, SRI International, Menlo Park, Calif., April 1984

382

asyc(7)
NAME

asyc - asynchronous serial port
DESCRIPTION

The asyc driver supports both the system board serial port and an additional serial
adapter simultaneously. Dp to two serial ports are supported. If an adapter for a
port is not installed, an attempt to open it will fail. Depending on your system processor type and DART, the port can be programmed for speed (50-38400 baud),
character length, and parity. Output speed is always the same as input speed. The
port behaves as described in termio (7).
The asynchronous port is a character-at-a-time device for both input and output.
This characteristic both limits the bandwidth that can be achieved over a line, and
increases the interrupt loading on the central processor. File transfer programs
such as uucp(lC) may be able to function well at speeds greater than 9600 baud,
depending on your system processor type and DART.
The baud rates of the serial adapter programmable baud-rate generator do not
correspond exactly with system baud rates. In particular, setting BO will cause a
disconnect, setting EXTA will set 19200 baud, and setting EXTB will set 38400 baud.
It is not possible to directly set 2000, 3600, or 7200 baud. The asynchronous ports
driver supports line signal (hardware) flow control when the device node
/dev/ttyO?h is used. The /dev/ttyO?s ports are software flow control nodes as
are the /dev/ttyO? nodes.
FILES

/dev/tty* /dev/term/*
SEE ALSO

signal(2), termio(7)

383

clone(7)
NAME

clone - open any major/minor device pair on a STREAMS driver
DESCRIPTION
clone is a STREAMS software driver that finds and opens an unused major/minor
device on another STREAMS driver. The major device number passed to clone during open corresponds to the clone driver and the minor device number

corresponds to the target driver. Each open results in a separate stream to a previously unused major/minor device.
The clone driver consists solely of an open function. This open function performs
all of the necessary work so that subsequent system calls [including close(2)]
require no further involvement of clone.
clone will generate an ENXIO error, without opening the device, if the major / minor
device number provided does not correspond to a valid major/minor device, or if
the driver indicated is not a STREAMS driver.
NOTICES

Multiple opens of the same major/minor device cannot be done through the clone
interface. Executing stat(2) on the file system node for a cloned device yields a different result from executing fstat using a file descriptor obtained from opening
the node.
REFERENCES

log(7)

384

connld (7)
NAME

connld -line discipline for unique stream connections
DESCRIPTION

connld is a STREAMS-based module that provides unique connections between
server and client processes. It can only be pushed [see streamio(7)] onto one end
of a STREAMS-based pipe that may subsequently be attached to a name in the file
system name space. After the pipe end is attached, a new pipe is created internally
when an originating process attempts to open(2) or creat(2) the file system name.
A file descriptor for one end of the new pipe is packaged into a message identical to
that for the ioctl I_SENDFD [see streamio(7)] and is transmitted along the stream
to the server process on the other end. The originating process is blocked until the
server responds.

The server responds to the I_SENDFD request by accepting the file descriptor
through the I_RECVFD ioctl message. When this happens, the file descriptor
associated with the other end of the new pipe is transmitted to the originating process as the file descriptor returned from open(2) or creat(2).
If the server does not respond to the I_SENDFD request, the stream that the connld
module is pushed on becomes uni-directional because the server will not be able to
retrieve any data off the stream until the I_RECVFD request is issued. If the server
process exits before issuing the I_RECVFD request, the open(2) or the creat(2) system calls will fail and return -1 to the originating process.
When the connld module is pushed onto a pipe, messages going back and forth
through the pipe are ignored by connld.
On success, an open of connld returns O. On failure, ermo is set to the following
values:
EINVAL

EINVAL
EPIPE
ENOMEM

ENXIO
EAGAIN

ENFILE

A stream onto which connld is being pushed is not a pipe or the
pipe does not have a write queue pointer pointing to a stream head
read queue.
The other end of the pipe onto which connld is being pushed is
linked under a multiplexor.
connld is being pushed onto a pipe end whose other end is no
longer there.
An internal pipe could not be created.
An M_HANGUP message is at the stream head of the pipe onto which
connld is being pushed.
Internal data structures could not be allocated.
A file table entry could not be allocated.

SEE ALSO

streamio(7)

385

console (7)
NAME

console - STREAMS-based console interface
DESCRIPTION

The file / dev/ console is the system console and refers to an asynchronous serial
data line originating from the system board.
The file /dev/contty refers to a second asynchronous serial data line originating
from the system board.
Both /dev/console and /dev/contty access the STREAMS-based console driver,
which when used in conjunction with the STREAMS line discipline module ldterm,
supports the termio(7) and termios(2) processing.
FILES

/dev/console
/dev/contty
SEE ALSO

crash(lM), ldterm(7), termio(7), termios(2)

386

cram (7)
NAME

cram - CMOS RAM interface
DESCRIPTION

The cram driver provides an interface to the 64 bytes of battery backed-up RAM.
This memory contains information such as diagnostics and configuration information.
ioetl Calls
CMOSREAD

This call is used to read the contents of one of the CMOS RAM locations.
The argument to the ioctl is the address of a buffer of two unsigned characters, the first of which is the address to be read. The ioctl will fill in the
second byte with the data. An address less than 0 or greater than 63 will
result in an error, with errno set to ENXIO.
CMOSWRITE

This call is used to write a value into one of the CMOS RAM locations. The
argument to the ioctl is the address of a buffer of two unsigned characters,
the first of which is the address and the second of which is the value to write
at that address. An address less than 0 or greater than 63 will result in an
error, with errno set to ENXIO. Note that only the super-user may open the
CMOS RAM device for writing, and that the CMOSWRITE ioctl will fail for
any other than the super-user.
Files
Idev/cram

387

DCD(7)
NAME

DCD - Direct-Coupled Disk host adapter Subsystem
DESCRIPTION

The DCD subsystem consists of at least one DCD Host Controller card which has at
least one logical unit attached to it.
The DCD subsystem adds support for non-SCSI devices under SDI for use with
related target drivers. This subsystem is accessed indirectly by opening an
appropriate target driver to access a target device that is on a DCD controller.
It is also possible to access this subsystem via the pass-through driver. To find the
appropriate device to use, while the device is being accessed through the target
driver, use the B_GETDEV ioctl to get the major and minor numbers of the passthough node. This node may either be created and/ or open for use.
There are four groups of ioctl(2) commands supported by DCD. The first group
contains the ioctl commands used by the DCD driver itself.
SDI_SEND

Used to send a pass through command to a target controller bypassing the associated target driver.
Used to reset the bus.

For a 80386-based computer, used to determine the Driver
Interface Version supported by the driver. It returns the
structure ver_no defined in sdi .h.
The second group is used by the driver and all target drivers that use the SCSI
Driver Interface protocol to communicate with their associated target controllers.
B_GETTYPE
Return the bus name (DCD) and device driver name of a
specific device.
The third group should be used by all the target drivers that use the SCSI Driver
Interface protocol to communicate with their associated target controllers. This
ioctl is not supported by the DCD driver.
Return the pass through major and minor numbers to the
calling utility to allow creation of a pass through the special
device file.
The fourth group should be used to get and set device geometry. These return or
accept the structure dsk~eom defined in sdi . h.
HA_GETPARMS
Return Host adapters idea of the device geometry. This is
what the system uses during the boot sequence. This is
used by certain target drivers.
HA_SETPARMS
Set the Host adapters idea of the device geometry. Note
that some Host adapters do not support this ioctl and
will result in an error.
HA_GETPPARMS Return the actual device geometry. This is the actual as
opposed to virtual device geometry.

388

DCD(7)
The DCD driver has a halt routine that is executed during shutdown, which allows
the controller enough time to flush the disk cache (if present) to disk. Although two
seconds are allowed for this flush, the actual timeout value is an external variable in
the DCD space.c file. You can modify this variable if a specific controller needs
more time to clear the cache.
Files
/usr/include/sys/sdi.h
/usr/include/sys/sdi_edt.h

REFERENCES
ioctl(2)

389

display (7)
NAME

display - system console display
SYNOPSIS

#include
#include
#include
DESCRIPTION

The system console (and user's terminal) is composed of two separate pieces: the
keyboard [see keyboard (7)] and the display. Because of their complexity, and
because there are three possible display interfaces (monochrome, color graphics,
and enhanced graphics adapters), they are discussed in separate manual entries.
The display normally consists of 25 lines of 80 columns each; 40-column lines are
also supported by the color/graphics adapter, and 43 lines of 80-columns each are
supported by the enhanced graphics adapter. When characters are written to the
console or one of its virtual screens (ldev/console or /dev/vtxx), the output
depends on the specific characters. All characters written to /dev/console are first
processed by the terminal interface [see tennio (7)]. For example, mapping newline characters to carriage return plus new-line, and expanding tabs to spaces, will
be done before the follOWing processing:
x

Where x is not one of the following, displays x.

BEL

Generates a bell (audible tone, no modulation).

Places the cursor at column 1 of the current line.

LF, VT

Places the cursor at the same column of the next line (scrolls if the the
current line is line 25).

Clears the screen and places the cursor at line 1, column 1.

If the cursor is not at column 1, it is moved to the left one position on
the same line. If the cursor is at column 1 but not line 1, it is moved to
column 79 of the previous line. Finally, if the cursor is at column 1,
line 1, it is not moved.

The display can be controlled by using specific sequences of characters that are
ANSI X3.64 escape sequences preceded by the ASCII character ESC. The escape
sequences, which work on either the monochrome, color graphics, or enhanced
graphics adapter, are the following:
ESC

ESC Q

Clears the screen and places the cursor at line 1, column 1.

n 'string'
Defines the function key n with string. The string delimiter ' may be
any character not in string. Function keys are numbered 0 through 11
(Fl = 0, F2 = 1, and so on.)

ESC [ n@
ESC [

390

Insert character-inserts n blanks at the current cursor position.
Horizontal Position Absolute-moves active position to column given
byn.

display (7)
ESC [ nA
ESC[na

Cursor up-moves the cursor up n lines (default: n=l).
Horizontal Position Relative-moves active position n characters to
the right (default: n=l).

ESC [ nB
ESC[nC
ESC[nc

Cursor down-moves the cursor down n lines (default: n=l).
Cursor right-moves the cursor right n columns (default: n=l).
Set Cursor Type-where n is 0 (underline cursor), l(blockcursor), or
2(no cursor). 0 is the default value for n.
Cursor left-moves the cursor left n columns (default: n=l).

ESC[nD

ESC[nd
ESC [ nE
ESC [ n e
ESC[nF
ESC[nG

Vertical Position Absolute-moves active position to line given by n.
Cursor next line-moves the cursor to column 1 of the next line, then
down n-llines (default: n=l).
Vertical Position Relative-moves the active position down n lines
(default: n=l).
Cursor previous line-moves the cursor to column 1 of the current
line, then up n lines (default: n=l).
Cursor horizontal position-moves the cursor to column n of the
current line (default: n=l).

ESC [ n ; m H Position cursor-moves the cursor to column m of line n (default: n=l,
m=l).

ESC [ n; m f Position cursor-moves the cursor to column m of line n (default: n=l,
m=l).

ESC [ n J

ESC[nK

Erase window--erases from the current cursor position to the end of
the window if n=O, from the beginning of the window to the current
cursor position if n=l, and the entire window if n=2 (default: n=O).
Erase line--erases from the current cursor position to the end of the
line if n=O, from the beginning of the line to the current cursor position if n=l, and the entire line if n=2 (default: n=O).

ESC [ n L
ESC [ nM

Insert line-inserts n lines at the current cursor position (default: n=l).
Delete line-deletes n lines starting at the current cursor position
(default: n=l).

ESC [ n P

Delete character-deletes n characters from a line starting at the
current cursor position (default: n=l).
Scroll up-scrolls the characters in the current window up n lines.
The bottom n lines are cleared to blanks (default: n=l).

ESC [ n S
ESC[nT
ESC[nX

Scroll down-scrolls the characters in the current window down n
lines. The top n lines are cleared to blanks (default: n=l).
Erase character-erases n character positions starting at the current
cursor position (default: n=l).

391

display (7)
ESC [ n Z
ESC [ 2 h
ESC [ 2 i
ESC [ 2 1

Cursor Backward Tabulation-moves active position back n tab stops.
Locks the keyboard and ignores keyboard input until unlocked. Characters are not saved.
Sends the screen to the host. The current screen display is sent to the
application.
Unlocks the keyboard. Re-enables keyboard input.

ESC [ Ps ; Ps; m

Character attributes-each Ps is a value in the table below; multiple
characters are separated by semicolons. These parameters apply to
successive characters being displayed, in an additive way (for example, both bold and underscoring can be selected). Only the parameters through 7 apply to the monochrome adapter; all parameters apply
to the color or graphics adapter and the enhanced graphics adapter.
(Default: Ps=O).
Ps

Meaning

all attributes off (normal display)
(white foreground with black background)
bold intensity
underscore on
(white foreground with red background on color)
blink on
VGA only: if blink (5) is on, turn blink off and background color to its light equivalent (that is, brown to
yellow).
reverse video
black
(gray)
foreground
red
(light red)
foreground
green
(light green)
foreground
brown
(yellow)
foreground
blue
(light blue)
foreground
magenta
(light magenta)
foreground
cyan
(light cyan)
foreground
white
(bright white)
foreground
black
(gray)
background
red
(light red)
background
green
(light green)
background
brown
(yellow)
background
blue
(light blue)
background
magenta
(light magenta)
background
cyan
(light cyan)
background
white
(bright white)
background

1
4
5
6
7
30
31
32
33
34
35
36
37
40
41
42
43
44
45
46
47

Note that for character attributes 30-37, the color selected for foreground will depend on whether the bold intensity attribute (1) is
currently on. If not, the first color listed will result; otherwise the
second color listed will result.

392

display (7)
Similarly, for character attributes 40-47, the color selected for background will depend on whether the blink attribute (5) is currently on
and bright background (6) has been turned on. If blink is not turned
on or bright background has not been selected, the first listed color
will result. Otherwise, the second color listed will result.
8 m

ESC [

sets blank (non-display)

ESC [ 10

m selects the primary font

ESC [ 11

m selects the first alternate font; lets ASCII characters less than 32 be
displayed as ROM characters

ESC [ 12 m

selects a second alternate font; toggles high bit of extended ASCII
code before displaying as ROM characters

ESC [ 38 m

enables underline option; white foreground with white underscore
(see the NOTES section)

39 m disables underline option (see the NOTES section)

ESC [

The following non-ANSI X3.64 escape sequences are supplied:
cA
Sets overscan color.

ESC [=

ESc[=p;dB

Sets bell parameters (where p is the pitch in Hz and d is the duration
in milliseconds)
ESC [=

s; e C Sets cursor parameters (where s is the starting and e is the ending
scanlines of the cursor).

ESC [=

Enables/ disables intensity of background color (where x is 0 for
enable and 1 for disable).

ESC [=

Sets/ clears blink versus bold background (where x is 0 for set and 1
for clear).

ESC [= C F

Sets normal foreground color. See GIO_ATTR for the valid values for c.

ESC [=

Sets normal background color. See
c.

GIO_ATTR

for the valid values for

ESC [=

Displays graphic character n.

ESC [=

Sets reverse foreground color. See GIO_ATTR for the valid values for c.

ESC [=

Sets reverse background color. See
c.

GIO_ATTR

for the valid values for

ESC [= C J

Sets graphic foreground color. See
c.

GIO_ATTR

for the valid values for

ESC[= C K

Sets graphic background color. See
c.

GIO_ATTR

for the valid values for

ESC [

ESC 7

Makes virtual terminal number n active.
Saves cursor position.

393

display (7)
ESC 8
ESC [ 0 k
ESC [ 1 k

Restores cursor position to saved value.
Disables the key-click feature (the default).
Enables the key-click feature. A tone is produced for each key press.

ioetl Calls

The following ioctl calls may be used to change the display used for the video
monitor. If the virtual terminal has not been put in process mode (see the
VT_SETMODE ioctl), setting the display mode to a non-text mode will turn off VI
switching. VI switches will be re-enabled after the display mode has been reset to a
text mode.
Note: All the following ioctls are performed on either a file descriptor to the virtual
terminals or to the special file /dev/video. ioctls to /dev/video are indicated
with an asterisk (*). For the ioctls to /dev/video to work, the controlling tty for
the process must be the virtual terminal on which the operation is to be performed.
If the tty is not a virtual terminat the return value will be -1 and ermo will be set
toEINVAL.
SWAPMONO (*)

This call selects the monochrome adapter as the output device for the
system console.
SWAPCGA (*) This call selects the color/graphics adapter as the output device for
the system console.
SWAPEGA (*) This call selects the enhanced graphics adapter as the output device
for the system console.
This call selects the video graphics array as the output device for the
system console.
The following ioctl call may be used to obtain more information about the display
adapter currently attached to the video monitor:
SWAPVGA (*)

CONS_CURRENT (*)

This call returns the display adapter type currently attached to the
video monitor. The return value can be one of: MONO, eGA, or EGA.
The following ioctl calls may be used to switch display modes on the various
video adapters:
SW_B40x25 (*)

This call selects 40x25 (40 columns by 25 rows) black and white text
display mode. It is valid only for eGA and EGA devices.
SW_C40x25 (*)

This call selects 40x25 (40 columns by 25 rows) color text display
mode. It is valid only for eGA and EGA devices.
SW_B80x25 (*)

This call selects 80x25 (80 columns by 25 rows) black and white text
display mode. It is valid only for eGA and EGA devices.

394

display (7)
SW_CBOx25 (*)

This call selects 80x25 (80 columns by 25 rows) color text display
mode. It is valid only for eGA and EGA devices.
SW_BG320 (*)

This call selects 320x200 black and white graphics display mode. It is
valid only for eGA and EGA devices.
SW_CG320 (*)

This call selects 320x200 color graphics display mode. It is valid only
for eGA and EGA devices.
SW_BG640 (*)

This call selects 640x200 black and white graphics display mode. It is
valid only for eGA and EGA devices.
SW_CG320_D (*)

This call selects EGA support for 320x200 graphics display mode
(EGA mode D). It is valid only for EGA devices.
SW_CG640_E (*)

This call selects EGA support for 640x200 graphics display mode
(EGA mode E). It is valid only for EGA devices.
SW_EGAMONOAPA (*)

This call selects EGA support for 640x350 graphics display mode
(EGA mode F). It is valid only for EGA devices.
SW_ENH_MONOAPA2 (*)

This call selects EGA support for 640x350 graphics display mode with
extended memory (EGA mode F*). It is valid only for EGA devices.
SW_CG640x350 (*)

This call selects EGA support for 640x350 graphics display mode
(EGA mode 10). It is valid only for EGA devices.
SW_ENH_CG640 (*)

This call selects EGA support for 640x350 graphics display mode with
extended memory (EGA mode 16). It is valid only for EGA devices.
SW_EGAMONOBOx25 (*)

This call selects EGA monochrome text display mode (EGA mode 7),
which emulates support provided by the monochrome adapter. It is
valid only for EGA devices.
SW_ENHB40x25 (*)

This call selects enhanced 40x25 black and white text display mode. It
is valid only for EGA devices.
SW_ENHC40x25 (*)

This call selects enhanced 40x25 color text display mode. It is valid
only for EGA devices.
SW_ENHBBOx25 (*)

This call selects enhanced 80x25 black and white display mode. It is
valid only for EGA devices.

395

display (7)
SW_ENHC80x25 (*)

This call selects enhanced 80x25 color text display mode. It is valid
only for EGA devices.
SW_ENHB80x43 (*)

This call selects enhanced 80x43 black and white text display mode. It
is valid only for EGA devices.
SW_ENHC80x43 (*)

This call selects enhanced 80x43 color text display mode. It is valid
only for EGA devices.
SW_MCAMODE (*)

This call reinitializes the monochrome adapter. It is valid only for
monochrome adapters.
SW_ATT640 (*)

This call selects 640x400 16 color mode, when an AT&T Super-Vu
video controller is attached.
Switching to an invalid display mode for a display device will result in an error.
The following ioctls may be used to obtain information about the current display
modes:
CONS_GET (*)

This call returns the current display mode setting for whatever display
adapter is being used. Possible return values include:
M_B40x25 (0), black and white 40 columns. CGA and EGA only.
M_C40x25 (1), color 40 columns. CGA and EGA only.
M_B80x25 (2), black and white 80 columns. CGA and EGA only.
M_C80x25 (3), color 80 columns. CGA and EGA only.
M_BG320 (4), black and white graphics 320 by 200. CGA and EGA
only.
M_CG320 (5), color graphics 320 by 200. CGA and EGA only.
M_BG640 (6), black and white graphics 640 by 200 high-resolution.
CGA and EGA only.
M_EGAMON080x25 (7), EGA-mono 80 by 25. EGA only.
M_CG320_D (13), EGA mode D.
M_CG640_E (14), EGA mode E.
M_EFAMONOAPA (15), EGA mode F.
M_CG640x350 (16), EGA mode 10.
M_ENHMONOAPA2 (17), EGA mode F with extended memory.
M_ENH_CG640 (18), EGA mode 16.

396

display (7)
M_ENH_B40x25 (19), EGA enhanced black and white 40 columns.
M _ENH_C40x25 (20), EGA enhanced color 40 columns.
M _ENH_B80x25 (21), EGA enhanced black and white 80 columns.
M _ENH_C80x25 (22), EGA enhanced color 80 columns.
M _ENH_B80x43 (Ox70), EGA black and white 80 by 43.
M _ENH_C80x43 (Ox71), EGA color 80 by 43.
M _MCA_MODE (Oxff), monochrome adapter mode.
MCA_GET

(*) This call returns the current display mode setting of the monochrome

adapter. See CONS_GET for a list of return values. If the monochrome
adapter is not installed, the call will fail and ermo will be set to 22
(EINVAL).
CGA_GET

(*) This

call returns the current display mode setting of the
color/graphics adapter. See CONS_GET for a list of return values. If
the color graphics adapter is not installed, the call will fail and ermo
will be set to 22 (EINVAL).

EGA_GET

(*) This call returns the current display mode setting of the enhanced
graphics adapter. See CONS_GET for a list of return values. If the
enhanced graphics adapter is not installed, the call will fail and ermo

will be set to 22 (EINVAL).
The following ioctl calls may be used to map the video adapter's memory into the
user's data space.
MAPCONS

(*) This call maps the display memory of the adapter currently being

used into the user's data space.
MAPMONO

(*) This call maps the monochrome adapter's display memory into the

user's data space.
MAPCGA (*)

This call maps the color/graphics adapter's display memory into the
user's data space.

MAPEGA

(*)

This call maps the enhanced graphics adapter's display memory into
the user's data space.

MAPVGA

(*)

This call maps the video graphics array's display memory into the
user's data space.

You can use ioctl calls to input a byte from the graphics adapter port or to output
a byte to the graphics adapter port. The argument to the ioctl uses the port_io _arg
data structure:
struct port_io_arg {
};

The previous example shows that the port_io _arg structure points to an array of four
port_io_struc data structures. The port_io _struc has the following format:

397

display (7)
struc port_io_struc
char
dir;
ushort port;
char
data;
};

/*direction flag (in
/*port address*/
/*b¥te of data*/

VS.

out)*/

You can specify one, two, three, or four of the port_io_struc structures in the array
for one ioctl call. The value of dir can be either IN_aN_PORT (to specify a byte
being input from the graphics adapter port) or OUT_ON]ORT (to specify a byte
being output to the graphics adapter port). Port is an integer specifying the port
address of the desired graphics adapter port. Data is the byte of data being input or
output as specified by the call. If you are not using any of the port_io_struc structures, load the port with 0, and leave the unused structures at the end of the array.
Refer to your hardware manuals for port addresses and functions for the various
adapters.
The following ioctl calls may be used to input or output bytes on the graphics
adapter port:
MCAIO (*)
This call inputs or outputs a byte on the monochrome adapter port as
specified.
CGAIO (*)

This call inputs or outputs a byte on the color/graphics adapter port
as specified.

EGAIO (*)

This call inputs or outputs a byte on the enhanced graphics adapter
port as specified.

VGAIO (*)

This call inputs or outputs a byte on the video graphics array port as
specified.

To input a byte on any of the graphics adapter ports, load dir with IN_aN_PORT
and load port with the port address of the graphics adapter. The byte input from
the graphics adapter port will be returned in data.
To output a byte, load dir with OUT_aN_PORT, load port with the port address of
the graphics adapter, and load data with the byte you want to output to the graphics adapter port.
The following ioctls may be used with either the monochrome, color graphics, or
enhanced graphicS adapters:
GIO_FONT8x8 (*)

This call gets the current 8x8 font in use.
GIO_FONT8x14 (*)
This call gets the current 8x14 font in use.
GIO_FONT8x16 (*)
This call gets the current 8x16 font in use.
KDDISPTYPE (*)

This call returns display information to the user. The argument
expected is the buffer address of a structure of type kd_disparam into
which display information is returned to the user. The kd_disparam
structure is defined as follows:

398

display (7)
struct kd_disparam
long type;
/*display type*/
char *addr;
/*display memory address*/
ushort ioaddr[MKDIOADDR);
/*valid I/O addresses*/

Possible values for the type field include:
KD_MONO (Ox01), for the IBM monochrome display adapter.
KD HERCULES (Ox02), for the Hercules monochrome graphics
adapter.
KD _CGA (Ox03), for the IBM color graphics adapter.
KD_EGA (Ox04), for the IBM enhanced graphics adapter.
KIOCSOUND (*)

Start sound generation. Turn on sound. The "arg" is the frequency
desired. A frequency of 0 turns off the sound.
KDGETLED

Get keyboard LED status. The argument is a pointer to a character.
The character will be filled with a boolean combination of the following values:
LED SCR
LED-CAP
LED-NUM

KDSETLED

Ox01
Ox04
Ox02

( flag bit for scroll lock )
( flag bit for caps lock)
( flag bit for num lock)

Set keyboard LED status. The argument is a character whose value is
the boolean combination of the values listed under KDGETLED.

KDMKTONE (*)

Generate a fixed length tone. The argument is a 32 bit value, with the
lower 16 bits set to the frequency and the upper 16 bits set to the duration (in milliseconds).
KDGKBTYPE

Get keyboard type. The argument is a pointer to a character type.
The character will be returned with one of the following values:
KB _84
KB _101
KB OTHER

Ox01
Ox02
Ox03

( 84 key keyboard)
( 101 key keyboard)

KDADDIO (*)

Add I/O port address to list of valid video adaptor addresses. Argument is an unsigned short type that should contain a valid port
address for the installed video adaptor.
KDDELIO (*) Delete I/O port address from list of valid video adaptor addresses.

Argument is an unsigned short type that should contain a valid port
address for the installed video adaptor.
KDENABIO (*)

Enable in's and out's to video adaptor ports. No argument.

399

display (7)
lIDDISABIO (*)

Disable in's and out's to video adaptor ports. No argument.
KDQUEMODE (*)

Enable/Disable special queue mode. Queue mode is used by AT&T's
X-Windows software to establish a shared queue for access to keyboard and mouse event information. The argument is a pointer to a
structure "kd_quemode." If a NULL pointer is sent as an argument,
the queue will be closed and the mode disabled. The structure
"kd_quemode" is as follows:
struct kcUlUemode {
int
qsize; 1* desired # of elements in queue *1
int
signo; 1* signal number to send when queue

goes non-empty *1
void

char

*qaddr; 1* user virtual address of queue (set by
driver) *1

};

KDSBORDER (*)

Set screen color border in EGA text mode. The argument is of type
character. Each bit position corresponds to a color selection. From bit
position 0 to bit position 6, the color selections are respectively; blue,
green, red, secondary blue, secondary green, and secondary red. Setting the bit position to a logic one will select the desired color or
colors. See the NOTES section.
KDSETMODE (*)

Set console in text or graphics mode. The argument is of type integer,
which should contain one of the following values:
KD TEXT
OxOO
( sets console to text mode)
KD-GRAPHICS OxOl
( sets console in graphics mode)
If the mode is set to KD GRAPHICS and the Virtual Terminal is not in
process mode (see the VT_SETMODE ioctl), no virtual terminal
switches will be possible until the mode is reset to KD_TEXT,
KD_TEXTO, or KDJEXTl.

Note, the user is responsible for programming the color/graphics
adaptor registers for the appropriate graphical state.
KDGETMODE (*)

Get current mode of console. Returns integer argument containing
either lID_TEXT or KD_GRAPHICS as defined in the KDSETMODE ioctl
description.
KDMAPDISP (*)
Maps display memory into user process address space. Argument is a
pointer to structure type "kd_memloc." Structure definition is as
follows:

400

disp\ay(7)

char
char
long
long

*vaddr;
*physaddr;
length;
ioflg;

/*
/*
/*
/*

virtual address to map to */
physical address to map from */
size in bytes to map */
enable i/o addresses if set */

}

KDUNMAPDISP (*)

Unmap display memory from user process address space. No argument required.
KDVDCTYPE

This call returns VDC controller / display information.

PIO_FONT8x8 (*)

This call uses the user supplied 8x8 font.
PIO_FONT8x14 (*)

This call uses the user supplied 8x14 font.
PIO_FONT8x16 (*)

This call uses the user supplied 8x16 font.
VT_OPENQRY

Inquires if this virtual terminal is already open. Find an available virtual terminal. The argument is a pointer to a long. The long will be
filled with the number of the first available "VT" that no other process
has open or -1 if none is available.
VT_GETMODE (*)

Determine what mode the active virtual terminal is currently in, either
or VT_PROCESS. The argument to the ioctl is the address
of the following type of structure:

VT_AUTO

struct vt_mode {
char
mode;
char
waitv;
short relsig;
short acqsig;
short frsig;

/*
/*
/*
/*
/*

VT mode */
if set, hang on writes when not active */
signal to use for release request */
signal to use for display acquired */
not used set to 0 */

#defineVT_AUTOOxOO
#defineVT_PROCESS

/* automatic VT switching */
OxOl
/* process controls switching */

The "vt mode" structure will be filled in with the current value for
each field.
VT_GETSTATE (*)

The VT_GETSTATE ioctl returns global virtual terminal state information. It returns the active virtual terminal in the v active field, and the
number of active virtual terminals and a bit mask of the global state in
the v state field, where bit x is the state of vt x (1 indicates that the
virtual terminal is open).

401

display (7)
VT_SETMODE (*)
Set the virtual terminal mode (Auto or Proced). The argument is a
pointer to a "vt_mode" structure, as defined above.
VT_SENDSIG (*)
The VT_SENDSIG ioctl specifies a signal (in v_signal) to be sent to a
bit mask of virtual terminals (in v_state).
The data structure used by the VT_GETSTATE and VT_SENDSIG ioctls is:
struct vt_stat {
ushort v_active;
ushort v_signal;
ushort v_state;

/* active vt*/
/* signal to send (VT_SENDSIG) */
/* vt bit mask (VT_SENDSIG and

VT_GETSTATE)*/
};
and is defined in /usr/include/sys/vt.h.

VT_RELDISP (*)
Used to tell the virtual terminal manager that the display has or has not
been released by the process. A zero value indicates refusal to release the
display. A value of VT_ACKACQ indicates an acquisition of a device. EINVAL is returned if a non-zero value that is not equal to VT_ACKACQ is
received and the virtual terminal has not yet been acquired. Otherwise, the
virtual terminal will be released.
VT_ACTIVATE (*)
Makes the virtual terminal number specified in the argument the
active "VT." The "VT" manager will cause a switch to occur in the
same way as if a hotkey sequence had been typed at the keyboard. If
the specified "VT" is not open or does not exist, the call will fail and
errno will be set to ENXIO.
KIOCINFO This call tells the user what the device is.
GIO_SCRNMAP (*)
This call gets the screen mapping table from the kernel.
GIO_ATTR This call returns the current screen attribute. The bits are interpreted
as follows:
Bit 0 determines underlining for black and white monitors (l=underlining on).
Bits 0-2, for color monitors only, select the foreground color. The following list indicates what colors are selected by the given value:
The value 0 selects black.
The value 1 selects red.
The value 2 selects green.
The value 3 selects brown.
The value 4 selects blue.
The value 5 selects magenta.
The value 6 selects cyan.
The value 7 selects white.

402

display (7)
Bit 3 is the intensity bit ( l=blink on).
Bits 4-6, for color monitors only, select the background color. For a
list of colors and their values, see the list under foreground colors.
Bit 7 is the blink bit (l=blink on).
GIO_COLOR (*)

This call returns a non-zero value if the current display is a color
display, otherwise, it returns a zero.
PIO_SClmMAP

This call puts the screen mapping table in the kernel.
The screen mapping table maps extended ASCII (8-bit) characters to ROM characters. It is an array [256] of char (typedef scmmap_t) and is indexed by extended
ASCII values. The value of the elements of the array are the ROM character to
display.
FILES

/dev/console
/dev/vtOO-n
/dev/video
/usr/include/sys/kd.h
SEE ALSO

console(7), ioctl(2), keyboard(7), stty(l), termio(7)
NOTES

Although it is possible to write character sequences that set arbitrary bits on the
screen in any of the three graphics modes, this mode of operation is not currently
supported.
Monochrome adaptors support underscore option as the default. EGA and VGA
adaptors require the use of the ESC [38m and ESC [39m escape sequences to
enable/ disable the underscore option respectively. After the underscore option has
been enabled on a EGA or VGA adaptor by using the ESC [38m sequence and until
the underline option has been disabled by using the ESC [39m sequence, characters
that have blue foreground attributes will be displayed in cyan foreground and characters that have blue background attributes will be displayed in white background
attributes.
It is currently not possible to access the 6845 start address registers. Thus, it is
impossible to determine the beginning of the color monitor's screen memory.

The alternate/background color bit (bit 4) of the color select register does not
appear to affect background colors in alphanumeric modes.
KDSBORDER ioctl calls will not work with AT&T's Super-Vu enhanced
color/graphics video adaptor. It will however, work with the IBM EGA card and
other EGA compatible video adaptors.

The low-resolution graphics mode appears to be 80 across by 100 down.

403

dpt(7)
NAME

dpt - DPT PM2012 SCSI host adapter subsystem
DESCRIPTION

The dpt host adapter subsystem enables SCSI target drivers (such as sdOl, stOl,
and so on) to communicate on the SCSI bus with target controllers and logical units.
This driver implements the Portable Device Interface (PDI) for such PDI target
drivers.
It is also possible to access this subsystem directly usiflg the pass-through driver

interface. This allows you to issue sb control blocks directly to the target controller.
To find the appropriate device to use, while any device is being accessed through
the target driver (for example, sdOl), use the B_GETDEV loctl to get the major and
minor numbers of the pass-through node. This node may be created and opened
for pass-through use (SDI_SEND ioctl).

ioctl Calls
The following ioct1(2) commands are supported by dpt:
SDI_SEND
Sends a pass-through command (SCSI control block) to a target controller,
bypassing the associated target driver.
SDI_BRESET
Resets the SCSI bus.
B_REDT
Reads the extended Equipped Device Table (EDT) data structure that is
stored in the dpt driver's internal data structure.
B_GETTYPE
Returns the bus name (for example, SCSI) and device driver name of a
specific device.
NOTICES

The DPT SCSI adapter will not work reliably with the Emulex SCSI/ESDI bridge
controller (also known as the AT&T DCM/4E). In the future, a hardware or
software solution may be implemented.

Files
/usr/include/sys/dpt.h
/usr/lnclude/sys/scsl.h
/usr/include/sys/sdl.h
/usr/include/sys/sdl_edt.h
/etc/conf/pack.d/dpt/space.c
REFERENCES

adsc(7), loctl(2), mcis(7), scOl(7), sdOl(7), stOl(7), swOl(7), wd7000(7)

404

ee16(7)
NAME

ee16 - EtherExpress 16 Ethernet Adapter Driver
SYNOPSIS

#include
#include
#include
fd

= open

(n/dev/ee16_0 n , O_RDWR)

DESCRIPTION

The ee16 driver provides a data link interface to the EtherExpress 16 Ethernet
adapter from Intel. It is a STREAMS-based driver that is compatible with the Data
Link Provider Interface (DLPI) and Logical Link Interface (LLI) software interfaces.
It supports DL_ETHER and DL_CSMACD for MAC type, DL_CL_ETHER for service
mode, and DL_STYLE1 for provider style. The ee16 driver can operate as a cloned

or non-cloned device.
A process must issue a DL_BIND_REQ primitive to receive frames from the network.
The process must specify the dl_sap field of the dl_bind_r~t structure. The type
field of an incoming frame is compared to the dCsap value. If the values are equal,
it is placed on the STREAMS read queue of the process. A privileged process may
set the dl_sap field to PROMISCUOUS_SAP. The PROMISCUOUS_SAP matches all incoming frames.
A privileged process may also bind to a SAP already bound by another process. In
cases where a frame qualifies to be sent to more than one process, independent
copies of the frame will be made and placed on the STREAMS read queue of each
process.
Received frames are delivered in dl_unitdata_ind_t structures. The source and
destination address each contain a 6-byte Ethernet address, followed by a 2-byte
type value.
USAGE

ioetl Calls

The following ioctls are supported:
DLIOCGMIB

Returns the DL_mib_t structure, which contains the Management Information Base (MIB). The MIB holds the Ethernet statistics kept in the driver.
1*

* Ether statistics structure.
*1
typedef struct {
ulang_t
etherAlignErrors;
ulang_t
etherCRCerrors;
ulong_t
etherMissedPkts;
ulang_t
etherOverrunErrors;
ulang_t
etherUnderrunErrors;
ulang_t
etherCollisians;
ulang_t
etherAbortErrors;
ulong_t
etherCarrierLost;

1*
1*
1*
1*
1*
1*
1*
1*

Frame alignment errors *1
CRC erros *1
Packet overflow or missed inter *1
OVerrun errors *1
Underrun errors *1
Total collisions *1
Transmits aborted at interface *1
Carrier sense signal lost *1

405

ee16 (7)
ulong_t
ulong_t
ulong_t
ulong_t
ulong_t
ulong_t
ulong_t

etherReadqFull;
etherRcvResources;
etherDependentl;
etherDependent2;
etherDependent3;
etherDependent4;
etherDependent5 ;

STREAMS read queue full * /
Receive resource alloc faliure
Device dependent statistic */
Device dependent statistic */
Device dependent statistic */
/* Device dependent statistic */
/* Device dependent statistic */

/*
/*
/*
/*
/*

Interface statistics compatible with MIB II SNMP requirements.

typedef struct {
/* ranges between 1 and ifNumber */
int
if Index;
/* len of desc. following this struct */
int
ifDescrLen;
ifType;
/* type of interface */
int
int
/* datagram size that can be sent/rcv */
ifMtu;
ulong_t
/* estimate of bandwidth in bits PS */
i fSpeed;
uchar_t
ifPhyAddress[DL_MAC_ADDR_LEN1;/* Ethernet Address */
int
ifAdminStatus;
/* desired state of the interface */
int
ifOperStatus;
/* current state of the interface */
ulong_t
ifLastChange;
/* sysQpTime when state was entered */
ulong_t
ifInOctets;
/* octets received on interface */
ulong_t
ifInUcastPkts;
/* unicast packets delivered */
ulong_t
ifInNUcastPkts;
/* non-unicast packets delivered */
ulong_t
ifInDiscards;
/* good packets received but dropped */
ulong_t
ifInErrors;
/* packets received with errors */
ulong_t
ifInunknownProtos;
/* packets recv'd to unbound proto */
ulong_t
/* octets transmitted on interface */
ifOUtOctets;
ulong_t
ifOUtUcastPkts;
/* unicast packets transmited */
ulong_t
ifOUtNUcastPkts;
/* non-unicast packets transmited */
ulong_t
ifOUtDiscards;
/* good outbound packets dropped * /
ulong_t
ifOUtErrors;
/* number of transmit errors */
ulong_t
ifOUtQlen;
/* length of output queue * /
DL_etherstat_t ifSpecific;
/* ethernet specific stats */
DL_mib_t;

The values in the MIB are compatible with those needed by the SNMP
protocol.
The ifDescrLen field indicates the length of the null terminated deSCription
string that immediately follows the DL_mib_t structure.
There are three fields in the MIB that are specific to the ee16 driver. The
ifSpecific.etherDependent1 field tracks the number of times the transceiver
failed to transmit a collision signal after transmission of a packet. The
ifSpecific.etherDependent2 field contains the number of collisions that
occurred after a slot time (out of window collisions). The
ifSpecific.etherDependent3 field tracks the number of times a transmit
interrupt timeout condition occurred.

406

ee16(7)
DLIOCSMIG

Allows a privileged process to initialize the values in the MIB (that is, the
A process cannot use this ioctl to change the
ifPhyAddress, the ifDeserLen, or the text of the description fields.

DL_mib_t structure).
DLIOCGENADDR

Returns the Ethernet address in network order.
DLIOCGLPCFLG

Returns the state of the local packet copy flag in the ioe Jval of the iocblk
structure. The local copy flag determines if packets looped back by the
driver should also be sent to the network. A non-zero value indicates that
frames should also be be sent to the network after being looped back. The
default value of this flag is zero.
DLIOCSLPCFLG

Allows a privileged process to set the local packet copy flag, causing all
packets looped back by the driver to be sent to the network as well.
DLIOCGPROMISC

Returns the value of the promiscuous flag in the ioe Jval of the iocblk structure. A non-zero value indicates that the Ethernet interface will receive all
frames on the network. The default value of this flag is zero.
DLIOCSPROMISC

Allows a privileged process to toggle the current state of the promiscuous
flag. When the flag is set, the driver captures all frames from the network.
Processes that are bound to a promiscuous SAP, or to a SAP that matches
the type field of the received frame, receive a copy of the frame.
DLIOCGETMULTI

Returns a list of multicast addresses (if it exists).
DLIOCADDMULTI

Allows a privileged process to add a new multicast address and enable its
reception. A 6-byte buffer pointing to the multicast address must be passed
as the parameter.
DLIOCDELMULTI

Allows a privileged process to delete a multicast address by passing a 6-byte
multicast address as the parameter.
Installation
You must select the interrupt level and the base I/O address for the EtherExpress
card at package installation time. Refer to the User's Guide that came with your
adaptor for more information.

You can also set these parameters in the /etc/conf/sdevice.d/ee16 file.
If there is one EtherExpress 16 card in the system, it is configured automatically to
the parameters specified at installation each time the system is initialized. During
initialization, the system determines the current base I/O address of the card, and
then programs the card to its new configuration. If the system doesn't find an EtherExpress 16 card, it displays an error message. Because of the way the system
searches for an EtherExpress 16 card, reads to I/O addresses without EtherExpress
16 cards may occur during the automatic configuration process.
407

ee16(7)
Automatic configuration occurs only when one EtherExpress 16 card is installed in
the system. If you want to install more than one card, use the following procedure:
When you install the ee16 package, specify the interrupt level and the base
I/O address for one EtherExpress 16 card, install the card in the system,
reboot the system, and use the automatic configuration process to assign
those parameters to the card.
Then, for each additional card, edit the /etc/conf/sdevice.d/ee16 file
and specify the interrupt level and base I/O address for the next EtherExpress 16 card (being careful not to use an interrupt level or base I/O address
that are being used by any other board in the system), shut down the system, remove the EtherExpress 16 card that's in the system, replace it with
the next EtherExpress 16 card, and reboot the system. The automatic
parameters
in
configuration
process
will
assign
the
/etc/conf/sdevice.d/ee16 to the new card.
When you have programmed the parameters for all the cards, shut down
and turn off the system, and install all the cards. The configuration files
need to reflect the fact that multiple cards are in use. When you boot the
system it recognizes that there are multiple EtherExpress 16 cards installed
and does not try to autoconfigure them.
Configuration

The
ee16
driver
has
four
configurable
parameters
in
the
/etc/conf/pack.d/ee16/space.c file. Any changes to this file must be followed
by a rebuild of the kernel and a reboot of the system for the changes to take effect.
The configurable parameters are:
N_SAPS

Defines the number of SAPs that can be bound at anyone time. This value
should be only slightly larger than anticipated SAP usage. A typical
TCP /IP system requires two SAPs (OxSOO and OxS06). A large value will
degrade performance and increase memory usage.
CABLE_TYPE

Defines the type of Ethernet cable attached to the Ethernet controller card.
A value of 0 specifies a thin Ethernet cable with a BNC connector. A value
of 1 specifies a thick Ethernet cable with an AUI connector.
STREAMS_LOG

Defines whether the driver should log debugging messages to the
STREAMS logger for the strace(lM) utility to display. The module ID
used with strace is 2101. A value of 0 indicates that no STREAMS debug
messages should be generated. A value of 1 will cause messages to be generated. You can temporarily set the driver to log messages by changing the
value of ee16strlog (a 4-byte integer) to 1 using the kernel debugger.
STREAMS tracing should only be performed when debugging a network
problem. It can cause a severe performance degradation if you use full ee16
STREAMS logging.

408

ee16(7)
IFNAME

This parameter is important only in a TCP lIP networking environment. It
defines the string used in displaying network statistics. This string should
match
the
logical
interface
name
assigned
in
letc/confnet .d/inet/interfaces file and with ifconfig(lM)
commands used in letc/inet/rc.inet configuration script.
Errors

The ee16 driver can return the following error codes:
ENXIO Invalid major number or board is not installed.
ECHRNG

No minor devices left if configured as a cloned device. Increase N SAP value
in letc/conf/pack.d/ee16/space.c Invalid minor device number if
configured as a non-cloned device.
An ioctl was made without the appropriate privilege.

EPERM
EINVAL

An ioctl was made that did not supply a required input andlor output
buffer.
DL_NOTSUPPORTED

Requested service primitive is not supported.
DL_BADPRIM

Unknown service primitive was requested.
DL_OUTSTATE
DL_BIND_REQ was issued when the Stream was bound, or DL_UNBIND_REQ
or DL_UNITDATA_REQ was issued when the Stream was unbound.
DL_ACCESS

An attempt was made to bind to PROMISCUOUS_SAP with insufficient
privilege.
DL_BOUND

The requested SAP is already bound. A privileged process may bind to an
already bound SAP.
DL_NOTINIT
DL_UNITDATA_REQ was

made on an Ethernet board that has gone offline due

to an error.
DL_BADDATA
DL_UNITDATA_REQ was

made with a data size that was either larger than the
SPDU maximum or smaller than the SPDU minimum.

Files

Idev/ee16*
letc/conf/pack.d/ee16/space.c
letc/conf/sdevice.d/ee16

REFERENCES
getmsg(2), ioctl(2), open(2), putmsg(2)

409

el16 (7)
NAME

e1l6 - EtherLink 16 Ethernet Adapter Driver
SYNOPSIS

#include
#include
#include
fd

= open

("/dev/el16_0", O_RDWR)

DESCRIPTION

The e1l6 driver provides a data link interface to the EtherLink 16 and
Etherlink/MC adapters from 3Com. It is a STREAMS-based driver compatible with
the Data Link Provider Interface (DLPI) and Logical Link Interface (LU) software
interfaces.
It supports DL_ETHER and DL_CSMACD for MAC type, DL_CLDLS for service mode,
and DL_STYLE 1 for provider style. The e1l6 driver can operate as a cloned or
non-cloned device.

A process must issue a DL_BIND_REQ primitive to receive frames from the network.
The process must specify the dl_sap field of the dl_bind_reCLt structure. The type
field of an incoming frame is compared to the dl_sap value. If the values are equal,
it is placed on the STREAMS read queue of the process. A privileged process may
set the dl_sap field to PROMISCUOUS_SAP. The PROMISCUOUS_SAP matches all incoming frames.
A privileged process may also bind to a SAP already bound by another process. In
cases where a frame qualifies to be sent to more than one process, independent
copies of the frame are created and placed on the STREAMS read queue of each
process.
Received frames are delivered in dl_unitdata_ind_t structures. The source and
destination address each contain contain a 6-byte Ethernet address, followed by a
2-byte type value.
USAGE

ioctl Calls
The following ioctls are supported:

DLIOCGMIB
Returns the DL_mib_t structure, which contains the Management Information Base (MIB). The MIB holds the Ethernet statistics kept in the driver.
/*

* Ether statistics structure.
*/

typedef struct {
ulong_t
etherAlignErrors;
ulong_t
etherCRCerrors;
ulong_t
etherMissedPkts;
ulong_t
etherOverrunErrors;
ulong_t
etherUnderrunErrors;
ulong_t
ethereollisions;

410

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

Frame alignment errors */
CRC erros */
Packet overflow or missed inter */
OVerrun errors */
Underrun errors */
Total collisions */

el16 (7)
ulong_t etherAbortErrors;
ulong_t
etherCarrierLost;
ulong_t
etherReadqFull ;
ulong_t
etherRcvResources;
ulong_t
etherDependentl;
ulong_t
etherDependent2 ;
ulong_t
etherDependent3 ;
ulong_t
etherDependent4 ;
ulong_t
etherDependentS;
DL_etherstat_t;

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

Transmits aborted at interface
Ca=ier sense signal lost * /
STREAMS read queue full */
Receive resource alloc faliure
Device dependent statistic */
Device dependent statistic */
Device dependent statistic */
Device dependent statistic */
Device dependent statistic */

* Interface statistics compatible with MIB II SNMP requirements.
*/

typedef struct {
int
ifIndex;
/* ranges between 1 and ifNumber * /
int
ifDescrLen;
/* len of desc. following this struct */
int
ifType;
/* type of interface */
int
ifMtu;
/* datagram size that can be sent/rcv * /
ulong_t
ifSpeed;
/* estimate of bandwidth in bits PS * /
uchar_t
ifPhyAddress [DL_MAC_ADDR_LENl ; /* Ethernet Address * /
int
ifAdminStatus;
/* desired state of the interface */
int
ifOperStatus;
/* cu=ent state of the interface */
ulong_t
ifLastChange;
/* sySUpTime when state was entered */
ulong_t
ifInOctets;
/* octets received on interface */
ulong_t
ifInUcastPkts;
/* unicast packets delivered */
ulong_t
ifIDNUcastPkts;
/* non-unicast packets delivered */
ulong_t
ifInDiscards;
/* good packets received but dropped */
ulong_t
ifInErrors;
/* packets received with errors */
ulong_t
ifInUnknownProtos;
/* packets recv'd to unbound proto */
ulong_t
ifOutOctets;
/* octets transmitted on interface */
ulong_t
ifOutUcastPkts;
/* unicast packets transmited * /
ulong_t
ifOutNUcastPkts;
/* non-unicast packets transmited */
ulong_t
ifOutDiscards;
/* good outbound packets dropped */
ulong_t
ifOutErrors;
/* number of transmit e=ors */
ulong_t
ifOutQlen;
/* length of output queue */
DL_etherstat_t ifSpecific;
/* ethernet specific stats */
DL_mib_t;

The values in the MIB are compatible with those needed by the SNMP
protocol.
The ifDescrLen field indicates the length of the null terminated description
string that immediately follows the DL_mib_t structure.
There are three fields in the MIB that are specific to the e116 driver. The
ifSpecific.etherDependentl field tracks the number of times the transceiver
failed to transmit a collision signal after transmission of a packet. The
ifSpecific.etherDependent2 field contains the number of collisions that
occurred after a slot time (out of window collisions). The

411

el16 (7)
ifSpeeifie.etherDependent3 field tracks the number of times a transmit interrupt timeout condition occurred.
DLIOCSMIB
Allows a privileged process to initialize the values in the MIB (that is, the
DL_mib_t structure). A process cannot use this ioctl to change the
ifPhyAddress, the ijDeserLen, or the text of the description fields.
DLIOCGENADDR
Returns the Ethernet address in network order.
DLIOCGLPCFLG
Returns the state of the local packet copy flag in the ioe Jval of the iocblk
structure. The local copy flag determines if packets looped back by the
driver should also be sent to the network. A non-zero value indicates that
frames should also be be sent to the network after being looped back. The
default value of this flag is zero.
DLIOCSLPCFLG
Allows a privileged process to set the local packet copy flag, causing all
packets looped back by the driver to be sent to the network as well.
DLIOCGPROMISC
Returns the value of the promiscuous flag in the ioeJval of the iocblk structure. A non-zero value indicates that the Ethernet interface will receive all
frames on the network. The default value of this flag is zero.
DLIOCSPROMISC
Allows a privileged process to toggle the current state of the promiscuous
flag. When the flag is set, the driver captures all frames from the network.
Processes that are bound to a promiscuous SAP, or to a SAP that matches
the type field of the received frame, receive a copy of the frame.
DLIOCGETMULTI
Retries the current list of multicast addresses (if it exists).
DLIOCADDMULTI
Allows a privileged process to add a new multicast address and enable its
reception. A 6-byte buffer pointing to the multicast address must be passed
as the parameter.
DLIOCDELMULTI
Allows a privileged process to delete a multicast address by passing a 6-byte
multicast address as the parameter.
Installation

You can select the interrupt vector, the base I/O address, and the base RAM
address for the EtherLink 16 adaptor at package installation time. Consult the
User's Manual that came with your adaptor for more information.
You can also set these parameters in the /etc/conf/sdevice.d/e116 file.
In addition, zero-wait-state operation of memory can be enabled or disabled at
installation time.

412

el16 (7)
If there is one EtherLink 16 card in the system, it is configured automatically to the
parameters specified at installation when the system is initialized. During initialization, the system determines the current base I/O address of the card, and then programs the card to its new configuration. If the system doesn't find an EtherLink 16
card, it displays an error message.

Automatic configuration occurs only when one EtherLink 16 card is installed in the
system. If more than one EtherLink 16 card needs to be present in the system, the
cards are assumed to have been configured already (the cards may be configured
using the configuration software that comes with the card).
Configuration

The
el16
driver
has
six
configurable
parameters
in
the
/etc/conf/pack.d/e116/space.c file. Any changes to this file must be followed
by a rebuild of the kernel and a reboot of the system for the changes to take effect.
The configurable parameters are:
N_SAPS

This defines the number of SAPs that can be bound at anyone time. This
value should be only slightly larger than anticipated SAP usage. A typical
TCP /IP system would require two SAPs (Ox800 and Ox806). A large value
will degrade system performance and increase memory usage.
CABLE_TYPE

Defines the type of ethernet cable attached to the Ethernet controller card.
A value of 0 specifies a thin Ethernet cable with a BNC connector. A value
of 1 specifies a thick Ethernet cable with an AUI connector.
STREAMS_LOG

Defines whether the driver should log debugging messages to the
STREAMS logger for the strace(lM) utility to display. The module ID
used with strace is 2101. A value of 0 indicates that no STREAMS debug
messages should be generated. A value of 1 causes messages to be generated. You can temporarily instruct the driver to log messages by changing
the value of e116strlog (a 4-byte integer) to 1 using the kernel debugger.
STREAMS tracing should only be performed when debugging a network
problem. It can cause a severe performance degradation if full el16
STREAMS logging is performed.
IFNAME

This parameter is important only in a TCP /IP networking environment. It
defines the string used in displaying network statistics. This string should
match
the
logical
interface
name
assigned
in
/etc/confnet.d/inet/interface file and with ifconfig(lM) commands
used in /etc/inet/rc. inet configuration script.
ZWS
SAAD

Enables or disables zero-wait-state operation of the memory. A value of 0
disables zero-wait-state operation while a value of 1 enables it.
Enables or disables software address decode in the adapter. In machines
which use the VTI chip set, this bit needs to be set.

413

el16 (7)
Errors

The el16 driver can return the following error codes:
ENXIO

Invalid major number or board is not installed.

ECHRNG

No minor devices left if configured as a cloned device. Increase N_SAP value
in /etc/conf/pack.d/e116/space.c Invalid minor device number if
configured as a non-cloned device.
EPERM An ioctl

was made without the appropriate privilege.

EINVAL

An ioctl was made that did not supply a required input and/or output
buffer.
DL_NOTSUPPORTED

Requested service primitive is not supported.
DL_BADPRIM

Unknown service primitive was requested.
DL_OUTSTATE
DL_BIND_REQ or DL_UNBIND_REQ was issued when the Stream was
or DL_UNITDATA_REQ was issued when the Stream was unbound.

bound,

DL_ACCESS

An attempt was made to bind to PROMISCUOUS_SAP with insufficient
privilege.
DL_BOUND

The requested SAP is already bound. A privileged process may bind to an
already bound SAP.
DL_NOTINIT
A DL_UNITDATA_REQ

was made on an Ethernet board that has gone offline

due to an error.
DL_BADDATA
DL_UNITDATA_REQ was

made with a data size that was either larger than the
SPDU maximum or smaller than the SPDU minimum.

Files
/dev/e116*
/etc/conf/pack.d/el16/space.c
/etc/conf/sdevice.d/el16

REFERENCES
open(2), getmsg(2), ioctl(2), putmsg(2)

414

fd(7)
NAME

fd - diskette (floppy disk)
DESCRIPTION

The diskette driver provides access to diskettes as both block and character devices.
Diskettes must be formatted before their use [see fonnat(lM)J. Both 5.25" and 3.50"
diskette formats are supported. The driver controls up to two diskette drives. The
minor device number specifies the drive number, the format of the diskette and the
partition number.
Diskette device file names (which correspond to a specific major and minor device)
use the following format:
/dev/{r}dsk/f{O,1}{5h,5d9,5d8,5d4,5d16,5q,3h,3d}{t,u}
where r indicates a raw (character) interface to the diskette, rdsk selects the raw
device interface and dsk selects the block device interface. 0 or 1 selects the drive to
be accessed: fO selects floppy drive 0, while fl selects drive 1. The following list
describes the format to be interacted with:
5h
5d9
5d8
5d4
5d16
5q
3h
3d

5.25" high density diskette (1.2MB).
5.25" double density diskette, 9 sectors per track (360KB).
5.25" double density diskette, 8 sectors per track (320KB).
5.25" double density diskette, 4 sectors per track (320KB).
5.25" double density diskette, 16 sectors per track (320KB).
5.25" quad density diskette (720KB).
3.50" high density diskette (1.44MB).
3.50" double density diskette (720KB).

Format specification is mandatory when opening the device for formatting. However, when accessing a floppy disk for other operations (read and write), the format
specification field can be omitted. In this case, the floppy disk driver will automatically determine the format previously established on the diskette and then perform
the requested operation (for example, cpio -itv

Temporary files; initialized to empty during the boot operation.

/var

Root of a subtree for varying files. Varying files are files that
are unique to a machine but that can grow to an arbitrary (that
is, variable) size. An example is a log file.

/var/adm
/var/cron
/var/mail
/var/opt

System logging and accounting files.
cron's log file.

/var/preserve
/var/spool

Where users' mail is kept.
Top-level directory used by application packages.
Backup files for vi(l) and ex(l).
Subdirectories for files used in printer spooling, mail delivery,
cron(lM), at (1), etc.

/var/tllI>
Transitory files; initialized to empty during the boot operation.
Because it is desirable to keep the root file system small and not volatile, on diskbased systems larger file systems are often mounted on /hame, /opt, /usr, and
/var.
The file system mounted on /usr contains architecture-dependent and
architecture-independent sharable files. The subtree rooted at /usr/share contains
architecture-independent sharable files; the rest of the /usr tree contains
architecture-dependent files. By mounting a common remote file system, a group
of machines with a common architecture may share a single /usr file system. A
single /usr/share file system can be shared by machines of any architecture. A
machine acting as a file server may export many different /usr file systems to
support several different architectures and operating system releases. Clients
usually mount /usr read-only so that they don't accidentally change any shared
files. The /usr file system contains the following subdirectories:

420

/usr /bin
/usr / sbin

Most system utilities.
Executables for system administration.

/usr/games
/usr/include
/usr/lib

/usr/share
/usr / share/man

Game binaries and data.
Include header files (for C programs, etc).
Program libraries, various architecture-dependent databases,
and executables not invoked directly by the user (system
daemons, etc).
Subtree for architecture-independent sharable files.
Subdirectories for on-line reference manual pages (if present).

/usr/share/lib
/usr/src

Architecture-independent databases.
Source code for utilities and libraries.

/usr/ucb

Berkeley compatibility package binaries.

filesystem (7)
/usr/ucbinclude Berkeley compatibility package header files.
/usr/ucblib

Berkeley compatibility package libraries.

A machine with disks may export root file systems, swap files, and /usr file sys-

tems to diskless or partially-disked machines that mount them into the standard file
system hierarchy. The standard directory tree for sharing these file systems from a
server is:
/export

The default root of the exported file system tree.
/ export/ exec/ architecture-name
The exported /usr file system supporting architecture-name for
the current release.
/ export/exec/ architecture-name. release-name
The exported /usr file system supporting architecture-name for
System V release-name.
/export/exec/share

The exported common /usr / share directory tree.
/ export/ exec/ share. release-name
The exported common /usr / share directory tree for System V
release-name.
/export/root/hostname

The exported root file system for hostname.
/ export / swap / hostname

The exported swap file for hostname.
/ export /var / hostname

The exported /var directory tree for hostname.
SEE ALSO

at(l), fsck(lM), init(lM), mknod(lM), mount(lM), sh(l), vi(l)

421

iS96(7)
NAME

i596 - i596 Ethernet Driver
SYNOPSIS

#include
#include
#include
fd

= open

(l/dev/i596_0", O_RDWR)

DESCRIPTION

The i596 driver provides a data link interface to the 82596 high-performance 32-bit
LAN coprocessor in the LP486/33E system. In this system, the 82596CA resides on
the host bus, sharing address, data, and control lines with the i486 processor. This
driver is a STREAMS-based driver that is compatible with the Data Link Provider
Interface (DLPI) and Logical Link Interface (LLI) software interfaces.
It supports DL_ETHER as MAC type, DL_CL_ETHER for service mode, and
DL_STYLEl for provider style. The i596 driver can operate as a cloned or noncloned device.

A process must issue a DL_BIND_REQ primitive to receive frames from the network.
The process must specify the dl_sap field of the dl_bind_re~t structure. The type
field of an incoming frame is compared to the dl_sap value. If the values are equal,
it is placed on the STREAMS read queue of the process. A privileged process may
set the dl_sap field to PROMISCUOUS_SAP. The PROMISCUOUS_SAP matches all incoming frames.
A privileged process may also bind to a SAP already bound by another process. In
cases where a frame qualifies to be sent to more than one process, independent
copies of the frame are created and placed on the STREAMS read queue of each
process.
Received frames are delivered in dl_unitdata_ind_t structures. The source and
destination address each contain a 6-byte Ethernet address followed by a 2-byte
type value.
USAGE

ioetl Calls
The following ioctls are supported:

DLIOCGMIB
Returns the DL_mib_t structure, which contains the Management Information Base (MIB). The MIB holds the Ethernet statistics that are kept in the
driver.
/*

* Ether statistics structure.
*/
typedef struct {
int
etherAlignErrors;
int
etherCRCerrors;
int
etherMissedPkts;
int
etherOverrunErrors;
int
etherUnderrunErrors;
422

/*
/*
/*
/*
/*

Frame alignment errors */
CRC errors */
Packet overflow or missed inter */
Overrun errors */
Underrun errors */

iS96(7)
int
etherCollisions;
int
etherAbortErrors;
int
etherCarrierLost;
int
etherReadqFuII;
int
etherRcvResources;
int
etherDependent 1;
int
etherDependent2;
int
etherDependent3;
int
etherDependent4;
int
etherDependent5 ;
DL_etherstat_t;

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

Total collisions */
Transmits aborted at interface
Carrier sense signal lost */
STREAMS read queue full */
Receive resource alloc failure
Device dependent statistic */
Device dependent statistic */
Device dependent statistic */
Device dependent statistic */
Device dependent statistic */

* Interface statistics compatible with MIB II SNMP requirements.
*/
typedef struct {
int
if Index;
/* ranges between 1 and ifNumber */
int
ifDescrLen;
/* len of desc. following this struct */
if Type;
/* type of interface */
int
int
ifMtu;
/* datagram size that can be sent/rcv */
ulong_t
if Speed;
/* estimate of bandwidth in bits PS */
uchar_t
ifPhyAddress[DL_MAC_ADDR_LEN];/* Ethernet Address */
int
ifAdminStatus;
/* desired state of the interface */
int
ifOperStatus;
/* current state of the interface */
ulong_t
ifLastChange;
/* sysUpTime when state was entered */
ulong_t
ifInOctets;
/* octets received on interface */
ulong_t
ifInUcastPkts;
/* unicast packets delivered */
ulong_t
ifInNUcastPkts;
/* non-unicast packets delivered */
ulong_t
ifInDiscards;
/* good packets received but dropped */
ulong_t
ifInErrors;
/* packets received with errors */
ulong_t
ifInUnknownProtos;
/* packets recv'd to unbound proto */
ulong_t
ifOUtOctets;
/* octets transmitted on interface */
ulong_t
ifOUtUcastPkts;
/* unicast packets transmited */
ulong_t
ifOUtNUcastPkts;
/* non-unicast packets transmited */
ulong_t
ifOUtDiscards;
/* good outbound packets dropped */
ulong_t
ifOUtErrors;
/* number of transmit errors */
ulong_t
ifOUtQlen;
/* length of output queue */
DL_etherstat_t if Specific;
/* ethernet specific stats */
DL_mib_t;

The values in the MIB are compatible with those needed by the SNMP protocol.
The ifDescrLen field indicates the length of the null terminated description
string that immediately follows the DL_mib_t structure.
There are three fields in the MIB that are specific to the i596 driver: The
ifSpecific.etherDependentl field tracks the number of times the transceiver
failed to transmit a collision signal after transmission of a packet. The
ifSpecific.etherDependent2 field contains the number of collisions that

423

i596 (7)
occurred

after

slot

time

(out

window

collisions).

The

ifSpeeifie.etherDependent3 field tracks the number of times a transmit inter-

rupt timeout condition occurred.
DLIOCSMIG
Allows a privileged process to initialize the values in the MIB (that is, the
DL_mib_t structure). A process cannot use this ioctl to change the
ifPhyAddress, the ijDeserLen, or the text of the description fields.
DLIOCGENADDR
Returns the Ethernet address in network order.
DLIOCGLPCFLG
Returns the state of the local packet copy flag in the ioe Jval of the iocblk
structure. The local copy flag determines whether packets looped back by
the driver should also be sent to the network. A non-zero value indicates
that frames should also be be sent to the network after being looped back.
The default value of this flag is zero.
DLIOCSLPCFLG
Allows a privileged process to set the local packet copy flag, causing all
packets looped back by the driver to be sent to the network as well.
DLIOCGPROMISC
Returns the value of the promiscuous flag in the ioe Jval field of the iocblk
structure. A non-zero value indicates that the Ethernet interface will receive
all frames on the network. The default value of this flag is zero.
DLIOCSPROMISC
Allows a privileged process to toggle the current state of the promiscuous
flag. When the flag is set, the driver captures all frames from the network.
Processes that are bound to a promiscuous SAP, or to a SAP that matches
the type field of the received frame, receive a copy of the frame.
Installation

You select the interrupt level for the i596 at package installation time. The following interrupts are valid: 9, 10, 11, or 15.
This interrupt should match the "LAN IRQ Level" value configured by the EISA
Configuration Utility (ECU). In addition, the "Onboard LAN" must be enabled and
the "LAN Media Type" set to either AUI or Twisted Pair, whichever is appropriate.
You can also set the interrupt level in the /etc/conf/sdevice.d/i596 file.
Configuration
The
i596
driver
has
three
configurable
parameters
in
the
/etc/conf/pack.d/i596/space.c file. Any changes to this file must be followed

by a rebuild of the kernel and a reboot of the system for the changes to take effect.
The configurable parameters are:
N_SAPS
Defines the number of SAPs that can be bound at anyone time. This value
should be only slightly larger than anticipated SAP usage. A typical
TCP lIP system would require two SAPs (OxSOO and OxS06). A large value
will degrade performance and increase memory usage.

424

i596 (7)
STREAMS_LOG

Defines whether the driver should log debugging messages to the
STREAMS logger for the strace(lM) utility to display. The module ID
used with strace is 2101. A value of 0 indicates that STREAMS debug
messages should not be generated. A value of 1 enables STREAMS debug
messages. You can make the driver temporarily log messages by changing
the value of i596strlog (a 4-byte integer) to 1 using the kernel debugger.
STREAMS tracing should only be performed when debugging a network
problem. It can cause a severe performance degradation if you use full i596
STREAMS logging.
IFNAME

This parameter is important only in a Tep lIP networking environment. It
defines the string used in displaying network statistics. This string should
match the logical interface name assigned in /etc/inet/strcf file and
with ifconfig(lM) commands used in / etc/ inet/rc. inet configuration
script.
Errors
The i596 driver can return the following error codes:
ENXIO Invalid major number or board is not installed.
ECHRNG

No minor devices left if configured as a cloned device. Increase N SAP value
in /etc/conf!pack.d/i596/space.c Invalid minor device number if
configured as a non-cloned device.

An ioctl was issued without the appropriate privilege.

EPERM
EINVAL

An ioctl was issued that did not supply a required input andlor output
buffer.
DL_NOTSUPPORTED

The requested service primitive is not supported.
DL_BADPRIM

An unknown service primitive was requested.
DL_OUTSTATE
DL~IND_REQ

was issued when the Stream was bound, or DL_UNBIND_REQ
or DL_UNITDATA_REQ was issued when the Stream was unbound.

DL_ACCESS

An attempt was made to bind to PROMISCUOUS_SAP with insufficient
privilege.
DL_BOUND

The requested SAP is already bound. A privileged process may bind to an
already bound SAP.
DL_NOTINIT
DL_UNITDATA_REQ was issued on an Ethernet board that has gone offline

due to an error.

425

i596 (7)
DL_BADDATA
DL_tlNITDATA_REQ

was issued with a data size that was either larger than
the SPDU maximum. or smaller than the SPDU minimum..

Files
/dev/i596_0
/etc/conf/pack.d/i596/space.c
/etc/conf/sdevice.d/i596

REFERENCES
open(2), getmsg(2), ioctl(2), putmsg(2)

426

ibmtok(7)
NAME

ibmtok - IBM Token Ring Driver
SYNOPSIS

#include
#include
#include

DESCRIPTION

The ibmtok driver provides a data link interface to both the 16/4 and the 16/4A
token ring adapters from IBM. It is a STREAMS-based driver that is compatible
with the Data Link Provider Interface (DLPI) and Logical Link Interface (LU)
software interfaces.
The ibmtok driver can operate as a cloned or non-cloned device.
A process must issue a DL_BIND _REQ primitive to receive frames from the network. The process must specify the dl_sap field of the dl_bind_re~t structure.
The type field of an incoming frame is compared to the dl_sap value. If the values
are equal, it is placed on the STREAMS read queue of the process.
Received frames are delivered in dl_unitdata_ind_t structures. The source and
destination address each contain a 6-byte Ethernet address, followed by the 1- or 2byte type value.
Any user process that has a Stream bound (using a DL_BIND_REQ) to the token ring
driver should explicitly unbind (using DL_UNBIND_REQ) before closing the Stream.
Any destructive close (closing without unbind) will render the SAP useless until the
board can be closed and opened again.
USAGE

You can select the interrupt level, base I/O address, ROM address and the shared
RAM address for the token ring card at package installation time. While interrupts
2,3,6, and 7 are valid for the AT version of the card, 2, 3,10, and 12 should be used
for the MeA version of the card. The shared RAM is a movable section of memory
and can be 8K, 16K, 32K or 64K. The starting address of the shared RAM is a function of the size and should fall on appropriate boundaries. For example, the starting address of a 16K RAM should only be on 16K boundaries. Similarly, you can
also choose the starting address of an 8K ROM. The ROM contains adapter
configuration information and is also used to control the adapter.
The base I/O address of the card can be one of the following addresses:
OxA20
OxA24

OxA23
OxA27

You can also set these parameters in the / etc / conf / sdevice . d/ ibmtok file.
Configuration
The
ibmtok
driver
has
four
configurable
parameters
in
the
/etc/conf/pack.d/ibmtok/space.c file. Any changes to this file must be

427

ibmtok(7)
followed by a rebuild of the kernel and a reboot of the system for the changes to
take effect.
The configurable parameters are:
tok_nhr_rcv_buffers
Defines the number of receive buffers that are minimally required. The
receive buffers are allocated in the shared RAM. Though the default value
is 20, the adapter can and will allocate all unused memory to the receive
buffers.
tok_rcv_buff_size
Defines the size of the receive buffers. The default value is 264.
tok_tx_buff_size
The size of the transmit buffer. The default value is 2048 bytes.
tok_nhr_tx_buffers
The number of transmit buffers. The default value is 1.
loctl Calls

The following ioctls are supported:
DLGDEVSTAT
Returns the tokstat structure, which contains the information about the
number of packets and bytes transmitted and received for that particular
SAP.
/*

* Per sap statistics structure.
*/
typedef struct {
ulong
toks_xpkts;
/*The number
ulong
toks_xbytes;
/*The number
ulong
toks_rpkts;
/*The number
ulong
toks_rbytes;
/*The number
tokdevstat;

of
of
of
of

packets transmitted */
bytes transmitted */
packets received */
bytes received */

DLGADDR
Returns the Ethernet address in network order.
Error Codes
The ibmtok driver can return the follOWing error codes:

Invalid major number, board not installed, or a non-functional board.
ECHRNG
No minor devices left, if configured as a cloned device.
EINTR Signal terminating a process sleeping on an event.
ENXIO

EINVAL

An ioctl was issued that did not supply a required input and/ or output
buffer.

428

ibmtok(7)
DL_NOTSUPPORTED
Requested service primitive is not supported.
DL_BADPRIM
Unknown service primitive was requested.
DL_OUTSTATE
DL_BIND_REQ was issued when the stream was bound, or DL_UNBIND_REQ
or DL_UNITDATA_REQ was issued when the stream was unbound.
DL_BOUND
The requested SAP is already bound.
DL_NOTINIT
A service primitive was issued to a token ring board that has gone offline
due to an error.
DL_BADDATA
DL_UNITDATA_REQ was issued with a data size that was either larger than
the SPDU maximum or smaller than the SPDU minimum.
Files
/dev/ibmtok*
/etc/conf/pack.d/ibmtok/space.c
/etc/conf/sdevice.d/ibmtok

REFERENCES
getmsg(2), ioctl(2), open(2), putmsg(2)

429

ICMP(7)
NAME

ICMP - Internet Control Message Protocol
SYNOPSIS

#include
#include
#include
s = socket (AF_lNET, SOClCRAW, proto);
t = t_open(lI/dev/icmpll, O_RDWR};
DESCRIPTION

ICMP is the error and control message protocol used by the Internet protocol family.
It is used by the kernel to handle and report errors in protocol processing. It may

also be accessed by programs using the socket interface or the Transport Level
Interface (TLI) for network monitoring and diagnostic functions. When used with
the socket interface, a raw socket type is used. The protocol number for ICMP, used
in the proto parameter to the socket call, can be obtained from getprotobyname()
[see getprotoent(3N)]. ICMP file descriptors and sockets are connectionless, and
are normally used with the t_sndudata I t_rcvudata and the sendto () I
recvfrom{ ) calls [see send(3N) and recv(3N)].
Outgoing packets automatically have an Internet Protocol (IP) header prepended to
them. Incoming packets are provided to the user with the IP header and options
intact.
ICMP is an datagram protocol layered above IP. It is used internally by the protocol
code for various purposes including routing, fault isolation, and congestion control.
Receipt of an ICMP redirect message will add a new entry in the routing table, or
modify an existing one. ICMP messages are routinely sent by the protocol code.
Received ICMP messages may be reflected back to users of higher-level protocols
such as TCP or UDP as error returns from system calls. A copy of all ICMP message
received by the system is provided to every holder of an open ICMP socket or TLI
descriptor.
SEE ALSO

getprotoent(3N),
inet(7),
ip(7),
t_rcvudata(3N), t_sndudata(3N)

recv(3N),

routing(4),

send(3N),

Postel, Jon, Internet Control Message Protocol - DARPA Internet Program Protocol
Specification, RFC 792, Network Information Center, SRI International, Menlo Park,
Calif., September 1981
DIAGNOSTICS

A socket operation may fail with one of the following errors returned:
EISCONN

ENOTCONN

430

An attempt was made to establish a connection on a socket
which already has one, or when trying to send a datagram with
the destination address specified and the socket is already connected.
An attempt was made to send a datagram, but no destination
address is specified, and the socket has not been connected.

ICMP(7)
ENOBUFS
EADDRNOTAVAIL

The system ran out of memory for an internal data structure.
An attempt was made to create a socket with a network
address for which no network interface exists.

NOTES

Replies to ICMP echo messages which are source routed are not sent back using
inverted source routes, but rather go back through the normal routing mechanisms.

431

ie6(7)
NAME

ie6 - 3C503 3Com Ethernet Driver
SYNOPSIS

#include
#include
#include
fd = open ( .. /dev/ie6_0" O_RDWR)
I

DESCRIPTION

The ie6 driver provides a data link interface to the 3C503 Ethernet controller from
3Com. It is a STREAMS-based driver, compatible with the Data Link Provider
Interface (DLPI) and Logical Link Interface (LL!) software interfaces.
The ie6 driver supports both DL_ETHER and DL_CSMACD for MAC type,
DL_CL_ETHER for service mode, and DL_STYLEl for provider style. The driver can
operate as a cloned or non-cloned device.
A process must issue a DL_BIND_REQ primitive to receive frames from the network.
This primitive includes a dl_bind_re~t structure.
The process must specify the dl_sap field of the dl_bind_r~t structure in host
order. The type field of an incoming frame is converted to host order and compared to the dl_sap value. If the values are equal, the frame is placed on the
STREAMS read queue of the requesting process. A privileged process may set the
dl_sap field to PROMISCUOUS_SAP. The PROMISCUOUS_SAP matches all incoming
frames.
A privileged process may bind to an SAP already bound by another process. In
cases where a frame qualifies to be sent to more than one process, independent
copies of the frame are made and placed on the STREAMS read queue of each process.
Received frames are delivered in dl_unitdata_ind_t structures. The source and
destination address each contain a 6-byte Ethernet address, followed by the 2-byte
type value, written in network order.
USAGE

ioetl Calls

The following ioctls are supported:
DLIOCGMIB
Returns the DL_mib_t structure, which contains the Management Information Base (MIB). The MIB holds the Ethernet statistics kept in the driver.
1*

* Ether statistics structure.
*1
typedef struct {
ulong_tetherAlignErrors;
1*
ulong_tetherCRCerrors;
1*
ulong_tetherMissedPkts;
1*
ulong_tetherOverrunErrors; 1*
ulong_tetherunderrunErrors; 1*
ulong_tetherCollisions;
1*
432

Frame aligmnent errors * I
CRe errors *1
Packet overflow or missed inter *1
OVerrun errors *1
und.errun errors *1
Total collisions *1

ie6(7)
ulong_t etherAbortErrors;
ulong_tetherCarrierLost;
ulong_tetherReadqFull;
ulong_tetherRcvResources;

1*
1*
1*
1*

Transmits aborted at interface *1
carrier sense signal lost *1
STREAMS read queue full * 1
Receive resource alloc faliure

1*
1*
1*
1*
1*

Device
Device
Device
Device
Device

*1
ulong_tetherDependentl;
ulong_tetherDependent2;
ulong_tetherDependent3;
ulong_tetherDependent4;
ulong_tetherDependent5;
DL_etherstat_t;

dependent
dependent
dependent
dependent
dependent

statistic
statistic
statistic
statistic
statistic

*1
*1
*1
*1
*1

1*
*

Interface statistics compatible with MIB II SNMP requirements.

*1
typedef struct {
ifIndex;
int
1* 1 through ifNumber *1
int
ifDescrLen;
1* len of desc. following this struct *1
int
ifType;
1* type of interface *1
int
ifMtu;
1* datagram size that can be sent/rev *1
ulong_tifSpeed;
1* estimate of bandwith in bits PS *1
uchar_tifPhyAddress[DL_MAC_ADDR_LEN];I* Ethernet Address *1
int
ifAdminStatus;
1* desired state of the interface *1
int
ifQperStatus;
1* current state of the interface *1
ulong_tifLastChange;
1* sySupTime when state was entered * 1
ulong_tifInOctets;
1* octets received on interface *1
ulong_tifInUcastPkts;
1* unicast packets delivered *1
ulong_tifInNUcastPkts;
1* non-unicast packets delivered *1
ulong_tifInDiscards;
1* good packets received but dropped *1
ulong_tifInErrors;
1* packets received with errors *1
ulong_tifInUnknow.nProtos;
1* packets reev'd to unbound proto

*1
ulong_tifOutOctets;
ulong_tifOutUcastPkts;
ulong_tifOutNUcastPkts;
ulong_tifOutDiscards;
ulang_tifOutErrors;
ulang_tifOutQlen;
DL_etherstat_t ifSpecific;
DL_mib_t;

1*
1*
1*
1*
1*
1*
1*

octets transmitted on interface '*1
unicast packets transmited *1
non-unicast packets transmited *1
good outbound packets dropped * 1
number of transmit errors * 1
length of output queue * 1
Ethernet specific stats *1

The values in the MIB are compatible with those needed by the SNMP protocol.
The ifDescrLen field indicates the length of the null-terminated description
string that immediately follows the DL_mib_t structure.

433

ie6(7)
There are three fields in the MIB that are specific to the ie6 driver: The
ifSpeeifie.etherDependentl field tracks the number of times the transceiver
failed to transmit a collision signal after transmission of a packet. The
ifSpeeifie.etherDependent2 field tracks the number of collisions that occurred
after a slot time (out-of-window collisions). The ifSpeeifie.etherDependent3
field tracks the number of times a transmit interrupt timeout condition
occurred.
DLIOCSMIG
Allows a privileged process to initialize the values in the MIB (that is, the
DL_mib_t structure). A process cannot use this ioctl to change the
ifPhyAddress, the ifDescrLen, or the text of the description fields.
DLIOCGENADDR
Returns the Ethernet address in network order.
DLIOCGLPCFLG
Returns the state of the local packet copy flag in the ioe-,val field of the
iocblk structure. The local copy flag determines if packets looped back by
the driver should also be sent to the network. A non-zero value indicates
that frames should also be be sent to the network after being looped back.
The default value of this flag is zero.
DLIOCSLPCFLG
Allows a privileged process to set the local packet copy flag, causing all
packets looped back by the driver to also be sent to the network.
DLIOCGPROMISC
Returns the value of the promiscuous flag in the ioe-,val of the iocblk structure. A non-zero value indicates that the Ethernet interface will receive all
frames on the network. The default value of this flag is zero.
DLIOCSPROMISC
Allows a privileged process to toggle the current state of the promiscuous
flag. When the flag is non-zero, the driver captures all frames from the network. Processes that are bound to the promiscuous SAP, or to an SAP that
matches the type field of the received frame, receive a copy of the frame.
DLIOCGETMULTI
Returns the current list of multicast addresses (if it exists).
DLIOCADDMULTI
Allows a privileged process to add a new multicast address and enable its
reception. A 6-byte buffer pointing to the multicast address must be passed
as the parameter.
DLIOCDELMULTI
Allows a privileged process to delete a multicast address by passing a 6-byte
multicast address as the parameter.
Configuration
The
ie6
driver
has
four
configurable
parameters
in
the
/etc/conf/pack.d/ie6/space.c file. If you change this file, you must rebuild

the kernel and reboot the system for the changes to take effect.

434

ie6(7)
The configurable parameters are:
N_SAPS

Defines the number of SAPs that can be bound at anyone time. This value
should be only slightly larger than anticipated SAP usage. A typical
TCP lIP system requires two SAPs (Ox800 and Ox806). If you assign too
large a value to this parameter, system performance and memory usage may
suffer.
CABLE_TYPE

Defines the type of Ethernet cable attached to the Ethernet controller card.
A value of 0 specifies thin Ethernet cable with a BNC connector. A value of
1 specifies thick Ethernet cable with a AUI connector.
STREAMS_LOG

Defines whether the driver should log debugging messages to the
STREAMS logger for the strace(lM) utility to display. The module ID
used with strace is 2101. A value of 0 indicates that no STREAMS debug
messages should be generated. A value of 1 enables STREAMS debug messages to be generated. You can also direct the driver to log messages temporarily by using the kernel debugger to change the value of ie6strlog (a
4-byte integer) to 1.
Use STREAMS tracing only when debugging a network problem, because
system performance suffers when full ie6 STREAMS logging is in progress.
IFNAME

This parameter is important only in a TCP lIP networking environment. It
defines the string used in displaying network statistics. This string should
match
the
logical
interface
name
assigned
in
the
/etc/confnet.d/inet/interfaces file and with ifconfig(lM) commands used in the / etc/ inet/rc . inet configuration script.
Errors

The ie6 driver can return the following error codes:
ENXIO Invalid major number or board is not installed.
ECHRNG

No minor devices left if configured as a cloned device. Increase N SAP value
in /etc/conf/pack.d/ie6/space.c Invalid minor device number if
configured as a non-cloned device.
EPERM An ioctl was made without the appropriate priVilege.
EINVAL

An ioctl was made that did not supply a required input and I or output
buffer.
DL_NOTSUPPORTED

Requested service primitive is not supported.
DL_BADPRIM

Unknown service primitive was requested.

435

ie6 (7)
DL_OUTSTATE
DL_BIND_REQ was issued when the Stream was bound, or DL_UNBIND_REQ
or DL_UNITDATA_REQ were issued when the Stream was unbound.
DL_ACCESS

An attempt was made to bind to PROMISCUOUS_SAP with insufficient
privilege.
DL_BOUND

The requested SAP is already bound. A privileged process may bind to an
already bound SAP.
DL_NOTINIT
DL_UNITDATA_REQ

was issued on an Ethernet board that has gone offline

due to an error.
DL_BADDATA
DL_UNITDATA_REQ

was issued with a data size that was either larger than
the SPDU maximum or smaller than the SPDU minimum.

Files
/dev/ie6_*
/etc/conf/pack.d/ie6/space.c

REFERENCES
getmsg(2), ifconfig(lM), ioctl(2), open(2), putmsg(2), strace(lM)

436

if(7)
NAME

if - general properties of Internet Protocol network interfaces
DESCRIPTION

A network interface is a device for sending and receiving packets on a network. A
network interface is usually a hardware device, although certain interfaces such as
the loopback interface, 10(7), are implemented in software. Network interfaces
used by the Internet Protocol (IP) must be STREAMS devices conforming to the
Datalink Provider Interface (DLPI).
An interface becomes available to IP when it is linked below the IP STREAMS device
with the I_LINK ioctl ( ) call. This may be initiated by the kernel at boot time or by
a user program some time after the system is running. Each IP interface must have
a name assigned to it with the SIOCSIFNAME ioct1 ( ). This name is used as a
unique handle on the interface by all of the other network interface ioct1 ( ) calls.
Each interface must be assigned an IP address with the SIOCSIFADDR ioct1 ( )
before it can be used. On interfaces where the network-to-link layer address mapping is static, only the network number is taken from the ioct1 ( ) request; the
remainder is found in a hardware specific manner. On interfaces which provide
dynamic network-to-link layer address mapping facilities [for example, lOMb/s
Ethernets using arp(7)], the entire address specified in the ioctl ( ) is used. A
routing table entry for destinations on the network of the interface is installed
automatically when an interface's address is set.

locns
The following ioct1 () calls may be used to manipulate IP network interfaces.
Unless specified otherwise, the request takes an ifreq structure as its parameter.
This structure has the form:
/* Interface request structure used for socket ioctl's. All */
/* interface ioctl's must have parameter definitions which */
/* begin with ifr_name. The remainder may be interface specific. */

struct ifreq {
#define IFNAMSIZ
16
char
ifr_name[IFNAMSIZ];
/* if name, for exarrple "emdl" * /
union {
struct sockaddr ifru_addr;
struct sockaddr ifru_dstaddr;
char
ifru_oname[IFNAMSIZ];
/* other if name */
struct sockaddr ifru_broadaddr;
short
ifru_flags;
int
ifru_metric;
char
ifru_data[1] ;
/* interface dependent data */
char
ifru_enaddr[6];
ifr_ifru;
#define ifr_addr
ifr_ifru.ifru_addr
/* address */
#define ifr_dstaddr
ifr_ifru.ifru_dstaddr
/* other end of p-to-p link */
#define ifr_oname
ifr_ifru.ifru_oname
/* other if name */
#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */
#define ifr_flags
ifr_ifru.ifru_flags
/* flags */
#define ifr_metric
ifr_ifru.ifru_metric
/* metric */
#define ifr_data
ifr_ifru.ifru_data
/* for use by interface */
#define ifr_enaddr
ifr_ifru.ifru_enaddr
/* ethernet address */
};

437

if(7)
SIOCSIFADDR

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.
Set interface flags field. If the interface is marked down, any
processes currently routing packets through the interface are
notified. The interface can be marked up or down by using
ifconfig(lM).

SIOCSIFFLAGS

Get interface flags.
SIOCGIFCONF
Get interface configuration list. This request takes an ifconf
structure (see below) as a value-result parameter. The
ifc_len 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.
The ifconf structure has the form:
1*
SIOCGIFFLAGS

*
*

Structure used in SIOCGIFCONF request.
Used to retrieve interface configuration
* for machine (useful for programs which
* must know all networks accessible).

*1
structifconf {
int
ifc_Ien;
1* size of associated buffer *1
union {
caddr_t ifcu_buf;
struct ifreq *ifcu_req;
ifc_ifcu;
#define ifc_buf ifc_ifcu.ifcu_buf 1* buffer address *1
#define ifc_req ifc_ifcu.ifcu_req 1* array of structures returned *1
};

SIOCSIFNAME

Set the name of the interface.
SEE ALSO

arp(7), ip(7), ifconfig(lM), 10(7)

438

irnx586 (7)
NAME

imx586 - IMXLAN586 Intel Ethernet Driver
SYNOPSIS

#include
#include
#include
fd

= open

("/dev/imx586_0", O_RDWR)

DESCRIPTION

The imx586 driver provides a data link interface to the iMX-LAN/586 Ethernet controller from Intel. It is a STREAMS-based driver, compatible with the Data Link
Provider Interface (DLPI) and Logical Link Interface (LU) software interfaces.
The imx586 driver supports both DL_ETHER and DL_CSMACD for MAC type,
DL_CL_ETHER for service mode, and DL_STYLEl for provider style. The driver can
operate as a cloned or non-cloned device.
A process must issue a DL_BIND_REQ primitive to receive frames from the network.
This primitive includes a dl_bind_re~t structure.
The process must specify the dl_sap field of the dl_bind_re~t structure in host
order. The type field of an incoming frame is converted to host order and compared to the dl_sap value. If the values are equal, the frame is placed on the
STREAMS read queue of the requesting process. A privileged process may set the
dl_sap field to PROMISCUOUS_SAP. The PROMISCUOUS_SAP matches all incoming
frames.
A privileged process may bind to an SAP already bound by another process. In
cases where a frame qualifies to be sent to more than one process, independent
copies of the frame are made and placed on the STREAMS read queue of each process.
Received frames are delivered in dl_unitdata_ind_t structures. The source and
destination address each contain a 6-byte Ethernet address, followed by a 2-byte
type value, written in network order.
USAGE

ioetl Calls
The following ioctls are supported:

DLIOCGMIB
Returns the DL_mib_t structure, which contains the Management Information Base (MIB). The MIB holds the Ethernet statistics kept in the driver.
/*

* Ether statistics structure.
*/
typedef struct {
ulong_tetherAlignErrors;
/*
ulong_tetherCRCerrors;
/*
ulong_tetherMissedPkts;
/*
ulong_tetherOverrunErrors; /*
ulong_tetherUnderrunErrors; /*
ulong_tetherCollisions;
/*

Frame alignment errors */
CRC errors */
Packet overflow or missed inter */
Overrun errors */
Underrun errors */
Total collisions */

439

irnx586 (7)
ulang_tetherAbortErrors;
ulang_tetherCarrierLost;
ulang_tetherReadqFull;
ulang_tetherRevResources;

1*
1*
1*
1*

Transmits aborted at interface *1
Carrier sense signal lost *1
STREAMS read queue full *1
Receive resource alloc faliure

ulong_tetherDependentl;
ulong_tetherDependent2;
ulong_tetherDependent3;
ulong_tetherDependent4;
ulang_tetherDependent5;
DIcetherstat_t;

1*
1*
1*
1*
1*

Device
Device
Device
Device
Device

*1
dependent
dependent
dependent
dependent
dependent

statistic
statistic
statistic
statistic
statistic

*1
*1
*1
*1
*1

1*
*

Interface statistics compatible with MIB II SNMP requirements.

*1
typedef struct {
int
if Index;
1* 1 through ifNumber *1
int
ifDescrLen;
1* len of desc. following this struct *1
int
ifType;
1* type of interface *1
int
ifMtu;
1* datagram size that can be sent/rev *1
ulang_tif8peed;
1* estimate of bandwith in bits PS *1
uchar_tifPhyAddress[DL_MAC_ADDR_LEN1;1* Ethernet Address *1
int
ifAdminStatus;
1* desired state of the interface *1
int
ifQperStatus;
1* current state of the interface *1
ulong_tifLastChange;
1* systJ:pTime when state was entered *1
ulong_tifInOctets;
1* octets received on interface *1
ulang_tifInUcastPkts;
1* unicast packets delivered *1
ulang_tifInNUcastPkts;
1* non-unicast packets delivered *1
ulong_tifInDiscards;
1* good packets received but dropped *1
ulang_tifInErrors;
1* packets received with errors *1
ulong_tifInUnknownProtos; 1* packets reev'd to unbound proto

*1
ulong_tifOutOctets;
ulong_tifOutUcastPkts;
ulong_tifOutNOcastPkts;
ulong_tifOutDiscards;
ulong_tifOutErrors;
ulong_tifOutQlen;
DL_etherstat_t if8pecific;
DL_mib_t;

1*
1*
1*
1*
1*
1*
1*

octets transmitted on interface '*1
unicast packets transmited *1
non-unicast packets transmited *1
good outbound packets dropped *1
number of transmit errors *1
length of output queue *1
Ethernet specific stats *1

440

irnx586 (7)
There are three fields in the MIB that are specific to the imx586 driver: The
ifSpecijie.etherDependentl field tracks the number of times the transceiver
failed to transmit a collision signal after transmission of a packet. The
ifSpeeijie.etherDependent2 field tracks the number of collisions that occurred
after a slot time (out-of-window collisions). The ifSpecijie.etherDependent3
field tracks the number of times a transmit interrupt timeout condition
occurred.
DLIOCSMIG
Allows a privileged process to initialize the values in the MIB (that is, the
DL_mib_t structure). A process cannot use this ioctl to change the
ifPhyAddress, the ifDescrLen, or the text of the description fields.
DLIOCGENADDR
Returns the Ethernet address in network order.
DLIOCGLPCFLG
Returns the state of the local packet copy flag in the ioe Jval field of the
iocblk structure. The local copy flag determines if packets looped back by
the driver should also be sent to the network. A non-zero value indicates
that frames should also be be sent to the network after being looped back.
The default value of this flag is zero.
DLIOCSLPCFLG
Allows a privileged process to set the local packet copy flag, causing all
packets looped back by the driver to also be sent to the network.
DLIOCGPROMISC
Returns the value of the promiscuous flag in the ioeJval of the iocblk structure. A non-zero value indicates that the Ethernet interface will receive all
frames on the network. The default value of this flag is zero.
DLIOCSPROMISC
Allows a privileged process to toggle the current state of the promiscuous
flag. When the flag is non-zero, the driver captures all frames from the network. Processes that are bound to the promiscuous SAP, or to an SAP that
matches the type field of the received frame, receive a copy of the frame.
DLIOCGETMULTI
Returns the current list of multicast addresses (if it exists).
DLIOCADDMULTI
Allows a privileged process to add a new multicast address and enable its
reception. A 6-byte buffer pointing to the multicast address must be passed
as the parameter.
DLIOCDELMULTI
Allows a privileged process to delete a multicast address by passing a 6-byte
multicast address as the parameter.
Configuration
The
imx586
driver
has
four
configurable
parameters
in
the
/etc/conf/pack.d/imx586/space.c file. If you change this file, you must

rebuild the kernel and reboot the system for the changes to take effect.

441

imx586 (7)
The configurable parameters are:
N_SAPS

Defines whether the driver should log debugging messages to the
STREAMS logger for the strace(lM) utility to display. The module ID
used with strace is 2101. A value of 0 indicates that no STREAMS debug
messages should be generated. A value of 1 enables STREAMS debug messages to be generated. You can also direct the driver to log messages temporarily by using the kernel debugger to change the value of imx586strIog
(a 4-byte integer) to 1.
Use STREAMS tracing only when debugging a network problem, because
system performance suffers when full imx586 STREAMS logging is in progress.
IFNAME

This parameter is important only in a TCP lIP networking environment. It
defines the string used in displaying network statistics. This string should
name
assigned
in
the
match
the
logical
interface
/etc/confnet.d/inet/interfaces file and with ifconfig(lM) commands used in the /etc/inet/rc.inet configuration script.

Errors
The imx586 driver can return the following error codes:
ENXIO Invalid major number or board is not installed.
ECHRNG

No minor devices left if configured as a cloned device. Increase N_SAP value
in /etc/conf/pack.d/imx586/space.c Invalid minor device number if
configured as a non-cloned device.
EPERM An

ioctl was made without the appropriate privilege.

EINVAL

An ioctl was made that did not supply a required input and I or output
buffer.
DL_NOTSUPPORTED

Requested service primitive is not supported.
DL_BADPRIM

Unknown service primitive was requested.
DL_OUTSTATE
DL_BIND_REQ was issued when the Stream was bound, or DL_tlNBIND_REQ
or DL_UNITDATA_REQ were issued when the Stream was unbound.

442

irnx586 (7)
DL_ACCESS

An attempt was made to bind to PROMISCUOUS_SAP with insufficient
privilege.
DL_BOUND

The requested SAP is already bound. A privileged process may bind to an
already bound SAP.
DL_NOTINIT
DL_UNITDATA_REQ

was issued on an Ethernet board that has gone offline

due to an error.
DL_BADDATA
DL_UNITDATA_REQ

was issued with a data size that was either larger than
the SPDU maximum or smaller than the SPDU minimum.

Files
/dev/imxS86_*
/etc/conf/pack.d/imxS86/space.c

REFERENCES
getmsg(2), ifconfig(lM), ioctl(2), open(2), putmsg(2), strace(lM)

443

inet(7}
NAME

inet - Internet protocol family
SYNOPSIS

#include
#include
DESCRIPTION

The Internet protocol family implements a collection of protocols which are centered around the Internet Protocol (IP) and which share a common address format.
The Internet family protocols can be accessed via the socket interface, where they
support the SOCICSTREAM, SOCICDGRAM, and SOCK_RAW socket types, or the Transport Level Interface (TLI), where they support the connectionless (T_CLTS) and
connection oriented (T_COTS_ORD) service types.
PROTOCOLS

The Internet protocol family comprises the Internet Protocol (IP), the Address Resolution Protocol (ARP), the Internet Control Message Protocol (ICMP), the Transmission Control Protocol (TCP), and the User Datagram Protocol (UDP).
TCP supports the socket interface's SOCICSTREAM abstraction and TLI's T_COTS_ORD
service type. UDP supports the SOCICDGRAM socket abstraction and the TLI T_CLTS
service type. See tcp(7) and udp(7). A direct interface to IP is available via both TLI
and the socket interface; See ip(7). ICMP is used by the kernel to handle and report
errors in protocol processing. It is also accessible to user programs; see iCIli>(7).
ARP is used to translate 32-bit IP addresses into 48-bit Ethernet addresses; see
arp(7).
The 32-bit IP address is divided into network number and host number parts. It is
frequency-encoded; The most-significant bit is zero in Class A addresses, in which
the high-order 8 bits represent the network number. Class B addresses have their
high order two bits set to 10 and use the high-order 16 bits as the network number
field. Class C addresses have a 24-bit network number part of which the high order
three bits are 110. Rather than using the default class A, B, or C address, a subnet
mask can be used for the network interface. See "Setting Up Subnets" in the
"Expanding Your TCP lIP Network" chapter in Network Administration for more
information on subnet masks. Subnet addressing is enabled and examined by the
following ioctl(2) commands; They have the same form as the SIOCSIFADDR command [see if(7)].
SIOCSIFNETMASK

Set interface network mask. The network mask defines the
network part of the address; If it contains more of the
address than the address type would indicate, then subnets
are in use.

SIOCGIFNETMASK

Get interface network mask.

ADDRESSING

IP addresses are four byte quantities, stored in network byte order. IP addresses
should be manipulated using the byte order conversion routines [see
byteorder(3N)].

444

inet (7)
Addresses in the Internet protocol family use the following structure:
struct sockaddr_in {
short
sin_family;
u_short sin-port;
struct
in_addr sin_addr;
char
sin_zero[8];
};

Library routines are provided to manipulate structures of this form; See inet(3N).
The sin_addr field of the sockaddr_in structure specifies a local or remote IP
address. Each network interface has its own unique IP address. The special value
INADDR_ANY may be used in this field to effect wildcard matching. Given in a
bind(3N) call, this value leaves the local IP address of the socket unspecified, so that
the socket will receive connections or messages directed at any of the valid IP
addresses of the system. This can prove useful when a process neither knows nor
cares what the local IP address is or when a process wishes to receive requests using
all of its network interfaces. The sockaddr_in structure given in the bind(3N) call
must specify an in_addr value of either IPADDR_ANY or one of the system's valid IP
addresses. Requests to bind any other address will elicit the error EADDRNOTAVAI.
When a connect(3N) call is made for a socket that has a wildcard local address, the
system sets the sin_addr field of the socket to the IP address of the network interface that the packets for that connection are routed via.
The sin-port field of the sockaddr_in structure specifies a port number used by
TCP or UDP. The local port address specified in a bind(3N) call is restricted to be
greater than IPPORT_RESERVED (defined in
#include
s

socket (AF_INET

t_open (" /dev/rawip"

open (" /dev/ip"

SOCK_RAW I

proto);

O_RDWR);

DESCRIPTION

IP is the internetwork datagram delivery protocol that is central to the Internet protocol family. Programs may use IP through higher-level protocols such as the
Transmission Control Protocol (TCP) or the User Datagram Protocol (UDP), or may
interface directly to IP. See tcp(7) and udp(7). Direct access may be via the socket
interface (using a raw socket) or the Transport Level Interface (TLI). The protocol
options defined in the IP specification may be set in outgoing datagrams.
The STREAMS driver /dev/rawip is the TLI transport provider that provides raw
access to IP. The device /dev/ip is the multiplexing STREAMS driver that implements the protocol processing of IP. The latter connects below to datalink providers
[interface drivers, see if(7)], and above to transport providers such as TCP and UDP.
Raw IP sockets are connectionless and are normally used with the sendto ( ) and
recvfrom() calls, [see send(3N) and recv(3N)] although the connect(3N) call
may also be used to fix the destination for future datagrams [in which case the
read(2) or recv(3N) and write(2) or send(3N) calls may be used]. If proto is zero,
the default protocol, IPPROTO_RAW, is used. If proto is non-zero, that protocol
number will be set in outgoing datagrams and will be used to filter incoming
datagrams. An IP header will be generated and prep ended to each outgoing
datagram; received datagrams are returned with the IP header and options intact.
A single socket option, IP_OPTIONS, is supported at the IP level. This socket option
may be used to set IP options to be included in each outgoing datagram. IP options
to be sent are set with setsockopt ( ) [see getsockopt(3N)]. The getsockopt(3N)
call returns the IP options set in the last setsockopt ( ) call. IP options on received
datagrams are visible to user programs only using raw IP sockets. The format of IP
options given in setsockopt ( ) matches those defined in the IP specification with
one exception: the list of addresses for the source routing options must include the
first-hop gateway at the beginning of the list of gateways. The first-hop gateway
address will be extracted from the option list and the size adjusted accordingly
before use. IP options may be used with any socket type in the Internet family.
At the socket level, the socket option SO_DONTROUTE may be applied. This option
forces datagrams being sent to bypass the routing step in output. Normally, IP
selects a network interface to send the datagram, and possibly an intermediate gateway, based on an entry in the routing table. See routing(4). When SO_OONTROUTE is
set, the datagram will be sent using the interface whose network number or full IP
address matches the destination address. If no interface matches, the error
ENETUNRCH will be returned.

447

IP(7}
Raw IP datagrams can also be sent and received using the TLI connectionless primitives.
Datagrams flow through the IP layer in two directions: from the network up to user
processes and from user processes down to the network. Using this orientation, IF is
layered above the network interface drivers and below the transport protocols such
as UDP and TCP. The Internet Control Message Protocol (ICMP) is logically a part of
IP. See icmp(7).
IP provides for a checksum of the header part, but not the data part of the
datagram. The checksum value is computed and set in the process of sending
datagrams and checked when receiving datagrams. IP header checksumming may
be disabled for debugging purposes by patching the kernel variable ipcksum to
have the value zero.
IP options in received datagrams are processed in the IP layer according to the protocol specification. Currently recognized IF options include: security, loose source

and record route (LSRR), strict source and record route (SSRR), record route, stream
identifier, and internet timestamp.
The IP layer will normally forward received datagrams that are not addressed to it.
Forwarding is under the control of the kernel variable ipforwarding: if ipforwarding is
zero, IP datagrams will not be forwarded; if ipforwarding is one, IP datagrams will
be forwarded. ipforwarding is usually set to one only in machines with more than
one network interface (internetwork routers). This kernel variable can be patched
to enable or disable forwarding.
The IP layer will send an ICMP message back to the source host in many cases when
it receives a datagram that can not be handled. A time exceeded ICMP message will
be sent if the time to live field in the IP header drops to zero in the process of forwarding a datagram. A destination unreachable message will be sent if a datagram
can not be forwarded because there is no route to the final destination, or if it can
not be fragmented. If the datagram is addressed to the local host but is destined for
a protocol that is not supported or a port that is not in use, a destination unreachable message will also be sent. The IP layer may send an ICMP source quench message if it is receiving datagrams too quickly. ICMP messages are only sent for the
first fragment of a fragmented datagram and are never returned in response to
errors in other ICMP messages.
The IP layer supports fragmentation and reassembly. Datagrams are fragmented on
output if the datagram is larger than the maximum transmission unit (MTU) of the
network interface. Fragments of received datagrams are dropped from the
reassembly queues if the complete datagram is not reconstructed within a short
time period.
Errors in sending discovered at the network interface driver layer are passed by IP
back up to the user process.
SEE ALSO

connect(3N), get sockopt (3N), icmp(7), if(7), inet(7), read(2), recv(3N),
routing(4), send(3N), tcp(7), udp(7), write(2)

448

IP (7)
Postel, Jon, Internet Protocol - DARPA Internet Program Protocol Specification, RFC 791,
Network Information Center, SRI International, Menlo Park, CaliL, September 1981
DIAGNOSTICS

A socket operation may fail with one of the following errors returned:
A IP broadcast destination address was specified and the caller
was not the privileged user.
EISCONN
An attempt was made to establish a connection on a socket
which already had one, or to send a datagram with the destination address specified and the socket was already connected.
EACCES

EMSGSIZE

ENETUNREACH

An attempt was made to send a datagram that was too large
for an interface, but was not allowed to be fragmented (such as
broadcasts).
An attempt was made to establish a connection or send a
datagram, where there was no matching entry in the routing
table, or if an ICMP destination unreachable message was
received.

ENOTCONN

A datagram was sent, but no destination address was specified,
and the socket had not been connected.

ENOBUFS

The system ran out of memory for fragmentation buffers or
other internal data structures.
An attempt was made to create a socket with a local address
that did not match any network interface, or an IP broadcast
destination address was specified and the network interface
does not support broadcast.

EADDRNOTAVAIL

The following errors may occur when setting or getting IP options:
EINVAL
An unknown socket option name was given.
EINVAL
The IP option field was improperly formed; an option field was
shorter than the minimum value or longer than the option
buffer provided.
NOTES

Raw sockets should receive ICMP error packets relating to the protocol; currently
such packets are simply discarded.
Users of higher-level protocols such as TCP and UDP should be able to see received
IP options.

449

kbd(7)
NAME

kbd - generalized string translation module
DESCRIPTION

The STREAMS module kbd is a programmable string translation module. It performs two types of operations on an input stream: the first type is simple byteswapping via a lookup table, the second is string translation. It is useful for code
set conversion and compose-key or dead-key character production on terminals and
production of overstriking sequences on printers. It also can be used for minor
types of key-rebinding, expansion of abbreviations, and keyboard re-arrangement
(an example of the latter would be swapping the positions of the Y and Z keys,
required for German keyboards, or providing Dvorak keyboard emulation for
QWERTY keyboards). The kbdcamp(lM) manual page discusses table construction,
the input language, and contains sample uses. It is intended mainly to aid administrators in configuring the module on a particular system; the user interface to the
module is only through the commands kbdload(lM) and kbdset(l).
The kbd module works by changing an input stream according to instructions
embodied in tables. It has no built in default tables. Some tables may be loaded
when the system is first brought up by pushing the module and loading standard or
often-used tables [see kbdload(lM)] that are retained in main-memory across invocations and made available to all users. These are called public tables. Users may
also load private tables at any time; these tables do not remain resident.
With the kbdset command, users may query the module for a list of available and
attached tables, attach various tables, and set the optional per-user hotkey, hot-key
mode, and verbose string for their particular invocation.
When a user attaches more than one table, the user's hot-key may be used to cycle
to the next table in the list. If only one table is specified, the hot-key may be used to
toggle translation on and off. When multiple tables are in use, the hot-key may be
used to cycle through the list of tables. [See kbdset(l) for a description of the available modes.]
In its initial state, kbd scans input for occurrences of bytes beginning a translation
sequence. When receiving such a byte, kbd attempts to match subsequent bytes of
the input to programmed sequences. Input is buffered beginning with the byte that
caused the state change and is released if a match is not found. When a match fails,
the first byte of the invalid sequence is sent upstream, the buffered input is shifted,
and the scan begins again with the resulting input sequence. If the current table
contains an error entry, its value (one or more bytes) is substituted for the offending
input byte. When a sequence is found to be valid, the entire sequence is replaced
with the result string specified for it.
The kbd module may be used in either the read or write directions, or both simultaneously. Maps and hot-keys may be specified independently for input and output.
The kbd also supports the use of external kernel-resident functions as if they were
tables; once declared and attached (via kbdload and kbdset respectively) they may
be used as simple tables or members of composites. To accomplish this, kbd understands the registration functions of the alp module and can access any function
registered with that module. Further information on external functions and their

450

kbd(7)
definition is contained in alp(7). External functions are especially useful in supporting multibyte code set conversions that would be difficult or impossible with
normal kbd tables.
Limitations
It is not an error to attach multiple tables without defining a hot-key, but the tables
will not all be accessible. It is recommended that the user's hot-key be set before
loading and attaching tables to avoid unpleasant side effects when an unfamiliar
arrangement is first loaded.

Each user has a limitation on the amount of memory that may be used for private
and attached tables. This "quota" is controlled by the kbd_umeIn variable described
below. When a user that is not a privileged user attempts to load a table or create a
composite table, the quota is checked, and the load will fail if it would cause the
quota to be exceeded. When a composite table is attached, the space for attachment
(which requires more space than the composite table itself) is charged against this
quota (attachment of simple tables is not charged against the quota). The quota is
enforced only when loading new tables. Detaching temporarily from unneeded
composite tables may reduce the current allocation enough to load a table that
would otherwise fail because of quota enforcement. To minimize chances of failure
while loading tables, it is advisable to load all required tables and make all required
composite tables before attaching any of them.
Configuration Parameters
The master (or space. c) file contains configurable parameters.
NKBDU is the maximum number of tables that may be attached by a single user. The

number should be large enough to cover uncommon cases, and must be at least 2.
Default is 6.
ZUMEM, from which the variable kbd_umem is assigned, is the maximum number of
bytes that a user (other than a privileged user) may have allocated to private tables
(that is, the quota). Default is 4096.

is the default timer value for timeout mode. It is the number of clock ticks
allowed before timing out. The value of one clock tick depends on the hardware,
but is usually 1/100 or 1/60 of a second. A timeout value of 20 is 1/5 second at
100Hz; with a 60Hz clock, a value of 12 produces a 1/5 second timeout. Values
from 5 to 400 inclusive are allowed by the module; if the value set for KBDTlME is
outside this range, the module forces it to the nearest limit. (This value is only a
default; users may change their particular stream to use a different value depending
on their own preferences, terminal baud-rate, and typing speed.)
KBDTlME

FILES

/usr/lib/kbd
/usr/lib/kbd/*.map

- directory containing system standard table files.
- source for some system table files.

SEE ALSO

alp(7), kbdcomp(lM), kbdload(lM), kbdset(l)
NOTES

NULL characters may not be used in result or input strings, because they are used as
string delimiters.

451

keyboard (7)
NAME

keyboard - system console keyboard
DESCRIPTION

The system console has two separate parts: the keyboard and the display [see
display (7)].

The keyboard is used to type data, and send certain control signals to the computer.
UNIX system software performs terminal emulation on the console screen and keyboard, and, in doing so, makes use of several particular keys and key combinations.
These keys and key combinations have special names that are unique to the UNIX
system, and mayor may not correspond to the keytop labels on your keyboard.
When you press a key, one of the following happens:
- An ASCII value is entered
- The meaning of another key, or keys, is changed.
- A string is sent to the computer.
- A function is initiated.
When a key is pressed (a keystroke), the keyboard sends a scancode to the computer. This scancode is interpreted by the keyboard driver. The actual code
sequence delivered to the terminal input routine [see tennio (7)] is defined by a set
of internal tables in the driver. These tables can be modified by software (see the
discussion of ioctl calls below). In addition, the driver can be instructed not to do
translations, delivering the keyboard up and down scan codes directly.
Changing Meanings

The action performed by a key can be changed by using certain keys in combination. For example, the SHIFT key changes the ASCII values of the alphanumeric
keys. Holding down the CTRL key while pressing another key sends a control code
(such as CTRL-d, CTRL-s, and CTRL-q). Holding down the ALT key also modifies a
key's value. The SHIFT, CTRL, and ALT keys can be used in combination.
Switching Screens

To change screens (virtual terminals), first run the vtlmgr command [see
vtlmgr(l)]. Switch the current screen by typing ALT-SYSREQ (also labeled ALTPRINTSCRN on some systems) followed by a key that identifies the desired screen.
Any active screen can be selected by following ALT-SYSREQ with Fn, where Fn is
one of the function keys. Fl refers to the first virtual terminal screen, F2 refers to
the second virtual terminal screen, and so on. ALT-SYSREQ h (home) refers to the
main console display (ldev/console). The next active screen can be selected with
ALT-SYSREQ n, and the previous screen can be selected with ALT-SYSREQ p.
The default screen switch enable sequence (ALT-SYSREQ) is configurable. The SYSREQ table entry can be changed by software (see discussion of ioctl calls below).
Special Keys

The follOWing table shows which keys on a typical console correspond to UNIX system keys. In this table, a hyphen (-) between keys means you must hold down the
first key while pressing the second. The mapping between characters that generate
signals and the signal generated is set with stty(l), and may be changed [see
stty(l)].

452

keyboard (7)
Name

Keytop

Action

INTR

DEL

Stops current action and returns to the shell. This key is
also called the RUB OUT or INTERRUPT key.

BACKSPACE

f-o

Deletes the first character to the left of the cursor.
Note that the "cursor left" key also has a left arrow (f-o) on
its key top, but you cannot backspace using that key.

CTRL-d

CTRL-D

Signals the end of input from the keyboard; also exits
current shell.

CTRL-h

CTRL-H

Deletes the first character to the left of the cursor. Also
called the ERASE key.

CTRL-q

CTRL-Q

Restarts printing after it has been stopped with CTRL-s.

CTRL-s

CTRL-S

Suspends printing on the screen (does not stop the program).

CTRL-u

CTRL-U

Deletes all characters on the current line. Also called the
KILL key.

CTRL-\

ESCAPE

ESC

Quits current command and creates a core
file, if allowed. (Recommended for debugging only.)
Special code for some programs. For example, changes
from insert mode to command mode in the vi(l) text editor.

RETURN

(down-left
arrow or

Terminates a command line and initiates an action from the
shell.

ENTER)
Fn

Function key n. Fl-F12 are unshifted, F13-F24 are shifted
Fl-F12, F25-F36 are CTRL-Fl through F12, and F37-F48
are CTRL-SHIFT-Fl through F12.
The next Fn keys (F49-F60) are on the number pad
(unshifted):
F55 - '6'
F49 - '7'
F50 - '8'
F56 - '+'
F57 - '1'
F51 - '9'
F58 - '2'
F52 - ' ,
F53 - '4'
F59 - '3'
F54 - '5'
F60 - '0'

Keyboard Map
The keyboard mapping structure is defined in /usr/include/sys/kd.h. Each key
can have ten states. The first eight states are:
-

BASE
SHIFT
CTRL
ALT

CTRL-SHIFT
ALT-SHIFT
ALT-CTRL
ALT-CTRL-SHIFT

453

keyboard (7)
The two remaining states are indicated by two special bytes. The first byte is a special state byte whose bits indicate whether the key is special in one or more of the
first eight states. The second byte is one of four codes represented by the characters
C, N, B, or 0 which indicate how the lock keys affect the particular key.
The following table describes the default keyboard mapping. All values, except for
special keywords (which are described later), are ASCII character values.
Heading
Description
SCAN CODE

BASE

SHIFT
LOCK

This column contains the scan code generated by the keyboard
hardware when a key is pressed. There are no table entries for the
scan code generated by releasing a key.
This column contains the normal value of a key press.
This column contains the value of a key press when the SHIFT is
also being held down.
This column indicates which lock keys affect that particular key:
- C indicates CAPSLOCK
- N indicates NUMLOCK
- B indicates both
- a indicates locking is off

The remaining columns are the values of key presses when combinations of the
CTRL, ALT and SHIFT keys are also held down.
The SRQTAB column entry is included in this table to provide a simple index of the
default virtual terminal key selectors to the scan code to which it is assigned. The
actual SRQTAB table is a stand-alone table which can be read or written using the
KDGKBENT and KDSKBENT ioctl calls.

454

keyboard (7)

SCAN
CODE

BASE

SHIFT

CTRL

CTRL
SHIFT

ALT

ALT
SHIFT

ALT
CTRL

ALT
CTRL
SHIFT

esc

2
3

'1'

esen

'2'

'@'

'1'
'2'

'3'

nul
'3'

5
6
7
8

'4'

'#'
'$'

esen
esen
esen
esen

esen
esen
esen

nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
bs

btab

nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap

cr
ktrl

nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap

nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap

Ismft

Ishift

nap
nap

10
11
12

'5'
'6'
'7'
'8'
'9'
'0'

'&'

'C
')'

'3'
'4'

'4'

'5'
'6'

'5'

'7'
'8'
'9'
'0'

rs
'T
'8'
'9'
'0'
ns

esen

esen
esen
esen

esen
esen
esen
esen
esen

esen
esen

'='

esen

14
15
16

ht
'q'

btab
'Q'

17
18

'w'

'W'
'E'

19
20
21
22

'r'

btab
del
etb
enq
dc2
dc4
em
nak
ht
si
die

btab
esen
esen
escn
esen
esen
esen
esen
esen
esen
esen
esen
esen
cr
letrl
esen
esen
esen
esen
esen
esen
esen
esen
esen
esen
esen
escn
Ismft
esen
esen

'+'

'j'

'k'

'K'

ht
del
etb
enq
dc2
dc4
em
nak
ht
si
die
esc
gs
cr
letrl
soh
dc3
eat
ack
bel
bs
nl
vt

'1'

'L'

'e'

'I'

'R'
'T'

'y'

'Y'

'u'

'U'

23
24

'i'
'0'

T
'0'

25
26
27
28
29
30
31

'p'

'P'

T
T

'{'

32
33
34
35
36
37
38
39
40
41

42
43

letrl

'a'

'A'

's'
'd'
'f'
'g'
'h'

'S'
'D'

'F'
'G'
'H'

esen

esen
esen

esen
esen
esen
esen
esen

esen
escn

nap
nap

esen
esen

cr
ktrl

letrl
soh
dc3
eat
ack
bel

bs
n1
vt

esen
esen
esen
esen

esen
esen
esen
esen
esen

esen
esen

esen
Ishift
'\ \'
'z'

Ishift

Ishift
fs

Ismft

Ishift

'I'

esen

'Z'

sub

esen

k_dbg

letrl

LOCK

SRQT AB

o
o
o
o
o
o
o
o
o
o
o
o
o
o
o

nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap

K PREY

o
o
o
o

nap
nap
nap
nap
nap
nap
nap

C
C
C
C
C
C
C
C

C
C
C
C

K FRCNEXT

nap

KVTF

C
C

nap
nap
nap
nap
nap
nap
nap
nop
nap

o
o
o
o
o
C

455

keyboard (7)

SCAN
CODE
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

456

BASE

SHIFT

CTRL

'x'

'X'
'C'

can
etx
syn
stx
so
cr

'c'
'v'

'V'

'b'

'B'

'n'

'N'
'M'

'm'

'<'
'>'

,/'

'?'

, /'

rshift

lalt

clock
fkey1
fkey2
fkey3
fkey4
fkey5
fkey6
fkey7
fkey8
fkey9
fkeylO
nlock
slock
fkey49
fkey50
fkey51
fkey52
fkey53
fkey54
fkey55
fkey56
fkey57
fkey58
fkey59
fkey60
del
fkey60
fkey58
fkey53
fkeyll
fkey12

clock
fkey13
fkey14
fkey15
fkey16
fkey17
fkey18
fkey19
fkey20
fkey21
fkey22
nlock
slock
'7'
'8'

lalt
nul
clock
fkey25
fkey26
fkey27
fkey28
fkey29
fkey30
fkey31
fkey32
fkey33
fkey34
nlock
slock
fkey49
fkey50
fkey51
fkey52
fkey53
fkey54
fkey55
fkey56
fkey57
fkey58
fkey59
fkey60
del
fkey60
fkey58
fkey53
fkey35
fkey36

'9'

'4'
'5'
'6'

'+'
'1'
'2'
'3'
'0'

fkey26
fkey58
fkey53
fkey23
fkey24

CTRL
SHIFT
can
etx
syn
stx
so
cr
'<'
'>'
ns
rshift

lalt
nul
clock
fkey37
fkey38
fkey39
fkey40
fkey41
fkey42
fkey43
fkey44
fkey45
fkey46
nlock
slock
'7'
'8'
'9'
'4'
'5'
'6'

'+'
'1'
'2'
'3'
'0'

nop
fkey58
fkey53
fkey47
fkey48

ALT
esen
escn
escn
esen
esen
escn
esen
esen
escn
rshift
esen
lalt
esen
clock
fkey1
fkey2
fkey3
fkey4
fkey5
fkey6
fkey7
fkey8
fkey9
fkeylO
nlock
slock
fkey49
fkey50
fkey51
fkey52
fkey53
fkey54
fkey55
fkey56
fkey57
fkey58
fkey59
fkey60
del
sysreq
fkey58
fkey53
fkeyll
fkey12

ALT
SHIFT

ALT
CTRL

ALT
CTRL
SHIFT

escn
escn
escn
escn
escn
escn

nop
nop
nop
nop
nop
nop
nop
nop
nop
rshift
nop
lalt
nop
clock
fkey25
fkey26
fkey27
fkey28
fkey29
fkey30
fkey31
fkey32
fkey33
fkey34
nlock
slock
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
rboot
sysreq
fkey58
fkey53
fkey35
fkey36

nop
nop
nop
nop
nop
nop
nop
nop
nop
rshift
nop
lalt
nop
clock
fkey37
fkey38
fkey39
fkey40
fkey41
fkey42
fkey43
fkey44
fkey45
fkey46
nlock
slock
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
sysreq
fkey58
fkey53
fkey47
fkey48

esen

esen
escn
rshift
esen
lalt
esen

clock
fkey13
fkey14
fkey15
fkey16
fkey17
fkey18
fkey19
fkey20
fkey21
fkey22
nlock
slock
esen
escn
esen
escn
esen
escn
esen
escn
esen
escn
esen

esen
esen

sysreq
fkey58
fkey53
fkey23
fkey24

LOCK

SRQTAB

C
C
C
C
C
C

nop
nop
nop
nop
K NEXT
nop
nop
nop
nop
nop
nop
nop
nop
nop
K VTF+1
K VTF+2
K VTF+3
K VTF+4
K VTF+5
K VTF+6
K VTF+7
K VTF+8
K VTF+9
K VTF+lO

o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
N
N
N
N

N
N

N
N
N
N
N
N
N

o
o
o
o
o

K VTF+l1
K VTF+12

keyboard (7)

SCAN
CODE
89
90
91
92

93
94
95
96
97
98
99
100
101
102

103
104
105
106
107
108

109

110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

BASE

SHIFT

CTRL

CTRL
SHIFT

nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap

nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nop
nap

nap
nap
nop
nop
nap
nap
nap
nap
nap
nap
nap
nap
nop
nap
nop
nap
nap
nap

nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap

ALT

ALT
SHIFT

ALT
CTRL

ALT
CTRL
SHIFT

nap
nap
nop
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap

nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap
nap

fkey53

nap
nap
nap

nap
nap
nap
nap
nap
nap

nap
nap
nop
nap
nap
nap

nap
nap
nap
nap
nap
nap

fkey51

nap
nap

nap
nap
nap
nap
nap
nap

ralt

raIt

rctrl
slack

retrl
slack

rctrl
brk

rctrl
slack

rctrl
slock

rctrl
brk

'I'
nap

'/'
nap

nap
nap

escn

nap

nap
nap

slack
fkey50
del
fkey57
fkey60

brk

slack

brk

nap

nop

nap

fkey55
fkey59
fkey49

fkcy55
fkey59
fkey49

del

rboot

del

nap
nap
nap
nap
nap
nap

LOCK

SRQTAB

o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o

K
K
K
K
K
K
K
K
K
K
K
K
K
K
K
K
K
K

NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP

K
K
K
K
K
K
K
K

NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP

nline
K
K
K
K
K
K
K
K
K
K
K

NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP

The following table lists the value of each of the special keywords used in the
preceding tables. The keywords are used only in the preceding tables for readability. In the actual keyboard map, a special keyword is represented by its value
with the corresponding special state bit being set.

457

keyboard (7)
Name

458

Value
0
2
3
4
5
6
7
8

Meaning

nop
lshift
rshift
clock
nlock
slock
alt
btab
ctrl
lalt
ralt
lctrl
rctrl
agr
fkey1

10
11
12
13
14
27

fkey96
sysreq
brk
escn

122
123
124
125

esco

126

escl

127

rboot
debug
NEXT
PREV
FNEXT
FPREV
VTF

128
129
130
131
132
133
134

VTL
MGRF

148
149

Virtual Terminal Last (VT14)
Virtual Terminal Manager First. Allows assigning special
significance to key sequence for actions by virtual terminal
layer manager. Used in SRQTAB table.

MGRL

179

Virtual Terminal Manager Last. Used in SRQTAB table.

No operation - no action from keypress
Left-hand shift
Right-hand shift
Caps lock
Numeric lock
Scroll lock
Alt key
Back tab key - generates fixed sequence (ESC[ Z)
Control key
Left-hand alt key
right-hand alt key
Left-hand control key
Right-hand control key
ALT-GR key (European keyboards only)
Function key #1

Function key #96
System request
Break key
Generate an ESC N x sequence, where x is the un-alt'ed value
of the scan code
Generate an ESC 0 x sequence, where x is the un-alt' ed value
of the scan code
Generate an ESC L x sequence, where x is the un-alt' ed value
of the scan code
Reboot system
Invoke kernel debugger
Switch to next virtual terminal on queue
Switch to previous virtual terminal on queue
Forced switch to next virtual terminal on queue
Forced switch to previous virtual terminal on queue
Virtual Terminal First (VTOO)

keyboard (7)
The following table lists names and decimal values for ASCII characters in the
preceding table. Names are used in place of numeric constants to make it easier to
read the scan code table. Only the decimal values are placed in the ioctl buffer.
These values are taken from ascii(5).
Name
nul
soh
stx
etx
eat
enq
ack
bel
bs
ht
nl
vt
np
cr
so
si
dIe

Value
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Name

Value

del
dc2
dc3
dc4
nak
syn
etb
can
em
sub
esc
fs
gs
rs
ns
del

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
127

String Key Mapping

The string mapping table is an array of 512 bytes (typedef strmap_t) containing
null-terminated strings that redefine the function keys. The first null-terminated
string is assigned to the first function key, the second string is assigned to the
second function key, and so on.
There is no limit to the length of any particular string; however, the whole table can
not exceed 512 bytes, including nulls. To make a string a null, add extra null
characters. The following table contains default function key values.

459

keyboard (7)
Default Function Key Values
Function
Key #
1
2
3
4
5
6
7

8
9

10
11

Function

Shift
Function

Ctrl
Function

Ctrl
Shift
Function

ESCOP
ESCOQ
ESC OR
ESC OS
ESCOT
ESCOU
ESCOV
ESC OW
ESC OX
ESCOY
ESCOZ
ESCOA

ESCOp
ESCOq
ESC Or
ESC Os
ESCOt
ESCOu
ESCOv
ESC Ow
ESC Ox
ESCOy
ESCOz
ESCOa

ESCOP
ESCOQ
ESC OR
ESC OS
ESCOT
ESCOU
ESCOV
ESC OW
ESC OX
ESCOY
ESCOZ
ESCOA

ESCOp
ESCOq
ESC Or
ESC Os
ESCOt
ESCOu
ESCOv
ESC Ow
ESC Ox
ESCOy
ESCOz
ESCOa

loctl Calls:
KDGKBMODE

This call gets the current keyboard mode. It returns one of the following
values, as defined in /usr/include/sys/kd.h:
#defineK_RAW
OxOO
/* Send row scan codes */
#defineK_XLATE
Ox01
/* Translate to ASCII */
KDSKBMODE

This call sets the keyboard mode. The argument to the call is either K_RAW
or K_XLATE. By using raw mode, the program can see the raw up and down
scan codes from the keyboard. In translate mode, the translation tables are
used to generate the appropriate character code.
KDGKBTYPE

This call gets the keyboard type. It returns one of the following values, as
defined in /usr/include/sys/kd.h:
#defineKB_84
#define KB_IO 1
#defineKB_OTHER

1
2
3

/*84 key keyboard* /
/*101 key keyboard* /
/*Other type keyboard */

KDGKBENT

This call reads one of the entries in the translation tables. The argument to
the call is the address of one of the following structures, defined in
/usr/include/sys/kd.h, with the first two fields filled in:
struct kbentry {
unchar kb_table;
unchar kb_index;
ushort kb_value;
};

460

/* Table to use */
/* Entry in table */
/* Value to get/set */

keyboard (7)
Valid values for the kb table field are:
#defineK_NORMTAB
#defineK_SHIFTTAB
#defineK_ALTTAB
#defineK_ALTSHIFTTAB
#defineK_SRQTAB

OxOO
OxOl
Ox02
Ox03
Ox04

/* Base */
/* Shifted * /
/*Alt*/
/* Shifted alt * /
/* Select sysreq
table * /

The ioctl will get the indicated entry from the indicated table and return it
in the third field.
The K_SRQTAB value for the kb table field allows access to the scancode
indexed table which allows assignment of a given virtual terminal selector
(K_VTF-K_VTL) or the virtual terminal layer manager (K_MGRF-K_MGRL)
specialkey assignments.
The virtual terminal selector (K_VTF) is normally associated with
/dev/ttyOO, on which the user login shell is commonly found. The following terminal selectors also are used to select virtual terminals:
K VTF+ 1 for the 1st virtual terminal (I dev /vt01)
K=VTF+2 for the 2nd virtual terminal (ldev /vt02)

K_VTF+ 12 for the 12th virtual terminal (I dev /vt12)
KDSKBENT
This call sets an entry in one of the translation tables. It uses the same structure as the KDGKBENT ioctl, but with the third field filled in with the value
that should be placed in the translation table. This can be used to partially
or completely remap the keyboard. This ioctl does not work for all keycodes.
The kd driver provides support for virtual terminals. The console minor device,
/dev/vtmon, provides virtual terminal key requests from the kd driver to the
process that has /dev/vtmon open. Two ioctls are provided for virtual terminal
support:
VT_GETSTATE
The VT_GETSTATE ioctl returns global virtual terminal state information.
It returns the active virtual terminal in the v active field, and the number of
active virtual terminals and a bit mask of the-global state in the v_state open
field, where bit x is the state of vt x (1 indicates that the virtual terminal is
open).
VT_SENDSIG
The VT_SENDSIG ioctl specifies a signal (in v_signal) to be sent to a bit
mask of virtual terminals (in v_state).

461

keyboard (7)
The data structure used by the VT_GETSTATE and VT_SENDSIG ioctls is:
struct vt_stat {
ushort v_active; /* active vt */
ushort v_signal; /* signal to send (VT_SENDSIG) */
ushort v_state; /* vt bit mask (VT_SENDSIG and VT_GETSTATE) */
};

and is defined in /usr/include/sys/vt.h.
VT_OPENQRY
The VT_OPENQRY

ioctl is used to get the next available virtual terminal. It
inquires if this vt is already open. This value is set in the last argument of
the ioctl (2) call.

GIO_KEYMAP

This call gets the entire keyboard mapping table from the kernel. The structure of the argument is given in /usr/include/sys/kd.h.
PIO_KEYMAP

This call sets the entire keyboard mapping table. The structure of the argument is given in /usr/include/sys/kd.h.
GIO_STRMAP

This call gets the function key string mapping table from the kernel. The
structure of the argument is given in /usr/include/sys/kd.h.
PIO_STRMAP

This call sets the function key string mapping table. The structure of the
argument is given in /usr/include/sys/kd.h.
TIOCKBOF

Extended character codes are disabled. This is the default mode.
TIOCKBON

Allows extended characters to be transmitted to the user program when the
extended keys are enabled. Then the keyboard is said to be fully enabled.
The extended characters are transmitted as a null byte followed by a second
byte containing the character's extended code. When a true null byte is sent,
it is transmitted as two consecutive null bytes.
When the keyboard is fully enabled, an 8-bit character code can be obtained by
holding down the ALT key and entering the 3-digit decimal value of the character
from the numeric keypad. The character is transmitted when the ALT key is
released.
Some keyboard characters have special meaning. Under default operations, pressing the DELETE key generates an interrupt signal that is sent to all processes designated with the associated control terminal. When the keyboard is fully enabled,
holding down the ALT key and pressing the 8 key on the home keyboard (not on the
numeric keypad) returns a null byte followed by Ox7F. This will produce the same
effect as the DELETE key (Ox7F) unless you have executed the stty(l) command
with the -isig option.

462

keyboard (7)
KBENABLED

If the keyboard is fully enabled (TIOCKBON), a non-zero value will be
returned. If the keyboard is not fully enabled (TIOCKBOF), a value of zero
will be returned.
GETFKEY

Obtains the current definition of a function key. The argument to the call is
the address of one of the following structures defined in
/usr/include/sys/kd.h:
struct fkeyarg {
unsigned short keynum;
unchar
keydef [MAXFK1;
I*Comes from ioctl.h via comcrt.h* /
char
flen;
};

The function key number must be passed in keynum (see arg structure
above). The string currently assigned to the key will be returned in keydeJ
and the length of the string will be returned in flen when the ioctl is
performed.
SETFKEY

Assigns a given string to a function key. It uses the same structure as the
keynum, the
string must be passed in keydeJ, and the length of the string (number of
characters) must be passed inflen.
GETFKEY ioctl. The function key number must be passed in

FILES

/dev/console
/dev/vtOO-n
/usr/include/sys/kd.h
SEE ALSO

ascii(5), console(7), display(7), ioctl(2), stty(l), termio(7), vtlmgr(l)

463

kmem(7)
NAME

kmem - perform I/O on kernel memory based on symbol name
SYNOPSIS

#include
int ioctl (int kmemfd, MIOC_READKSYM, st:ruct mioc_rksym *rks);
int ioctl (int kmemfd, MIOC_IREADKSYM, st:ruct mioc_rksym *rks);
int ioctl (int kmemfd, MIOC_WRITEKSYM, st:ruct mioc_rksym *rks);
DESCRIPTION

When used with a valid file descriptor for /dev/kmem (kmemfd), these ioctl commands [see ioctl(2)] can be used to read or write kernel memory based on information provided in the mioc_rksym structure, which includes the following
members:
char *mirk_symname;
void *mirk_buf;
size_t mirk_buflen;

1* symbol at whose address read will start *1
1* buffer into which data will be written *1
1* length (in bytes) of read buffer *1

The second argument to ioctl determines which I/O operation is being performed:
ioctl

Meaning

MIOC_READKSYM

Read bufLen bytes of kernel memory starting at the address for
symname into buf.

MIOC_IREADKSYM

Read sizeof (void *) bytes of kernel memory starting at the
address for symname and use that as the address from which to
read bufLen bytes of kernel memory into buf.

MIOC_WRITEKSYM

Write bufLen bytes into kernel memory starting at the address
for symname from buf.

DIAGNOSTICS

In addition to the error conditions listed on ioctl(2), these ioctl commands can
fail for the following reasons:
EBADF

kmemfd open for reading and this is MIOC_WRITEKSYM or
kmemfd open for writing and this is MIOC_READKSYM

EFAULT

Value of mirk_buflen results in attempt to read outside kernel virtual address space, or the third argument to ioctl is
an invalid pointer, or an invalid pointer is given for the symbol name or buffer in the mioc_rksym structure
Second argument to ioctl is invalid
Symbol name is longer than MAXSYMNMLEN characters
Symbol names not found in the running kernel (including
loaded modules)
kmemfd open on wrong minor device (that is, not /dev/kmem)

EINVAL
ENAMETOOLONG
ENOMATCH

ENXIO

464

kmem(7)
SEE ALSO

getksym(2), ioctl(2), nlist(3E)

465

Idterm (7)
NAME

ldterm - standard STREAMS terminal line discipline module
DESCRIPTION

ldterm is a STREAMS module that provides most of the tennio(7) terminal interface. This module does not perform the low-level device control functions specified
by flags in the c_cflag word of the termio/termios structure or by the IGNBRK,
IGNPAR, PARMRK, or INPCK flags in the c_iflag word of the termio/termios structure; those functions must be performed by the driver or by modules pushed below
the ldterm module. All other termio/termios functions are performed by
ldterm; some of them, however, require the cooperation of the driver or modules
pushed below ldterm and may not be performed in some cases. These include the
IXOFF flag in the c_iflag word and the delays specified in the c_oflag word.
ldterm also handles EUC and multi-byte characters.

When ldterm is pushed onto a stream, the open routine initializes the settings of
the tennio flags. The default settings are:
c_iflag
c_oflag
c_cflag
c_lflag

BRKINTi ICRNLi IXONi ISTRIP
OPOSTiONLCRiTAB3

0
ISIGilCANONiECHOiECHOK

The remainder of this section describes the processing of various STREAMS messages on the read- and write-side.
Read-side Behavior

Various types of STREAMS messages are processed as follows:
M_BREAK

When this message is received, either an interrupt signal is generated or
the message is treated as if it were an M_DATA message containing a single ASCII NUL character, depending on the state of the BRKINT flag.

M_DATA

This message is normally processed using the standard termio input
processing. If the lCANON flag is set, a single input record ("line") is
accumulated in an internal buffer and sent upstream when a lineterminating character is received. If the lCANON flag is not set, other
input processing is performed and the processed data are passed
upstream.
If output is to be stopped or started as a result of the arrival of characters (usually CNTRL-Q and CNTRL-S), M_STOP and M_START messages are
sent downstream. If the IXOFF flag is set and input is to be stopped or
started as a result of flow-control considerations, M_STOPI and
loLSTARTI messages are sent downstream.
M_DATA messages are sent downstream, as necessary, to perform echo-

ing.
If a signal is to be generated, an M_FLUSH message with a flag byte of
FLUSHR is placed on the read queue. If the signal is also to flush output,
an M_FLUSH message with a flag byte of FLUSHW is sent downstream.

466

Idterm (7)
M_CTL

If the size of the data buffer associated with the message is the size of
struct iocblk, Idterm will perform functional negotiation to determine where the termio(7) processing is to be done. If the command
field of the iocblk structure (ioc_cmd) is set to MC_NO_CANON, the input
canonical processing normally performed on M_DATA messages is disabled and those messages are passed upstream unmodified; this is for
the use of modules or drivers that perform their own input processing,
such as a pseudo-terminal in TIOCREMOTE mode connected to a program
that performs this processing. If the command is MC_DO_CANON, all input
processing is enabled. If the command is MC_PART_CANON, then an
M_DATA message containing a termios structure is expected to be
attached to the original M_CTL message. The Idterm module will examine the iflag, oflag, and Iflag fields of the termios structure and
from then on will process only those flags which have not been turned
ON. If none of the above commands are found, the message is ignored;
in any case, the message is passed upstream.

M_FLUSH

The read queue of the module is flushed of all its data messages and all
data in the record being accumulated are also flushed. The message is
passed upstream.

M_IOCACK

The data contained within the message, which is to be returned to the
process, are augmented if necessary, and the message is passed
upstream.

All other messages are passed upstream unchanged.
Write-side Behavior

Various types of STREAMS messages are processed as follows:
M_FLUSH
M_IOCTL

M_DATA

The write queue of the module is flushed of all its data messages and
the message is passed downstream.
The function of this ioctl is performed and the message is passed
downstream in most cases. The TCFLSH and TCXONC ioctls can be performed entirely in the Idterm module, so the reply is sent upstream and
the message is not passed downstream.
If the OPOST flag is set, or both the XCASE and lCANON flags are set, output processing is performed and the processed message is passed
downstream along with any M_DELAY messages generated. Otherwise,
the message is passed downstream without change.

All other messages are passed downstream unchanged.
ioetls

The following ioctls are processed by the Idterm module. All others are passed
downstream. EUC_WSET and EUC_WGET are I_STR ioctl calls whereas other
ioctls listed here are TRANSPARENT ioctls.
TCGETS/TCGETA

The message is passed downstream; if an acknowledgment is seen, the
data provided by the driver and modules downstream are augmented
and the acknowledgement is passed upstream.

467

Idterm (7)
TCSETS/TCSETSW/TCSETSF/TCSETA/TCSETAW/TCSETAF

TCFLSH

TCXONC

TCSBRK
EUC_WSET

EUC_WGET

The parameters that control the behavior of the Idterm module are
changed. If a mode change requires options at the stream head to be
changed, an M_SETOPTS message is sent upstream. If the lCANON flag is
turned on or off, the read mode at the stream head is changed to
message-nondiscard or byte-stream mode, respectively. If the TOSTOP
flag is turned on or off, the tostop mode at the stream head is turned on
or off, respectively.
If the argument is 0, an M_FLUSH message with a flag byte of FLUSHR is
sent downstream and placed on the read queue. If the argument is 1,
the write queue is flushed of all its data messages and an M_FLUSH message with a flag byte of FLUSHW is sent upstream and downstream. If
the argument is 2, the write queue is flushed of all its data messages and
an M_FLUSH message with a flag byte of FLUSHRW is sent downstream
and placed on the read queue.
If the argument is 0 and output is not already stopped, an M_STOP message is sent downstream. If the argument is 1 and output is stopped, an
M_START message is sent downstream. If the argument is 2 and input is
not already stopped, an M_STOPI message is sent downstream. If the
argument is 3 and input is stopped, an M_STARTI message is sent downstream.
The message is passed downstream, so the driver has a chance to drain
the data and then send and an M_IOCACK message upstream.
This call takes a pointer to an eucioc structure, and uses it to set the
EUC line discipline's local definition for the code set widths to be used
for subsequent operations. Within the stream, the line discipline may
optionally notify other modules of this setting via M_CTL messages.
This call takes a pointer to an eucioc structure, and returns in it the
EUC code set widths currently in use by the EUC line discipline.

SEE ALSO

pseudo(I), console(7), termio(7), termios(2)

468

10 (7)
NAME

10 - software loopback network interface
SYNOPSIS

= open

(n/dev/10opn,

O_RDWR);

DESCRIPTION

The 100pback device is a software datalink provider (interface driver) that returns
all packets it receives to their source without involving any hardware devices. It is
a STREAMS device conforming to the datalink provider interface (DLPI). See if(7)
for a general description of network interfaces.
The 100pback interface is used to access Internet services on the local machine.
Because it is available on all machines, including those with no hardware network
interfaces, programs can use it for guaranteed access to local servers. A typical
application is the comsat(lM) server which accepts notification of mail delivery
from a local client. The loopback interface is also used for performance analysis
and testing.
By convention, the name of the loopback interface is 100, and it is configured with
Internet address 127.0.0.1. This address may be changed with the
SIOCSIFADDR ioct1 ( ).
SEE ALSO

comsat(lM), if(7), inet(7)

469

log(7)
NAME

log - interface to STREAMS error logging and event tracing
SYNOPSIS
#inc1ude
#inc1ude
#inc1ude
#inc1ude

DESCRIPTION
log is a STREAMS software device driver that provides an interface for console logging and for the STREAMS error logging and event tracing processes [strerr(lM),
strace(lM)]. log presents two separate interfaces: a function call interface in the
kernel through which STREAMS drivers and modules submit log messages; and a
subset of ioct1(2) system calls and STREAMS messages for interaction with a user

level console logger, an error logger, a trace logger, or processes that need to submit
their own log messages.
Kernel Interface
log messages are generated within the kernel by calls to the function str1og:

str1og{short mid, short sid, char level, ushort flags,
char *fmt, unsigned argl, •.• );

Required definitions are contained in stream.h, str1og.h, log.h, and sys1og.h
in /usr/inc1ude/sys. mid is the STREAMS module JD number for the module or
driver submitting the log message. sid is an internal sub-JD number usually used to
identify a particular minor device of a driver. level is a tracing level that allows for
selective screening out of low priority messages from the tracer. flags are any combination of SL_ERROR (the message is for the error logger), SL_TRACE (the message
is for the tracer), SL_CONSOLE (the message is for the console logger), SL_FATAL
(advisory notification of a fatal error), and SL_NOTIFY (request that a copy of the
message be mailed to the system administrator). fmt is a printf(3S) style format
string, except that %s, 'Yoe, %E, %g, and %G conversion specifications are not handled.
Up to NLOGARGS (currently 3) numeric or character arguments can be provided.
User Interface
log is opened via the clone interface, /dev/1og. Each open of /dev/1og obtains a
separate stream to log. In order to receive log messages, a process must first notify
log whether it is an error logger, trace logger, or console logger via a STREAMS
I_STR ioct1 call (see below). For the console logger, the I_STR ioct1 has an
ic_cmd field of I_CONSLOG, with no accompanying data. For the error logger, the
I_STR ioct1 has an ic_cmd field of I_ERRLOG, with no accompanying data. For
the trace logger, the ioctl has an ic_cmd field of I_TRCLOG, and must be accompanied by a data buffer containing an array of one or more struct trace_ids
elements. Each trace_ids structure specifies an mid, sid, and level from which message will be accepted. str10g will accept messages whose mid and sid exactly
match those in the trace_ids structure, and whose level is less than or equal to the
level given in the trace_ids structure. A value of -1 in any of the fields of the
trace_ids structure indicates that any value is accepted for that field.

470

log (7)
Once the logger process has identified itself via the ioctl call, log will begin sending up messages subject to the restrictions noted above. These messages are
obtained via the getrnsg (2) system call. The control part of this message contains a
log_ctl structure, which specifies the mid, sid, level, flags, time in ticks since boot
that the message was submitted, the corresponding time in seconds since Jan. I,
1970, a sequence number, and a priority. The time in seconds since 1970 is provided
so that the date and time of the message can be easily computed, and the time in
ticks since boot is provided so that the relative timing of log messages can be determined.
The priority is comprised of a priority code and a facility code, found in
sys/ syslog. h. If SL_CONSOLE is set in flags, the priority code is set as follows. If
SL_WARN is set, the priority code is set to LOG_WARNING. If SL_FATAL is set, the
priority code is set to LOG_CRIT. If SL_ERROR is set, the priority code is set to
LOG_ERR. If SL_NOTE is set, the priority code is set to LOG_NOTICE. If SL_TRACE is
set, the priority code is set to LOG_DEBUG. If only SL_CONSOLE is set, the priority
code is set to LOG_INFO. Messages originating from the kernel have the facility
code set to LOG_KERN. Most messages originating from user processes will have the
facility code set to LOG_USER.
Different sequence numbers are maintained for the error and trace logging streams,
and are provided so that gaps in the sequence of messages can be determined (during times of high message traffic some messages may not be delivered by the logger
to avoid hogging system resources). The data part of the message contains the
unexpanded text of the format string (null terminated), followed by NLOGARGS
words for the arguments to the format string, aligned on the first word boundary
following the format string.
A process may also send a message of the same structure to log, even if it is not an
error or trace logger. The only fields of the log_ctl structure in the control part of
the message that are accepted are the level, flags, and pri fields; all other fields are
filled in by log before being forwarded to the appropriate logger. The data portion
must contain a null terminated format string, and any arguments (up to NLOGARGS)
must be packed one word each, on the next word boundary follOWing the end of
the format string.
ENXIO is returned for I_TRCLOG ioctls without any trace_ids structures, or for
any unrecognized I_STR ioctl calls. Incorrectly formatted log messages sent to

the driver by a user process are silently ignored (no error results).
Processes that wish to write a message to the console logger may direct their output
to /dev/conslog, using either write(2) or putrnsg(2).
EXAMPLES

Example of I_ERRLOG notification:
struct strioctl ioc;
ioc.ic_crnd = I_ERRLOG;
ioc.ic_tirnout = 0;
/* default timeout (15 secs.) */
ioc.ic_len = 0;
ioc.ic_dp = NULL;
ioctl(1og, I_STR, &ioc);

471

log (7)
Example of I_TRCLOG notification:
struct trace_ids tid[2];
tid[O].ti_mid = 2;
tid[O].ti_sid = 0;
tid[O].ti_level = 1;
tid[1].ti_mid = 1002;
tid[1].ti_sid = -1;
/* any sub-id will be allowed */
tid[1].ti_level = -1; /* any level will be allowed */
ioc.ic_cmd = I_TRCLOG;
ioc.ic_timout = 0;
ioc.ic_len = 2 * sizeof(struct trace_ids);
ioc.ic_dp = (char *)tid;
ioctl(log, I_STR, &ioc);
Example of submitting a log message (no arguments):
struct strbuf ctl, dat;
struct log_ctl lc;
char *message = "Don't forget to pick up some milk
on the way home";
ctl.len
ctl.buf
dat.len
dat.buf
lc.level
lc.flags

ctl.maxlen = sizeof(lc);
(char *)&lc;
dat.maxlen
message;

strlen(message);

= 0;

= SL_ERRORISL_NOTIFY;

putmsg(log, &ctl, &dat, 0);
FILES

/dev/log
/dev/conslog
SEE ALSO

c1one(7), getmsg(2), intro(2), putmsg(2), strace(lM), strerr(lM), write(2)
NOTES

The log driver high and low water marks are tunable via the master file.

472

Ip (7)
NAME

lp - parallel port interface
DESCRIPTION

The parallel port (lp) driver supports both the primary (monochrome) and secondary parallel printer adapters simultaneously. Up to two printers are supported. If
an adapter for a printer is not installed, an attempt to open it will fail. The close
waits until all output is completed before returning to the user. The lp driver
allows only one process at a time to write to the adapter. If it is already busy, an
open for writing will return an error. However, the driver allows multiple opens to
occur if they are read-only.
The parallel printer adapters are character devices. The minor device number
corresponds to the primary or secondary parallel printer adapter. Thus, minor
device 0 corresponds to the primary parallel printer adapter, while minor device 1
corresponds to the secondary adapter.
The parallel port behaves as described in tennio(7).
FILES

/dev/lp*
SEE ALSO

stty(l), termio(7)

473

mcis(7)
NAME

mds - MCIS SCSI host adapter driver
DESCRIPTION

The MCIS host adapter subsystem serves as a means for SCSI target drivers (such as
sdOl, stOl, and so on) to communicate on the SCSI bus with target controllers and
logical units. This driver implements the SCSI Driver Interface (SDI) for such SCSI
target drivers.
It is also possible to access this subsystem using the pass-through driver interface.
To find the appropriate device to use, while any device is being accessed through
the target driver, use the B_GETDEV ioctl to get the major and minor numbers of the
pass-through node. This node may be created and opened for use.
ioetl Calls

There are three groups of ioctl(2) commands supported by mds. The first group
contains the ioctl commands used by the mcis driver itself:
SDI_SEND
Sends a pass-through command to a target controller, bypassing the associated target driver.
SDI_BRESET
Resets the SCSI bus.
B_REDT
Reads the extended edt data structure that is stored in the mds driver's
internal data structure.
B_HA_CNT

Gets the value of the number of host adapters for which the mcis driver is
configured.
The second group is used by the mcis driver and all target drivers that use the SDI
protocol to communicate with their associated target controllers.
B_GETTYPE
Returns the bus name (for example, scsi) and device driver name of a
specific device.
The third group should be supported by all target drivers that use the SDI protocol
to communicate with their associated target controllers. However, this ioctl is not
supported by the mcis driver.
B_GETDEV
Returns the pass-through major and minor numbers to the calling utility to
allow creation of a pass-through special device file.
Files
/usr/include/sys/mcis.h
/usr/include/sys/scsi.h
/usr/include/sys/sdi.h
/usr/include/sys/sdi_edt.h
/etc/conf/pack.d/mcis/space.c

474

mcis(7)
NOTICES
On IBM MCA SCSI systems (for example, Model 57 and Model 90), the SCSI boot
disk must be configured to be at SCSI target address (SCSI ID) 6. If you attempt to
use a SCSI disk not at SCSI ID 6 as a boot device, it may not work.

REFERENCES
ioctl(2)

475

mem(7}
NAME
mem, kmem - core memory

DESCRIPTION

The file /dev/msm is a special file that is an image of the core memory of the computer. For example, it may be used to examine and patch the system.
Byte addresses in /dev/m.em. are interpreted as memory addresses. References to
non-existent locations cause errors to be returned.
Examining and patching device registers is likely to lead to unexpected results
when read-only or write-only bits are present.
The file /dev/lanem is the same as /dev/mer.n except that kernel virtual memory
rather than physical memory is accessed.
Files

/dev/msm
/dev/kmem
NOTES

Some of /dev/kmem cannot be read because of write-only addresses or unequipped
memory addresses.

476

mouse(7)
NAME

mouse - mouse device driver for bus, serial, and PS/2 mouse devices
DESCRIPTION

The mouse device driver supports several types of mouse devices:
Logitech bus mouse that attaches to a plug-in card and is designed to be
used in an eight-bit card slot.
Logitech serial type mouse that plugs directly into a serial port connector.
PS/2 compatible mouse that connects to a PS/2 auxiliary port.
Microsoft bus mouse that attaches to a plug-in card and is designed to
be used in an eight-bit card slot.
Microsoft serial type mouse that plugs directly into a serial port connector.
The driver will support multiple mouse applications running in virtual terminal
screens, both under the UNIX System and MS-DOS via SimulTask, VP fix, Merge,
or another similar product.
Support for mouse administration is also provided. See mouseadmin(l).
The following ioctl's are supported:
MOUSEIOCMON
MOUSEISOPEN

Used exclusively by /usr/lib/mousemgr to receive open and
close commands from /dev/mouse driver.
Used exclusively by mouseadmin. Returns 16-byte character array
indicating which mouse devices are currently open; 1 is open, 0 is
not open. The array is in the linear order established by
/usr/bin/mouseadmin in building the display and device map
pairs.

MOUSEIOCCONFIG

Used exclusively by mouseadmin to configure display and mouse
pairs. The mse_cfg data structure is used to pass display and
device mapping and map pair count information to the driver:
struct mse_cfg {
struct mousemap *mapping;
unsigned
count;
}

struct mousemap {
dev_t
disp_dev;
dev_t
mse_dev;
}

int
MOUSEIOCREAD

type;

Read mouse position and status data. The following data structure
is used to return mouse position information to a user application:

477

mouse(7)
struct mouseinfo {
unsigned char status;
char
xmotion:
char
ymotion;
MOUSEIOCREAD will set errno to EFAULT for failure to return a
valid mouseinfo structure. The status byte contains the button
state information according to the following format:

o Mv

Lc Mc Rc L M R

where:
Mv:

is 1 if the mouse has moved since last MOUSEIOCREAD

Lc:

is 1 if Left button has changed state since last
MOUSEIOCREAD

Mc:

is 1 if Middle button has changed state since last
MOUSEIOCREAD

Rc:

is 1 if Right button has changed state since last
MOUSEIOCREAD

current state of Left button (1 == depressed)

current state of Middle button

current state of Right button

The Mv bit is required because the total x and y delta since the last
MOUSEIOCREAD ioctl could be 0 yet the mouse may have been
moved. The Lc, Mc, and Rc bits are required for a similar reason; if
a button had been pushed and released since the last
MOUSEIOCREAD ioctl, the current state bit would be unchanged but
the application would want to know the button had been pushed.
The xmotion and ymotion fields are signed quantities relative to
the previous position in the range -127 to 127. Deltas that would
overflow a signed char have been truncated.
MOUSE320

Used to send commands and receive responses from the PS/2
compatible mouse devices. Failed MOUSE320 commands will
return ENXIO as the errno value. The following data structure is
used to pass commands, status, and position information between
the driver and a user application:
struct cmd_32 0
int
int
int
int

cmd;
argl;
arg2;
arg3;

Valid commands for the PS/2 compatible devices are as follows:

478

mouse(7)
MSERESET

reset mouse

MSERESEND

resend last data

MSESETDEF

set default status

MSEOFF

disable mouse

MSEON

enable mouse

MSESPROMPT

set prompt mode

MSEECHON

set echo mode

MSEECHOFF

reset echo mode

MSESTREAM

set stream mode

MSESETRES

set resolution (counts per millimeter)
valid arg1 values are as follows:
00 = 1 count/mm.
01 = 2 count/mm.
02 = 4 count/mm.
03 = 8 count/mm.

MSESCALE2

set 2:1 scaling

MSESCALEl

set 1:1 scaling

MSECHGMOD

set sampling rate (reports per second)
valid arg1 values are as follows:
OA = 10 reports/sec.
14 = 20 reports/sec.
28 = 40 reports/sec.
3C = 60 reports/sec.
50 = 80 reports/sec.
64 = 100 reports/sec.
C8 = 200 reports/sec.

MSEGETDEV

read device type returns a zero (0) for the PS/2
compatible mouse.

MSEREPORT

read
mouse
report
returns
three-byte
mouse/button position where bytes two and
three are 9-bit 2's complement relative motions
with the 9th bit (sign bit) coming from byte 1.
Byte 1
bO -left button (1 == depressed)
b1 - right button
b2 - middle button
b3 - always 1
b4 - X data sign (1 == negative)
b5 - Y data sign
b6 - X data overflow
b7 - Y data overflow

479

mouse (7)
Byte 2
X axis position data
Byte 3
Y axis position data
MSESTATREQ

status request returns three-byte report with the
following format:
Byte 1
bO - right button (1 == depressed)
bl - middle button
b2 - left button
b3 - always 0
b4 - scaling 1:1 = 0, 2:1 = 1
b5 - disabled(O)/enabled(l)
b6 - stream(O)/prompt(l) mode
b7 - always 0
Byte 2
bO - 6 current resolution
b7 - always 0
Byte 3
bO - 7 current sampling rate

NOTE

The mouse also supports queue mode for accessing mouse input, both motion and
button events; see display(7) for more information on the KDQUEMODE ioctl.
FILES

/dev/mouse
/usr/lib/mousemgr
/usr/include/sys/mouse.h
SEE ALSO

mouseadmin(1 )

480

null (7)
NAME

null - the null file
DESCRIPTION

Data written on the null special file, /dev/null, is discarded.
Reads from a null special file always return 0 bytes.
Files
/dev/null

481

pckt(7)
NAME

pckt - STREAMS Packet Mode module
DESCRIPTION

pckt is a STREAMS module that may be used with a pseudo terminal to packetize
certain messages. The pckt module should be pushed [see I_PUSH, streamio(7)]
onto the master side of a pseudo terminal.
Packetizing is performed by prefixing a message with an loLPROTO message. The
original message type is stored in the 4 byte data portion of the M_PROTO message.

On the read-side, only the M_PROTO, M_PCPROTO, M_STOP, loLSTART, M_STOPI,
M_STARTI, M_IOCTL, M_DATA, M_FLUSH, and M_READ messages are packetized. All
other message types are passed upstream unmodified.
Since all unread state information is held in the master's stream head read queue,
flushing of this queue is disabled.
On the write-side, all messages are sent down unmodified.
With this module in place, all reads from the master side of the pseudo terminal
should be performed with the getmsg(2) or getpmsg system call. The control part
of the message contains the message type. The data part contains the actual data
associated with that message type. The onus is on the application to separate the
data into its component parts.
SEE ALSO

crash(lM), getmsg(2), ioctl(2), Idtenn(7), ptem(7), pty(7),
tennio(7)

482

streamio(7),

prf(7)
NAME

prf - operating system pro filer
DESCRIPTION

The special file /dev/prf provides access to activity information in the operating
system. The profiler commands load the measurement facility with text addresses
to be monitored. Reading the file returns these addresses and a set of counters indicative of activity between adjacent text addresses.
The recording mechanism is driven by the system clock and samples the program
counter at line frequency. Samples that catch the operating system are matched
against the stored text addresses and increment corresponding counters for later
processing.
The file /dev/prf is a pseudo-device with no associated hardware.
FILES

/dev/prf
NOTES

If the prf device is not configured into the kernel, to tum it on you must edit the
/etc/conf/sdevice.d/prf file, change the second field from N to Y, and

reconfigure the kernel.
When the profiler is turned on, loadable modules are locked into memory and cannot be unloaded. Subsequently loaded modules will also be locked until profiling is
disabled.
SEE ALSO

profiler(lM)

483

ptem(7)
NAME

ptem - STREAMS pseudo-terminal emulation module
DESCRIPTION

ptem is a SJREAMS module that when used in conjunction with a line discipline and
pseudo terminal driver emulates a terminal. See pseudo(l).
The ptem module must be pushed [see I_PUSH, streamio(7)] onto the slave side
of a pseudo terminal STREAM, before the Idterm module is pushed.
On the write-side, the TCSETA, TCSETAF, TCSETAW, TCGETA, TCSETS, TCSETSW,
TCSETSF, TCGETS, TCSBRK, JWINSIZE, TIOCGWINSZ, and TIOCSWINSZ termio
ioctl(2) messages are processed and acknowledged. A hang up (such as stty 0) is
converted to a zero length M_DATA message and passed downstream. termio
cflags and window row and column information are stored locally one per
stream. M_DELAY messages are discarded. All other messages are passed downstream unmodified;
On the read-side all messages are passed upstream unmodified with the following
exceptions. All M_READ and M_DELAY messages are freed in both directions. An
ioctl TCSBRK is converted to an M_BREAK message and passed upstream and an
acknowledgement is returned downstream. An ioctl TIOCSIGNAL is converted
into an M_PCSIG message, and passed upstream and an acknowledgement is
returned downstream. Finally an ioctl TIOCREMOTE is converted into an M_CTL
message, acknowledged, and passed upstream.
SEE ALSO

crash(lM), ioctl(2), Idterm(7), pckt(7), pseudo(l), pty(7), streamio(7), stty(l),
termio(7)

484

pty(7)
NAME

pty - STREAMS pseudo-terminal driver
DESCRIPTION

The pseudo-terminal subsystem (pty) supports a pair of STREAMS-based devices
called the master device and the slave device. The slave device provides processes
with an interface that is identical to the terminal interface. However, whereas all
devices that provide the terminal interface have some kind of hardware device
behind them, the slave device has another process manipulating it through the master half of the pseudo terminal. Anything written on the master device is given to
the slave as input and anything written on the slave device is presented as input on
the master side.
The master device, called ptm, is accessed through the clone driver and is the controlling part of the system. The slave device, called pts, works with a line discipline module such as Idterm.(7), a hardware emulation module such as ptem(7), and
optionally with an ioctl translation module such as ttcOIl\Pat(7) to provide a terminal interface to the user process. An optional packetizing module called pCkt(7)
is also provided to support "packet mode" when it is pushed on the master side.
The master device is opened via the open(2) system call with /dev/ptmx as the
device to be opened. The clone open finds the next available minor device for that
major device; a master device is available only if it and its corresponding slave
device are not already open.
When the master device is opened, the corresponding slave device is automatically
locked out, and no user may open that device until it is unlocked. A user may
invoke grantpt(3C) to change the owner and permissions of the slave device to
that of the user who is running the process. Once the permissions have been
changed, the device may be unlocked by the user. Only the owner or a privileged
user can access the slave device. The user then invokes unlockpt(3C) to unlock the
slave device. The user calls ptsname(3C) to get the name of the slave device, and
then invokes the open system call with the name that was returned by the function.
After both the master and slave devices have been opened, the user has two file
deScriptors that provide full-duplex communication using two streams. The two
streams are automatically connected. The user may then push modules onto either
side of the stream. The user also must push the ptem and Idterm. modules onto the
slave side to get terminal semantics.
The master and slave devices pass all STREAMS messages to their adjacent queues.
Only M_FLUSH needs some processing. Because the read queue of one side is connected to the write queue of the other, the FLUSHR flag is changed to FLUSHW and
vice versa.
When the master device is closed, an M_HANGUP message is sent to the slave device,
which renders the device unusable. The process on the slave side gets the ermo
ENXIO when attempting to write on that stream, but it can read any data remaining
on the stream head read queue. When all the data have been read, read returns 0,
indicating that the stream can no longer be used.

485

pty(7)
On the last close of the slave device, a zero-length message is sent to the master
side. When the master side application issues a read and a is returned, the user
decides whether to issue a close, which dismantles the pseudo-terminal, or not close
the master device so that the pseudo-tty subsystem will be available for another
user to open the slave device.
ioctls
The master device supports the ISPTM and UNLKPT ioctls that are used by the
grantpt, unlockpt, and ptsname functions.

The ioctl ISPTM determines whether the file descriptor is that of an open
master device. On success, it returns the major/minor number (type dev_t)
of the master device, which can be used to determine the name of the
corresponding slave device. On failure it returns -1.
The ioctl UNLKPT unlocks the master and slave devices. It returns a on
success. On failure, it returns -1 and sets ermo to EINVAL, indicating that
the master device is not open.
The format of these commands is:
int ioctl (int fd, int command, int arg);
where command is either ISPTM or UNLKPT and arg is O.
The master side application is responsible for detecting an interrupt character and
sending an interrupt signal SIGINT to the process on the slave side. This can be
done as follows:
ioctl (fd, TIOCSIGNAL, SIGINT);
where SIGINT is defined in the header file signal. h.
FILES

/dev/ptmx

pseudo-terminal master device

/dev/pts/*

pseudo-terminal slave devices

SEE ALSO

grantpt(3C), ldtenn(7), pckt(7), pseudo(l), ptem(7), ptsname(3C), ttcompat(7),
unlockpt(3C)

486

rtc(7)
NAME
rtc -

real time clock interface

DESCRIPTION
The rtc driver supports the real time clock chip, allowing it to be set with the

correct local time and allowing the time to be read from the chip.
loctl Calls
RTCRTlME

This call is used to read the local time from the real time clock chip. The
argument to the ioctl is the address of a buffer of RTCNREG unsigned characters (RTCNREG is defined in sys/rtc.h). The ioctl will fill in the buffer
with the contents of the chip registers. Currently, RTCNREG is 14, and the
meanings of the byte registers are as follows:
Register

a
1
2
3

4
5
6

7
8
9
A
B
C
D

Contents
Seconds
Second alarm
Minutes
Minute alarm
Hours
Hour alarm
Day of week
Date of month
Month
Year
Status register A
Status register B
Status register C
Status register D

For further information on the functions of these registers, see your
hardware technical reference manual.
RTCSTlME

This call is used to set the time into the real time clock chip. The argument
to ioctl is the address of a buffer of RTCNREGP unsigned characters
(RTCNREGP is defined in sys/rtc.h). These bytes should be the desired chip
register contents. Currently, RTCNREGP is 10, representing registers 0-9 as
shown above. Note that only the super-user may open the real time clock
device for writing and that the RTCSTlME ioctl will fail for any other than
the super-user.
FILES
Idev/rtc

487

sad (7)
NAME

sad - STREAMS Administrative Driver
SYNOPSIS

#include
#include
#include
#include

int ioctl (int fildes, int command, ••• 1* arg *!);
DESCRIPTION

The STREAMS Administrative Driver provides an interface for applications to perform administrative operations on STREAMS modules and drivers. The interface is
provided through ioctl(2) commands. Privileged operations may access the sad
driver via Idev/sad/admin. Unprivileged operations may access the sad driver
via Idev/sad/user.

fildes is an open file descriptor that refers to the sad driver. command determines the
control function to be performed as described below. arg represents additional
information that is needed by this command. The type of arg depends upon the
command, but it is generally an integer or a pointer to a command-specific data
structure.
Commands
The autopush facility [see autopush(lM)] allows one to configure a list of modules
to be automatically pushed on a stream when a driver is first opened. Autopush is
controlled by the next commands.
SAD_SAP
Allows the administrator to configure the autopush information for
the given device. arg points to a strapush structure which contains
the following members:
uint
long
long
long
long
uint

sap_cmd;
sap_major;
sap_minor;
sap_lastminor;
sap_npush;
sap_list [MAXAPUSH] [FMNAMESZ + 1];

The sap_cmd field indicates the type of configuration being done. It
may take on one of the following values:
SAP_ONE
Configure one minor device of a driver.
SAP_RANGE
SAP_ALL
SAP_CLEAR

Configure a range of minor devices of a driver.
Configure all minor devices of a driver.
Undo configuration information for a driver.

The sap_major field is the major device number of the device to be
configured. The sap_minor field is the minor device number of the
device to be configured. The SatLlastminor field is used only with
the SAP_RANGE command, with which a range of minor devices
between sap_minor and sap_lastminor, inclusive, are to be
configured. The minor fields have no meaning for the SAP_ALL

488

sad(7)
command. The sap_npush field indicates the number of modules to
be automatically pushed when the device is opened. It must be less
than or equal to MAXAPUSH, defined in sad.h. It must also be less
than or equal to NSTRPUSH, the maximum number of modules that
can be pushed on a stream, defined in the kernel master file. The
field sap_list is an array of module names to be pushed in the
order in which they appear in the list.
When using the SAP_CLEAR command, the user sets only sap_major
and sap_minor. This will undo the configuration information for
any of the other commands. If a previous entry was configured as
SAP_ALL, sap_minor should be set to zero. If a previous entry was
configured as SAP_RANGE, sap_minor should be set to the lowest
minor device number in the range configured.
On failure, errno is set to the following value:
EFAULT

arg points outside the allocated address space.

EINVAL

The major device number is invalid, the number of
modules is invalid, or the list of module names is
invalid.

ENOSTR

The major device number does not represent a
STREAMS driver.

EEXIST

The major-minor device pair is already configured.

ERANGE

The command is SAP_RANGE and sap_lastminor is
not greater than sap_minor, or the command is
SAP_CLEAR and sap_minor is not equal to the first
minor in the range.

ENODEV

The command is SAP_CLEAR and the device is not
configured for autopush.

ENOSR

An internal autopush data structure cannot be allocated.

Allows any user to query the sad driver to get the autopush
configuration information for a given device. arg points to a strapush structure as described in the previous command.
The user should set the sap_major and sap_minor fields of the
strapush structure to the major and minor device numbers, respectively, of the device in question. On return, the strapush structure
will be filled in with the entire information used to configure the
device. Unused entries in the module list will be zero-filled.
On failure, errno is set to one of the following values:
EFAULT

arg points outside the allocated address space.

EINVAL

The major device number is invalid.

489

sad(7}
The major device number does not represent a
STREAMS driver.
The device is not configured for autopush.

ENOSTR
ENODEV

Allows any user to validate a list of modules (for example, to see if
they are installed on the system). arg is a pointer to a str_list
structure with the following members:
int
struct str_mlist

sl_nmods;
*sl_modlist;

The str_mlist structure has the following member:
char

1_name[FMNAMESZ+1];

sl_mnods indicates the number of entries the user has allocated in
the array and sl_modlist points to the array of module names. The
return value is 0 if the list is valid, 1 if the list contains an invalid
module name, or -Ion failure. On failure, errno is set to one of the
following values:
EFAULT
arg points outside the allocated address space.
EINVAL
The sl_mnods field of the str_list structure is less
than or equal to zero.
SEE ALSO

intro(2), ioctl(2), open(2)
DIAGNOSTICS

Unless specified otherwise above, the return value from ioctl is 0 upon success
and -1 upon failure with errno set as indicated.

490

sc01(7)
NAME

seQl - CD-ROM Target Driver
DESCRIPTION

seQl is a Portable Device Interface (PDI)-compliant CD-ROM target driver that
provides access to one or more CD-ROM drives. Each drive must be attached to a
SCSI bus controlled by an PDI-compliant host adapter driver [for example, see
adse(7)].

Access to a particular drive is accomplished using the seQl device files located in
/dev/ [r] edrom. Each device file identifies a particular drive based on the SCSI ID
assigned to that drive. The binding between a device file and a CD-ROM drive is as
follows:
/dev/redrom/edQ CD-ROM drive with lowest SCSI ID
/dev/redrom/edl CD-ROM drive with next to lowest SCSI ID

and so on.
Most CD-ROM drives can handle CD-ROM disks that contain two types of data:
informational data and audio data. The seQl driver allows access to both types of
data.
A CD-ROM disk that contains informational data is treated as a random-access
storage device, such as a hard disk. The information on the disk is divided into
consecutively numbered, fixed-size (usually 2 Kbytes) sectors that can be accessed
in any order. The standard tools for reading data from a random-access device,
such as dd(l) or read (2 ), can be used to read informational data from a CD-ROM.
However, all write operations are prohibited.
Audio commands control the operation of the drive's audio output hardware (usually a headphone jack located on the drive). For example, the C_PLAYAUDIO ioctl
causes the audio hardware to decode and convert the audio data to analog at a
specific location on the disk, and play the audio on the drive's audio output
hardware. Audio data is not returned to the host system.
All audio data commands are executed through the ioctl interface and often require
a parameter structure that identifies the audio data to be acted upon. Unlike informational data, audio data is not referenced by a sector address. The methods used
to identify a particular section of audio data should be described in the SCSI interface section of the reference manual supplied with your CD-ROM drive. Audio
data cannot be read as if it were informational data, and informational data cannot
be played using the drive's audio hardware.
ioetl Calls
The seQl driver uses several ioetl(2) commands, listed below. Many of these
ioetl(2) commands provide a convenient method for sending one of the
preselected SCSI commands directly to the drive. SCSI commands not explicitly
supported by the seQl driver can be sent to the drive using the pass-through
facility provided by the SDI host adapter driver. For an example, see adse(7).

The following ioctls are used to identify a target driver and to get a pass-through
major and minor number for a target device.

491

sc01(7)
B_GETTYPE

Returns the type of peripheral bus (for example, scsi) used and the name of
this driver (for example, sc01).
B_GETDEV

Returns the major and minor number of the pass-through device for the
CD-ROM drive. For example, see adsc(7) for details.
The following ioctls cause the appropriate Group-a, Group-I, or Group-6 SCSI commands to be sent to the device. These commands are defined by the SCSI bus
specification and should also be described in the SCSI Interface section of the reference manual supplied with your CD-ROM drive.
Group a
C_TESTUNIT

Sends a Test Unit Ready command to the device.
C_REZERO

Sends a Rezero Device command to the device.
C_SEEK

Sends a Seek command to the device.
C_INQUIR

Sends an Inquiry command to the device and returns the resulting
data back to the caller.
C_STARTUNIT

Sends a Start Unit command to the device.
C_STOPUNIT

Sends a Stop Unit command to the device.
C_PREVMV

Sends a Prevent Media Removal command to the device.
C_ALLOMV

Sends an Allow Media Removal command to the device.
Group-I
C_READCAPA

Sends a Read Capacity command to the device and returns the
data sent by the drive.
Group-6
C_AUDIOSEARCH

Sends an Audio Search command to the device.
C_PLAYAUDIO

Sends a Play Audio command to the device.
C_STILL

Sends a Still command to the device.

492

sc01(7)
C_TRAYOPEN

Sends a Tray Open command to the device.
C_TRAYCLOSE

Sends a Tray Close command to the device.
Note: The Group 6 IOCTL's support only the drives that are software compatible
with the Toshiba XM-320lB.
The following ioctls are also supported by the scOl driver.
B_GET_SUBDEVS

Returns the number of sub-devices supported by this driver (for
example, 1).
Files
/usr/include/sys/cd_ioctl.h
/usr/include/sys/cdram.h
/usr/include/sys/scOl.h
/etc/conf/pack.d/scOl/space.c
/dev/[r]cdram/cd*
/usr/include/sys/scsi.h
/usr/include/sys/sdi.h
/usr/include/sys/sdi_edt.h

REFERENCES
adsc(7), dpt(7), ioctl(2), mcis(7), sdOl(7), stOl(7), swOl(7), wd7000(7)

493

sd01 (7)
NAME

sdOl- POI disk target driver
DESCRIPTION

The sdOl disk target driver is the device-level driver for both Small Computer System Interface (SCSI) hard disks, SCSI optical disks, and ESOI/ST506/IDE/MFM
integral disks. It provides block and character (raw) access to the disk, and I/O
controls (ioctl) to the disk. sdOl sets up two levels of organization to the disk, to
allow the disk to be shared with other operating systems, and provide efficient
sized portions within the UNIX system.
The first level of organization of the disk by sdOl is the partition table. The partition table divides the disk into pieces (called partitions) which serve as a logical
disks. There are a maximum of 4 partitions for each disk. A partition has four
characteristics: a start sector, a length, an operating system type (for example,
UNIX, DOS, Extended DOS, and so on), and an active flag (which indicates the
current boatable partition). A valid partition has at least the first three fields
defined. A boatable valid partition has all four fields defined/ on.
The partition table is maintained by the fdisk(lM) command. The sdOl target
driver searches the partition table for UNIX partitions. The active flag is used not
only to indicate that a partition on the boot disk is boatable, but also indicates
whether it is accessible (for example, a UNIX partition on the second disk which
isn't active cannot be accessed).
Within a UNIX partition is the second level of organization of the disk. The UNIX
partition is broken into contiguous sections called slices. The slices of a UNIX partition are defined by the Virtual Table Of Contents (VTOC). The VTOC provides the
means to break up the UNIX partition in smaller pieces to better manage the space,
to differentiate slices for special purposes, and to allow protection of some of the
slices. The VTOC allows for a maximum of 16 slices per disk. A slice also has four
characteristics: a start sector, a length, a slice type (for example, root, user, swap,
stand, and so on), and permissions (valid and mountable/unmountable). A slice
can contain a filesystem (for example, VXFS, S5, BFS, and so on), can be used as
swap space for paging, or left to be organized by an application such as a database.
Several of the slices have required definitions as follows:
Slice 0 The whole UNIX partition; that is, it has the same start and length as the
UNIX partition.
Slice 7 The boot slice which contains UNIX boot code (if it is the boot disk), the
VTOC information, and the POINFO (described later). This slice occupies
sector 1 through 34 of UNIX partition.
Slice 8 The alternates slice, containing the table of remapped sectors, sectors which
have been remapped, and spare sectors available for remapping.
Slice 9 Used in 4.0 and earlier UNIX releases additionally as the alternate track
area. The alternates mechanism was consolidated in SVR4.2 to use one slice.
On the boot disk, there are several other slices which also have required definitions:

494

sd01(7)
Slice 1 The root filesystem
Slice 2 The swap slice
Slice 10
The boot slice which contains the BFS filesystem
Finally, on a boot disk, the optional filesystems are organized as follows:
Slice 3 The /usr filesystem
Slice 4 The /home filesystem
Slice 5 Points to the first DOS partition, if defined
Slice 6 The dump slice (holds memory dumps)
Slice 11
The /var filesystem
Slice 12
The /home2 filesystem
Slice 13
The /tmp filesystem
Slice 14
Points to the second DOS partition, if defined
Slice 15
Points to the third DOS partition, if defined
The slices of a disk are represented by device nodes, which have the major number
for sdOl and a minor number pointing to one of slices. Since there are sixteen
slices, there are therefore sixteen minors per disk, so minor 0 through 15 are for the
first disk, 16 through 31 are for the second disk, 32 through 47 for the third disk and
so on. The system supports 256 minors per major number so thus there are 16 sets
of disk devices per major number. sdOl supports multiple major numbers, and
currently supports 7 major numbers, which allows for up to 112 disks. When the
disk device is opened, the partition table and the VTOC are read by sdOl to fill out
its tables of partitions and slices.
Mapping of bad blocks is performed dynamically and automatically by the sdOl
disk driver, without user intervention and without retaining a fixed bad block log
on the disk. The SCSI direct-access controllers reassign the defective blocks to an
area on the disk reserved for this purpose. The sdOl disk driver can map both marginal bad blocks (that is, readable with some difficulty) and actual bad blocks (that
is, unreadable). The sdOl driver does not map or report a bad block residing in a
non-UNIX System (that is, MS-DOS) partition of the disk. In addition, even with
dynamic bad block handling, it is possible for damage to occur that cannot be
mapped automatically. This means that you may have to restore the file system
from the last full backup, if the bad block occurs in a critical area of the disk which
cannot tolerate bad sectors.
The sdOl disk driver reports problems with driver error messages. The error
numbers in the error messages identify the type of error. For SCSI sense codes,
extended
sense
codes,
and
command
codes,
see
the
file
/usr/include/sys/scsLh.
For
SDI
return
codes,
see
the
file

495

sd01(7)
/usr/include/sys/sdi.h.
The sdOl driver receives command requests from the kernel through the
Input/Output (I/O) control call ioct1(2). The sdOl driver generates the requested
commands and passes them to the host adapter driver. When command execution
is complete, the host adapter driver notifies the sdOl driver through an interrupt.
After this notification, the sdOl driver performs any required error recovery and
indicates to the kernel that the I/O request is complete.
The files in the /dev/dsk directory access the disk thi-ough the system's normal
buffering mechanism, and may be read and written without regard to physical disk
records.
There is also a [r] raw interface that 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. Therefore, raw I/O is considerably more efficient when many
words are transmitted. The names of the raw disk files contain /dev/rdsk and
have the same form as the /dev/dsk files.
In raw I/O, the buffer must begin on a 512-byte boundary, and transfer counts
must be integral multiples of 512 bytes.
The special device file names associated with the sdOl disk driver have the form:
/dev/[r]dsk/c#t#d#s#
The naming convention for the sdOl disk special device file name components is as
follows:
[r]
The optional r in / [r]dsk denotes a raw (that is, character) device; /dsk
without the optional r indicates a block device
c#
# is the occurrence of the host adapter board in the system (that is, card
number), ranging are from 0-2 (machine dependent)
t#
# is the target controller number, ranging are from O-F hexadecimal
d#
# is the logical unit number of the disk device, ranging are from 0-3, since
each target controller currently supports up to four disks
s#
# is the disk slice number or VTOC partition number, ranging are from O-F
hexadecimal
The disk parameters-number of cylinders, heads, and sectors per track-are
obtained at driver initialization (init) time. If the disk is an ESDI/ST506/IDE drive,
the CMOS contains parameters for the first two disks. For SCSI disks, a read capacity command is issued, and the disk parameters are calculated based on a disk
geometry of 32 sectors per track and 64 heads. This geometry is for drives with 512
byte sectors. It is adjusted if the number of bytes per sector changes. The disk
parameters are stored in Physical Descriptor Information (PDINFO) structure
which is stored in the boot slice of the disk. The PDINFO is kept as a sanity check
against those found at driver init time.
When the machine is booted, the primary boot code (BIOS) looks in the fdisk table
for the active partition and jumps to sector 0 of that partition to find the first-stage
bootstrap. If the first-stage bootstrap is over one sector in length, it is the responsibility of the first-stage bootstrap to understand this. The boot code will read in the
VTOC to locate the BFS filesystem. It will then load the kernel and begin executing
496

sd01(7)
the kernel.
ioetl Calls
The ioctl calls used by the sdOl driver to control the reading and writing of data
to disk are as follows:
V_CONFIG
Used to modify the parameters (cylinders and heads) of a disk device. Its
usage is not recommended and it is no longer used in any of the system
commands. The argument to the ioctl is the address of one of the following structures, defined in sys/vtoc.h, containing the new configuration
parameters:
union io_arg {
struct {
ushortncyl;/* NUmber of cylinders */
uncharnhead;/* Heads/cylinder */
uncharnsec;/* Sectors/track */
ushortsecsiz;/* Bytes/sector */
} ia_cd;
}

Note that it is not possible to change the sector size on the hard disk with
this ioctl, and that an attempt to do so results in the ioctl failing, with
erma set to EINVAL. This call is provided for backward compatibility with
any commands which use it. This call should no longer be used and will be
removed in the future.
V_REMOUNT

Forces sdOl to re-read the VTOC on the next open operation of the drive. It
fails if any slice other than slice 0 is currently open, since the VTOC information cannot be updated while a process is using a slice. This is used by
disksetup when it changes the VTOC to signal sdOl to update its internal
tables.
V_GETPARMS
Gets information about the current drive configuration. The argument to
the ioctl is the address of the following structure, defined in sys/vtoc. h,
which are filled in by the ioctl:
struct disk-ParmS {
chardp_type;/* Disk type (see below) */
unchardp_heads;/* No. of heads */
ushortdp_cyls;/* No. of cylinders */
unchardp_sectors;/* No. of sectors/track */
ushortdp_secsiz;/* No. of b¥tes/sector */
ushortdp-ptag;/* CUrrently not used */
ushortdp-pflag; /* CUrrently not used * /
daddr_tdp-pstartsec;/* Starting abs. sector no. */
daddr_tdp-Pnumsec;/* CUrrently not used */
}

1* Disk types */

497

sd01(7}
#defineDPT_NOTDISKO/* Not a disk device */
#defineDPT_WINI1/* Winchester disk */
#defineDPT_FLOPPY2/* Floppy */
#defineDPT_OTHER3/* Other type of disk */
#defineDPT_SCSI_HD4/* SCSI hard disk */
#defineDPT_SCSI_ODS/* SCSI optical disk */
/* Partition tag */
#defineV_BOOT1/* Boatable partition */
#defineV_ROOT2/* Root filesystem */
#defineV_SWAP3/* swap slice */
#defineV_USR4/* User filesystem */
#defineV_BACKDPS/* Entire disk */
#defineV_ALTS6/* Alternate sectors (SVR4.0 and earlier) */
#defineV_OTHER7/* Non-UNIX System partition */
#defineV_ALTTRK8/* Alternate tracks (SVR4.0 and earlier) */
#defineV_STAND9/* stand (BFS) filesystem */
#defineV_VAROA/* Var filesystem */
#defineV_HOMEOB/* Home filesystem */
#defineV_DUMPOC/* Dump slice */
#defineV_ALTSCTROD/* Alternate sectors (SVR4.2) */
/* Partition flag */
#defineV_UNMNTOx001/* Unmountable partition */
#defineV_RONLYOx010/* Read only partition */
#defineV_OPENOxlOO/* Partition open */
#defineV_VALID0x200/* Partition valid to use */

For SCSI disks the disk type is DPT_SCSI_HD. For ESDI/ST506/IDE disks
the disk type is DPT_WINI.
V_PDLOC
Returns the logical sector address of the pdinfo structure. The value is
returned in pdloc.
unsignedlongpdloc;
V_RDABS/V_WRABS
Used as a means for reading/writing any sector on the hard disk. Only
users with root privilege can freely access any sector. Users who do not
have root privilege can access the partition table (sector 0) or the boot slice
(to allow access to the VTOC). The absolute sector address to be written to
is placed in abs_sec. The data for the sector is read to or written from
abs_buf. The size of abs_buf should be diskyarrns.dp_secsize for the
current drive. Note that both the first cylinder (containing the fdisk table,
first-stage bootstrap and VTOC) and the first track of the active partition
(containing the first-stage bootstrap) can only be accessed using partition 0,
since these tracks are normally not considered part of any other partition in
the VTOC. The absio structure is defined in sys/vtoc.h.

498

sd01(7)
struct absio {
daddr_tabs_sec;/* Absolute sector no. (from O) */
char*abs_buf;/* Sector buffer */
};
V_PREAD/V_PWRITE
Used to read or write any size data block on the disk, regardless of the physical sector size. Only users with root privilege can use these calls. The
starting logical sector address to be written to or read from is placed in
sectst, the number of bytes to be transferred is placed in datasz, the data
to be transferred is placed in memaddr, and the phyio structure is defined in
sys/vtoc.h.

struct phyio
intretval;/*
unsignedlong
unsignedlong
unsignedlong

Return value */
sectst;/* Sector address */
memaddr;/* Buffer address */
datasz;/* Transfer size in bytes */

} ;

V_PDREAD/V_PDWRITE
Used to read or write the Physical Description sector on the disk, regardless
of this sector's location. Only users with root privilege can use these calls.
The starting logical sector address to be written to or read from is assigned
by the sdOl driver, the physical sector size of the disk must be placed in
datasz, the data to be transferred is placed in memaddr, and the phyio
structure is defined in sys/vtoc.h.
SD_PDLOC
Returns the physical sector address of the pdinfo structure. The value is
returned in pdloc.
unsignedlongpdloc;

SDI_RESERVE
Reserves a SCSI disk for a processor.
SDI_RELEASE
Releases a SCSI disk from a processor.
SDI_RESTAT
Returns device reservation status.

The following ioctl commands are used to identify a target driver and to get
pass-through major and minor numbers for a target device:
B_GETTYPE

Returns the bus name (for example, scsi) and device driver name (for
example, sdOl) of a specific device.
B_GETDEV

Returns the pass-through major and minor numbers to the calling utility,
allowing creation of a pass-through special device file.

499

sd01(7)
Files
/dev/dsk/*
/dev/rdsk/*
/usr/inelude/sys/sesi.h
/usr/inelude/sys/sdi.h
/usr/inelude/sys/sdi_edt.h
/usr/inelude/sys/vtoe.h

NOTES
The sdOl driver retries failed transfers up to two times depending on the error
type. Certain errors are not retried. sdOl displays an appropriate message upon
encountering an error during the transfer.
The VTOC and second-stage bootstrap require that no bad sectors occur in the first
30 sectors of the UNIX System partition on the disk. When a marginal bad block
occurs, the driver's warning indicates that the controller's error-correction algorithm successfully recovered from an error. This may be a symptom of a sector
going bad.

REFERENCES
adse(7), disksetup(lM), dpt(7), edvtoe(lM), fdisk(lM), fs(4), ioctl(2) mcis(7)
mount(lM), prtvtoe(lM), seOl(7), stOl(7), swOl(7), wd7000(7)

500

sockio(7)
NAME

sookio - iootls that operate directly on sockets
SYNOPSIS

#include
DESCRIPTION

The ioctls listed in this manual page apply directly to sockets, independent of any
underlying protocol. The setsockopt call (see getsockopt(3N» is the primary
method for operating on sockets, rather than on the underlying protocol or network
interface. iootls for a specific network interface or protocol are documented in the
manual page for that interface or protocol.
SIOCSPGRP

The argument is a pointer to an into Set the process-group
ID that will subsequently receive SIGIO or SIGURG signals for
the socket referred to by the descriptor passed to iootl to
the value of that into

SIOCGPGRP

The argument is a pointer to an into Set the value of that
int to the process-group ID that is receiving SIGIO or
SIGURG signals for the socket referred to by the descriptor
passed to ioctl.

SIOCCATMARK

The argument is a pointer to an into Set the value of that
int to 1 if the read pointer for the socket referred to by the
descriptor passed to iootl points to a mark in the data
stream for an out-of-band message. Set the value of that int
to 0 if the read pointer for the socket referred to by the
descriptor passed to ioctl does not point to a mark in the
data stream for an out-of-band message.

SEE ALSO

ioctl(2) getsockopt(3N),

501

st01 (7)
NAME

stOl - Portable Device Interface (PDI) tape target driver
DESCRIPTION

The stOl tape driver receives command requests from the kernel through the
read(2), write(2), and ioctl(2) system calls. The stOl driver generates the
appropriate commands and passes them through the host adapter driver to the tape
device. When command execution is complete, the host adapter driver notifies
stOl through an interrupt. After this notification, stOl performs any required
error recovery, and indicates to the kernel that the Input/Output (I/O) request is
complete. The stOl driver operates independently of the hardware used to communicate with the HBA bus.
I/O requests must be in length a multiple of the tape block length. The default
value is 512 bytes.
Only raw character interface files are provided. When opened, the tape is assumed
to be positioned as desired. If a retension-on-open special file is opened, the tape is
retensioned before any I/O is performed. When a T_RWD, T_RETENSION, T_LOAD, or
T_UNLOAD ioctl is requested and the tape has been written, two file marks are
written before the ioctl is executed.
The open(2) on a tape device can fail is a tape is not inserted, resulting in the error
report EIO. An open(2) can also fail if the tape controller associated with the special
file is not detected by the driver. In this case, the error reported is ENXIO.
The following table lists the actions that occur on close. depending on whether the
file is designated as rewind or no-rewind, and if the tape was written or read:
Rewind
on Close?
Yes
Yes

Tape
Read?
Yes
N/ A

Tape
Written?
N/ A
Yes

Yes
No
No
No

No
No
Yes
N/A

No
No
N/A
Yes

Action
on Close
Rewind tape.
Write two file marks and rewind
tape.
Rewind tape
No tape movement
Position tape after next file mark
Write one file mark and position
tape after this file mark

A read occurring when the tape is positioned immediately before a file mark
returns zero(O) bytes, and the tape is positioned after the file mark. As with other
raw devices, seeks are ignored. Some tape devices allow both reads and writes to
occur between rewinds; the stOl driver supports these devices.
ioetl Calls

The following ioctl calls are used by the stOl driver to control tape positioning:
T_SFF/T_SFB

502

Positions the tape forward or backward arg [see ioct1(2)] number
of file marks from the current tape head position toward the Endof-Tape (EOT) or Beginning-of-Tape (BOT). Forward movement of
the tape leaves the tape positioned on the EOT side of a file mark
or at EOT, and backwards movement leaves the tape positioned on

st01 (7)

T_SBF /T_SBB

T_RWD

T_WRFlLEM

T_EOD
T_STD

T_PREVMV

T_ALLOMV

T_LOAD
T_UNLOAD

T_ERASE

the BOT side of a file mark or at BOT. A backward positioning
operation causes the next read to return 0 bytes unless arg is
greater than the number of file marks between the current position
and BOT. The value of arg must be a positive integer. A value of 0
is not considered an error, but does not result in any tape movement.
Positions the tape forward or backward arg number of blocks from
the current tape head position toward the EaT or BOT. Upon
command completion, the tape head is positioned in the gap
between tape blocks. Thus, skipping a block forward advances to
the next block, and skipping a block backward retreats to the last
block. The value of arg must be a positive integer. Upon any
attempt to skip over a file mark, the tape is positioned on the
EaT /BOT side of the file mark for forward/backward movement,
and the positioning operation ceases. A value of 0 is not considered an error, but does not result in any tape movement.
Rewinds the tape from the current tape position to the BOT. Two
file marks are written before the rewind if the tape has been written. This command does not unload the tape.
Writes file marks to the tape. The value of arg defines the number
of consecutive file marks to be written. If an error occurs while
writing file marks, the number of file marks that have been successfully written is indeterminate.
Positions the tape just beyond the last file mark.
Defines the recording density of the tape media being used. The
numeric density code used is as defined in the SCSI-2 draft
specification.
Locks the tape in the drive. This prevention may be in the form of
a mechanical lock or an LED to indicate the device is in use.
T_PREVMV is supported only on devices that implement this
feature. For example, ICT devices are among those which do not
support this ioctl.
Unlocks the tape in the drive. This command is used to undo the
lock created by T_PREVMV. T_ALLOMV is supported only on devices
that implement this feature. For example, ICT devices are among
those which do not support this ioctl.
Loads the tape media and position the tape BOT.
Unloads the tape. Most devices rewind the tape before unloading.
Devices capable of ejecting the tape will do so in response to this
command.
Erases the tape, from BOT to EaT. If the tape is not positioned at
BOT, the tape is positioned at BOT before performing the erase
function.

503

5t01 (7)
T_RDBLKLEN

Returns the minimum and maximum block lengths supported by
the tape device. The value of arg must be a struct blklen. See
the me /usr/include/sys/st01.h for more information.

T_WRBLKLEN

Sets the current block length for the tape device. The value of arg
must be a struct blklen with both max bien and min bien set to
the desired block length. See the file /usr/include/sYs/st01.h
for more information.

Retensions the tape in the drive, running the tape at high speed
from BOT to EaT, and then back again. The retension operation
leaves the tape positioned at BOT.
The following ioctl commands identify a target driver and get a pass-through
major and minor number for a target device.
B_GETTYPE
Gets the bus name (for example, scsi) and device driver name (for
example, stOl) of a specific device
Gets the pass-through major and minor number to the calling utility, allowing creation of a pass-through special device file.

T_RETENSION

Files
/usr/include/sys/stOl_ioctl.h
/usr/include/sys/stOl.h
/usr/include/sys/sdi_edt.h

NOTES
Once any drive error is encountered, the driver will not perform any other functions until the file is closed.
The stOl tape driver does not always require block sizes that are in multiples of 512
bytes, but block size is device dependent. You should set the tape driver to use the
block size supported by the tape device. Failure to set the block
size correctly will result in an error when the driver attempts to write a block of the
unsupported size.
The tape driver does not support the use of the sar command.

REFERENCES
adsc(7), close(2), dpt(7), ioctl(2), mcis(7), read(2), scOl(7), sdOl(7), swOl(7),
wd7000(7), write(2)

504

streamio (7)
NAME

streamio - STREAMS ioctl commands
SYNOPSIS

#include
#include
int ioctl (intfildes, int command, ••• /* arg *!);
DESCRIPTION
STREAMS [see intro(2)] ioctl commands are a subset of the ioctl(2) system calls

which perform a variety of control functions on streams.

fildes is an open file descriptor that refers to a stream. command determines the control function to be performed as described below. arg represents additional information that is needed by this command. The type of arg depends upon the command, but it is generally an integer or a pointer to a command-specific data structure. The command and arg are interpreted by the stream head. Certain combinations of these arguments may be passed to a module or driver in the stream.
Since these STREAMS commands are a subset of ioctl, they are subject to the errors
described there. In addition to those errors, the call will fail with ermo set to EINVAL, without processing a control function, if the stream referenced by fildes is
linked below a multiplexor, or if command is not a valid value for a stream.
Also, as described in ioctl, STREAMS modules and drivers can detect errors. In
this case, the module or driver sends an error message to the stream head containing an error value. This causes subsequent system calls to fail with ermo set to this
value.

Command Functions
The following ioctl commands, with error values indicated, are applicable to all
STREAMS files:
Pushes the module whose name is pointed to by arg onto the top of
the current stream, just below the stream head. If the stream is a
pipe, the module will be inserted between the stream heads of both
ends of the pipe. It then calls the open routine of the newly-pushed
module. On failure, ermo is set to one of the following values:
EINVAL
Invalid module name.

EFAULT
ENXIO

arg points outside the allocated address space.
Open routine of new module failed.

ENXIO
Hangup received on fildes.
Removes the module just below the stream head of the stream
pointed to by fildes. To remove a module from a pipe requires that
the module was pushed on the side it is being removed from. arg
should be 0 in an I_POP request. On failure, errno is set to one of
the following values:
EINVAL
No module present in the stream.

505

streamio (7)
Hangup received on fildes.
Retrieves the name of the module just below the stream head of the
stream pointed to by fildes, and places it in a null terminated character string pointed at by argo The buffer pointed to by arg should be at
least FMNAMEsz+l bytes long. A #include declaration is required. On failure, ermo is set to one of the following
values:
ENXIO

EFAULT

arg points outside the allocated address space.

EINVAL

No module present in stream.

This request flushes all input and/or output queues, depending on
the value of argo Valid arg values are:
FLUSHR
Flush read queues.
FLUSHW
Flush write queues.
FLUSHRW
Flush read and write queues.
If a pipe or FIFO does not have any modules pushed, the read queue

of the stream head on either end is flushed depending on the value of

argo
If FLUSHR is set and fildes is a pipe, the read queue for that end of the
pipe is flushed and the write queue for the other end is flushed. If

fildes is a FIFO, both queues are flushed.
If FLUSHW is set and fildes is a pipe and the other end of the pipe
exists, the read queue for the other end of the pipe is flushed and the
write queue for this end is flushed. If fildes is a FIFO, both queues of
the FIFO are flushed.
If FLUSHRW is set, all read queues are flushed, that is, the read queue
for the FIFO and the read queue on both ends of the pipe are flushed.
Correct flush handling of a pipe or FIFO with modules pushed is
achieved via the pipemod module. This module should be the first
module pushed onto a pipe so that it is at the midpoint of the pipe
itself.
On failure, ermo is set to one of the following values:
ENOSR
Unable to allocate buffers for flush message due to
insufficient STREAMS memory resources.
EINVAL
Invalid arg value.
ENXIO
Hangup received on fildes.
I_FLUSHBAND

Flushes a particular band of messages. arg points to a bandinfo
structure that has the following members:
unsigned char
bi....,pri;
bi_flag;
int
The bi_flag field may be one of
described earlier.
506

FLUSHR,

FLUSHW,

FLUSHRW

streamio (7)
Informs the stream head that the user wants the kernel to issue the
SIGPOLL signal [see signal(2)] when a particular event has occurred
on the stream associated with fildes. I_SETSIG supports an asynchronous processing capability in STREAMS. The value of arg is a bitmask that specifies the events for which the user should be signaled.
It is the bitwise-GR of any combination, except where noted, of the
following constants:
S_INPUT
Any message other than an M_PCPROTO has arrived on
a stream head read queue. This event is maintained
for compatibility with prior releases. This is set even
if the message is of zero length.
An ordinary (non-priority) message has arrived on a
stream head read queue. This is set even if the message is of zero length.
A priority band message (band> 0) has arrived on a
stream head read queue. This is set even if the message is of zero length.
A high priority message is present on the stream head
read queue. This is set even if the message is of zero
length.
The write queue just below the stream head is no
longer full. This notifies the user that there is room on
the queue for sending (or writing) data downstream.
This event is the same as S_OUTPUT.
A priority band greater than 0 of a queue downstream
exists and is writable. This notifies the user that there
is room on the queue for sending (or writing) priority
data downstream.
A STREAMS signal message that contains the SIGPOLL
signal has reached the front of the stream head read
queue.
An M_ERROR message has reached the stream head.
An M_HANGUP message has reached the stream head.
S_BANDURG
When used in conjunction with S_RDBAND, SIGURG is
generated instead of SIGPOLL when a priority message reaches the front of the stream head read queue.
A user process may choose to be signaled only of high priority messages by setting the arg bitrnask to the value S_HIPRI.
Processes that want to receive SIGPOLL signals must explicitly register to receive them using I_SETSIG. If several processes register to
receive this signal for the same event on the same stream, each
process will be signaled when the event occurs.

507

streamio (7)
If the value of arg is zero, the calling process will be unregistered and
will not receive further SIGPOLL Signals. On failure, ermo is set to
one of the following values:
EINVAL

arg value is invalid or arg is zero and process is not

EAGAIN

registered to receive the SIGPOLL signal.
Allocation of a data structure to store the signal
request failed.

Returns the events for which the calling process is currently
registered to be sent a SIGPOLL signal. The events are returned as a
bitmask pointed to by arg, where the events are those specified in the
description of I_SETSIG above. On failure, ermo is set to one of the
following values:
EINVAL
Process not registered to receive the SIGPOLL signal.
EFAULT

arg points outside the allocated address space.

Compares the names of all modules currently present in the stream
to the name pointed to by arg, and returns 1 if the named module is
present in the stream. It returns 0 if the named module is not
present. On failure, ermo is set to one of the following values:
EFAULT
EINVAL

arg points outside the allocated address space.
arg does not contain a valid module name.

Allows a user to retrieve the information in the first message on the
stream head read queue without taking the message off the queue.
I_PEEK is analogous to getmsg(2) except that it does not remove the
message from the queue. arg points to a strpeek structure which
contains the following members:
struct strbuf
struct strbuf
long

ctlbuf;
databuf;
flags;

The maxlen field in the ctlbuf and databuf strbuf structures [see
getmsg(2)] must be set to the number of bytes of control information
and/ or data information, respectively, to retrieve. flags may be set
to RS_HIPRI or O. If RS_HIPRI is set, I_PEEK will look for a high
priority message on the stream head read queue. Otherwise, I_PEEK
will look for the first message on the stream head read queue.
I_PEEK returns 1 if a message was retrieved, and returns 0 if no message was found on the stream head read queue. It does not wait for
a message to arrive. On return, ctlbuf specifies information in the
control buffer, databuf specifies information in the data
buffer, and flags contains the value RS_HIPRI or O. On failure,
ermo is set to the following value:
EFAULT
arg points, or the buffer area specified in ctlbuf or
databuf is, outside the allocated address space.

508

streamio (7)
Queued message to be read is not valid for
Invalid value for flags.

EBADMSG
EINVAL

Sets the read mode [see
Valid arg values are:

read(2)]

I_PEEK

using the value of the argument argo

RNORM

Byte-stream mode, the default.

RMSGD

Message-discard mode.

RMSGN

Message-nondiscard mode.

Setting both RMSGD and RMSGN is an error.

RMSGD

and RMSGN override

RNORM.

In addition, treatment of control messages by the stream head may
be changed by setting the following flags in arg:
RPROTNORM

Fail read with EBADMSG if a control message is at the
front of the stream head read queue. This is the
default behavior.

RPROTDAT

Deliver the control portion of a message as data when
a user issues read.

RPROTDIS

Discard the control portion of a message, delivering
any data portion, when a user issues a read.

On failure,

I_GRDOPT

errno

arg is not one of the above valid values.

EINVAL

Both RMSGD and RMSGN are set.

Returns the current read mode setting in an int pointed to by the
argument argo Read modes are described in read(2). On failure,
errno is set to the following value:
EFAULT

I_NREAD

arg points outside the allocated address space.

Counts the number of data bytes in data blocks in the first message
on the stream head read queue, and places this value in the location
pointed to by argo The return value for the command is the number
of messages on the stream head read queue. For example, if zero is
returned in arg, but the ioctl return value is greater than zero, this
indicates that a zero-length message is next on the queue. On failure,
errno is set to the following value:
EFAULT

I_FDINSERT

is set to the following value:

EINVAL

arg points outside the allocated address space.

Creates a message from user specified buffer(s), adds information
about another stream and sends the message downstream. The message contains a control part and an optional data part. The data and
control parts to be sent are distinguished by placement in separate
buffers, as described below.

arg points to a

strfdinsert

structure which contains the following

members:

509

streamio (7)
struct strbuf
struct strbuf
long
int
int

ctlbuf;
databuf;
flags;
fildes;
offset;

The len field in the ctlbuf strbuf structure [see putmsg(2)] must
be set to the size of a pointer plus the number of bytes of control
information to be sent with the message. fildes in the strfdinsert
structure specifies the file descriptor of the other stream. offset,
which must be word-aligned, specifies the number of bytes beyond
the beginning of the control buffer where I_FDINSERT will store a
pointer. This pointer will be the address of the read queue structure
of the driver for the stream corresponding to fildes in the strfdinsert structure. The len field in the databuf strbuf structure
must be set to the number of bytes of data information to be sent
with the message or zero if no data part is to be sent.
flags specifies the type of message to be created. An ordinary
(non-priority) message is created if flags is set to 0, a high priority
message is created if flags is set to RS_HIPRI. For normal messages, I_FDINSERT will block if the stream write queue is full due to
internal flow control conditions. For high priority messages,
I_FDINSERT does not block on this condition. For normal messages,
I_FDINSERT does not block when the write queue is full and
O_NDELAY or O_NONBLOCK is set. Instead, it fails and sets ermo to
EAGAIN.
I_FDINSERT also blocks, unless prevented by lack of internal
resources, waiting for the availability of message blocks, regardless
of priority or whether O_NDELAY or O_NONBLOCK has been specified.
No partial message is sent. On failure, ermo is set to one of the
following values:
EAGAIN A non-priority message was specified, the O_NDELAY or
O_NONBLOCK flag is set, and the stream write queue is full
due to internal flow control conditions.
ENOSR Buffers could not be allocated for the message that was to
be created due to insufficient STREAMS memory resources.
EFAULT arg points, or the buffer area specified in ctlbuf or databuf is, outside the allocated address space.
EINVAL One of the following: fildes in the strfdinsert structure
is not a valid, open stream file descriptor; the size of a
pointer plus offset is greater than the len field for the
buffer specified through ctlptr; offset does not specify a
properly-aligned location in the data buffer; an undefined
value is stored in flags.

510

streamio (7)
ENXIO

Hangup received on fildes of the ioctl call or fildes in
the strfdinsert structure.

ERANGE The len field for the buffer specified through databuf does

not fall within the range specified by the maximum and
minimum packet sizes of the topmost stream module, or the
len field for the buffer specified through databuf is larger
than the maximum configured size of the data part of a
message, or the len field for the buffer specified through
ctlbuf is larger than the maximum configured size of the
control part of a message.
I_FDINSERT can also fail if an error message was received by the
stream head of the stream corresponding to fildes in the strfdinsert structure. In this case, ermo will be set to the value in the
message.

Constructs an internal STREAMS ioctl message from the data pOinted
to by arg, and sends that message downstream.
This mechanism is provided to send user ioctl requests to downstream modules and drivers. It allows information to be sent with
the ioctl, and will return to the user any information sent upstream
by the downstream recipient. I_STR blocks until the system
responds with either a positive or negative acknowledgement message, or until the request "times out" after some period of time. If
the request times out, it fails with ermo set to ETlME.
At most, one I_STR can be active on a stream. Further I_STR calls
will block until the active I_STR completes at the stream head. The
default timeout interval for these requests is 15 seconds. The
O_NDELAY and O_NONBLOCK [see open(2)] flags have no effect on this
call.
To send requests downstream, arg must point to a strioctl structure which contains the following members:
int
int
int
char

ic_cmd;
ic_timout;
ic_Ien;
*ic_dp;

ic_cmd is the internal ioctl command intended for a downstream
module or driver and ic_timout is the number of seconds (-1 =
infinite, 0 = use default, >0 = as specified) an I_STR request will wait
for acknowledgement before timing out. The default timeout is
infinite. ic_Ien is the number of bytes in the data argument and
ic_dp is a pointer to the data argument. The ic_Ien field has two
uses: on input, it contains the length of the data argument passed in,
and on return from the command, it contains the number of bytes
being returned to the user (the buffer pointed to by ic_dp should be
large enough to contain the maximum amount of data that any
module or the driver in the stream can return).

511

streamio (7)
The stream head will convert the information pointed to by the
strioctl structure to an internal ioctl command message and
send it downstream. On failure, errno is set to one of the following
values:
Unable to allocate buffers for the ioctl message due
ENOSR
to insufficient STREAMS memory resources.
EFAULT
arg points, or the buffer area specified by ic_dp and
ic_Ien (separately for data sent and data returned) is,
outside the allocated address space.
EINVAL
ic_Ien is less than 0 or ic_Ien is larger than the maximum configured size of the data part of a message or
ic_timout is less than-l.
Hangup received on fildes.
ENXIO
A downstream ioctl timed out before acknowledgement was received.
An I_STR can also fail while waiting for an acknowledgement if a
message indicating an error or a hangup is received at the stream
head. In addition, an error code can be returned in the positive or
negative acknowledgement message, in the event the ioctl command
sent downstream fails. For these cases, I_STR will fail with errno
set to the value in the message.
Sets the write mode using the value of the argument argo Legal bit
settings for arg are:
SNDZERO
Send a zero-length message downstream when a write
of 0 bytes occurs.
To not send a zero-length message when a write of 0 bytes occurs,
this bit must not be set in argo
On failure, errno may be set to the following value:

ETIME

EINVAL

arg is not the above valid value.

Returns the current write mode setting, as described above, in the
int that is pointed to by the argument argo
Requests the stream associated with fildes to send a message, containing a file pointer, to the stream head at the other end of a stream
pipe. The file pointer corresponds to arg, which must be an open file
descriptor.
I_SENDFD converts arg into the corresponding system file pointer. It
allocates a message block and inserts the file pointer in the block.
The user ID and group ID associated with the sending process are
also inserted. This message is placed directly on the read queue [see
intro(2)] of the stream head at the other end of the stream pipe to
which it is connected. On failure, errno is set to one of the following
values:

512

streamio (7)
EAGAIN

The sending stream is unable to allocate a message
block to contain the file pointer.

EAGAIN

The read queue of the receiving stream head is full
and cannot accept the message sent by I_SENDFD.

EBADF

arg is not a valid, open file descriptor.

fildes is not connected to a stream pipe.
Hangup received on fildes.
Retrieves the file descriptor associated with the message sent by an
I_SENDFD ioctl over a stream pipe. arg is a pointer to a data buffer
large enough to hold an strrecvfd data structure containing the
following members:
EINVAL
ENXIO

int fd;
uid_t uid;
gid_t gid;
char fill [8] ;
fd is an integer file descriptor. uid and gid are the user ID and
group ID, respectively, of the sending stream.
If O_NDELAY and O_NONBLOCK are clear [see open(2)], I_RECVFD will
block until a message is present at the stream head. If O_NDELAY or
O_NONBLOCK is set, I_RECVFD will fail with ermo set to EAGAIN if no
message is present at the stream head.

If the message at the stream head is a message sent by an I_SENDFD,
a new user file descriptor is allocated for the file pointer contained in
the message. The new file descriptor is placed in the fd field of the
strrecvfd structure. The structure is copied into the user data
buffer pointed to by argo

On failure, ermo is set to one of the following values:
EAGAIN
EBADMSG
EFAULT
EMFlLE
ENXIO
EOVERFLOW

I_S_RECVFD

A message is not present at the stream head read
queue, and the O_NDELAY or O_NONBLOCK flag is set.
The message at the stream head read queue is not a
message containing a passed file descriptor.
arg points outside the allocated address space.
NOFILES file descriptors are currently open.
Hangup received on fildes.
uid or gid is too large to be stored in the structure
pointed to by argo

Retrieves the file descriptor associated with the message sent by an
I_SENDFD ioctl over a stream pipe. arg is a pointer to a data buffer
large enough to hold an s_strrecvfd data structure containing the
following members:

513

streamio (7)
int fd;
uid_t uid;
gid_t gid;
struct sub_attr s_attrs;
fd is an integer file descriptor. uid and gid are the user lO and
group lO, respectively, of the sending stream. sub_attr contains
security relevant information. The sub_attr structure is used as an
argument for the secadvise(2) system call, which provides advisory
access information.
If O_NDELAY and O_NONBLOCK are clear [see open(2»), I_RECVFD will
block until a message is present at the stream head. If O_NDELAY or
O_NONBLOCK is set, I_RECVFD will fail with errno set to EAGAIN if no

message is present at the stream head.
If the message at the stream head is a message sent by an I_SENDFD,

a new user file descriptor is allocated for the file pointer contained in
the message. The new file descriptor is placed in the fd field of the
s_strrecvfd structure. The structure is copied into the user data
buffer pointed to by argo
On failure, errno is set to one of the following values:

ENOMEM

The system cannot allocate
s_strrecvfd structure.

memory

EAGAIN

A message is not present at the stream head read
queue, and the O_NDELAY or O_NONBLOCK flag is set.

EBADMSG

The message at the stream head read queue is not a
message containing a passed file descriptor.

EFAULT
EMFILE

arg points outside the alloc~ted address space.
NOFILES file descriptors are currently open.

ENXIO

Hangup received onfildes.

EOVERFLOW

for

the

uid or gid is too large to be stored in the structure
pointed to byarg.
Allows the user to list all the module names on the stream, up to and
including the topmost driver name. If arg is NULL, the return value is
the number of modules, including the driver, that are on the stream
pOinted to by fildes. This allows the user to allocate enough space for
the module names. If arg is non-NULL, it should point to an
str_list structure that has the following members:

int sl_nmods;
struct str_mlist
The str_mlist structure has the following member:
char l_name[FMNAMESZ+l];

514

streamio (7)
sl_nmods indicates the number of entries the user has allocated in
the array. On success, the return value is 0, sl_modlist contains the
list of module names, and sl_mnods indicates the number of entries
that have been filled in. On failure, errno may be set to one of the
following values:

The sl_mnods member is less than 1.
Unable to allocate buffers
Allows the user to see if the current message on the stream head read
queue is "marked" by some module downstream. arg determines
how the checking is done when there may be multiple marked messages on the stream head read queue. It may take the following
values:

EINVAL

EAGAIN

ANYMARK

Check if the message is marked.

Check if the message is the last one marked on the
queue.
If both ANYMARK and LASTMARK are set, ANYMARK supersedes LASTLASTMARK

MARK.

The return value is 1 if the mark condition is satisfied and
wise. On failure, errno may be set to the following value:
I_CKBAND

I_GETBAND

°other-

EINVAL
A value other than (ANYMARK I LASTMARK) is set in argo
Check if the message of a given priority band exists on the stream
head read queue. This returns 1 if a message of a given priority
exists, or -Ion error. arg should be an integer containing the value
of the priority band in question. On failure, errno may be set to the
following value:
EINVAL
Invalid arg value.
Returns the priority band of the first message on the stream head
read queue in the integer referenced by argo On failure, errno may
be set to the following value:

No message on the stream head read queue.
Check if a certain band is writable. arg is set to the priority band in
question. The return value is 0 if the priority band arg is flow controlled, 1 if the band is writable, or -Ion error. On failure, errno
may be set to the following value:
EINVAL
Invalid arg value.

ENODATA

I_CANPUT

I_SETCLTIME

Allows the user to set the time the stream head will delay when a
stream is closing and there is data on the write queues. Before closing each module and driver, the stream head will delay for the
specified amount of time to allow the data to drain. If, after the
delay, data is still present, data will be flushed. arg is a pointer to the
number of milliseconds to delay, rounded up to the nearest valid

515

streamio (7)
value on the system. The default is fifteen seconds. On failure,
errno may be set to the following value:
EINVAL
Invalid arg value.
I_GETCLTIME

Returns the close time delay in the long pointed by argo
The following four commands are used for connecting and disconnecting multiplexed STREAMS configurations.
I_LINK
Connects two streams, where fildes is the file descriptor of the stream
connected to the multiplexing driver, and arg is the file descriptor of
the stream connected to another driver. The stream designated by
arg gets connected below the multiplexing driver. I_LINK requires
the multiplexing driver to send an acknowledgement message to the
stream head regarding the linking operation. This call returns a multiplexor ID number (an identifier used to disconnect the multiplexor,
see I_UNLINK) on success, and a -Ion failure. On failure, errno is
set to one of the following values:
ENXIO
Hangup received onfildes.
ETIME
EAGAIN

Time out before acknowledgement message was
received at stream head.
Temporarily unable to allocate storage to perform the
I_LINK.

ENOSR

Unable to allocate storage to perform the I_LINK due
to insufficient STREAMS memory resources.

EBADF

arg is not a valid, open file descriptor.
fildes stream does not support multiplexing.
arg is not a stream, or is already linked under a multi-

EINVAL
EINVAL

plexor.
The specified link operation would cause a "cycle" in
the resulting configuration; that is, if a given driver is
linked into a multiplexing configuration in more than
one place.
EINVAL
fildes is the file descriptor of a pipe or FIFO.
An I_LINK can also fail while waiting for the multiplexing driver to
acknowledge the link request, if a message indicating an error or a
hangup is received at the stream head of fildes. In addition, an error
code can be returned in the positive or negative acknowledgement
message. For these cases, I_LINK will fail with errno set to the
value in the message.
Disconnects the two streams specified by fildes and argo fildes is the
file descriptor of the stream connected to the multipleXing driver.
arg is the multiplexor ID number that was returned by the I_LINK. If
arg is -1, then all Streams which were linked to fildes are disconnected. As in I_LINK, this command requires the multiplexing
EINVAL

516

streamio (7)
driver to acknowledge the unlink. On failure, ermo is set to one of
the following values:
ENXIO

Hangup received on fildes.

ETIME

Time out before acknowledgement message was
received at stream head.
Unable to allocate storage to perform the I_UNLINK
due to insufficient STREAMS memory resources.

ENOSR

arg is an invalid multiplexor ID number or fildes is not
the stream on which the I_LINK that returned arg was
performed.
EINVAL
fildes is the file descriptor of a pipe or FIFO.
An I_UNLINK can also fail while waiting for the multiplexing driver
to acknowledge the link request, if a message indicating an error or a
hangup is received at the stream head of fildes. In addition, an error
code can be returned in the positive or negative acknowledgement
message. For these cases, I_UNLINK will fail with ermo set to the
value in the message.
Connects two streams, where fildes is the file descriptor of the stream
connected to the multiplexing driver, and arg is the file descriptor of
the stream connected to another driver. The stream designated by
arg gets connected via a persistent link below the multiplexing
driver. I_PLINK requires the multiplexing driver to send an acknowledgement message to the stream head regarding the linking
operation. This call creates a persistent link which can exist even if
the file descriptor fildes associated with the upper stream to the multiplexing driver is closed. This call returns a multiplexor ID number
(an identifier that may be used to disconnect the multiplexor, see
I_PUNLINK) on success, and a -Ion failure. On failure, ermo may
be set to one of the following values:
ENXIO
Hangup received on fildes.
ETIME
Time out before acknowledgement message was
received at the stream head.
EAGAIN
Unable to allocate STREAMS storage to perform the
EINVAL

I_PLINK.
EBADF

EINVAL
EINVAL
EINVAL

arg is not a valid, open file descriptor.
fildes does not support multiplexing.
arg is not a stream or is already linked under a multiplexor.
The specified link operation would cause a "cycle" in
the resulting configuration; that is, if a given stream
head is linked into a multiplexing configuration in
more than one place.

517

streamio (7)
fildes is the file descriptor of a pipe or FIFO.
An I_PLINK can also fail while waiting for the multiplexing driver to
acknowledge the link request, if a message indicating an error on a
hangup is received at the stream head of fildes. In addition, an error
code can be returned in the positive or negative acknowledgement
message. For these cases, I_PLINK will fail with errno set to the
value in the message.
EINVAL

I_PUNLINK

Disconnects the two streams specified by fildes and arg that are connected with a persistent link. fildes is the file descriptor of the stream
connected to the multiplexing driver. arg is the multiplexor ID
number that was returned by I_PLINK when a stream was linked
below the multiplexing driver. If arg is MUXID_ALL then all streams
which are persistent links to fildes are disconnected. As in I_PLINK,
this command requires the multiplexing driver to acknowledge the
unlink. On failure, errno may be set to one of the following values:
ENXIO

Hangup received on fildes.

ETIME

Time out before acknowledgement message was
received at the stream head.

EAGAIN

Unable to allocate buffers for the acknowledgement
message.

EINVAL

Invalid multiplexor ID number.

EINVAL

fildes is the file descriptor of a pipe or FIFO.

An I_PUNLINK can also fail while waiting for the multiplexing driver
to acknowledge the link request if a message indicating an error or a
hangup is received at the stream head of fildes. In addition, an error
code can be returned in the positive or negative acknowledgement
message. For these cases, I_PUNLINK will fail with errno set to the
value in the message.
SEE ALSO

close(2), fcntl(2), getmsg(2), intro(2), ioctl(2), open(2), poll(2), putmsg(2),
read(2), signal(2), signal(5), write(2)
DIAGNOSTICS

Unless specified otherwise above, ioctl returns 0 on success and -Ion failure and
sets errno as indicated.

518

sw01 (7)
NAME

swOl- Portable Device Interface (PDI) WORM Target Driver
DESCRIPTION

The swOl driver is a PDI-compliant WORM (Write Once Read Many) target driver
that provides access to one or more WORM drives. Each drive must be attached to
a SCSI Bus that is controlled by a PDI-compliant host adapter driver.
Access to the particular drive is accomplished through the swOl device nodes
located in /dev/ [rlwonn.
Each device node identifies a particular drive based on the SCSI ID assigned to that
drive. The binding between a device node and a WORM drive is as follows:
/dev/rwonn/wonnO

WORM drive with lowest SCSI ID

/dev/rwonn/wonnl

WORM drive with next to lowest SCSI ID

and so on.
A WORM drive uses removable media divided into consecutively numbered,
fixed-size sectors that may be accessed in any order, similar to a hard disk. Most of
the standard tools for reading and writing to and from a hard disk, such as such as
dd(l) or read(2), work with a WORM drive. However, keep in mind that for
WORM drives, each sector can be written to only once. This characteristic causes
problems if a WORM device is mounted [mount(lM)] without using the read-only
flag, -r.
ioetl Calls
The swOl driver supports several ioctl functions [see ioctl(2) in the Programmer's
Reference Manual], which are accessed through the ioctl system call. Many of the
supported ioctl calls provide a convenient method for sending one of the
preselected SCSI commands directly to the drive. SCSI commands not explicitly
supported by swOl can be sent to the drive using the pass-through facility provided
by the SDI host adapter driver.
The following ioctl calls are defined and required by the SDI interface.
Returns the type of peripheral bus (for example, scsi)
used and the name of the driver (for example, swOl) for
this specific device
Returns the major and minor number of the passthrough device for the WORM drive
Sends a SCSI Reserve command to the drive
SDI RELEASE

Sends a SCSI Release command to the drive

The following ioctl calls send the appropriate Group-O SCSI command to the
device. These commands are defined by the SCSI bus specification and should also
be described in the SCSI interface section of the reference manual supplied with
your WORM drive.
Sends a Test Unit Ready command to the device

519

sw01 (7)
W_REZERO
W_SEEK

Sends a Rezero Device command to the device
Sends a Seek command to the device

W_INQUIR

Sends an Inquiry command to the device, and returns
the resulting data back to the calling process

W_STARTUNIT

Sends a Start Unit command to the device
Sends a Stop Unit command to the device

W_STOPUNIT
W_PREVMV
W_ALLOMV

Sends a Prevent Media Removal command to the device
Sends an Allow Media Removal command to the device

The following ioctl calls send the appropriate Group-l SCSI command to the
device. The Group-l SCSI commands are defined by the SCSI bus specification and
should be described in the SCSI interface section of the reference manual supplied
with your WORM drive.
Sends a Read Capacity command to the device, and
returns the data sent by the drive
W_VERIFY
Sends a Verify command to the device
The following ioctl calls send the appropriate Group-6 SCSI command to the
drive. Group-6 SCSI commands are vendor specific and should be described in the
SCSI interface section of the reference manual supplied with your drive. Since the
format of these SCSI commands is vendor specific, these ioctl calls are supported
only by products compatible with the Toshiba D070 drive.
W_STNCHECK
Sends a Stand-By Check command to the device
W_LOADCART
Sends a Load Cartridge command to the device
Sends an Unload Cartridge command to the device
Sends a Read Control Block command to the device
The following ioctl calls send the appropriate Group-7 SCSI command to the
drive. Group-7 SCSI commands are vendor specific and should be described in the
SCSI interface section of the reference manual supplied with your drive. Since the
format of these SCSI commands is vendor specific, these ioctl calls are supported
only by products compatible with the Toshiba D070 drive.
Sends a Check command to the device
Sends a Contrary Check command to the device
W_UNLOADCA
W_READCB

The following ioctl calls are also supported the swOl driver.
B_GET_SUBDEVS
Returns the number of sub-devices supported by this
driver
Enables the swOl related system error messages
Disables the swOl related system error messages
Files
/usr/include/sys/swOl.h
/etc/conf/pack.d/swOl/space.c
/dev/[r]worm./*

520

sw01 (7)
/usr/inelude/sys/sesi.h
/usr/inelude/sys/sdi.h
/usr/inelude/sys/sdi_edt.h

REFERENCES
adse(7), dpt(7), ioctl(2), mcis(7), mount(lM), seOl(7), sdOl(7), stOl(7), wd7000(7)

521

sxt(7)
NAME

sxt - pseudo-device driver
DESCRIPTION

The special file /dev/sxt is a pseudo-device driver that interposes a discipline
between the standard tty line disciplines and a real device driver. The standard
disciplines manipulate virtual tty structures (channels) declared by the /dev/sxt
driver. /dev/sxt acts as a discipline manipulating a real tty structure declared by a
real device driver. The /dev/sxt driver is currently only used by the shl(l)
command.
Virtual ttys are named by inodes in the subdirectory /dev/sxt and are allocated in
groups of up to eight. To allocate a group, a program should exclusively open a file
with a name of the form /dev/sxt/??O (channel 0) and then execute a SXTIOCLINK
ioctl call to initiate the multiplexing.
Only one channel, the controlling channel, can receive input from the keyboard at a
time; others attempting to read will be blocked.
There are two groups of ioctl(2) commands supported by sxt. The first group
contains the standard ioctl commands described in termio(7), with the addition
of the following:
TIOCEXCL
Set exclusive use mode: no further opens are permitted until
the file has been closed.
Reset exclusive use mode: further opens are once again perTIOCNXCL
mitted.
The second group are commands to sxt itself. Some of these may only be executed
on channel o.
Allocate a channel group and multiplex the virtual ttys onto
SXTIOCLINK
the real tty. The argument is the number of channels to allocate. This command may only be executed on channel o.
Possible errors include:
EINVAL
ENOTTY

ENXIO
EBUSY

ENOMEM
EBADF

SXTIOCSWl'CH

There is no system memory available for allocating the virtual tty structures.
Channel 0 was not opened before this call.

Set the controlling channel. Possible errors include:
EINVAL
An invalid channel number was given.
EPERM

522

The argument is out of range.
The command was not issued from a real tty.
linesw is not configured with sxt.
An SXTIOCLINK command has already been
issued for this real tty.

The command was not executed from channel o.

sxt(7)
SXTIOCWF

Cause a channel to wait until it is the controlling channel.
This command will return the error, EINVAL, if an invalid
channel number is given.

SXTIOCUBLK

Turn off the loblk control flag in the virtual tty of the indicated channel. The error EINVAL will be returned if an
invalid number or channel 0 is given.

SXTIOCSTAT

Get the status (blocked on input or output) of each channel
and store in the sxtblock structure referenced by the argument. The error EFAULT will be returned if the structure cannot be written.

SXTIOCTRACE

Enable tracing. Tracing information is written to the console.
This command has no effect if tracing is not configured.

SXTIOCNOTRACE

Disable tracing. This command has no effect if tracing is not
configured.

/dev/sxt/?? [0-7]

Virtual tty devices

FILES
SEE ALSO

ioctl(2), open(2), shl(l), stty(l) termio(7)

523

TCP(7)
NAME

TCP - Internet Transmission Control Protocol
SYNOPSIS

#include
#include
s
t

= socket (AF_INET, SOCK_STREAM,
= t_open("/dev/tcp", O_RrMR);

0);

DESCRIPTION

TCP is the virtual circuit protocol of the Internet protocol family. It provides reliable, flow-controlled, in order, two-way transmission of data. It is a byte-stream
protocol layered above the Internet Protocol (IP), the Internet protocol family's
internetwork datagram delivery protocol.
Programs can access TCP using the socket interface as a SOCK_STREAM socket type,
or using the Transport Level Interface (TLI) where it supports the connectionoriented (T_COTS_ORD) service type.
TCP uses IP's host-level addressing and adds its own per-host collection of port
addresses. The endpoints of a TCP connection are identified by the combination of
an IP address and a TCP port number. Although other protocols, such as the User
Datagram Protocol (UDP), may use the same host and port address format, the port
space of these protocols is distinct. See inet(7) for details on the common aspects
of addressing in the Internet protocol family.
Sockets utilizing TCP are either active or passive. Active sockets initiate connections
to passive sockets. Both types of sockets must have their local IP address and TCP
port number bound with the bind(3N) system call after the socket is created. By
default, TCP sockets are active. A passive socket is created by calling the
listen(3N) system call after binding the socket with bind ( ). This establishes a
queuing parameter for the passive socket. After this, connections to the passive
socket can be received with the accept(3N) system call. Active sockets use the
connect(3N) call after binding to initiate connections.
By using the special value INADDR_ANY, the local IP address can be left unspecified
in the bind ( ) call by either active or passive TCP sockets. This feature is usually
used if the local address is either unknown or irrelevant. If left unspecified, the
local IP address will be bound at connection time to the address of the network
interface used to service the connection.
Once a connection has been established, data can be exchanged using the read(2)
and write(2) system calls.
TCP supports one socket option, TCP_NODELAY, which is set with setsockopt ( )
and tested with getsockopt(3N). Under most circumstances, TCP sends data when
it is presented. When outstanding data has not yet been acknowledged, it gathers
small amounts of output to be sent in a single packet once an acknowledgement is
received. For a small number of clients, such as window systems that send a stream
of mouse events which receive no replies, this packetization may cause significant
delays. Therefore, TCP provides a boolean option, TCP_NODELAY (defined in
/usr/include/netinet/tcp.h), to defeat this algorithm. The option level for

524

TCP(7)
the setsockopt () call is the protocol number for TCP, available from
getprotobyname ( ) [see getprotoent(3N)].
Options at the IP level may be used with TCP; See ip(7).
TCP provides an urgent data mechanism, which may be invoked using the out-ofband provisions of send(3N). The caller may mark one byte as urgent with the
MSG_OOB flag to send(3N). This sets an urgent pointer pointing to this byte in the
TCP stream. The receiver on the other side of the stream is notified of the urgent
data by a SIGURG signal. The SIOCATMARK ioctl ( ) request returns a value indicating whether the stream is at the urgent mark. Because the system never returns
data across the urgent mark in a single read(2) call, it is possible to advance to the
urgent data in a simple loop which reads data, testing the socket with the SIOCATMARK ioctl ( ) request, until it reaches the mark.

Incoming connection requests that include an IP source route option are noted, and
the reverse source route is used in responding.
A checksum over all data helps TCP implement reliability. Using a window-based
flow control mechanism that makes use of positive acknowledgements, sequence
numbers, and a retransmission strategy, TCP can usually recover when datagrams
are damaged, delayed, duplicated or delivered out of order by the underlying communication medium.
If the local TCP receives no acknowledgements from its peer for a period of time, as

would be the case if the remote machine crashed, the connection is closed and an
error is returned to the user. If the remote machine reboots or otherwise loses state
information about a TCP connection, the connection is aborted and an error is
returned to the user.
SEE ALSO

accept(3N), bind(3N), connect(3N), getprotoent(3N), getsockopt(3N),
inet(7), ip(7), listen(3N), read(2), send(3N), write(2)
Postel, Jon, Transmission Control Protocol- DARPA Internet Program Protocol
Specification, RFC 793, Network Information Center, SRI International, Menlo Park,
Calif., September 1981
DIAGNOSTICS

A socket operation may fail if:
EISCONN

A connect ( ) operation was attempted on a socket on which a
connect ( ) operation had already been performed.

ETIMEOOUT

A connection was dropped due to excessive retransmissions.

ECONNRESET

The remote peer forced the connection to be closed (usually
because the remote machine has lost state information about
the connection due to a crash).

ECONNREFUSED

The remote peer actively refused connection establishment
(usually because no process is listening to the port).

EADDRINUSE

A bind ( ) operation was attempted on a socket with a network
address/port pair that has already been bound to another
socket.

525

TCP(7)
EADDRNOTAVAIL

A bind ( ) operation was attempted on a socket with a network

address for which no network interface exists.
EACCES

A bind () operation was attempted with a reserved port

number and the effective user ID of the process was not the
privileged user.
ENOBUFS

526

The system ran out of memory for internal data structures.

termio(7)
NAME

tennio - general terminal interface
SYNOPSIS

#include
ioctl (int fildes, int request, struct tennio *arg)
ioctl (int fildes, int request, int arg) i

#include
ioctl (int fildes, int request, struct ter.mios *arg)

DESCRIPTION

System V supports a general interface for asynchronous communications ports that
is hardware-independent. The user interface to this functionality is via function
calls (the preferred interface) described in tennios(2) or ioctl commands
described in this section. This section also discusses the common features of the
terminal subsystem which are relevant with both user interfaces.
When a terminal file is opened, it normally causes the process to wait until a connection is established. In practice, users' programs seldom open terminal files; they
are opened by the system and become a user's standard input, output, and error
files. The very first terminal file opened by the session leader, which is not already
associated with a session, becomes the controlling terminal for that session. The
controlling terminal plays a special role in handling quit and interrupt signals, as
discussed below. The controlling terminal is inherited by a child process during a
fork(2). A process can break this association by changing its session using
setsid(2).
A terminal associated with one of these files ordinarily operates in full-duplex
mode. Characters may be typed at any time, even while output is occurring, and
are only lost when the character input buffers of the system become completely full,
which is rare (for example, if the number of characters in the line discipline buffer
exceeds {MAJCCANON} and IMAXBEL [see below] is not set), or when the user has
accumulated {MAX_INPUT} number of input characters that have not yet been read
by some program. When the input limit is reached, all the characters saved in the
buffer up to that point are thrown away without notice.
Session Management (Job Control)

A control terminal will distinguish one of the process groups in the session associated with it to be the foreground process group. All other process groups in the
session are designated as background process groups. This foreground process
group plays a special role in handling signal-generating input characters, as discussed below. By default, when a controlling terminal is allocated, the controlling
process's process group is assigned as foreground process group.
Background process groups in the controlling process's session are subject to a job
control line discipline when they attempt to access their controlling terminal. Process groups can be sent signals that will cause them to stop, unless they have made
other arrangements. An exception is made for members of orphaned process
groups. These are process groups which do not have a member with a parent in
another process group that is in the same session and therefore shares the same controlling terminal. When a member's orphaned process group attempts to access its

527

termio(7)
controlling terminal, errors will be returned. since there is no process to continue it
if it should stop.
If a member of a background process group attempts to read its controlling termi-

nal, its process group will be sent a SIGTTIN signal, which will normally cause the
members of that process group to stop. If, however, the process is ignoring or holding SIGTTIN, or is a member of an orphaned process group, the read will fail with
errno set to EIO, and no signal will be sent.
If a member of a background process group attempts to write its controlling termi-

nal and the TOSTOP bit is set in the c_lflag field, its process group will be sent a
SIGTTOU signal, which will normally cause the members of that process group to
stop. If, however, the process is ignoring or holding SIGTTOU, the write will
succeed. If the process is not ignoring or holding SIGTTOU and is a member of an
orphaned process group, the write will fail with ermo set to EIO, and no signal will
be sent.
If TOSTOP is set and a member of a background process group attempts to ioctl its
controlling terminal, and that ioctl will modify terminal parameters (for example,
TCSETA, TCSETAW, TCSETAF, or TIOCSPGRP), its process group will be sent a
SIGTTOU signal, which will normally cause the members of that process group to
stop. If, however, the process is ignoring or holding SIGTTOU, the ioctl will
succeed. If the process is not ignoring or holding SIGTTOU and is a member of an
orphaned process group, the write will fail with errno set to EIO, and no signal will
be sent.
Canonical Mode Input Processing

Normally, terminal input is processed in units of lines. A line is delimited by a
newline (ASCII LF) character, an end-of-file (ASCII EOT) character, or an end-of-line
character. This means that a program attempting to read will be suspended until an
entire line has been typed. Also, no matter how many characters are requested in
the read call, at most one line will be returned. It is not necessary, however, to read
a whole line at once; any number of characters may be requested in a read, even
one, without losing information.
During input, erase and kill processing is normally done. The ERASE character (by
default, the character #) erases the last character typed. The WERASE character (the
character control-W) erases the last "word" typed in the current input line (but not
any preceding spaces or tabs). A "word" is defined as a sequence of non-blank
characters, with tabs counted as blanks. Neither ERASE nor WERASE will erase
beyond the beginning of the line. The KILL character (by default, the character @)
kills (deletes) the entire input line, and optionally outputs a newline character. All
these characters operate on a key stroke basis, independent of any backspacing or
tabbing that may have been done. The REPRINT character (the character control-R)
prints a newline followed by all characters that have not been read. Reprinting also
occurs automatically if characters that would normally be erased from the screen
are fouled by program output. The characters are reprinted as if they were being
echoed; consequencely, if ECHO is not set, they are not printed.
The ERASE and KILL characters may be entered literally by preceding them with the
escape character (\). In this case, the escape character is not read. The erase and
kill characters may be changed.

528

termio(7)
Non-canonical Mode Input Processing

In non-canonical mode input processing, input characters are not assembled into
lines, and erase and kill processing does not occur. The MIN and TIME values are
used to determine how to process the characters received.
MIN represents the minimum number of characters that should be received when
the read is satisfied (that is, when the characters are returned to the user). TIME is a
timer of O.lO-second granularity that is used to timeout bursty and short-term data
transmissions. The values for MIN and TIME should be set by the programmer in the
tennios or tennio structure. The four possible values for MIN and TIME and their
interactions are described below.
Case A: MIN> a, TIME > a
In this case, TIME serves as an intercharacter timer and is activated after the first
character is received. Since it is an intercharacter timer, it is reset after a character is received. The interaction between MIN and TIME is as follows: as soon as
one character is received, the intercharacter timer is started. If MIN characters
are received before the intercharacter timer expires (note that the timer is reset
upon receipt of each character), the read is satisfied. If the timer expires before
MIN characters are received, the characters received to that point are returned to
the user. Note that if TIME expires, at least one character will be returned
because the timer would not have been enabled unless a character was received.
In this case (MIN> a, TIME > a), the read sleeps until the MIN and TIME mechanisms are activated by the receipt of the first character. If the number of characters read is less than the number of characters available, the timer is not reactivated and the subsequent read is satisfied immediately.
Case B: MIN> a, TIME = a
In this case, since the value of TIME is zero, the timer plays no role and only MIN
is Significant. A pending read is not satisfied until MIN characters are received
(the pending read sleeps until MIN characters are received). A program that uses
this case to read record based terminalI/O may block indefinitely in the read
operation.
Case C: MIN = a, TIME > a
In this case, since MIN = a, TIME no longer represents an intercharacter timer: it
now serves as a read timer that is activated as soon as a read is done. A read is
satisfied as soon as a single character is received or the read timer expires. Note
that, in this case, if the timer expires, no character is returned. If the timer does
not expire, the only way the read can be satisfied is if a character is received. In
this case, the read will not block indefinitely waiting for a character; if no character is received within TIME*.lO seconds after the read is initiated, the read
returns with zero characters.
Case D: MIN = a, TIME = a
In this case, return is immediate. The minimum of either the number of characters requested or the number of characters currently available is returned
without waiting for more characters to be input.
Comparison of the Different Cases of MIN, TIME Interaction

Some points to note about MIN and TIME:

529

termio(7)
1. In the following explanations, note that the interactions of MIN and TIME are not
symmetric. For example, when MIN > 0 and TIME = 0, TIME has no effect. However, in the opposite case, where MIN = 0 and TIME> 0, both MIN and TIME playa
role in that MIN is satisfied with the receipt of a single character.
2. Also note that in case A (MIN> 0, TIME > 0), TIME represents an intercharacter
timer, whereas in case C (TIME = 0, TIME> 0), TIME represents a read timer.
These two points highlight the dual purpose of the MIN/TIME feature. Cases A and
B, where MIN > 0, exist to handle burst mode activity (for example, file transfer programs), where a program would like to process at least MIN characters at a time. In
case A, the intercharacter timer is activated by a user as a safety measure; in case B,
the timer is turned off.
Cases C and D exist to handle single character, timed transfers. These cases are
readily adaptable to screen-based applications that need to know if a character is
present in the input queue before refreshing the screen. In case C, the read is timed,
whereas in case D, it is not.
Another important note is that MIN is always just a minimum. It does not denote a
record length. For example, if a program does a read of 20 bytes, MIN is 10, and 25
characters are present, then 20 characters will be returned to the user.

Writing Characters
When one or more characters are written, they are transmitted to the terminal as
soon as previously written characters have finished typing. Input characters are
echoed as they are typed if echoing has been enabled. If a process produces characters more rapidly than they can be typed, it will be suspended when its output
queue exceeds some limit. When the queue is drained down to some threshold, the
program is resumed.
Special Characters
Certain characters have special functions on input. These functions and their
default character values are summarized as follows:
INTR
(Rubout or ASCII DEL) generates a SIGINT signal. SIGINT is sent to all
frequent processes associated with the controlling terminal. Normally,
each such process is forced to terminate, but arrangements may be made
either to ignore the signal or to receive a trap to an agreed upon location. [See signal(5)].
QUIT
(CTRL-I or ASCII FS) generates a SIGQUIT signal. Its treatment is identical to the interrupt signal except that, unless a receiving process has
made other arrangements, it will not only be terminated but a core
image file (called core) will be created in the current working directory.
(#) erases the preceding character. It does not erase beyond the start of a
ERASE
line, as delimited by a NL, EOF, EOL, or EOL2 character.
(CTRL-W or ASCII ETX) erases the preceding "word". It does not erase
WERASE
beyond the start of a line, as delimited by a NL, EOF, EOL, or EOL2 character.

530

termio (7)
KILL

REPRINT

EOF

NL
EOL
EOL2

SWTCH
SUSP
DSUSP

STOP

START

DISCARD

(@) deletes the entire line, as delimited by a NL, EOF, EOL, or EOL2 character.
(CTRL-R or ASCII DC2) reprints all characters, preceded by a newline,
that have not been read.
(CTRL-D or ASCII EOT) may be used to generate an end-of-file from a terminal. When received, all the characters waiting to be read are immediately passed to the program, without waiting for a newline, and the EOF
is discarded. Thus, if no characters are waiting (that is, the EOF
occurred at the beginning of a line) zero characters are passed back,
which is the standard end-of-file indication. The EOF character is not
echoed unless it is escaped or ECHOCTL is set. Because EOT is the
default EOF character, this prevents terminals that respond to EOT from
hanging up.
(ASCII LF) is the normal line delimiter. It cannot be changed or escaped.
(ASCII NULL) is an additional line delimiter, like NL. It is not normally
used.
is another additional line delimiter.

(CTRL-Z or ASCII EM) is used only when shllayers is invoked.
(CTRL-Z or ASCII SUB) generates a SIGTSTP signal. SIGTSTP stops all
processes in the foreground process group for that terminal.
(CTRL-Y or ASCII EM) It generates a SIGTSTP signal as SUSP does, but the
signal is sent when a process in the foreground process group attempts
to read the DSUSP character, rather than when it is typed.
(CTRL-S or ASCII DC3) can be used to suspend output temporarily. It is
useful with CRT terminals to prevent output from disappearing before it
can be read. While output is suspended, STOP characters are ignored
and not read.
(CTRL-Q or ASCII DCl) is used to resume output. Output has been
suspended by a STOP character. While output is not suspended, START
characters are ignored and not read.
(CTRL-O or ASCII SI) causes subsequent output to be discarded. Output
is discarded until another DISCARD character is typed, more input
arrives, or the condition is cleared by a program.

(CTRL-V or ASCII SYN) causes the special meaning of the next character
to be ignored. This works for all the special characters mentioned
above. It allows characters to be input that would otherwise be interpreted by the system (for example, KILL, QUIT).
The character values for INTR, QUIT, ERASE, WERASE, KILL, REPRINT, EOF, EOL, EOL2,
SWTCH, SUSP, DSUSP, STOP, START, DISCARD, and LNEXT may be changed to suit
individual tastes. If the value of a special control character is ]OSIX_VDISABLE (0),
the function of that special control character is disabled. The ERASE, KILL, and EOF
characters may be escaped by a preceding \ character, in which case no special
function is done. Any of the special characters may be preceded by the LNEXT character, in which case no special function is done.
LNEXT

531

termio(7)
Modem Disconnect

When a modem disconnect is detected, a SIGHUP signal is sent to the terminal's controlling process. Unless other arrangements have been made, these signals cause
the process to terminate. If SIGHUP is ignored or caught, any subsequent read
returns with an end-of-file indication until the terminal is closed.
Processes in background process groups that attempt to access the controlling terminal after modem disconnect while the terminal is still allocated to the session will
receive appropriate SIGTTOU and SIGTTIN signals. Unless other arrangements have
been made, this signal causes the processes to stop.
The controlling terminal will remain in this state until it is reinitialized with a successful open by the controlling process, or deallocated by the controlling process.
Terminal Parameters

The parameters that control the behavior of devices and modules providing the
termios interface are specified by the termios structure defined by termios. h.
Several ioctl(2) system calls that fetch or change these parameters use this structure that contains the following members:
tcflag_t
tcflag_t
tcflag_t
tcflag_t
cc_t

c_iflag;
c_oflag;
c_cflag;
c_lflag;
c_cc[NCCS);

1*
1*
1*
1*
1*

input modes *1
output modes *1
control modes *1
local modes *1
control chars *1

The special control characters are defined by the array c_cc. The symbolic name
NCCS is the size of the control-character array and is also defined by tennios .h.
The relative positions, subscript names, and typical default values for each function
are as follows:

a
1

3
4
5
6

7
8

VINTR
VQUIT
VERASE
VKILL
VEOF
VEOL
VEOL2
VSWl'CH

DEL

FS
#
@

EOT
NUL
NUL
NUL

DCI
DC3

11
12

VSTRT
VSTOP
VSUSP
VDSUSP
VREPRINT

VDISCRD

DC2
S1

VWERASE
VLNEXT

ETB
SYN

9
10

SUB
EM

16-19 reserved
For the non-canonical mode the positions of VEOF and VEaL are shared by WIN and
VTIME:

532

VMIN
VTIME

used to set the value of MIN
used to set the value of TIME

termio(7)
Input Modes
The c_iflag field describes the basic terminal input control:
IGNBRK
BRKINT

IGNPAR
PARMRK
INPCK
ISTRIP
INLCR
IGNCR
ICRNL

IUCLC
IXON
lXANY
IXOFF

IMAXBEL

Ignore break condition.
Signal interrupt on break.
Ignore characters with parity errors.
Mark parity errors.
Enable input parity check.
Strip character.
Map NL to CR on input.
Ignore CR.
Map CR to NL on input.
Map upper-case to lower-case on input.
Enable start! stop output control.
Enable any character to restart output.
Enable start! stop input control.
Echo BEL on input line too long.

If IGNBRK is set, a break condition (a character framing error with data an zeros)
detected on input is ignored, that is, not put on the input queue and therefore not
read by any process. If IGNBRK is not set and BRKINT is set, the break condition
shan flush the input and output queues and if the terminal is the controlling terminal of a foreground process group, the break condition generates a single SIGINT
signal to that foreground process group. If neither IGNBRK nor BRKINT is set, a
break condition is read as a single ASCII NULL character ('\0'), or if PARMRK is set, as
'\377', '\0', '\0'.
If IGNPAR is set, a byte with framing or parity errors (other than break) is ignored.
If PARMRK is set, and IGNPAR is not set, a byte with a framing or parity error (other
than break) is given to the application as the three-character sequence: '\377', '\0',
X, where X is the data of the byte received in error. To avoid ambiguity in this case,
if ISTRIP is not set, a valid character of '\377' is given to the application as '\377',
'\377'. If neither IGNPAR nor PARMRK is set, a framing or parity error (other than
break) is given to the application as a single ASCII NULL character ('\0').
If INPCK is set, input parity checking is enabled. If INPCK is not set, input parity
checking is disabled. This anows output parity generation without input parity
errors. Note that whether input parity checking is enabled or disabled is independent of whether parity detection is enabled or disabled. If parity detection is
enabled but input parity checking is disabled, the hardware to which the terminal is
connected will recognize the parity bit, but the terminal special file will not check
whether this is set correctly or not.
If ISTRIP is set, valid input characters are first stripped to seven bits, otherwise an
eight bits are processed.
If INLCR is set, a received NL character is translated into a CR character. If IGNCR is
set, a received CR character is ignored (not read). Otherwise, if ICRNL is set, a
received CR character is translated into a NL character.

533

termio(7)
If IUCLC is set, a received upper case, alphabetic character is translated into the

corresponding lower case character.
If IXON is set, start/stop output control is enabled. A received STOP character

suspends output and a received START character restarts output. The STOP and
characters will not be read, but will merely perform flow control functions.
If lXANY is set, any input character restarts output that has been suspended.
If IXOFF is set, the system transmits a STOP character when the input queue is
nearly full, and a START character when enough input has been read so that the
input queue is nearly empty again.
START

If lMAXBEL is set, the ASCII BEL character is echoed if the input stream overflows.

Further input is not stored, but any input already present in the input stream is not
disturbed. If IMAXBEL is not set, no BEL character is echoed, and all input present in
the input queue is discarded if the input stream overflows.
The initial input control value is BRKINT, ICRNL, IXON, ISTRIP.
Output Modes
The c_oflag field specifies the system treatment of output:
OPOST
Post-process output.
OLCUC
Map lower case to upper on output.
ONLCR
Map NL to CR-NL on output.
OCRNL
Map CR to NL on output.
ONOCR
No CR output at column O.
ONLRET
NL performs CR function.
OFILL
Use fill characters for delay.
OFDEL
Fill is DEL, else NULL.
NLDLY
Select newline delays:
NLO
NLl
CRDLY
Select carriage-return delays:
CRO
CRl
CR2

CR3
TABDLY
TABO
TABl
TAB2
TAB3
XTABS
BSDLY
BSO
BSl
VTDLY
VTO
VTl
FFDLY
FFO
FFl
534

Select horizontal tab delays:
or tab expansion:
Expand tabs to spaces.
Expand tabs to spaces.
Select backspace delays:
Select vertical tab delays:
Select form feed delays:

termio (7)
If OPOST is set, output characters are post-processed as indicated by the remaining

flags; otherwise, characters are transmitted without change.
If OLCUC is set, a lower case alphabetic character is transmitted as the corresponding

upper case character. This function is often used in conjunction with IUCLC.
If ONLCR is set, the NL character is transmitted as the CR-NL character pair. If OCRNL
is set, the CR character is transmitted as the NL character. If ONOCR is set, no CR
character is transmitted when at column 0 (first position). If ONRET is set, the NL

character is assumed to do the carriage-return function; the column pointer is set to

o and the delays specified for CR are used. Otherwise, the NL character is assumed
to do just the line-feed function; the column pointer remains unchanged. The
column pointer is also set to 0 if the CR character is actually transmitted.
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. If OFILL is set, fill characters are transmitted for delay instead of
a timed delay. This is useful for high baud rate terminals that need only a minimal
delay. If OFDEL is set, the fill character is DEL; otherwise it is NULL.
If a form-feed or vertical-tab delay is specified, it lasts for about 2 seconds.
Newline delay lasts about 0.10 seconds. If ONLRET is set, the carriage-return delays
are used instead of the newline delays. If OFILL is set, two fill characters are
transmitted.
Carriage-return delay type 1 is dependent on the current column position, type 2 is
about 0.10 seconds, and type 3 is about O.lS seconds. If OFILL is set, delay type 1
transmits two fill characters, and type 2 transmits four fill characters.
Horizontal-tab delay type 1 is dependent on the current column position. Type 2 is
about 0.10 seconds. Type 3 specifies that tabs are to be expanded into spaces. If
OFILL is set, two fill characters are transmitted for any delay.
Backspace delay lasts about O.OS seconds. If OFILL is set, one fill character is
transmitted.
The actual delays depend on line speed and system load.
The initial output control value is OPOST,

ONLCR, TAB3.

Control Modes
The c_cflag field describes the hardware control of the terminal:
CBAUD

BO
B50
B75
BllO
B134
B150
B200
B300
B600
B1200
B1800

Baud rate:
Hang up
SO baud
7Sbaud
110 baud
134 baud
lS0baud
200 baud
300 baud
600 baud
1200 baud
1800 baud

535

termio (7)
B2400
B4S00
B9600
B19200
EXTA

B3S400
EXTB

2400 baud
4800 baud
9600 baud
19200 baud
External A
38400 baud
External B

CSIZE
CS5
CS6
CS7
CSS

Character size:
5 bits
6 bits
7 bits
8 bits

CSTOPB
CREAD

Send two stop bits, else one
Enable receiver
Parity enable
Odd parity, else even
Hang up on last close
Local line, else dial-up
Input baud rate, if different from output rate
Extended parity for mark and space parity

PARENB
PARODD

HUPCL
CLOCAL

CIBAUD
PAREXT

The CBAUD bits specify the baud rate. The zero baud rate, BO, is used to hang up the
connection. If BO is specified, the data-terminal-ready signal is not asserted. Normally, this disconnects the line. If the CIBAUD bits are not zero, they specify the
input baud rate, with the CBAUD bits specifying the output baud rate; otherwise, the
output and input baud rates are both specified by the CBAUD bits. The values for the
CIBAUD bits are the same as the values for the CBAUD bits, shifted left IBSHIFT bits.
For any particular hardware, impossible speed changes are ignored.
The CSIZE bits specify the character size in bits for both transmission and reception.
This size does not include the parity bit, if any. If CSTOPB is set, two stop bits are
used; otherwise, one stop bit is used. For example, at 110 baud, two stops bits are
required.
If PARENB is set, parity generation and detection is enabled, and a parity bit is added
to each character. If parity is enabled, the PARODD flag specifies odd parity if set;
otherwise, even parity is used.
If CREAD is set, the receiver is enabled. Otherwise, no characters are received.
If HUPCL is set, the line is disconnected when the last process with the line open
closes it or terminates. That is, the data-terminal-ready signal is not asserted.
If CLOCAL is set, the line is assumed to be a local, direct connection with no modem
control; otherwise, modem control is assumed.

The initial hardware control value after open is B300, CSS, CREAD, HUPCL.
Local Modes

The c_lflag field of the argument structure is used by the line discipline to control
terminal functions. The basic line discipline provides the following:

536

termio(7)
ISIG
ICANON
XCASE
ECHO
ECHOE
ECHOK
ECHONL
NOFLSH
TOSTOP
ECHOCTL
ECHOPRT
ECHOKE
FLUSHO
PENDIN
IEXTEN

Enable signals.
Canonical input (erase and kill processing).
Canonical upper flower presentation.
Enable echo.
Echo erase character as BS-SP-BS.
Echo NL after kill character.
Echo NL.
Disable flush after interrupt or quit.
Send SIGTTOU for background output.
Echo control characters as 'char, delete as A?~
Echo erase character as character erased.
BS-SP-BS erase entire line on line kill.
Output is being flushed.
Retype pending input at next read or input character.
Enable extended (implementation-defined) functions.

If ISIG is set, each input character is checked against the special control characters
INTR, QUIT, SWTCH, SUSP, STATUS, and DSUSP. If an input character matches one of
these control characters, the function associated with that character is performed. If
ISIG is not set, no checking is done. Thus, these special input functions are possible
only if ISIG is set.
If ICANON is set, canonical processing is enabled. This enables the erase and kill edit
functions, and the assembly of input characters into lines delimited by NL, EOF, EOL,
and EOL2. If ICANON is not set, read requests are satisfied directly from the input
queue. A read is not satisfied until at least MIN characters have been received or the
timeout value TIME has expired between characters. This allows fast bursts of input
to be read efficiently while still allowing single character input. The time value
represents tenths of seconds.
If XCASE is set, and if ICANON is set, an upper case letter is accepted on input by
preceding it with a \ character, and is output preceded by a \ character. In this
mode, the following escape sequences are generated on output and accepted on
input:
for:

use:
\'
\!
\~

{

\ (

}
\

For example, A is input as \a, \n as \ \n, and \N as \ \ \n.
If ECHO is set, characters are echoed as received.
When ICANON is set, the following echo functions are possible.
1. If ECHO and ECHOE are set, and ECHOPRT is not set, the ERASE and WERASE characters are echoed as one or more ASCII BS SP BS, which clears the last character(s)
from a CRT screen.

537

termio(7)
2. If ECHO and ECHOPRT are set, the first ERASE and WERASE character in a sequence
echoes as a backslash (\), followed by the characters being erased. Subsequent
ERASE and WERASE characters echo the characters being erased, in reverse order.
The next non-erase character causes a slash (I) to be typed before it is echoed.
ECHOPRT should be used for hard copy terminals.
3. If ECHOKE is set, the kill character is echoed by erasing each character on the line
from the screen (using the mechanism selected by ECHOE and ECHOPRT).
4. If ECHOK is set, and ECHOKE is not set, the NL character is echoed after the kill
character to emphasize that the line is deleted. Note that an escape character (\)
or an LNEXT character preceding the erase or kill character removes any special
function.
5. If ECHONL is set, the NL character is echoed even if ECHO is not set. This is useful
for terminals set to local echo (so called half-duplex).
If ECHOCTL is set, all control characters (characters with codes between a and 37
octal) other than ASCII TAB, ASCII NL, the START character, and the STOP character,
ASCII CR, and ASCII BS are echoed as AX, where X is the character given by adding
100 octal to the code of the control character (so that the character with octal code 1
is echoed as ~A), and the ASCII DEL character, with code 177 octal, is echoed as A?
If NOFLSH is set, the normal flush of the input and output queues associated with
the INTR, QUIT, and SUSP characters is not done. This bit should be set when restarting system calls that read from or write to a terminal [see sigaction(2)].
If TOSTOP is set, the signal SIGTTOU is sent to a process that tries to write to its controlling terminal if it is not in the foreground process group for that terminal. This
signal normally stops the process. Otherwise, the output generated by that process
is output to the current output stream. Processes that are blocking or ignoring
SIGTTOU signals are excepted and allowed to produce output, if any.
If FLUSHO is set, data written to the terminal is discarded. This bit is set when the
FLUSH character is typed. A program can cancel the effect of typing the FLUSH
character by clearing FLUSHO.
If PENDIN is set, any input that has not yet been read is reprinted when the next

character arrives as input.
If IEXTEN is set, the following implementation-defined functions are enabled: spe-

cial characters (WERASE, REPRINT, DISCARD, and LNEXT) and local flags (TOSTOP,
ECHOCTL, ECHOPRT, ECHOKE, FLUSHO, and PENDIN).
The initial line-discipline control value is ISIG, ICANON, ECHO, ECHOK.

Terminal Size
The number of lines and columns on the terminal's display is specified in the winsize structure defined by sys/tennios.h and includes the following members:

538

termio(7)
unsigned short
unsigned short
unsigned short
unsigned short

ws_raw;
/* rows, in characters */
ws_col;
/* columns, in characters */
ws_xpixel;/* horizontal size, in pixels */
ws"""ypixel;/* vertical size, in pixels */

termio Structure
The System V tennio structure is used by some ioctls; it is defined by
sys/termio.h and includes the following members:
unsigned short c_iflag;
/* input modes * /
unsigned short c_oflag;
/* output modes */
unsigned short c_cflag;
/* control modes */
unsigned short c_lflag;
/* local modes */
char
c_line;
/* line discipline */
unsigned char
c_cc[NCC]; /* control chars */
The special control characters are defined by the array c_cc. The symbolic name
NCC is the size of the control-character array and is also defined by tennio.h. The
relative positions, subscript names, and typical default values for each function are
as follows:

o
1
2
3

VINTR
VQUIT

DEL

VERASE

VKILL
VEOF
VEOL

@
EOT
NUL
NUL

6 VEOL2
7 reserved
For the non-canonical mode the positions of VEOF and VEOL are shared by WIN and
VTIME:

4
5

VMIN
VTIME

used to set the value of MIN
used to set the value of TIME

The calls that use the tennio structure only affect the flags and control characters
that can be stored in the termio structure; all other flags and control characters are
unaffected.
Modem lines
On special files representing serial ports, the modem control lines supported by the
hardware can be read, and the modem status lines supported by the hardware can
be changed. The following modem control and status lines may be supported by a
device; they are defined by sys/tennios.h:
TIOCM_LE
line enable
TIOCM_DTR
data terminal ready
TIOCM_RTS
request to send
TIOCM_ST
secondary transmit
TIOCM_SR
secondary receive
TIOCM_CTS
clear to send
TIOCM_CAR
carrier detect
TIOCM_RNG
ring
TIOCM_DSR
data set ready
539

termio(7)
TIOCM_CD is a synonym for TIOCM_CAR,
TIOCM_RNG. Not all of these are necessarily

and TIOCM_RI is a synonym for
supported by any particular device;
check the manual page for the device in question.

IOCTLS

The ioctls supported by devices and STREAMS modules providing the termios
interface are listed below. Some calls may not be supported by all devices or
modules. The functionality provided by these calls is also available through the
preferred function call interface specified on tennios(2).
TCGETS
The argument is a pointer to a tennios structure. The current terminal parameters are fetched and stored into that structure.
The argument is a pointer to a tennios structure. The current terTCSETS
minal parameters are set from the values stored in that structure.
The change is immediate.
The argument is a pointer to a tennios structure. The current terTCSETSW
minal parameters are set from the values stored in that structure.
The change occurs after all characters queued for output have been
transmitted. This form should be used when changing parameters
that affect output.
The argument is a pointer to a tennios structure. The current terTCSETSF
minal parameters are set from the values stored in that structure.
The change occurs after all characters queued for output have been
transmitted; all characters queued for input are discarded and then
the change occurs.
The argument is a pointer to a te:rmio structure. The current terTCGETA
minal parameters are fetched, and those parameters that can be
stored in a tennio structure are stored into that structure.
TCSETA
The argument is a pointer to a tennio structure. Those terminal
parameters that can be stored in a tennio structure are set from
the values stored in that structure. The change is immediate.
The argument is a pointer to a te:rmio structure. Those terminal
TCSETAW
parameters that can be stored in a tennio structure are set from
the values stored in that structure. The change occurs after all
characters queued for output have been transmitted. This form
should be used when changing parameters that affect output.

540

TCSETAF

The argument is a pointer to a tennio structure. Those terminal
parameters that can be stored in a tennio structure are set from
the values stored in that structure. The change occurs after all
characters queued for output have been transmitted; all characters
queued for input are discarded and then the change occurs.

TCSBRK

The argument is an int value. Wait for the output to drain. 1£ the
argument is 0, then send a break (zero valued bits for 0.25
seconds).

termio (7)
TOWNC

TCFLSH

TIOCGPGRP

TIOCSPGRP

TIOCGSID

Start/stop control. The argument is an int value. If the argument
is 0, suspend output; if 1, restart suspended output; if 2, suspend
input; if 3, restart suspended input.
The argument is an int value. If the argument is 0, flush the input
queue; if 1, flush the output queue; if 2, flush both the input and
output queues. On some controllers, if the argument is 0, input
flow control characters will be flushed, causing the unflushed output queue to overflow a busy output device.
The argument is a pointer to a pid_t. Set the value of that pid_t
to the process group ID of the foreground process group associated
with the terminal. See tennios(2) for a description or TCGETPGRP.
The argument is a pointer to a pid_t. Associate the process group
whose process group ID is specified by the value of that pid_t
with the terminal. The new process group value must be in the
range of valid process group ID values. Otherwise, the error EPERM
is returned. See tennios(2) for a description of TCSETPGRP.
The argument is a pointer to a pid_t. The session ID of the terminal is fetched and stored in the pid_t.

TIOCGWINSZ

The argument is a pointer to a winsize structure. The terminal
driver's notion of the terminal size is stored into that structure.

TIOCSWINSZ

The argument is a pointer to a winsize structure. The terminal
driver's notion of the terminal size is set from the values specified
in that structure. If the new sizes are different from the old sizes, a
SIGWINCH signal is set to the process group of the terminal.
The argument is a pointer to an int whose value is a mask containing modem control lines to be turned on. The control lines
whose bits are set in the argument are turned on; no other control
lines are affected.

TIOCMBIS

TIOCMBIC

The argument is a pointer to an int whose value is a mask containing modem control lines to be turned off. The control lines
whose bits are set in the argument are turned off; no other control
lines are affected.

TIOCMGET

The argument is a pointer to an into The current state of the
modem status lines is fetched and stored in the int pointed to by
the argument.
The argument is a pointer to an int containing a new set of
modem control lines. The modem control lines are turned on or
off, depending on whether the bit for that mode is set or clear.

TIOCMSET

FILES

/dev/*
SEE ALSO
fork(2), ioctl(2), setsid(2), signal(2), streamio(7), tennios(2)

541

termiox(7)
NAME

termiox - extended general terminal interface
DESCRIPTION

The extended general terminal interface supplements the termio(7) general terminal interface by adding support for asynchronous hardware flow control, isochronous flow control and clock modes, and local implementations of additional asynchronous features. Some systems may not support all of these capabilities because
of either hardware or software limitations. Other systems may not permit certain
functions to be disabled. In these cases the appropriate bits will be ignored. See
termiox.h for your system to find out which capabilities are supported.
Hardware Flow Control Modes
Hardware flow control supplements the termio(7) IXON, IXOFF, and lXANY character flow control. Character flow control occurs when one device controls the data
transfer of another device by the insertion of control characters in the data stream
between devices. Hardware flow control occurs when one device controls the data
transfer of another device using electrical control signals on wires (circuits) of the
asynchronous interface. Isochronous hardware flow control occurs when one
device controls the data transfer of another device by asserting or removing the
transmit clock signals of that device. Character flow control and hardware flow
control may be simultaneously set.
In asynchronous, full duplex applications, the use of the Electronic Industries
Association's EIA-232-D Request To Send (RTS) and Clear To Send (CTS) circuits is
the preferred method of hardware flow control. An interface to other hardware
flow control methods is included to provide a standard interface to these existing
methods.
The EIA-232-D standard specified only uni-directional hardware flow control - the
Data Circuit-terminating Equipment or Data Communications Equipment (DCE)
indicates to the Data Terminal Equipment (DTE) to stop transmitting data. The
termiox(7) interface allows both uni-directional and bi-directional hardware flow
control; when bi-directional flow control is enabled, either the DCE or DTE can indicate to each other to stop transmitting data across the interface. Note: It is assumed
that the asynchronous port is configured as a DTE. If the connected device is also a
DTE and not a DCE, then DTE to DTE (for example, terminal or printer connected to
computer) hardware flow control is possible by using a null modem to interconnect
the appropriate data and control circuits.
Clock Modes
Isochronous communication is a variation of asynchronous communication
whereby two communicating devices may provide transmit and/ or receive clock to
each other. Incoming clock signals can be taken from the baud rate generator on
the local isochronous port controller, from CCITT V.24 circuit 114, Transmitter Signal Element Timing - DCE source (EIA-232-D pin 15), or from ccrn V.24 circuit 115,
Receiver Signal Element Timing - DCE source (EIA-232-D pin 17). Outgoing clock
signals can be sent on CCITT V.24 circuit 113, Transmitter Signal Element Timing DTE source (EIA-232-D pin 24), on CCITT V.24 circuit 128, Receiver Signal Element
Timing - DTE source (no EIA-232-D pin), or not sent at all.

542

termiox(7)
In terms of clock modes, traditional asynchronous communication is implemented
simply by using the local baud rate generator as the incoming transmit and receive
clock source and not outputting any clock signals.
Terminal Parameters

The parameters that control the behavior of devices providing the termiox interface are specified by the termiox structure, defined in the sys/termiox.h header
file. Several ioctl(2) system calls that fetch or change these parameters use this
structure:
#define NFF
5
struct
termiox {
unsigned short
x_hflag;
unsigned short
unsigned short
unsigned short

/* hardware flow control
modes */
x_cflag;
/* clock modes */
x_rflag[NFF];/* reserved modes */
x_sflag;
/* spare local modes */

};

The x_hflag field describes hardware flow control modes:
RTSXOFF
0000001 Enable RTS hardware flow control on input.
CTSXON
0000002 Enable CTS hardware flow control on output.
DTRXOFF
0000004 Enable DTR hardware flow control on input.
CDXON
0000010 Enable CD hardware flow control on output.
ISXOFF
0000020 Enable isochronous hardware flow control on input.
The EIA-232-D DTR and CD circuits are used to establish a connection between two
systems. The RTS circuit is also used to establish a connection with a modem. Thus,
both DTR and RTS are activated when an asynchronous port is opened. If DTR is
used for hardware flow control, then RTS must be used for connectivity. If CD is
used for hardware flow control, then CTS must be used for connectivity. Thus, RTS
and DTR (or CTS and CD) cannot both be used for hardware flow control at the same
time. Other mutual exclusions may apply, such as the simultaneous setting of the
termio(7) HUPCL and the termiox(7) DTRXOFF bits, which use the DTE ready line for
different functions.
Variations of different hardware flow control methods may be selected by setting
the the appropriate bits. For example, bi-directional RTS/CTS flow control is
selected by setting both the RTSXOFF and CTSXON bits and bi-directional DTR/CTS
flow control is selected by setting both the DTRXOFF and CTSXON. Modem control or
uni-directional CTS hardware flow control is selected by setting only the CTSXON bit.
As previously mentioned, it is assumed that the local asynchronous port (for example, computer) is configured as a DTE. If the connected device (for example, printer)
is also a DTE, it is assumed that the device is connected to the computer's asynchronous port via a null modem that swaps control circuits (typically RTS and CTS). The
connected DTE drives RTS and the null modem swaps RTS and CTS so that the
remote RTS is received as CTS by the local DTE. In the case that CTSXON is set for
hardware flow control, printer's lowering of its RTS would cause CTS seen by the
computer to be lowered.
Output to the printer is suspended

543

termiox(7)
until the printer's raising of its RTS, which would cause CTS seen by the computer to
be raised.
If RTSXOFF is set, the Request To Send (RTS) circuit (line) will be raised, and if the
asynchronous port needs to have its input stopped, it will lower the Request To
Send (RTS) line. If the RTS line is lowered, it is assumed that the connected device
will stop its output until RTS is raised.
If CTSXON is set, output will occur only if the Clear To Send (CTS) circuit (line) is
raised by the connected device. If the CTS line is lowered by the connected device,
output is suspended until CTS is raised.
If DTRXOFF is set, the DTE Ready (DTR) circuit (line) will be raised, and if the asynchronous port needs to have its input stopped, it will lower the DTE Ready (DTR)
line. If the DTR line is lowered, it is assumed that the connected device will stop its
output until DTR is raised.
If CDXON is set, output will occur only if the Received Line Signal Detector (CD) circuit (line) is raised by the connected device. If the CD line is lowered by the connected device, output is suspended until CD is raised.
If ISXOFF is set, and if the isochronous port needs to have its input stopped, it will
stop the outgoing clock signal. It is assumed that the connected device is using this
clock signal to create its output. Transit and receive clock sources are programmed
using the x_cflag fields. If the port is not programmed for external clock generation, ISXOFF is ignored. Output isochronous flow control is supported by
appropriate clock source programming using the JCcflag field and enabled at the
remote connected device.
The x_cflag field specifies the system treatment of clock modes.
XMTCLK
0000007 Transmit clock source:
XCIBRG
0000000 Get transmit clock from internal baud rate
generator.
XCTSET
0000001 Get transmit clock from transmitter signal
element timing (DCE source) lead, CCITT
V.24 circuit 114, EIA-232-D pin 15.
XCRSET
0000002 Get transmit clock from receiver signal
element timing (DCE source) lead, CCITT
V.24 circuit 115, EIA-232-D pin 17.
RCVCLK
0000070 Receive clock source:
RCIBRG
0000000 Get receive clock from internal baud rate
generator.
RCTSET
0000010 Get receive clock from transmitter signal
element timing (DCE source) lead, ccnT
V.24 circuit 114, EIA-232-D pin 15.
RCRSET
0000020 Get receive clock from receiver signal
element timing (DCE source) lead, CCITT
V.24 circuit 115, EIA-232-D pin 17.
TSETCLK
0000700 Transmitter signal element timing (DTE source)
lead, CCITT V.24 circuit 113, EIA-232-D
pin 24, clock source:
TSETCOFF 0000000 TSET clock not provided.

544

termiox(7)
0000100 Output receive baud rate generator on
circuit 113.
TSETCTBRG 0000200 Output transmit baud rate generator on
circuit 113.
TSETCTSET 0000300 Output transmitter signal element timing
(DCE source) on circuit 113.
TSETCRSET 0000400 Output receiver signal element timing
(DCE source) on circuit 113.
RSETCLK
0007000 Receiver signal element timing (DTE source)
lead, CCITT V.24 circuit 128, no EIA-232-D
pin, clock source:
RSETCOFF 0000000 RSET clock not provided.
RSETCRBRG 0001000 Output receive baud rate generator on
circuit 128.
RSETCTBRG 0002000 Output transmit baud rate generator on
circuit 128.
RSETCTSET 0003000 Output transmitter signal element timing
(DCE source) on circuit 128.
RSETCRSET 0004000 Output receiver signal element timing
(DCE) on circuit 128.
TSETCRBRG

If the XMTCLK field has a value of XCIBRG the transmit clock is taken from the
hardware internal baud rate generator, as in normal asynchronous transmission. If
XMTCLK = XCTSET the transmit clock is taken from the Transmitter Signal Element
Timing (DCE source) circuit. If XMTCLK = XCRSET the transmit clock is taken from
the Receiver Signal Element Timing (DCE source) circuit.
If the RCVCLK field has a value of RCIBRG the receive clock is taken from the
hardware Internal Baud Rate Generator, as in normal asynchronous transmission.
If ReveLK = RCTSET the receive clock is taken from the Transmitter Signal Element
Timing (DCE source) circuit. If RCVCLK = RCRSET the receive clock is taken from the
Receiver Signal Element Timing (DCE source) circuit.
If the TSETCLK field has a value of TSETCOFF the Transmitter Signal Element Timing
(DTE source) circuit is not driven. If TSETCLK = TSETCRBRG the Transmitter Signal
Element Timing (DTE source) circuit is driven by the Receive Baud Rate Generator.
If TSETCLK = TSETCTBRG the Transmitter Signal Element Timing (DTE source) circuit is driven by the Transmit Baud Rate Generator. If TSETCLK = TSETCTSET the
Transmitter Signal Element Timing (DTE source) circuit is driven by the Transmitter
Signal Element Timing (DCE source). If TSETCLK = TSETCRBRG the Transmitter Signal Element Timing (DTE source) circuit is driven by the Receiver Signal Element
Timing (DCE source).
If the RSETCLK field has a value of RSETCOFF the Receiver Signal Element Timing
(DTE source) circuit is not driven. If RSETCLK = RSETCRBRG the Receiver Signal Element Timing (DTE source) circuit is driven by the Receive Baud Rate Generator. If
RSETCLK = RSETCTBRG the Receiver Signal Element Timing (DTE source) circuit is
driven by the Transmit Baud Rate Generator. If RSETCLK = RSETCTSET the Receiver
Signal Element Timing (DTE source) circuit is driven by the Transmitter Signal Element Timing (DCE source). If RSE'l'CLK = RSETCRBRG the Receiver Signal Element
Timing (DTE source) circuit is driven by the Receiver Signal Element Timing (DCE
source).
545

termiox(7)
The x_rflag is reserved for future interface definitions and should not be used by
any implementations. The x_sflag may be used by local implementations wishing
to customize their terminal interface using the termiox(7) ioctl system calls.
ioctls

The ioctl(2) system calls have the form:
ioctl (int fildes, int command, struct termiox *arg>;

The commands using this form are:
TCGETX
The argument is a pointer to a termiox structure. The current terminal
parameters are fetched and stored into that structure.
TCSETX

The argument is a pointer to a termiox structure. The current terminal
parameters are set from the values stored in that structure. The change
is immediate.

TCSETXW

The argument is a pointer to a termiox structure. The current terminal
parameters are set from the values stored in that structure. The change
occurs after all characters queued for output have been transmitted.
This form should be used when changing parameters that will affect
output.
The argument is a pointer to a termiox structure. The current terminal
parameters are set from the values stored in that structure. The change
occurs after all characters queued for output have been transmitted; all
characters queued for input are discarded and then the change occurs.

TCSETXF

FILES

/dev/*
SEE ALSO

ioctl(2), stty(l), termio(7)

546

ticlts (7)
NAME

ticlts, ticots, ticotsord -loopback transport providers
SYNOPSIS

#include
#include
#include
DESCRIPTION

The devices known as ticlts, ticots, and ticotsord are "loopback transport
providers," that is, stand-alone networks at the transport level. Loopback transport
providers are transport providers in every sense except one: only one host (the local
machine) is "connected to" a loopback network. Loopback transports present a TPI
(STREAMS-level) interface to application processes and are intended to be accessed
via the TLI (application-level) interface. They are implemented as clone devices and
support address spaces consisting of "flex-addresses," that is, arbitrary sequences
of octets, of length> 0, represented by a netbuf structure.
ticlts is a datagram-mode transport provider. It offers (connectionless) service of
type T_CLTS. Its default address size is TCL_DEFAULTADDRSZ. ticlts prints the
following error messages [see t_rcvuderr(3N)]:

TCL_BADADDR
TCL_BADOPT
TCL_NOPEER
TCL_PEERBADSTATE

bad address specification
bad option specification
bound
peer in wrong state

ticots is a virtual circuit-mode transport provider. It offers (connection-oriented)
service of type T_COTS. Its default address size is TCO_DEFAULTADDRSZ. ticots
prints the following disconnect messages [see t_rcvdis(3N)]:

TCO_NOPEER
TCO_PEERNOROOMONQ
TCO_PEERBADSTATE
TCO_PEERINITIATED
TCO_PROVIDERINITIATED

no listener on destination address
peer has no room on connect queue
peer in wrong state
peer-initiated disconnect
provider-initiated disconnect

ticotsord is a virtual circuit-mode transport provider, offering service of type
T_COTS_ORD (connection-oriented service with orderly release). Its default address
size is TCOO_DEFAULTADORSZ. ticotsord prints the following disconnect messages
[see t_rcvdis(3N)]:

TCOO_NOPEER
TCOO_PEERNOROOMONQ
TCOO_PEERBADSTATE
TCOO_PEERINITIATED
TCOO~ROVIDERINITIATED

no listener on destination address
peer has no room on connect queue
peer in wrong state
peer-initiated disconnect
provider-initiated disconnect

USAGE

Loopback transports support a local !PC mechanism through the TLI interface.
Applications implemented in a transport provider-independent manner on a
client-server model using this IPC are transparently transportable to networked
environments.

547

ticlts (7)
Transport provider-independent applications must not include the header files
listed in the synopsis section above. In particular, the options are (like all transport
provider options) provider dependent.
ticlts and ticots support the same service types (T_CLTS and T_COTS) supported by the OSI transport-level model. The use of ticlts and ticots is
encouraged.
ticotsord supports the same service type (T_COTS_ORD) supported by the rep lIP
model. The use of ticotsord is discouraged except for reasons of compatibility.
FILES

Idev/ticlts
Idev/ticots
/dev/ticotsord

548

timod(7)
NAME

timod - Transport Interface cooperating STREAMS module
DESCRIPTION

timod is a STREAMS module for use with the Transport Interface (TI) functions of
the Network Services library. The timod module converts a set of ioct1(2) calls
into STREAMS messages that may be consumed by a transport protocol provider
which supports the Transport Interface. This allows a user to initiate certain TI

functions as atomic operations.
The timod module must be pushed onto only a stream terminated by a transport
protocol provider which supports the TI.
All STREAMS messages, with the exception of the message types generated from the
ioctl commands described below, will be transparently passed to the neighboring
STREAMS module or driver. The messages generated from the following ioctl
commands are recognized and processed by the timod module. The format of the
ioctl call is:
#include

struct strioctl strioctl;
strioctl.ic_cmd = cmd;
strioctl.ic_timeout = INFTIM;
strioctl. ic_Ien = size;
strioctl.ic_dp
{char *}buf
ioctl{fildes, I_STR, &strioctl};

Where, on issuance, size is the size of the appropriate TI message to be sent to the
transport provider and on return size is the size of the appropriate TI message from
the transport provider in response to the issued TI message. buf is a pointer to a
buffer large enough to hold the contents of the appropriate TI messages. The TI
message types are defined in sys/tihdr.h. The possible values for the cmd field
are:
Bind an address to the underlying transport protocol provider.
The message issued to the TI_BIND ioctl is equivalent to the TI
message type T_BIND_REQ and the message returned by the successful completion of the ioctl is equivalent to the TI message
type T_BIND_ACK.
Unbind an address from the underlying transport protocol provider. The message issued to the TI_UNBIND ioctl is equivalent
to the TI message type T_UNBIND_REQ and the message returned
by the successful completion of the ioctl is equivalent to the TI
message type T_OK_ACK.
Get the TI protocol specific information from the transport protocol
provider. The message issued to the TI_GETINFO ioctl is
equivalent to the TI message type T_INFO_REQ and the message

549

timod(7)
returned by the successful completion of the ioctl is equivalent to
the TI message type T_INFO_ACK.
Get, set or negotiate protocol specific options with the transport
protocol provider. The message issued to the TI_OPTMGMT ioctl
is equivalent to the TI message type T_OPTMGMT_REQ and the message returned by the successful completion of the ioctl is
equivalent to the TI message type T_OPTMGMT_ACK.
FILES

sys/timod.h
sys/tiuser.h
sys/tihdr.h
sys/errno.h
SEE ALSO

tirdwr(7)
DIAGNOSTICS

If the ioctl system call returns with a value greater than 0, the lower 8 bits of the
return value will be one of the TI error codes as defined in sys/tiuser. h. If the TI

error is of type TSYSERR, then the next 8 bits of the return value will contain an
error as defined in sys/errno.h [see intro(2)].

550

tirdwr (7)
NAME

tirdwr - Transport Interface read/write interface STREAMS module
DESCRIPTION

tirdwr is a STREAMS module that provides an alternate interface to a transport provider which supports the Transport Interface (TI) functions of the Network Services
library (see Section 3N). This alternate interface allows a user to communicate with
the transport protocol provider using the read(2) and write(2) system calls. The
putmsg(2) and getmsg(2) system calls may also be used. However, putmsg and
getmsg can only transfer data messages between user and stream.
The tirdwr module must only be pushed [see I_PUSH in strearnio(7)] onto a
stream terminated by a transport protocol provider which supports the TI. After
the tirdwr module has been pushed onto a stream, none of the Transport Interface
functions can be used. Subsequent calls to TI functions will cause an error on the
stream. Once the error is detected, subsequent system calls on the stream will
return an error with errno set to EPROTO.

The following are the actions taken by the tirdwr module when pushed on the
stream, popped [see I_POP in strearnio(7)] off the stream, or when data passes
through it.
push

write

When the module is pushed onto a stream, it will check any existing data
destined for the user to ensure that only regular data messages are present.
It will ignore any messages on the stream that relate to process management, such as messages that generate signals to the user processes associated with the stream. If any other messages are present, the I_PUSH will
return an error with ermo set to EPROTO.
The module will take the following actions on data that originated from a
wri te system call:

All messages with the exception of messages that contain control
portions (see the putmsg and getmsg system calls) will be transparently passed onto the module's downstream neighbor.
Any zero length data messages will be freed by the module and they
will not be passed onto the module's downstream neighbor.

read

Any messages with control portions will generate an error, and any
further system calls associated with the stream will fail with errno
set to EPROTO.
The module will take the following actions on data that originated from
the transport protocol provider:
All messages with the exception of those that contain control
portions (see the putmsg and getmsg system calls) will be transparently passed onto the module's upstream neighbor.
The action taken on messages with control portions will be as
follows:

551

tirdwr(7)
Messages that represent expedited data will generate an error.
All further system calls associated with the stream will fail with
errno set to EPROTO.
Any data messages with control portions will have the control
portions removed from the message prior to passing the
message on to the upstream neighbor.
Messages that represent an orderly release indication from the
transport provider will generate a zero length data message,
indicating the end of file, which will be sent to the reader of the
stream. The orderly release message itself will be freed by the
module.
Messages that represent an abortive disconnect indication from
the transport provider will cause all further write and putmsg
system calls to fail with errno set to ENXIO. All further read
and getmsg system calls will return zero length data (indicating
end of file) once all previous data has been read.
With the exception of the above rules, all other messages with
control portions will generate an error and all further system
calls associated with the stream will fail with ermo set to
EPROTO.
Any zero length data messages will be freed by the module and they
will not be passed onto the module's upstream neighbor.

pop

When the module is popped off the stream or the stream is closed, the
module will take the following action:
If an orderly release indication has been previously received, then an
orderly release request will be sent to the remote side of the transport connection.

SEE ALSO

getmsg(2), intro(2), intro(3) putmsg(2), read(2), streamio(7), timod(7), write(2)

552

ttcompat (7)
NAME

ttcompat - V7, 4BSD and XENIX STREAMS compatibility module
SYNOPSIS

#include
#include
#include
#include

ioctl(fd, I_PUSH, "ttcompat")i
DESCRIPTION

ttcompat is a STREAMS module that translates the ioctl calls supported by the
older Version 7, 4BSD and XENIX terminal drivers into the ioctl calls supported by
the termio interface [see termio(7)]. All other messages pass through this module
unchanged; the behavior of read and write calls is unchanged, as is the behavior of
ioctl calls other than the ones supported by ttcompat.

This module can be automatically pushed onto a stream with the autopush(lM)
mechanism when a terminal device is opened; it does not have to be explicitly
pushed onto a stream. This module requires that the termios interface be supported by the modules and the application can push the driver downstream. The
TCGETS, TCSETS, and TCSETSF ioctl calls must be supported; if any information
set or fetched by those ioctl calls is not supported by the modules and driver
downstream, some of the V7 / 4BSD /XENIX functions may not be supported. For
example, if the CBAUD bits in the c_cflag field are not supported, the functions provided by the sg_ispeed and sg_ospeed fields of the sgttyb structure (see below)
will not be supported. If the TCFLSH ioctl is not supported, the function provided
by the TIOCFLUSH ioctl will not be supported. If the TCXONC ioctl is not supported, the functions provided by the TIOCSTOP and TIOCSTART ioctl calls will
not be supported. If the TIOCMBIS and TIOCMBIC ioctl calls are not supported,
the functions provided by the TIOCSDTR and TIOCCDTR ioctl calls will not be supported.
The basic ioctl calls use the sgttyb structure defined by sys/ioctl.h:
struct sgttyb
char
char
char
char
int

sg_i speed i
sg_ospeedi
sg_erasei
sg_killi
sg_flags i

The sg_ispeed and sg_ospeed fields describe the input and output speeds of the
device, and reflect the values in the c_cflag field of the termios structure. The
sg_erase and sg_kill fields of the argument structure specify the erase and kill
characters respectively, and reflect the values in the VERASE and VKILL members of
the c_cc field of the termios structure.
The sg_flags field of the argument structure contains several flags that determine
the system's treatment of the terminal. They are mapped into flags in fields of the
terminal state, represented by the termios structure.

553

ttcompat(7)
Delay type 0 is always mapped into the equivalent delay type 0 in the c_oflag
field of the termios structure. Other delay mappings are performed as follows:
sg_flags

c_oflag

BSl
FFl
CRl
CR2

BSl
VTl
CR2
CR3

CR3
TABl
TAB2
XTABS
NLl
NL2

TABl
TAB2
TAB3
ONLRETI CRl
NLl

not supported

If previous TIOCLSET or TIOCLBIS ioctl calls have not selected LlTOUT or PASSB
mode, and if RAN mode is not selected, the ISTRIP flag is set in the c_iflag field of
the termios structure, and the EVENP and ODDP flags control the parity of characters sent to the terminal and accepted from the terminal:
Parity is not to be generated on output or checked on input:

The character size is set to CSB and the flag is cleared in the c_cflag
field of the termios structure.
Even parity characters are to be generated on output and accepted on input:
The flag is set in the c_iflag field of the termios structure, the character size is set to CS7 and the flag is set in the c_cflag field of the
termios structure.
Odd parity characters are to be generated on output and accepted on input:
The flag is set in the c_iflag field, the character size is set to CS7 and
the and flags are set in the c_cflag field of the termios structure.
Even parity characters are to be generated on output and characters of either
parity are to be accepted on input:
The flag is cleared in the c_iflag field, the character size is set to CS7
and the flag is set in the c_cflag field of the termios structure.
The RAW flag disables all output processing (the OPOST flag in the c_oflag field, and
the XCASE flag in the c_lflag field, are cleared in the termios structure) and input
processing (all flags in the c_iflag field other than the lXOFF and lXANY flags are
cleared in the termios structure). 8 bits of data, with no parity bit, are accepted on
input and generated on output; the character size is set to CSB and the PARENB and
PARODD flags are cleared in the c_cflag field of the termios structure. The signalgenerating and line-editing control characters are disabled by clearing the ISIG and
lCANON flags in the c_lflag field of the termios structure.
The CRMOD flag turns input RETURN characters into NEWLINE characters, and output and echoed NEWLINE characters to be output as a RETURN followed by a
LINEFEED. The ICRNL flag in the c_iflag field, and the OPOST and ONLCR flags in
the c_oflag field, are set in the termios structure.

554

ttcompat (7)
The LCASE flag maps upper-case letters in the ASCII character set to their lower-case
equivalents on input (the IUCLC flag is set in the c_iflag field), and maps lowercase letters in the ASCII character set to their upper-case equivalents on output (the
OLCUC flag is set in the c_oflag field). Escape sequences are accepted on input, and
generated on output, to handle certain ASCII characters not supported by older terminals (the XCASE flag is set in the c_lflag field).
Other flags are directly mapped to flags in the tennios structure:
sg_flags

flags in tennios structure

CBREAK
ECHO
TANDEM

complement of ICANON in c_lflag field
ECHO in c_lflag field
IXOFF in c_iflag field

Another structure associated with each terminal specifies characters that are special
in both the old Version 7 and the newer 4BSD terminal interfaces. The following
structure is defined by sys/ ioctl. h:
struct tchars
char
char
char
char
char
char
};

t_intrc;
t_quitc;
t_startc;
t_stopc;
t_eofc;
t_brkc;

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

interrupt */
quit */
start output */
stop output */
end-of - file * /
input delimiter (like nl) */

XENIX defines the tchar structure as tc. The characters are mapped to members of
the c_cc field of the tennios structure as follows:
tchars

c_cc index

t_intrc
t_quitc
t_startc
t_stopc
t_eofc
t_brkc

VINTR
VQUIT
VSTART
VSTOP
VEOF
VEOL

Also associated with each terminal is a local flag word, specifying flags supported
by the new 4BSD terminal interface. Most of these flags are directly mapped to flags
in the tennios structure:
local flags
LCRTBS
LPRTERA
LCRTERA
LTILDE
LTOSTOP
LFLUSHO
LNOHANG

flags in tennios structure
not supported
ECHOPRT in the c_lflag field
ECHOE in the c_lflag field

not supported
TOSTOP in the c_lflag field
FLUSHO in the c_lflag field
CLOCAL

in the c_cflag field

555

ttcompat(7)
LCRTKIL
LCTLECH
LPENDIN
LDECCTQ
LNOFLSH

ECHOKE in the c_lflag field
CTLECH in the c_lflag field
PENDIN in the c_lflag field
complement of IXANY in the c_iflag field
NOFLSH in the c_lflag field

Another structure associated with each terminal is the ltchars structure which
defines control characters for the new 4BSD terminal interface. Its structure is:
struct ltchars {
char t_suspc;
1* stop process signal *1
char t_dsuspc;
1* delayed stop process signal *1
char t_rprntc;
1* reprint line *1
char t_flushc;
1* flush output (toggles) *1
char t_werasc;
1* word erase *1
char t_lnextc;
1* literal next character *1
};

The characters are mapped to members of the c_cc field of the tennios structure
as follows:
ltchars
c_cc index
t_suspc
VSUSP
t_dsuspc
VDSUSP
t_rprntc
VREPRINT
t_flushc
VDISCARD
t_werasc
VWERASE
t_lnextc
VLNEXT
ioctls

ttcOIl\Pat responds to the following ioctl calls. All others are passed to the
module below.
TIOCGETP
The argument is a pointer to an sgttyb structure. The current terminal state is fetched; the appropriate characters in the terminal state are
stored in that structure, as are the input and output speeds. The
values of the flags in the sg_flags field are derived from the flags in
the terminal state and stored in the structure.
TIOCEXCL
TIOCNXCL
TIOCSETP

556

Set "exclusive-use" mode; no further opens (except by a privileged
user) are permitted until the file has been closed.
Turn off "exclusive-use" mode.
The argument is a pointer to an sgttyb structure. The appropriate
characters and input and output speeds in the terminal state are set
from the values in that structure, and the flags in the terminal state are
set to match the values of the flags in the sg_flags field of that structure. The state is changed with a TCSETSF ioctl so that the interface
delays until output is quiescent, then throws away any unread characters, before changing the modes.

ttcompat(7)
The argument is a pointer to an sgttyb structure. The terminal state
is changed as TIOCSETP would change it, but a TCSETS ioctl is used,
so that the interface neither delays nor discards input.
TIOCHPCL
The argument is ignored. The HUPCL flag is set in the c_cflag word
of the terminal state.
TIOCFLUSH The argument is a pointer to an int variable. If its value is zero, all
characters waiting in input or output queues are flushed. Otherwise,
the value of the int is treated as the logical OR of the FREAD and
FWRlTE flags defined by sys/file.h; if the FREAD bit is set, all characters waiting in input queues are flushed, and if the FWRITE bit is set,
all characters waiting in output queues are flushed.
TIOCBRK
The argument is ignored. The break bit is set for the device.
TIOCCBRK
The argument is ignored. The break bit is cleared for the device.
TIOCSETN

TIOCSDTR
TIOCCDTR

The argument is ignored. The Data Terminal Ready bit is set for the
device.
The argument is ignored. The Data Terminal Ready bit is cleared for
the device.

The argument is ignored. Output is stopped as if the STOP character
had been typed.
TIOCSTART The argument is ignored. Output is restarted as if the START character
had been typed.
TIOCGETC
The argument is a pointer to a tchars structure. The current terminal
state is fetched, and the appropriate characters in the terminal state
are stored in that structure.
TIOCSETC
The argument is a pointer to a tchars structure. The values of the
appropriate characters in the terminal state are set from the characters
in that structure.
TIOCLGET
The argument is a pointer to an into The current terminal state is
fetched, and the values of the local flags are derived from the flags in
the terminal state and stored in the int pointed to by the argument.
TIOCLBIS
The argument is a pointer to an int whose value is a mask containing
flags to be set in the local flags word. The current terminal state is
fetched, and the values of the local flags are derived from the flags in
the terminal state; the specified flags are set, and the flags in
the terminal state are set to match the new value of the local flags
word.
TIOCSTOP

TIOCLBIC

The argument is a pointer to an int whose value is a mask containing
flags to be cleared in the local flags word. The current terminal state is
fetched, and the values of the local flags are derived from the flags in
the terminal state; the specified flags are cleared, and the flags in the
terminal state are set to match the new value of the local flags word.

557

ttcompat (7)
The argument is a pointer to an int containing a new set of local flags.
The flags in the terminal state are set to match the new value of the
local flags word.
TIOCGLTC
The argument is a pointer to an ltchars structure. The values of the
appropriate characters in the terminal state are stored in that structure.
TIOCSLTC
The argument is a pointer to an ltchars structure. The values of the
appropriate characters in the terminal state are set from the characters
in that structure.
FIORDCHK
FIORDCHK returns the number of immediately readable characters.
The argument is ignored.
FIONREAD
FIONREAD returns the number of immediately readable characters in
the int pointed to by the argument.
LDSMAP
Calls the function emsetmap ( tp, mp) if the function is configured in
the kernel.
LDGMAP
Calls the function emgetmap (tp, mp) if the function is configured in
the kernel.
LDNMAP
Calls the function emumnap ( tp , mp) if the function is configured in
the kernel.
The following ioctls are returned as successful for the sake of compatibility.
However, nothing significant is done (that is, the state of the terminal is not
changed in any way).
TIOCLSET

TIOCSETD
TIOCGETD
DIOCSETP
DIOCSETP
DIIOGETP

LOOPEN
LDCLOSE
LDCHG
LDSETT
LDGETT

SEE ALSO
ioctl(2), ldteIlll(7), teIlllio(7), teIlllios(2)
NOTES
TIOCBRK and TIOCCBRK should be handled by the driver. FIONREAD and FIORDCHK

are handled in the stream head.

558

tty (7)
NAME

tty - controlling terminal interface
DESCRIPTION

The file /dev/tty is, in each process, a synonym for the control terminal associated
with the process group of that process, if any. It is useful for programs or shell
sequences that wish to be sure of writing messages on the terminal no matter how
output has been redirected. It can also be used for programs that demand the name
of a file for output, when typed output is desired and it is tiresome to find out what
terminal is currently in use.
FILES

/dev/tty
/dev/tty*
SEE ALSO

console(7)

559

UDP(7)
NAME
UDP - Internet User Datagram Protocol
SYNOPSIS

#include
#include
s

= socket (AP_INET ,

SOC1CDGRAM, 0);

t = t_open(" /dev/udp",

O_RDWR);

DESCRIPTION
UDP is a simple datagram protocol which is layered directly above the Internet Protocol (IP). Programs may access UDP using the socket interface, where it supports
the SOCK_DGRAM socket type, or using the Transport Level Interface (TIl), where it

supports the connectionless (T_CLTS) service type.
Within the socket interface, UDP is normally used with the sendto ( ), sendmsg ( ),
recvfrom( ), and recvmsg () calls [see send(3N) and recv(3N)]. If the
connect(3N) call is used to fix the destination for future packets, then the recv(3N)
or read(2) and send(3N) or write(2) calls may be used.
UDP address formats are identical to those used by the Transmission Control Protocol (TCP). Like TCP, UDP uses a port number along with an IP address to identify
the endpoint of communication. The UDP port number space is separate from the
TCP port number space (that is, a UDP port may not be connected to a TCP port).
The bind(3N) call can be used to set the local address and port number of a UDP
socket. The local IP address may be left unspecified in the bind ( ) call by using the
special value INADDR_ANY. If the bind ( ) call is not done, a local IP address and
port number will be assigned to the endpoint when the first packet is sent. Broadcast packets may be sent (assuming the underlying network supports this) by using
a reserved broadcast address. This address is network interface dependent. Broadcasts may only be sent by the privileged user.

Options at the IP level may be used with UDP; see ip(7).
As the RFC allows, there are a variety of ways that a UDP packet can be lost or corrupted, including a failure of the underlying communication mechanism. UDP
implements a checksum over the data portion of the packet. If the checksum of a
received packet is in error, the packet will be dropped with no indication given to
the user. A queue of received packets is provided for each UDP socket. This queue
has a limited capacity. Arriving datagrams which will not fit within its high-water
capacity are silently discarded.
As the RFC allows, UDP processes Internet Control Message Protocol (ICMP) error
messages received in response to UDP packets it has sent. See iCJlQ;)(7). ICMP source
quench messages are ignored. ICMP destination unreachable, time exceeded and
parameter problem messages disconnect the socket from its peer so that subsequent
attempts to send packets using that socket will return an error. UDP will not
guarantee that packets are delivered in the order they were sent. As well, duplicate
packets may be generated in the communication process.

560

UDP(7)
SEE ALSO

bind(3N), connect(3N), iC1ll>(7), inet(7), ip(7), read(2), recv(3N), send(3N),
tcp(7), write(2)

Postel, Jon, User Datagram Protocol, RFC 768, Network Information Center, SRI International, Menlo Park, Calif., August 1980
DIAGNOSTICS

A socket operation may fail if:
EISCONN

EISCONN

ENOTCONN

EADDRlNUSE

EADDRNOTAVAIL
EINVAL
EACCES

ENOBUFS

A connect ( ) operation was attempted on a socket on which a
connect () operation had already been performed, and the

socket could not be successfully disconnected before making
the new connection.
A sendto ( ) or sendmsg ( ) operation specifying an address to
which the message should be sent was attempted on a socket
on which a connect ( ) operation had already been performed.
A send() or write() operation, or a sendto() or
sendmsg () operation not specifying an address to which the
message should be sent, was attempted on a socket on which a
connect ( ) operation had not already been performed.
A bind ( ) operation was attempted on a socket with a network
address/port pair that has already been bound to another
socket.
A bind ( ) operation was attempted on a socket with a network
address for which no network interface exists.
A sendmsg ( ) operation with a non-NULL msg_accrights was
attempted.
A bind () operation was attempted with a reserved port
number and the effective user ID of the process was not the
privileged user.
The system ran out of memory for internal data structures.

561

vxfsio (7)

(VXFS)

NAME

vxfsio - vxfs file system control functions
SYNOPSIS

#include
#include
int ioctl (intfildes, int cmd, arg>;
DESCRIPTION

The vxfs ioctl(2) enhancements provide for extended control over open files.
The argument fildes is an open file_descriptor.
The data type and value of arg are specific to the type of command specified by cmd.
Unless specified, arg is treated as an int type. The symbolic names for commands
and file status flags are defined by the sys/fs/vx_ioctl.h header file.
The enhancements available are:
VJCSETCACHE

Set caching advisories. These advisories allow an application to indicate to
the file system which forms of caching would be most advantageous.
NOTE:

VJCSETCACHE

is available with the VxFS Advanced package only.

The values for arg are such that multiple advisories may be set by combining
values with bitwise OR operations. The possible values for arg are:
VX_RANDOM

Indicates that the file is being accessed randomly. Read-ahead
should not be performed.
VX_SEQ

Indicates that the file is being accessed sequentially. Maximum
read-ahead should be performed.
VX_DIRECT

Indicates that data associated with read and write operations is to be
transferred directly to or from the user supplied buffer, without
being cached. When this options is enabled, all I/O operations must
begin on block boundaries and must be a multiple of the block size
in length. The buffer supplied with the I/O operations must be
aligned to a page boundary.
If an I/O request fails to meet alignment criteria, or the file is
currently being accessed for mapped I/O, the I/O request will be
performed as a data synchronous I/O operation.
VX_NOREUSE

Indicates that buffered data does not need to be retained in anticipation of further use by the application.
VJCDSYNC

Indicates that data synchronous I/O mode is desired. In data synchronous I/O mode, a write operation returns to the caller after the

562

(VXFS)

vxfsio(7)

data has been transferred to external media, but the inode is not
updated synchronously if only the times in the inode need to be
updated.
Only one of

VJCRANDOM, VJCSEQ, or VX_DlRECT may be specified. The
and VX_DSYNC options may not be used in conjunction with
The caching advisories for a file are maintained on a per-file
basis. Changes made to the advisories by a process affect I/O operations by
all processes currently accessing the file.

VX_NOREUSE
VX_DlRECT.

The VX_SETCACHE ioctl returns a 0 if the caching advisories are successfully
set. If the operation fails, the return value is -1 and the external variable
ermo will be a general DIAGNOSTIC.
VX_GETCACHE

Get caching advisories in effect for the file. The argument arg should be a
pointer to to an into
The VX_GETCACHE ioctl returns a 0 if the caching advisories are successfully
obtained and the advisories are returned in argo If the operation fails, the
return value is -1 and the external variable ermo will be a general DIAGNOSTIC.
VX_SETEXT

Set extent information.
NOTE: VX_SETEXT is available with the VxFS Advanced package only.
The extent information is set according to the parameters specified by argo
The argument arg points to a structure of type VJcext defined in
sys/fs/vx_ioctl.h, which contains the following members:
off_t
off_t
int

ext_size; /* extent size */
reserve; /* space reservation */
a_flags; /* allocation flags */

The ext size element is used to request a fixed extent size, in
blocks, for the file. If a fixed extent size is not required, zero should
be used to allow the default allocation policy to be used. Changes to
the fixed extent size made after the file contains indirect blocks have
no effect unless all current indirect blocks are freed via file truncation and/or reservation deallocation.
The reserve element is used to set the amount of space preallocated
to the file. If the reserve amount is greater than the current reservation, the allocation for the file is increased to match the reserve
amount. If the reserve amount is less than the current reservation,
the allocation is decreased. The allocation will not be reduced to less
than the current file size.
File reservation cannot be increased beyond the ulimi t (2) of the
requesting process. However, an existing reservation will not be
trimmed to the requesting process's ulimit(2). Reservation of
space for existing sparse files will not cause blocks to be allocated to
fill in the holes, but will only allocate blocks after the end of the file.

563

vxfsio(7)

(VXFS)

Thus, it's possible to have a larger reservation for a file than blocks
in the file.
The reservation amount is independent of file size since reservation
is used to preallocate space for a file. The a_flags element is used
to indicate the type of reservation required. The choices are:
VJCNOEXTEND

The file may not be extended once the current reservation is
exceeded. The reservation may be increased if necessary by
another invocation of the ioctl, but the file will not be
automatically extended.
VJCTRIM

The reservation for the file is to be trimmed to the current file
size upon last close by all processes that have the file open.
VJCCONTlGUOUS

The reservation must be allocated contiguously (as a single
extent). ext_size will become the fixed extent size for subsequent allocations, but has no affect on this one. The reservation will fail if the file has gone into indirect extents, unless
the amount of space requested is the same as the indirect
extent size. If the contiguous allocation request is done on an
empty file, this will not happen.
VJCALIGN

Align all new extents on an ext_size boundary relative to
the starting block of an allocation unit. If VJCCONTlGUOUS is
set, the single extent allocated during this invocation is not
subject to the alignment restriction.
VJCNORESERVE

The reservation is to be made as a non-persistent allocation
to the file. The on-disk inode will not be updated with the
reservation information so that the reservation will not survive a system crash. The reservation is associated with the
file until the close of the file. The reservation is trimmed to
the current file size on close.
VJCCHGSIZE

The reservation is to be immediately incorporated into the
file. The file's on-disk inode is updated with the size and
block count information that is increased to include the
reserved space. Unlike an fcntl F_FREESP operation which
"truncates-up" [see fcntl(2»), the space included in the file
is not initialized. This operation is restricted to users with
appropriate privileges.
Write permission to a file is required to set extent information, but
any process that can open the file can get the extent information.
Extent information only applies to regular files. Only one set of
extent information is kept per file. Except in those cases noted above

564

(VXFS)

vxfsio(7}

as non-persistent, the extent information becomes part of the on-disk
inode information, and thus persists across reboots.
The VJCSETEXT ioctl returns a 0 if the extent information is successfully set.
If the operation fails, the return value is -1 and the external variable ermo
will be a general DIAGNOSTIC.
VJCGETEXT

Get extent information. Return the extent information associated with fildes.
The argument arg points to a structure of type vx_ext as defined in
sys/fs/vx_ioctl.h.
The VJCGETEXT ioctl returns a 0 if the extent information is successfully
obtained. If the operation fails, the return value is -1 and the external variable ermo will be a general DIAGNOSTIC.
VJCGETFSOPT

Get file system options. The argument arg should be a pointer to to an into
This command may be used by any user who can open the root inode on the
file system. The options returned in arg are:
VJCFSO_BLKCLEAR

Indicates that all newly allocated blocks will be guaranteed to contain all zeros.
VJCFSO_CACHE_CLOSESYNC

Indicates that any non-logged changes to the inode or data will be
flushed to disk when the file is closed.
VX_FSO_CACHE_DIRECT

Indicates that any non-synchronous I/O will be handled as if the
cache advisory had been set on the file. Also, any nonlogged changes to the inode or data will be flushed to disk when the
file is closed.

VX_DIRECT

VX_FSO_CACHE_DSYNC

Indicates that any writes that don't have either O_SYNC or the
advisory set will be handled as if the VX_DSYNC advisory
had been set on the file. Also, any non-logged changes to the inode
or data will be flushed to disk when the file is closed.

VX_DIRECT

VX_FSO_NODATAINLOG

Indicates that intent logging of user data for synchronous writes is
disabled.
VX_FSO_NOLOG

Indicates that intent logging of structural changes to the file system
is disabled.
VX_FSO_OSYNC_CLOSESYNC

Indicates that any non-logged changes to the inode or data will be
flushed to disk when a file accessed with O_SYNC is closed.

565

vxfsio(7)

(VXFS)

VX_FSO_OSYNC_DIRECT
Indicates that any O_SYNC I/O will be handled as if the VX_DIRECT
cache advisory had been set on the file instead. Also, any nonlogged changes to the inode or data will be flushed to disk when a
file accessed with O_SYNC is closed.
VX_FSO_OSYNC_DSYNC
Indicates that any O_SYNC writes will be handled as if the VX_DSYNC
cache advisory had been set on the me instead. Also, any nonlogged changes to the inode or data will be flushed to disk when a
file accessed with O_SYNC is closed.
VX_FSO_SNAPPED
Indicates that a snapshot backup is in progress on the file system.
VX_FSO_SNAPSHOT
Indicates that this file system is a snapshot backup of another file
system.
VX_FSO_VJFS
Indicates that this is not the VxFS Advanced package.
The VX_GETFSOPT ioctl returns a 0 if the file system options are successfully
obtained. If the operation fails, the return value is -1 and the external variable ermo will be a general DIAGNOSTIC.
VX_FREEZE
Sync then freeze the file system. Once frozen, all further operations against
the file system block until a VX_THAW operation is received. The argument
arg is a timeout value expressed in seconds. If a VX_THAW operation is not
received within the specified timeout interval, the file system will perform a
vx_THAwoperation automatically.
This command may only be used by a user with appropriate privilege, on
the root directory of the file system.
The VX_FREEZE ioctl returns a 0 if the file system is successfully frozen. H
the operation fails, the return value is -1 and the external variable ermo will
be a general DIAGNOSTIC.
VX_THAW
Unblock a file system that has been frozen by a VX_FREEZE operation. The
argument arg should be NULL. The process that is to issue a VX_THAW
operation must have the root directory of the file system open, and must
ensure that it does not access the file system after the file system has been
frozen, to ensure that the process itself does not block.
This command may only be used by a user with appropriate privilege, on
the root directory of the file system.
The VX_THAW ioctl returns a 0 if the file system is successfully unfrozen. If
the operation fails, the return value is -1 and the external variable ermo will
be a general DIAGNOSTIC or one of the following:

566

(VXFS)

vxfsio(7)

DIAGNOSTICS

The following values are returned in erma upon operation failures:
EACCESS

The calling process does not have write access to the file specified
by fildes.

EAGAIN

The file system is not currently frozen.
An attempt was made to reserve space larger than the maximum
file size limit for this process.
The command or argument is invalid.

EFBIG
EINVAL

EROFS

The process does not have appropriate privilege.
The file specified by fildes is not the root directory of a vxfs file
system.
The file system is mounted read-only.

EIO

An I/O error occurred while attempting to perform the operation.

ENOSPC

Requested space could not be obtained.
An address specified by an argument is invalid.

EPERM
ENODEV

EFAULT

SEE ALSO

getrlimit(2),ioctl(2),ulimit(2)

567

wd(7}
NAME

wd - Western Digital WD8003 Ethernet Driver
SYNOPSIS

#include
#include
#include
fd = open (l/dev/wd_O",

O_RDWR)

DESCRIPTION

The wd driver provides a data link interface to the WD8003 family of ISA and MCA
Ethernet controllers from Western Digital. It is a STREAMS-based driver, compatible with the Data Link Provider Interface (DLPI) and Logical Link Interface (LU)
software interfaces.
The wd driver supports both DL_ETHER and DL_CSMACD for MAC type,
DL_CL_E'l'HER for service mode, and DL_STYLEl for provider style. The driver can
operate as a cloned or non-cloned device.
A process must issue a DL_BIND_REQ primitive to receive frames from the network.
This primitive includes a dl_bind_re
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.3
Linearized : No
XMP Toolkit : Adobe XMP Core 4.2.1-c041 52.342996, 2008/05/07-21:37:19
Create Date : 2015:10:21 12:26:56-08:00
Modify Date : 2015:10:21 12:00:25-07:00
Metadata Date : 2015:10:21 12:00:25-07:00
Producer : Adobe Acrobat 9.0 Paper Capture Plug-in
Format : application/pdf
Document ID : uuid:69ff0c7f-5927-0d46-83e7-038031a9d5e3
Instance ID : uuid:2a4481f1-67d0-864f-a85a-301ee342d908
Page Layout : SinglePage
Page Mode : UseNone
Page Count : 612

EXIF Metadata provided by EXIF.tools

0130176826_System_Files_and_Devices_Reference_1992 0130176826 System Files And Devices Reference 1992

Navigation menu

Versions of this User Manual:

Views

Navigation