4BSD_Sections_2 8 4BSD Sections 2

4BSD_Sections_2-8 manual pdf -FilePursuit

4BSD_Sections_2-8 4BSD_Sections_2-8

User Manual: 4BSD_Sections_2-8

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

Download
Open PDF In Browser	View PDF

UNIX Programmer's Manual

INTRO (2)

INTRO (2)

NAME

intro - introduction to system calls and error numbers
SYNOPSIS

#include 
DESCRIPTION

This section describes all of the system calls. Most of these calls have one or more error
returns. An error condition is indicated by an otherwise impossible return value. This is
almost always -1; the individual descriptions specify the details.
As with normal arguments, all return codes and values from functions are of type integer
unless otherwise noted. An error number is also made available in the external variable erma,
which is not cleared on successful calls. Thus errno should be tested only after an error has
occurred.
The following is a complete list of the errors and their names as given in

o

< errno.h >.

Error 0
Unused.
EPERM Not owner
Typically this error indicates an attempt to modify a file in some way forbidden except
to its owner or super-user. It is also returned for attempts by ordinary users to do
things allowed only to the super-user.

2 ENOENT No such file or directory
This error occurs when a file name is specified and the file should exist but doesn't. or
when one of the directories in a path name does not exist.
3 ESRCH No such process
The process whose number was given to kill and ptrace does not exist, or is already
dead.
4 EINTR Interrupted system call
An asynchronous signal (such as interrupt or quit), which the user has elected to catch.
occurred during a system call. If execution is resumed after processing the signal, it
will appear as if the interrupted system call returned this error condition.
S EIO I/O error
Some physical I/O error occurred during a read or write. This error may in some cases
occur on a call following the one to which it actually applies.
6 ENXIO No such device or address
I/O on a special file refers to a subdevice which does not exist, or beyond the limits of
the device. It may also occur when. for example, an illegal tape drive unit number is
selected or a disk pack is not loaded on a drive.
7 E2BIG Arg list too long
An argument list longer than 10240 bytes is presented to execve.
8 ENOEXEC Exec format error
A request is made to execute a file which, although it has the appropriate permissions.
does not start with a valid magic number, see a.out{S).
9 EBADF Bad file number
Either a file descriptor refers to no open file, or a read (resp. write) request is made to
a file which is open only for writing (resp. reading).
10 ECHILD No children
Wait and the process has no living or unwaited-for children.

4th Berkeley Distribution

12 February 1983

INTRO (2)

UNIX Programmer's Manual

INTRO (2)

11 EAGAIN No more processes
In a fork, the system's process table is full or the user is not allowed to create any more
processes.
12 ENOMEM Not enough core
During an exeeve or break, a program asks for more core or swap space than the system
is able to supply. A lack of swap space is normally a temporary condition, however a
lack of core is not a temporary condition; the maximum size of the text, data, and stack
segments is a system parameter.
13 EACCES Permission denied
An attempt was made to access a file in a way forbidden by the protection system.
14 EF A ULT Bad address
The system encountered a hardware fault in attempting to access· the arguments of a
system call.
1S ENOTBLK Block device required
A plain file was mentioned where a block device was required, e.g. in mount.
16 EBUSY Mount device busy
An attempt to mount a device that was already mounted or an attempt was made to
dismount a device on which there is an active file directory. (open file, current directory, mounted-on file, active text segment).
17 EEXIST File exists
An existing file was mentioned in an inappropriate context, e.g. link.
18 EXDEV Cross-device link
A hard link to a file on another device was attempted.
19 ENODEV No such device
An attempt was made to apply an inappropriate system call to a device; e.g. read a
write-only device.
20 ENOTDIR Not a directory
A non-directory was specified where a directory is required, for example in a path name
or as an argument to ehdir.
21 EISD IR Is a directory
An attempt to write on a directory.
22 EINVAL Invalid argument
Some invalid argument: dismounting a non-mounted device, mentioning an unknown
,signal in Signal, reading or writing a file for which seek has generated a negative pointer.
Also set by'math functions, see intro(3).
23 ENFILE File table overflow
The system's table of open files is full, and temporarily no more opens can be accepted.
24 EMFILE Too many open files
Customary configuration limit is 20 per process.
2S ENOTTY Not a typewriter
, , The, file mentioned 'in an ioel! is not a terminal or one of. the other devices. to which
,
these calls apply ~
26 ETXTBSY Text file busy
An attempt to execute a pure-procedure program which is currently open for writing
(or reading!). Also an attempt to open for writing a pure-procedure program that is
being executed.

4th Berkeley Distribution

12 February 1983

2

INTRO (2)

UNIX Programmer's Manual

INTRO (2)

27 EFBIG File too large
The size of a file exceeded the maximum (about 109 bytes).
28 ENOS PC No space left on device
During a write to an ordinary file, there is no free space left on the device.
29 ESPIPE Illegal seek
An Iseek was issued to a pipe. This error may also be issued for other non-seekable
devices.
30 EROFS Read-only file system
An attempt to modify a file or directory was made on a device mounted read-only.
31 EMLINK Too many links
An attempt to make more than 32767 hard links to a file.
32 EPIPE Broken pipe
A write on a pipe or socket for which there is no process to read the data. This condition normally generates a signal~ the error is returned if the signal is ignored.
33 EDOM Math argument
The argument of a function in the math package OM) is out of the domain of the
function.
34 ERANG E Result too large
The value of a function in the math package (3M) is unrepresentable within machine
precision.
35 EWOULDBLOCK Operation would block
An operation which would cause a process to block was attempted on a object in nonblocking mode (see ioctl (2».
36 EINPROGRESS Operation now in progress
An operation which takes a long time to complete (such as a connect (2» was
attempted on a non-blocking object (see ioctl (2».
37 EALREADY Operation already in progress
An operation was attempted on a non-blocking object which already had an operation in
progress.
38 ENOTSOCK Socket operation on non-socket
Self-explanatory.
39 EDESTADDRREQ Destination address required
A required address was omitted from an operation on a socket.
40 EMSGSIZE Message too long
A message sent on a socket was larger than the internal message buffer.
41 EPROTOTYPE Protocol wrong type for socket
A protocol was specified which does not support the semantics of the socket type
requested. For example you cannot use the ARPA Internet UDP protocol with type
SOCK_STREAM.
42 ENOPROTOOPT Bad protocol option
A bad option was specified in a getsockopt(2) or setsockopt(2) call.
43 EPROTONOSUPPOR T Protocol not supported
The protocol has not been configured into the system or no implementation for it
exists.

4th Berkeley Distribution

12 February 1983

3

INTRO(2)

UNIX Programmer's Manual

INTRO (2)

44 ESOCKTNOSUPPORT Socket type not supported
The support for the socket type has not been configured into the· system or no implementation for it exists.

45 EOPNOTSUPP Operation not supported on socket
For example, trying to accept a connection on a datagram socket.
46 EPFNOSUPPORT Protocol family not supported
The protocol family has not been configured into the system or no implementation for
it exists.
47 EAFNOSUPPORT Address family not supported by protocol family
An address incompatible with the requested protocol was used. For example, you
shouldn't necessarily expect to be able to use PUP Internet addresses with ARPA Internet protocols.
48 EADDRINUSE Address already in use
Only one usage of each address is normally permitted.
49 EADDRNOTAVAIL Can't assign requested address
Normally results from an attempt to create a socket with an address not on this
machine.

SO ENETDOWN Network is down
A socket operation encountered a dead network.

51 ENETUNREACH Network is unreachable
A socket operation was attempted to an unreachable network.

52 ENETRESET Network dropped connection on reset
The host you were connected to crashed and rebooted.
53 ECONNABORTED Software caused connection abort
A connection abort was caused internal to your host machine.
54 ECONNRESET Connection reset by peer
A connection was forcibly closed by a peer. This normally results from the peer executing a shutdown (2) call.
55 ENOBUFS No buffer space available
An operation on a socket or pipe was not performed because the system lacked
sufficient buffer space.
56 EISCONN Socket is already connected
A connect request was made on an already connected socket; or, a sendto or sendmsg
request on a connected socket specified a destination other than the connected party.
57 ENOTCONN Socket is not connected
An request to send or receive data was disallowed because the socket is not connected.
58 ESHUTDOWN Can't send after socket shutdown
A request to send data was disallowed because the socket had already been shut down
with a previous shutdowrt(2) call.

59 unused
60 ETIMEDOUT Connection timed out
A connect request failed because the connected party did not properly respond after a
period of time. (The timeout period is dependent 0:1 the communication protocol.)
61 ECONNREFUSED Connection refused
No connection could be made because the target machine actively refused it. This usually results from trying to connect. to a service which is inactive on the foreign host.

4th Berkeley Distribution

12 February 1983

4

INTRO (2)

UNIX Programmer's Manual

INTRO (2)

62 ELOOP Too many levels of symbolic links
A path name lookup involved more than 8 symbolic links.
63 ENAMETOOLONG File name too long
A component of a path name exceeded 255 characters, or an entire path name
exceeded 1023 characters.
64 ENOTEMPTY Directory not empty
A directory with entries other than
and
was supplied to a remove directory or
rename call.
H."

H •• "

DEFINITIONS

Process ID
Each active process in the system is uniquely identified by a positive integer called a process ID. The range of this ID is from 0 to {PROC_MAX}.
Parent process ID
A new process is created by a currently active process; see !ork(2). The parent process ID
of a process is the process ID of its creator.
Process Group ID
Each active process is a member of a process group that is identified by a positive integer
called the process group ID. This is the process ID of the group leader. This grouping
permits the signalling of related processes (see killpg(2» and the job control mechanisms
of csh(I).
Tty Group ID
Each active process can be a member of a terminal group that is identified by a positive
integer called the tty group ID. This grouping is used to arbitrate between multiple jobs
contending for the same terminal~ see csh(}), and tty(4).
Real User ID and Real Group ID
Each user on the system is identified by a positive integer termed the real user ID.
Each user is also a member of one or more groups. One of these groups is distinguished
from others and used in implementing accounting facilities. The positive integer
corresponding to this distinguished group is termed the real group ID.
All processes have a real user ID and real group ID. These are initialized from the
equivalent attributes of the process which created it.
Effective User Id, Effective Group Id, and Access Groups
Access to system resources is governed by three values: the effective user ID, the
effective group ID, and the group access list.
The effective user ID and effective group ID are initially the process's real user ID and
real group ID respectively. Either may be modified through execution of a set-user-ID or
set-group-ID file (possibly by one its ancestors) ~ see execve(2).
The group access list is an additional set of group ID's used only in determining resource
accessibility. Access checks are performed as described below in HFile Access Permissions".
Super-user
A process is recognized as a super-user process and is granted special privileges if its
effective user ID is O.
Special Processes
The processes with a process ID's of 0, 1, and 2 are special. Process 0 is the scheduler.
Process 1 is the initialization process init, and is the ancestor of every other process in the
system. It is used to control the process structure. Process 2 is the paging daemon.

4th Berkeley Distribution

12 February 1983

5

INTRO (2)

UNIX Programmer's Manual

INTRO (2)

Descriptor
An integer assigned by the system when a file is referenced by open(2), dup(2). or pipe (2)
or a socket is referenced by socket(2) or socketpair(2) which uniquely identifies an access
path to that file or socket from a given process or any of its children.
File Name
Names consisting of up to {FILENAME_MAXI characters may be used to name an ordinary file, special file, or directory.
These characters may be selected from the set of all ASCII character excluding 0 (null)
and the ASCII code for / (slash). (The parity bit~ bitS, must be OJ
Note that it is generally unwise to use ., ?, [or] as part of file names because of the special meaning attached to these characters by the shell.
Path Name
A path name is a null-terminated character string starting with an optional slash (0, followed by zero or more directory names separated by slashes, optionally followed by a file
name. The total length of a path name must be less than {PATHNAME_MAX} characters.
If a path name begins with a slash, the path search begins at the root directory. Otherwise, the search begins from the current working directory. A slash by itself names the
root directory. Anull path name refers to the current directory.
Directory
A directory is a special type of file which contains entries which are references to other
files. Directory entries are called links. By convention, a directory contains at least two
links, . and .. ,referred to as dot and dot-dot respectively. Dot refers to the directory itself
and dot-dot refers to its parent directory.
Root Directory and Current Working Directory
Each process has associated with it a concept of a root directory and a current working
directory for the purpose of resolving path name searches. A process's root directory
need not be the root directory of the root file system.
File Access Permissions
Every file in the file system has a set of access permissions. These permissions are used
in determining whether a process may perform a requested operation on the file (such as
opening a file for writing). Access permissions are established at the time a file is created.
They may be changed at some later time through the chmod(2) call.
File access is broken down according to whether a file may be: read, written, or executed.
Directory files use the execute permission to control if the directory may be searched.
File access permissions are interpreted by the system as they apply to three different
classes of users: the owner of the file, those users in the file's group, anyone else. Every
file has an independent set of access permissions for each of these classes. When an
access check is made, the system decides if permission should be granted by checking the
access information applicable to the caller.
Read, write, and execute/search permissions on a file are granted to a process if:
The process's effective user 10 is that of the super-user.
The process's effective user 10 matches the user 10 of the owner of the file and the
owner permissions allow the access.
The process's effective userID does not match the user ID of the owner of the file, and
either the process's effective group ID matches the group ID of the file, Of the group 10
of the file is in the process's group access list, and the group permissions allow the access.

4th Berkeley Distribution

12 February 1983

6

INTRO (2)

UNIX Programmer's Manual

INTRO (2)

Neither the effective user ID nor effective group ID and group access list of the process
match the corresponding user ID and group ID of the file, but the permissions for "other
users" allow access.
Otherwise, permission is denied.
Sockets and Address Families
A socket is an endpoint for communication between processes. Each socket has queues
for sending and receiving data.
Sockets are typed according to their communications properties. These properties include
whether messages sent and received at a socket require the name of the partner, whether
communication is reliable, the format used in naming message recipients, etc.
Each instance of the system supports some collection of socket types; consult socket(2)
for more information about the types available and their properties.
Each instance of the system supports some number of sets of communications protocols.
Each protocol set supports addresses of a certain format. An Address Family is the set of
addresses for a specific group of protocols. Each socket has an address chosen from the
address family in which the socket was created.
SEE ALSO

intro(3), perror(3)

4th Berkeley Distribution

12 February 1983

7

ACCEPT (2)

UNIX Programmer's Manual

ACCEPT (2)

NAME

accept - accept a connection on a socket
SYNOPSIS

#include
#include

< sys/types.h>
< sys/socket.h>

ns == accept(s, addr, addrlen}
int ns, s;
struct sockaddr ·addr;
int ·addrlen;
DESCRIPTION

The argument s is a socket which has been created with socket(2) , bound to an address with
bind(2), and is listening for connections after a Iisten(2). Acceptextracts the first connection on
the queue of pending connections, creates a new socket with the same properties of s and allocates a new file descriptor, ns. for the socket. If no pending connections are present on the
queue, and the socket is not marked as non-blocking. accept blocks the caller until a connection
is present. If the socket is marked non-blocking and no pending connections are present on the
queue, accept returns an error as described below. The accepted socket, ns, may not be used to
accept more connections. The original socket s remains open.
The argument addr is a result parameter which is filled in with the address of the connecting
entity, as known to the communications layer. The exact format of the add, parameter is determined by the domain in which the communication is occurring. The add,len is a value-result
parameter: it should initially contain the amount of space pointed to by addr, on return it will
contain the actual length (in bytes) of the address returned. This call is used with connectionbased socket types, currently with SOCK_STREAM.

It is possible to select(2) a socket for the purposes of doing an accept by selecting it for read.
RETVRN VALUE

The call returns -Ion error. If it succeeds it returns a non-negati\,e integer which is a descriptor for the accepted socket.
ERRORS

The accept will fail if:
[EBADF]

The descriptor is invalid.

[ENOTSOCK]

The descriptor references a file, not a socket.

[EOPNOTSUPP]

The referenced socket is not of type SOCK_STREAM.

[EFAULT]

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

[EWOULDBLOCK]

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

SEE ALSO

bind(2), connect(2), listen(2). select(2). socket(2)

4th Berkeley Distribution

~,

7 July 1983

ACCESS (2)

UNIX Programmer's Manual

ACCESS (2)

NAME

access - determine accessibility of file
SYNOPSIS

#include
#define
#define
#define
#define

< sys/file.h>

R_OK
W_OK
X_OK
F_OK

4
2
1
0

/- test for
/- test for
/- test for
/- test for
accessible = access(path, mode)
int accessible;
char -path;
int mode;

read permission • /
write permission ./
execute (search) permission - /
presence of file - /

DESCRIPTION

Access checks the given file path for accessibility according to mode, which is an inclusive or of
the bits R OK, W OK and X OK. Specifying mode as F OK (i.e. 0) tests whether the directories leading to the file can be-searched and the file exists:The real user ID and the group access list (including the real group ID) are used in verifying
permission, so this call is useful to set- UID programs.
Notice that only access bits are checked. A directory may be indicated as writable by access,
but an attempt to open it for writing will fail (although files may be created there)~ a file may
look executable, but execve will fail unless it is in proper format.
RETURN VALUE

If path cannot be found or if any of the desired access modes would not be granted, then a -1
value is returned~ otherwise a 0 value is returned.
ERRORS

Access to the file is denied if one or more of the following are true:
[ENOTDIR]

A component of the path prefix is not a directory.

[ENOENT]

The argument path name was too long.

[ENOENT]

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

[EPERM]

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

[ELOOP]

Too many symbolic links were encountered in translating the pathname.

[EROFS]

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

[ETXTBSY]

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

[EACCES]

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

[EFAULT]

Path points outside the process's allocated address space.

SEE ALSO

chmod(2), sta«2)

4th Berkeley Distribution

18 July 1983

ACCT(2)

UNIX Programmer's Manual

ACCT (2)

NAME

acct - turn accounting on or off
SYNOPSIS

acct(file)
char -file;
DESCRIPTION

The system is prepared to write a record in an accounting .file for each process as it terminates.
This call, with a null-terminated string naming an existing file as argument. turns on accounting~ records for each terminating process are appended to file. An argument of 0 causes
accounting to be turned off.
The accounting file format is given in acct(5).
This call is permitted only to the super-user.
NOTES

Accounting is automatically disabled when the file system the accounting file resides on runs
out of space~ it is enabled when space once again becomes available.
RETVRN VALUE

On error - 1 is returned. The file must exist and the call may be exercised only by the superuser. It is erroneous to try to turn on accounting when it is already on.
ERRORS

Acct will fail if one of the following is true:

[EPERM]
[EPERM]
[ENOTDIR]
[ENOENT]
[EISDIR]
[EROFS]
[EFAULT]
[ELOOP]
[EACCES]

The caller is not the super-user.
The pathname contains a character with the high-order bit set.
A component of the path prefix is not a directory.
The named file does not exist.
The named file is a directory.
The named file resides on a read-only file system.
File points outside the process's allocated address space.
Too many symbolic links were encountered in translating the pathname.
The file is a character or block special file.

SEE ALSO

acct(5), sa (8)
BUGS

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

4th Berkeley Distribution

13 February 1983

BIND (2)

UNIX Programmer's Manual

BIND (2)

NAME

bind - bind a name to a socket
SYNOPSIS

#include < sys/types.h >
#include < sys/socket.h >
bind (s, name, namelen)
lnt s;
struct sockaddr -name;
lnt namelen;

DESCRIPTION

Bind assigns a name to an unnamed socket. When a socket is created with socket(2) it exists in
a name space (address family) but has no name assigned. Bind requests the name, be assigned
to the socket.
NOTES

Binding a name in the UNIX domain creates a socket in the file system which must be deleted
by the caller when it is no longer needed (using unlink (2) ). The file created is a side-effect of
the current implementation, and will not be created in future versions of the UNIX ipc domain.
The rules used in name binding vary between communication domains. Consult the manual
entries in section 4 for detailed information.
RETURN VALUE

If the bind is successful, a 0 value is returned. A return value of -1 indicates an error, which
is further specified in the global errno.
ERRORS

The bind call will fail if:
[EBADF]

S is not a valid descriptor.

S is not a socket.
[EADDRNOTAVAIL]
The specified address is not available from the local machine.
[ENOTSOCK]

[EADDRINUSE]

The specified address is already in use.

[EINVAL]

The socket is already bound to an address.

[EACCESS]

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

[EFAULT]

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

SEE ALSO

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

4th Berkeley Distribution

27 July 1983

1

BRK (2)

UNIX Programmer's Manual

BRK (2)

NAME
brk, sbrk - change data segment size
SYNOPSIS

caddr_t brk(addr)
caddr_t addr;
caddr_t sbrk(jncr)
int incr;
DESCRIPTION

Brk sets the system's idea of the lowest data segment location not used by the program (called
the break) to add, (rounded up to the next multiple of the system's page size). Locations
greater than addr and below the stack pointer are not in the address space and will thus cause a
memory violation if accessed.

In the alternate function sbrk, incr more bytes are added to the program's data space and a
pointer to the start of the new area is returned.
When a program begins execution via execve the break is set at the highest location defined by
the program and data storage areas. Ordinarily, therefore, only programs with growing data
areas need to use sbrk.
The getrlimit(2) system call may be used to determine the maximum permissible size of the
data segment~ it will not be possible to set the break beyond the rlim max value returned from
a call to getrlimit, e.g. "etext + rlp-rlim_max." (See end(3) for the definition of etexr.)
RETURN VALUE

Zero is returned if the brk could be set: -1 if the program requests more memory than the system limit. Sbrk returns -1 if the break could not be set.
ERRORS

Sb,k will fail and no additional memory will be allocated if one of the following are true:

[ENOMEM]

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

[ENOMEM]

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

[ENOMEM]

Insufficient space existed in the swap area to support the expansion.

SEE ALSO

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

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

4th Berkeley Distribution

27 July 1983

CHOIR (2)

CHOIR (2)

UNIX Programmer's Manual

NAME

chdir - change current working directory
SYNOPSIS

chdir(path)
char ·path;
DESCRIPTION
Path is the pathname of a directory. Chdir causes this directory to become the current working

directory, the starting point for path names not beginning with

··r'.

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

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and
errllo is set to indicate the error.
ERRORS
Chdir will fail and the current working directory will be unchanged if one or more of the follow-

ing are true:
[ENOTDIR]

A component of the pathname is not a directory.

[ENOENT]
[ENOENT]

The named directory does not exist.

[EPERM]

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

[EACCES]
[EFAULT]
[ELOOP]

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

The argument path name was too long.

Path points outside the process's allocated address space.

Too many symbolic links were encountered in translating the pathname.

SEE ALSO

chroot(2)

4th Berkeley Distribution

2 July 1983

CHMOD (2)

UNIX Programmer's Manual

CHMOD (2)

NAME

chmod - change mode of file
SYNOPSIS

chmod(path, mode)
char ·path;
int mode;
fchmod(fd, mode)
int fd, mode;
DESCRIPTION

The file whose name is given by path or referenced by the descriptor fdhas its mode changed to
mode. Modes are constructed by or'ing together some combination of the following:
04000 set user ID on execution
02000 set group ID on execution
01000 save text image after execution
00400 read by owner
00200 write by owner
00100 execute (search on directory) by owner
00070 read. write, execute (search) by group
00007 read. write. execute (search) by others
If an executable file is set up for sharing (this is the default) then mode 1000 prevents the system from abandoning the swap-space image of the program-text portion of the file when its last
user terminates. Ability to set this bit is restricted to the super-user.
Only the owner of a file (or the super-user) may change the mode.
Writing or changing the owner of a file turns off the set-ust:r-id and set-group-id bits. This
makes the system somewhat more secure by protecting set-user-id (set-group-id) files from
remaining set-user-id (set-group-id) if they are modified. at the expense of a degree of compatibility.
RETCRN VALUE

Upon successful completion. a value of 0 is returned. Otherwise, a value of -1 is returned and
errno is set to indicate the error.
ERRORS
ChmodwiJI fail and the file mode wiJI be unchanged if:

[EPERM]
[ENOTDIR]
[ENOENT]
[ENOENT]
[EACCES]
[EPERM]

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

A component of the path prefix is not a directory.
The pathname was too long.
The named file does not exist.
Search permission is denied on a component of the path prefix.
The effective user ID does not match the owner of the file and the effective
user ID is not the super-user.
[EROFS]
The named file resides on a read-only file system.
[EFAULT]
Path points outside the process's allocated address space.
[ELOOP]
Toomany symbolic links were eqcountered in translating the pathr.ame.
Fchmod will fail if:
[EBADF]
The descriptor is not valid.
[EINVAL]
Fdrefers to a socket, not to a file.

4th Berkeley Distribution

2 July 1983

CHMOD (2)

[EROFS]

UNIX Programmer's Manual

CHMOD (2)

The file resides on a read-only file system.

SEE ALSO

open(2), chown(2)

4th Berkeley Distribution

2 July 1983

2

CHOWN (2)

UNIX Programmer's Manual

CHOWN (2)

NAME

chown - change owner and group of a file
SYNOPSIS

chown(path, owner, group)
char ·path;
int owner, group;
fchown(fd, owner, group)
int fd, owner, group;
DESCRIPTION

The file which is named by path or referenced by fd has its owner and group changed as
specified. Only the super-user may execute this call. because if users were able to give files
away. they could defeat the file-space accounting procedures.
On some systems. chown clears the set-user-id and set-group-id bits on the file to prevent
accidental creation of set-user-id and set-group-id programs owned by the super-user.
Fchown is particularly useful when used in conjunction with the file locking primitives (see
.llock(2».

Only one of the owner and group id's may be set by specifying the other as -1.
RETURS VALUE

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

Chown will fail and the file will be unchanged if:

[EINV AL]
[ENOTDIR]
[ENOENT]
[EPERM]

The argument path does not refer to a file.
A component of the path prefix is not a directory.
The argument pathname is too long.
The argument contains a byte with the high-order bit set.

[ENOENT]

The named file does not exist.

[EACCES]
[EPERM]

Search permission is denied on a component of the path prefix.
The effective user ID does not match the owner of the file and the effective
user ID is not the super-user.

[EROFS]

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

[EFAUL T1
[ELOOP]

Path points outside the process's allocated address space.

Too many symbolic links were encountered in translating the pathname.

Fchown will fail if:
[EBADF]
Fddoes not refer to a valid descriptor.
[EINVAL]
Fdrefers to a socket, not a file.
SEE ALSO

chmod(2), flock(2)

4th Berkeley Distribution

27 July 1983

UNIX Programmer's Manual

CHROOT (2)

CHROOT (2)

NAME

chroot - change root directory
SYNOPSIS

chroot(dirname)
char *dirname;
DESCRIPTION

Dirname is the address of the pathname of a directory, terminated by a null byte. Chrootcauses
this directory to become the root directory, the starting point for path names beginning with
In order for a directory to become the root directory a process must have execute (search)
access to the directory.
This call is restricted to the super-user.
RETURN VALUE

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

Chroot will fail and the root directory will be unchanged if one or more of the following are
true:
[ENOTDIR]
A component of the path name is not a directory.
[ENOENT]
The pathname was too long.
[EPERM]

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

[ENOENT]

The named directory does not exist.

[EACCES]

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

[EFAULT]

Path points outside the process's allocated address space.
Too many symbolic links were encountered in translating the pathname.

[ELOOP]
SEE ALSO

chdid2)

4th Berkeley Distribution

2 July 1983

CLOSE (2)

UNIX Programmer's Manual

CLOSE (2)

NAME

close - delete a descriptor
SYNOPSIS
close(d)

iot d;
DESCRIPTION

The close call deletes a descriptor from the per-process object reference table. If this is the last
reference to the underlying object. then it will be deactivated. For example. on the last close of
a file the current seek pointer associated with the file is lost~ on the last close of a socket(2)
associated naming information and queued data are discarded~ on the last close of a file holding
an advisory lock the lock is released~ see further Jlock(2).
A close of all of a process's descriptors is automatic on exit. but since there is a limit on the
number of active descriptors per process. close is necessary for programs which deal with many
descriptors.
When a process forks (see jork(2» , all descriptors for the new child process reference the same
objects as they did in the parent before the fork. If a new process is then to be run using
execve(2) , the process would normally inherit these descriptors. Most of the descriptors can be
rearranged with dup2(2) or deleted with close before the exeo'e is attempted. but if some of
these descriptors will still be needed if the execve fails, it is necessary to arrange for them to be
closed if the execve succeeds. For this reason. the call "fcntJ(d. F_SETFD. I)" is provided
which arranges that a descriptor will be closed after a successful execve~ the call "fcntl (d.
F_SETFD, 0)" restores the default. which is to not close the descriptor.
RETURN VALUE

Upon successful completion. a value of 0 is returned. Otherwise. a value of -1 is returned and
the global integer variable err no is set to indicate the error.
ERRORS

Close will fail if:
[EBADF]
D is not an active descriptor.
SEE ALSO

accept(2), flock(2), open(2). pipe(2), socket(2), socketpair(2), execve(2). fcntH2)

4th Berkeley Distribution

27 July 1983

UNIX Programmer's Manual

CONNECT (2)

CONNECT (2)

NAME

connect - initiate a connection on a socket
SYNOPSIS

#include < sys/types.h>
#include < sys/socket.h>
connect(s, name, namelen}
int s;
struct sockaddr • name;
int namelen;
DESCRIPTION

The parameter s is a socket. If it is of type SOCK_DGRAM, then this call permanently
specifies the peer to which datagrams are to be sent if it is of type SOCK_STREAM. then this
call attempts to make a connection to another socket. The other socket is specified by name
which is an address in the communications space of the socket. Each communications space
interprets the name parameter in its own way.
RETURN VAL liE

If the connection or binding succeeds. then 0 is returned. Otherwise a -1 is returned. and a
more specific error code is stored in errno.
ERRORS

The call fails if:
[EBADF]

S is not a valid descriptor.

[ENOTSOCK]

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

[EADDRNOT AVAIL]
The specified address is not available on this machine.
[EAFNOSUPPORT] Addresses in the specified address family cannot be used with this socket.
[EISCONN]

The socket is already connected.

[ETIMEDOUT]

Connection establishment timed out without establishing a connection.

[ECONNREFUSED] The attempt to connect was forcefully rejected.
[ENETUNREACH]
[EADDRINUSE]

The network isn't reachable from this host.
The address is already in use.

[EFAULT]

The name parameter specifies an area outside the process address space.

[EWOULDBLOCK] The socket is non-blocking and the and the connection cannot be completed immediately. It is possible to select(2) the socket while it is connecting by selecting it for writing.
SEE ALSO

accept(2), select(2), socket(2), getsockname(2)

4th Berkeley Distribution

7 July 1983

CREAT(2)

UNIX Programmer's Manual

CREAT(2)

NAME

creat - create a new file
SYNOPSIS

creat(name, mode)
char -name;
DESCRIPTION

This interface is obsoleted by open (2).
Crear creates a new file or prepares to rewrite an existing file called flame. given as the address
of a null-terminated string. If the file did not exist. it is given mode mode. as modified by the
process's mode mask (see umask(2». Also see chmod(2) for the construction of the mode
argument.

If the file did exist. its mode and owner remain unchanged but it is truncated to 0 length.
The file is also opened for writing. and its file descriptor is returned.
NOTES

The mode given is arbitrary: it need not allow writing. This feature has been used in the past
by programs to construct a simple exclusive locking mechanism. It is replaced by the O_EXCL
open mode. or ./fock(2) facilitity.
RETVRN VALVE

The value -1 is returned if an error occurs. Otherwise. the call returns a non-negative descriptor which only permits writing.
ERRORS
Crear will fail and the file will not be created or truncated if one of the following occur:

[EPERM]

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

[ENOTDIR]

A component of the path prefix is not a directory.

[EACCES]

A needed directory does not have search permission.

[EACCES]

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

[EACCES]

The file exists. but it is unwritable.

[EISDIR]

The file is a directory.

[EMFILE]

There are already too many files open.

[EROFS]

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

[ENXIO]
[ETXTBSY]

The file is a character special or block special file. and the associated device
does not exist.
The file is a pure procedure (shared text) file that is being executed.

[EFAULT]

Name points outside the process's allocated address space.

[ELOOP]
Too many symbolic links were encountered in translating the pathname.
[EOPNOTSUPP]
The file was a socket (not currently implemented).
SEE ALSO

open(2). write(2). close(2), chmod(2), umask(2)

4th Berkeley Distribution

2 July 1983

DUP (2)

UNIX Programmer's Manual

DUP(2)

NAME

dup, dup2 - duplicate a descriptor
SYNOPSIS

newd - dup (oldd)
lnt newd, oldd;
dup2 (oldd, newd)
lnt oldd, newd;
DESCRIPTION
Dup duplicates an existing object descriptor. The argument oldd is a small non-negative integer

index in the per-process descriptor table. The value must be less than the size of the table,
which is returned by getdtablesize(2). The new descriptor newd returned by the call is the
lowest numbered descriptor which is not currently in use by the process.
The object referenced by the descriptor does not distinguish between references using oldd and
newd in any way. Thus if newd and oldd are duplicate references to an open file, read(2) ,
write(2) and Iseek(2) calls all move a single pointer into the file. If a separate pointer into the
file is desired, a different object reference to the file must be obtained by issuing an additional
open(2) call.
In the second form of the call, the value of newd desired is specified. If this descriptor is
already in use, the descriptor is first deallocated as if a c/ose(2) call had been done first.
RETURN VALUE

The value -1 is returned if an error occurs in either call. The external variable errno indicates
the cause of the error.
ERRORS
Dup and dup2 fail if:

[EBADF]

Oldd or newd is not a valid active descriptor

[EMFILE]

Too many descriptors are active.

SEE ALSO

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

4th Berkeley Distribution

12 February 1983

1

EXECVE(2)

UNIX Programmer's Manual

EXECVEC2>

NAME

execve - execute a file
SYNOPSIS

execve(name, argv, envp)
char *name, *argvll, -envpll:
DESCRIPTION
Execve transforms the calling process into a new process. The new process is constructed from
an ordinary file called the new process .file. This file is either an executable object file, or a file
of data for an interpreter. An executable object file consists of an identifying header, followed
by pages of data representing the initial program (text) and initialized data pages. Additional
pages may be specified by the header to be initialize with zero data. See a.out(S>.

An interpreter file begins with a line of the form'" #! imerpreter"~ When an interpreter file is
execve'd, the system execve's the specified ;merpreter, giving it the name of the originally
exec'd file as an argument, shifting over the rest of the original arguments.
There can be no return from a successful execve because the calling core image is lost. This is
the mechanism whereby different process images become active.
The argument argl' is an array of character pointers to null-terminated character strings. These
strings constitute the argument list to be made available to the new process. By convention. at
least one argument must be present in this array, and the first element of this array should be
the name of the executed program (i.e. the last component of name>.
The argument em'p is also an array of character pointers to null-terminated strings. These
strings pass information to the new process which are not directly arguments to the command.
see env;ron(7).
Descriptors open in the calling process remain open in the new process. except for those for
which the c1ose-on-exec flag is set~ see c/ose(2). Descriptors which remain open are unaffected
by execve.
Ignored signals remain ignored across an exen'e, but signals that are caught are reset to their
default values. The signal stack is reset to be undefined~ see sigved2) for more information.
Each process has real user and group IDs and a e.ffective user and group IDs. The rea/lD
identifies the person using the system~ the effective lD determines his access privileges. Execl'e
changes the effective user and group ID to the owner of the executed file if the file has the
'"set-user-ID" or '"set-group-ID" modes. The real user ID is not affected.
The new process also inherits the following attributes from the calling process:
process 10
parent process I D
process group ID
access groups
working directory
root directory
control terminal
resource usages
interval timers
resource limits
file mode mask
signal mask

see
see
see
see
see
see
see
see
see
see
see
see

getpid (2)
getppid(2)
getpgrp(2)
getgroups(2)
chdir(2)
chroot(2)
tl)'(4)

getrusage(2)
getitimed2)
getrlimit(2)
umask(2)
sigved2)

When the executed program begins, it is called as follows:

4th Berkeley Distribution

27 July 1983

EXECVE(2)

UNIX Programmer's Manual

EXECVE(2)

main(argc, argv, envp)
int argc~
char **argv, .... envp~
where argc is the number of elements in arg\' (the "arg count") and argl'is the array of character pointers to the arguments themselves.
Envp is a pointer to an array of strings that constitute the envirollment of the process. A pointer
to this array is also stored in the global variable "environ". Each string consists of a name. an
,. -= H, and a null-terminated value. The array of pointers is terminated by a null pointer. The
shell sh( 1) passes an environment entry for each global shell variable defined when the program is called. See environ(7) for some conventionally used names.
RETURN VALUE
If execve returns to the calling process an error has occurred~ the return value will be -1 and
the global variable errllo will contain an error code.
ERRORS
Execve will fail and return to the calling process if one or more of the following are true:

[ENOENT]

One or more components of the new process file's path name do not exist.

[ENOTDIR]

A component of the new process file is not a directory.

[EACCES]

Search permission is denied for a directory listed in the new process file's path
prefix.

[EACCES]

The new process file is not an ordinary file.

[EACCES]

The new process file mode denies execute permission.

[ENOEXEC]

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

[ETXTBSY]

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

[ENOMEM]

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

[E2BIG]

The number of bytes in the new process's argument list is larger than the
system-imposed limit of IARG_MAXI bytes.

[EFAUL T]

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

[EFAUL T]

Path, argv, or efnp point to an illegal address.

CAVEATS

If a program is setuid to a non-super-user. but is executed when the real uid is "root", then the
program has the powers of a super-user as well.
SEE ALSO

exit(2), fork(2), execl(3), environ(7)

4th Berkeley Distribution

27 July 1983

2

EXIT (2)

UNIX Programmer's Manual

EXIT (2)

NAME

_exit - terminate a process
SYNOPSIS

_exit (status)
int status;
DESCRIPTION
_exit terminates a process with the following consequences:

All of the descriptors open in the calling process are closed.
If the parent process of the calling process is executing a wait or is interested in the SIGCHLD
signal. then it is notified of the calling process's termination and the low-order eight bits of
status are made available to it~ see wait(2).
The parent process ID of all of the calling process's existing child processes are also set to I.
This means that the initialization process (see intro(2» inherits each of these processes as well.
Most C programs call the library routine exit(3) which performs cleanup actions in the standard
i/o library before calling _eXit.
RETURN VALl:E

This call never returns.
SEE ALSO

fork(2), wait(2). exit(3)

4th Berkeley Distribution

27 July 1983

UNIX Programmer's Manual

FCNTL(2)

FCNTL (2)

NAME

fcntl - file control
SYNOPSIS

#Include 
res - fcntl (fd, cmd, aq>
lnt res;
lnt fd, cmd, aq;
DESCRIPTION

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

Return a new descriptor as follows:
Lowest numbered available descriptor greater than or equal to argo
Same object references as the original descriptor.
New descriptor shares the same file pointer if the object was a file.
Same access mode (read, write or read/write).
Same file status flags (i.e., both file descriptors share the same file status flags).
The close-on-exec flag associated with the new file descriptor is set to remain
open across execv(2) system calls.
Get the close-on-exec flag associated with the file descriptor /d. If the loworder bit is 0, the file will remain open across exec, otherwise the file will be
closed upon execution of exec.
Set the close-on-exec flag associated with /d to the low order bit of arg (0 or 1
as above).

F_GETFL

Get descriptor status flags, as described below.

F_SETFL

Set descriptor status flags.

F_GETOWN

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

F_SETOWN

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

The flags for the F_GETFL and F_SETFL flags are as follows:
FNDELAY

Non-blocking 110; if no data is available to a read call, or if a write operation
would block, the call returns -1 with the error EWOULDBLOCK.

FAPPEND

Force each write to append at the end of file; corresponds to the 0 APPEND
flag of open (2) .
-

FASYNC

Enable the SIGIO signal to be sent to the process group when I/O is possible,
e.g. upon availability of data to be read.

RETURN VALUE

Upon successful completion, the value returned depends on cmd as follows:
F_DUPFD
F_GETFD
F_GETFL
F_GETOWN

4th Berkeley Distribution

A new file descriptor.
Value of flag (only the low-order bit is defined).
Value of flags.
Value of file descriptor owner.

18 July 1983

1

FCNTL (2)

UNIX Programmer's Manual

other

FCNTL (2)

Value other than -1.

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

Fentl will fail if one or more of the following are true:
[EBADF]
Fildes is not a valid open file descriptor.
[EMFILE]
Cmd is F_DUPFD and the maximum allowed number of file descriptors are
currently open.
[EINV AL]
Cmd is F DUPFD and arg is negative or greater the maximum allowable
number (see getdtablesize(2».
SEE ALSO

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

BUGS
The asynchronous 110 facilities of FNDELAY and FASYNC are currently available only for tty
operations. No SIGIO signal is sent upon draining of output sufficiently for non-blocking writes
to occur.

4th Berkeley Distribution

18 July 1983

2

FLOCK (2)

UNIX Programmer's Manual

FLOCK (2)

NAME

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

#include < sys/ftle.h >
#deftneLOCK_SH
1
#deftne LOCK_EX
2
#deftneLOCK_NB
4
#deftneLOCK_UN
8
flock (fd, operation)
int fd, operation;

/.
/.
/.
/.

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

DESCRIPTION
Flock applies or removes an advisory lock on the file associated with the file descriptor fd. A
lock is applied by specifying an operation parameter which is the inclusive or of LOCK_SH or
LOCK_EX and, possibly, LOCK_NB. To unlock an existing lock operation should be
LOCK_UN.

Advisory locks allow cooperating processes to perform consistent operations on files, but do not
guarantee consistency (i.e. processes may still access files without using advisory locks possibly
resulting in inconsistencies).
The locking mechanism allows two types of locks: shared locks and exclusive locks. At any time
multiple shared locks may be applied to a file, but at no time are multiple exclusive, or both
shared and exclusive, locks allowed simultaneously on a file.
A shared lock may be upgraded to an exclusive lock, and vice versa, simply by specifying the
appropriate lock type~ this results in the previous lock being released and the new lock applied
(possibly after other processes have gained and released the lock).
Requesting a lock on an object which is already locked normally causes the caller to blocked
until the lock may be acquired. If LOCK_NB is included in operation, then this will not happen~ instead the call will fail and the error EWOULDBLOCK will be returned.
NOTES

Locks are on files, not file descriptors. That is, file descriptors duplicated through dup( 2) or
fork(2) do not result in multiple instances of a lock, but rather multiple references to a single
lock. If a process holding a lock on a file forks and the child explicitly unlocks the file, the
parent will lose its lock.
Processes blocked awaiting a lock may be awakened by signals.
RETURN VALUE
Zero is returned if the operation was successful~ on an error a - I is returned and an error code
is left in the global location errno.
ERRORS
The flock call fails if:

[EWOULDBLOCK]

The file is locked and the LOCK_NB option was specified.

[EBADF]

The argument fd is an invalid descriptor.

[EINVAL]

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

SEE ALSO
open(2), close(2), dup(2), execve(2), fork(2)

4th Berkeley Distribution

27 July 1983

FORK (2)

UNIX Programmer's Manual

FORK (2)

NAME

fork - create a new process
SYNOPSIS

pld - forkO
lnt pldj
DESCRIPTION

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

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

Fork will fail and no child process will be created if one or more of the following are true:
[EAGAIN]

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

[EAGAIN]

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

SEE ALSO

execve (2), wait (2)

4th Berkeley Distribution

12 February 1983

1

FSYNC (2)

UNIX Programmer's Manual

FSYNC(2)

NAME

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

fsync(fd)
tnt fd;
DESCRIPTION

Fsync causes all modified data and attributes of fd to be moved to a permanent storage device.
This normally results in all in-core modified copies of buffers for the associated file to be written to a disk.
Fsync should be used by programs which require a file to be in a known state; for example in
building a simple transaction facility.
RETURN VALUE

A 0 value is returned on success. A -1 value indicates an error.
ERRORS

The fsync fails if:
[EBADF]

Fd is not a valid descriptor.

[EINV AL]

Fd refers to a socket, not to a file.

SEE ALSO

sync (2) , sync(S), update(S)
BUGS

The current implementation of this call is expensive for large files.

4th Berkeley Distribution

12 February 1983

1

GETDTABLESIZE ( 2 )

UNIX Programmer's Manual

GETDTABLESIZE ( 2 )

NAME

getdtablesize - get descriptor table size
SYNOPSIS

nds - letdtablesize ()
int nds;
DESCRIPTION

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

c)ose(2) , dup(2), open(2)

4th Berkeley Distribution

12 February 1983

1

GETGID (2)

UNIX Programmer's Manual

GETGID (2)

NAME

getgid, getegid - get group identity
SYNOPSIS

lid - letlld ()
int lid;
eaid - letelld()
int eaid;
DESCRIPTION
Getgid returns the real group ID of the current process, getegid the effective group ID.

The real group ID is specified at login time.
The effective group ID is more transient, and determines additional access permission during
execution of a "set-group-ID" process, and it is for such processes that getgid is most useful.
SEE ALSO

getuid (2), setregid (2), setgid (3)

4th Berkeley Distribution

12 February 1983

1

GI·~·I'GROUPS( 2)

gctgroup~

GI~TGI{OUPS( 2)

UN IX Progr,ilnrncr\ Manual

_. get group access list

SYNOPSIS

It include :t'IUPTION

gcts the curn.'1l1 grnllp access list or till' lIscr process and stOI\'S it in thc arr;!y ,l)dscl. The
indicaks the !lumher of' elltries which 1I1, will ever be rrturtled.

(/d'p.. l"OlfIJS

IXlralllClL'r II,!~I'IJUI)S

HETUltN V AI.UI-:
(,"".!!I"OIII'S rdllf'llS the 1l1l11lhcJ' or groups P!lt ill gids{'/. i\ v;dllC
or llIol'l'indical l .'s t!J:ll the call
o.:..IICCl'l'lkd. ;\ \'aIUl'
I illdicatc:, tll:lt ;til ,-'ITOI' occllrn..'d . and the error code is storl'd ill the global "Iri
#define ITIMER_REAL
0
#define ITIMER_VIRTUAL 1
#define ITIMER_PROF
2

/- real time intervals -/
/- virtual time intervals -/
/- user and system virtual time -/

getitimer(which, value}
int which;
struct itimerval -value;
setitimer(which, value, ovalue}
int which;
struct itimerval -value, -ovalue;
DESCRIPTION
The system provides each process with three interval timers, defined in < sys/time. h > . The
getitimer call returns the current value for the timer specified in which, while the setitimer call
sets the value of a timer (optionally returning the previous value of the timer).

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

/. timer interval ./
/. current value ./

}~

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

Three macros for manipulating time values are defined in < sys/time. h >. Timerc/ear sets a time
value to zero, timerisset tests if a time value is non-zero, and timercmp compares two time
values (beware that > == and < == do not work with this macro).
RETURN VALUE
If the calls succeed, a value of 0 is returned. If an error occurs, the value -1 is returned, and
a more precise error code is placed in the global variable errno.

4th Berkeley Distribution

27 July 1983

G ETITIMER ( 2 )

ERRORS

UNIX Programmer's Manual

GETITIMER ( 2 )

.

The possible errors are:
[EFAULT]

The value structure specified a bad address.

[EINVAL]

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

SEE ALSO

sigvec(2), gettimeofday(2)

4th Berkeley Distribution

27 July 1983

2

GETPAGESIZE (2)

UNIX Programmer's Manual

GETPAGESIZE ( 2 )

NAME

getpagesize - get system page size
SYNOPSIS

pagesize == i;etpagesize ()
int pagesize;
DESCRIPTION

Getpagesize returns the number of bytes in a page. Page granularity is the granularity of many
of the memory managemen t calls.
The page size is a system page size and may not be the same as the underlying hardware page
size.
SEE ALSO

sbrk (2), pagesize (1)

4th Berkeley Distribution

18 July 1983

1

GETPEERNAME ( 2 )

UNIX Programmer's Manual

GETPEERNAME ( 2 )

NAME

getpeername - get name of connected peer
SYNOPSIS

getpeername(s, name, namelen)
int s;
struct sockaddr -name;
int -namelen;
DESCRIPTION

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

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

The call succeeds unless:
[EBADF]

The argument s is not a valid descriptor.

[ENOTSOCK]

The argument s is a file, not a socket.

[ENOTCONN] The socket is not connected.
[ENOBUFS]

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

[EFAULT]

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

SEE ALSO

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

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

4th Berkeley Distribution

21 July 1983

1

GETPGRP(2)

UNIX Programmer's Manual

GETPGRP (2)

NAME

getpgrp - get process group
SYNOPSIS

pgrp == getpgrp(pid)
int prgp;
int pid;
DESCRIPTION

The process group of the specified process is returned by getpgrp. If pid is zero, then the call
applies to the current process.
Process groups are used for distribution of signals, and by terminals to arbitrate requests for
their input: processes which have the same process group as the terminal are foreground and
may read, while others will block with a signal if they attempt to read.
This call is thus used by programs such as csh(I) to create process groups in implementing job
control. The TIOCGPGRP and TIOCSPGRP calls described in tty(4) are used to get/set the
process group of the control terminal.
SEE ALSO

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

4th Berkeley Distribution

2 July 1983

1

GETPID (2)

UNIX Programmer's Manual

GETPID (2)

NAME

getpid, getppid - get process identification
SYNOPSIS

pld - letpld ()
1001 pld;

ppld - letppld ()
1001 ppld;
DESCRIPTION
Getpid returns the process ID of the current process. Most often it is used with the host
identifier gethostid(2) to generate uniquely-named temporary files.
Getppid returns the process ID of the parent of the current process.

SEE ALSO

gethostid (2)

4th Berkeley Distribution

12 February 1983

1

GETPRIORITY (2)

UNIX Programmer's Manual

GETPRIORITY (2)

NAME

getpriority, setpriority - get/set program scheduling priority
SYNOPSIS

#include

< sys/resource.h >

#deftne PRIO_PROCESS
0
1
#define PRIO_PGRP
2
#define PRIO_USER
prio = getpriority(which, who}
int prio, which, who;
setpriority(which, who, prio}
int which, who, prio;

/. process • /
/. process group ./
/. user id ./

DESCRIPTION

The scheduling priority of the process, process group, or user, as indicated by which and who is
obtained with the getpriority call and set with the setpriority call. Which is one of
PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, and who is interpreted relative to which (a
process identifier for PRIO PROCESS, process group identifier for PRIO PGRP, and a user ID
for PRIO_USER). Prio is -a value in the range -20 to 20. The default priority is O~ lower
priorities cause more favorable scheduling.
The getpriority call returns the highest priority (lowest numerical value) enjoyed by any of the
specified processes. The setpriority call sets the priorities of all of the specified processes to the
specified value. Only the super-user may lower priorities.
RETURN VALUE

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

Getpriority and setpriority may return one of the following errors:

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

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

4th Berkeley Distribution

18 July 1983

G ETRLIMIT ( 2 )

UNIX Programmer's Manual

GETRLIMIT (2)

NAME

getrlimit, setrlimit - control maximum system resource consumption
SYNOPSIS

#include < sys/time.h >
#include 
getrlimit (resource, rip)
Int resource;
struct rlimlt -rip;
setrlimit (resource, rip)
int resource;
struct rlimit -rip;
DESCRIPTION

Limits on the consumption of system resources by the current process and each process it
creates may be obtained with the getrlimit call, and set with the setrlimit call.
The resource parameter is one of the following:
RLIMIT_CPU
the maximum amount of cpu time (in milliseconds) to be used by each process.
RLIMIT_FSIZE the largest size, in bytes, of any single file which may be created.
RLIMIT_DATA the maximum size, in bytes, of the data segment for a process~ this defines
how far a program may extend its break with the sbrk(2) system call.
RLIMIT_STACK the maximum size, in bytes, of the stack segment for a process~ this defines
how far a program's stack segment may be extended, either automatically by
the system, or explicitly by a user with the sbrk(2) system call.
RLIMIT _CORE the largest size, in bytes, of a core file which may be created.
RLIMIT_RSS
the maximum size, in bytes, a process's resident set size may grow to. This
imposes a limit on the amount of physical memory to be given to a process~
if memory is tight, the system will prefer to take memory from processes
which are exceeding their declared resident set size.
A resource limit is specified as a soft limit and a hard limit. When a soft limit is exceeded a
process may receive a signal (for example, if the cpu time is exceeded), but it will be allowed
to continue execution until it reaches the hard limit (or modifies its resource limit). The rlimil
structure is used to specify the hard and soft limits on a resource,
struct rlimit {
I- current (soft) limit -I
int
r1im_cur~
int
I- hard limit -/
r1im_max~
}~

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

4th Berkeley Distribution

7 July 1983

1

UNIX Programmer's Manual

G ETRLIMIT ( 2 )

G ETRLIMIT ( 2 )

A file i/o operation which would create a file which is too large will cause a signal SIGXFSZ to
be generated, this normally terminates the process, but may be caught. When the soft cpu time
limit is exceeded, a signa! SIGXCPU is sent to the offending process.
RETURN VALUE

A 0 return value indicates that the call succeeded, changing or returning the resource limit. A
return value of -1 indicates that an error occurred, and an error code is stored in the global
location errno.
ERRORS

The possible errors are:
[EFAUL T]

The address specified for rip is invalid.

[EPERM]

The limit specified to setrlimit would have
raised the maximum limit value, and the caller is not the super-user.

SEE ALSO

cshO), quota(2)
BUGS

There should be limit and unlimit commands in sh (1) as well as in csh.

4th Berkeley Distribution

7 July 1983

2

GETRUSAGE (2)

UNIX Programmer's Manual

GETRUSAGE (2 )

NAME

getrusage - get information about resource utilization
SYNOPSIS

#Include < sys/tlme.h >
#Include < sys/resource.h >
#deftne RUSAGE_SELF
0
#deftne RUSAGE_CHILDREN -1
letrusale(who, rusage)
Int who;
struct rusale -rusale;

I- calling process -I
I- terminated child processes -I

DESCRIPTION

Getrusage returns information describing the resources utilized by the current process, or all its
terminated child processes. The who parameter is one of RUSAGE SELF and
RUSAGE_CHILDREN. If rusage is non-zero, the buffer it points to will be filled in with the
following structure:
struct rusage (
struct timeval ru_utime~
struct timeval ru_stime;
int
ru_maxrss;
int
ruJxrss;
int
ruJdrss;
int
ruJsrss;
int
ru_minflt~
int
ru_majflt~
int
ru_nswap;
int
ruJnblock;
int
ru_oublock;
ru_msgsnd;
int
int
ru_msgrcv;
int
ru_nsignals;
int
ru_nvcsw~
int
ru_nivcsw;
);

/- user time used -/
/- system time used -/
/////////////-

integral shared memory size -/
integral unshared data size -/
integral unshared stack size -/
page reclaims -/
page faults -/
swaps -/
block input operations -/
block output operations -/
messages sent -/
messages received -/
signals received -/
voluntary context switches -/
involuntary context switches -/

The fields are interpreted as follows:
ru_utime

the total amount of time spent executing in user mode.

ru_stime

the total amount of time spent in the system executing on behalf of the
process (es) .

ru_maxrss

the maximum resident set size utilized (in kilobytes).

ruJxrss

an "integral" value indicating the amount of memory used which was also
shared among other processes. This value is expressed in units of kilobytes seconds-of-execution and is calculated by summing the number of shared
memory pages in use each time the internal system clock ticks and then
averaging over 1 second intervals.

ruJdrss

an integral value of the amount of unshared memory residing in the data segment of a process (expressed in units of kilobytes - seconds-of-execution).

ruJsrss

an integral value of the amount of unshared memory residing in the stack segment of a process (expressed in units of kilobytes - seconds-of-execution).
the number of page faults serviced without any ilo activity; here i/o activity is

4th Berkeley Distribution

18 July 1983

1

GETRUSAGE (2)

UNIX Programmer's Manual

GETRUSAGE (2)

avoided by "reclaiming" a page frame from the list of pages awaiting reallocation.
ru_majflt

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

ru_nswap

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

rujnblock

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

ru_outblock

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

ru_msgsnd

the number of ipc messages sent.

ru_msgrcv
ru_nsignals

the number of ipc messages received.

ru_nvcsw

the number of times a context switch resulted due to a process voluntarily giving up the processor before its time slice was completed (usually to await availability of a resource).

ru_nivcsw

the number of times a context switch resulted due to a higher priority process
becoming runnable or because the current process exceeded its time slice.

the number of signals delivered.

NOTES

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

gettimeofday(2), wait(2)

BUGS
There is no way to obtain information about a child process which has not yet terminated.

4th Berkeley Distribution

18 July 1983

2

GETSOCKNAME (2)

UNIX Programmer's Manual

GETSOCKNAME ( 2)

NAME

getsockname - get socket name
SYNOPSIS

getsockname(s, name, namelen}
lnt 5;
struct sockaddr -name;
lnt -namelen;
DESCRIPTION

Getsockname returns the current name for the specified socket. The name/en parameter should
be initialized to indicate the amount of space pointed to by name. On return it contains the
actual size of the name returned (in bytes).
DIAGNOSTICS

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

The call succeeds unless:
[EBADF]

The argument s is not a valid descriptor.

[ENOTSOCK]

The argument s is a file, not a socket.

[ENOBUFS]

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

[EF AUL T]

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

SEE ALSO

bind (2), socket (2)
BUGS

Names bound to sockets in the UNIX domain are
length name.

4th Berkeley Distribution

1 April 1983

inaccessible~

getsockname returns a zero

UNIX Programmer's Manual

GETSOCKOPT ( 2 )

GETSOCKOPT ( 2 )

NAME

getsockopt, setsockopt - get and set options on sockets
SYNOPSIS

#include < sys/types.h >
#include 
getsockopt (5, level, optname, optval, optlen)
int s, level, optname;
char .optval;
int .optlen;
setsockopt(s, level, optname, optval, optlen)
int s, level, optname;
char .optval;
int optlen;
DESCRIPTION
Getsockopt and setsockopt manipulate options associated with a socket. Options may exist at mul-

tiple protocollevels~ they are always present at the uppermost Hsocket" level.
When manipulating socket options the level at which the option resides and the name of the
option must be specified. To manipulate options at the Hsocket" level. level is specified as
SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example. to indicate an option is to be
interpreted by the TCP protocol, level should be set to the protocol number of TCP~ see
getprotoent(3N) .

The parameters optval and opt/en are used to access option values for setsockopt. For getsockopt
they identify a buffer in which the value for the requested option (s) are to be returned. For
getsockopt. opt/en is a value-result parameter, initially containing the size of the buffer pointed
to by optval, and modified on return to indicate the actual size of the value returned. If no
option value is to be supplied or returned, optval may be supplied as O.
Optname and any specified options are passed uninterpreted to the appropriate protocol module
for interpretation. The include file < sys/socket.h > contains definitions for "socket" level
options~ see socket (2) . Options at other protocol levels vary in format and name, consult the
appropriate entries in (4P).
RETURN VALUE

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

The call succeeds unless:
[EBADF]
The
[ENOTSOCK]
The
[ENOPROTOOPT] The
[EFAUL T]
The

argument s is not a valid descriptor.
argument s is a file, not a socket.
option is unknown.
options are not in a valid part of the process address space.

SEE ALSO

socket(2), getprotoent(3N)

4th Berkeley Distribution

7 July 1983

GETTIMEOFDA Y (2 )

UNIX Programmer's Manual

GETTIMEOFDA Y ( 2 )

NAME

gettimeofday, settimeofday - getlset date and time
SYNOPSIS

#include < sys/time.h >
gettimeofday  as:

1* seconds since Jan. 1, 1970 *1
1* and microseconds *1

struct timezone {
int
tz_minuteswest~/* of Greenwich *1
int
tz_dsttime~
1* type of dst correction to apply *1
}~
The timezone structure indicates the local time zone (measured in minutes of time westward
from Greenwich), and a flag that, if nonzero, indicates that Daylight Saving time applies locally
during the appropriate part of the year.
Only the super-user may set the time of day.
RETURN

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

The following error codes may be set in errno:
[EFAULT]

An argument address referenced invalid memory.

[EPERM]

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

SEE ALSO

date(I), ctime(3)
BUGS

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

4th Berkeley Distribution

27 July 1983

1

GETUID (2)

UNIX Programmer's Manual

GETUID (2)

NAME

getuid, geteuid - get user identity
SYNOPSIS
uld - Ketuld ()
Int uld;

euld - Keteuld ()
Int euld;
DESCRIPTION
Getuid returns the real user ID of the current process, geteuid the effective user ID.

The real user ID identifies the person who is logged in. The effective user ID gives the process
additional permissions during execution of "set-user-ID" mode processes, which use getuid to
determine the real-user-id of the process which invoked them.
SEE ALSO

getgid (2), setreuid (2)

4th Berkeley Distribution

12 February 1983

IOCTL (2)

UNIX Programmer's Manual

IOCTL (2)

NAME

ioctl - control device
SYNOPSIS

#include < sys/ioctl.h >
ioctl (d, request, argp)
int d, request;
char .argp;
DESCRIPTION

loctl performs a variety of functions on open descriptors. In particular. many operating characteristics of character special files (e.g. terminals) may be controlled with iocrl requests. The
writeups of various devices in section 4 discuss how ioctl applies to them.
An ioctl request has encoded in it whether the argument is an Hin" parameter or Hout" parameter, and the size of the argument argp in bytes. Macros and defines used in specifying an ioctl
request are located in the file < sys/ioetl.h>.
RETURN VALUE

If an error has occurred, a value of -1 is returned and errllo is set to indicate the error.
ERRORS

Joerl will fail if one or more of the following are true:
[EBADF]

D is not a valid descriptor.

[ENOTTY]

D is not associated with a character special device.

[ENOTTY]

The specified request does not apply to the kind of object which the descriptor
d references.

[EINVAL]

Request or argp is not valid.

SEE ALSO

execve(2), fcntI(2). mt(4), tty(4), intro(4N)

4th Berkeley Distribution

7 July 1983

1

KILL (2)

UNIX Programmer's Manual

KILL (2)

NAME

kill - send signal to a process
SYNOPSIS

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

The sending and receiving processes must have the same effective user ID, otherwise this call
is restricted to the super-user. A single exception is the signal SIGCONT which may always be
sent to any child or grandchild of the current process.
If the process number is 0, the signal is sent to all other processes in the sender's process
group; this is a variant of killpg(2).
If the process number is -1, and the user is the super-user, the signal is broadcast universally
except to system processes and the process sending the signal.
Processes may send signals to themselves.
RETURN VALUE
Upon successful completion. a value of 0 is returned. Otherwise, a value of -1 is returned and
errno is set to indicate the error.
ERRORS
Kill will fail and no signal will be sent if any of the following occur:

[EINV AL]

Sig is not a valid signal number.

[ESRCH]

No process can be found corresponding to that specified by pid.

[EPERM]

The sending process is not the super-user and its effective user id does not
match the effective user-id of the receiving process.

SEE ALSO
getpid (2), getpgrp(2), killpg(2), sigved2)

4th Berkeley Distribution

27 July 1983

KILLPG (2)

UNIX Programmer's Manual

KILLPG (2)

NAME

killpg - send signal to a process group
SYNOPSIS

killpg (pgrp, sig)
int pgrp, sig;
DESCRIPTION

Killpg sends the signal sig to the process group pgrp. See sigvec(2) for a list of signals.

The sending process and members of the process group must have the same effective user ID,
otherwise this call is restricted to the super-user. As a single special case the continue signal
SIGCONT may be sent to any process which is a descendant of the current process.
RETURN VALUE

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

Killpg will fail and no signal will be sent if any of the following occur:

[EINV ALl

Sig is not a valid signal number.

[ESRCH)

No process can be found corresponding to that specified by pid.

[EPERM]

The sending process is not the super-user and one or more of the target
processes has an effective user ID different from that of the sending process.

SEE ALSO

kiI1(2), getpgrp(2), sigved2)

4th Berkeley Distribution

27 July 1983

1

LINK (2)

UNIX Programmer's Manual

LINK (2)

NAME

link - make a hard link to a file
SYNOPSIS

link (namel, name2)
char .namel, .name2;
DESCRIPTION

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

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

Link will fail and no link will be created if one or more of the following are true:
[EPERM]

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

[ENOENT]

Either pathname was too long.

[ENOTDIR]

A component of either path prefix is not a directory.

[ENOENT]

A component of either path prefix does not exist.

[EACCES]

A component of either path prefix denies search permission.

[ENOENT]

The file named by name} does not exist.

[EEXIST]

The link named by name2 does exist.

[EPERM]

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

[EXDEV]

The link named by name2 and the file named by name} are on different file
systems.

[EACCES]

The requested link requires writing in a directory with a mode that denies write
permission.

[EROFS]

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

[EFAULT]

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

[ELOOP]

Too many symbolic links were encountered in translating the pathname.

SEE ALSO

symlink(2), unIink(2)

4th Berkeley Distribution

12 February 1983

LISTEN (2)

UNIX Programmer's Manual

LISTEN (2)

NAME

listen - listen for connections on a socket
SYNOPSIS

listen (s, b-.cklog)
lnt s, backlog;
DESCRIPTION

To accept connections, a socket is first created with socket (2) , a backlog for incoming connections is specified with listen(2) and then the connections are accepted with accept(2). The listen
call applies only to sockets of type SOCK_STREAM or SOCK_PKTSTREAM.
The backlog parameter defines the maximum length the queue of pending connections may
grow to. If a connection request arrives with the queue full the client will receive an error wi th
an indication of ECONNREFUSED.
RETURN VALUE

A 0 return value indicates success; -1 indicates an error.
ERRORS

The call fails if:
[EBADF]

The argument s is not a valid descriptor.

[ENOTSOCK]

The argument s is not a socket.

[EOPNOTSUPP]

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

SEE ALSO

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

The backlog is currently limited (silently) to S.

4th Berkeley Distribution

12 February 1983

1

LSEEK (2)

UNIX Programmer's Manual

LSEEK (2)

NAME

lseek - move read/write pointer
SYNOPSIS

#define L_SET
0
#define L_INCR 1
#define L_XTND 2

/- set the seek pointer -/
/- increment the seek pointer -/
/- extend the file size -/

pos == Iseek (d, offset, whence)
Int pos;
lnt d, offset, whence;
DESCRIPTION

The descriptor d refers to a file or device open for reading and/or writing. Lseek sets the file
pointer of d as follows:
If whence is L_SET, the pointer is set to offiet bytes.
If whence is L_INCR, the pointer is set to its current location plus offset.
If whence is L_XTND, the pointer is set to the size of the file plus offiet.
Upon successful completion, the resulting pointer location as measured in bytes from beginning
of the file is returned. Some devices are incapable of seeking. The value of the pointer associated with such a device is undefined.
NOTES
Seekin~ far

beyond the end of a file, then writing, creates a gap or "hole", which occupies no
physical space and reads as zeros.

RETURN VALliE

Upon successful completion, a non-negative integer, the current file pointer value, is returned.
Otherwise, a value of -1 is returned and errno is set to indicate the error.
ERRORS

Lseek will fail and the file pointer will remain unchanged if:
[EBADF]
Fildes is not an open file descriptor.
[ESPIPE]
Fildes is associated with a pipe or a socket.
[EINVAL]
Whence is not a proper value.
[EINVAL]
The resulting file pointer would be negative.
SEE ALSO

dup(2), open (2)
BUGS

This document's use of whence is incorrect English, but maintained for historical reasons.

4th Berkeley Distribution

7 July 1983

MKDIR (2)

UNIX Programmer's Manual

MKDIR (2)

NAME

mkdir - make a directory file
SYNOPSIS

mkdir(path, mode)
char .path;
int mode;
DESCRIPTION
Mkdir creates a new directory file with name path. The mode of the new file is initialized from
mode. (The protection part of the mode is modified by the process's mode mask~ see
umask(2».

The directory's owner ID is set to the process's effective user ID. The directory's group 10 is
set to that of the parent directory in which it is created.
The low-order 9 bits of mode are modified by the process's file mode creation mask: all bits set
in the process's file mode creation mask are cleared. See umask(2).
RETURN VALUE

A 0 return value indicates success. A-I return value indicates an error, and an error code is
stored in errno.
ERRORS
Mkdir will fail and no directory will be created if:

[EPERM]

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

[EPERM]

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

[ENOTDIR]

A component of the path prefix is not a directory.

[ENOENT]

A component of the path prefix does not exist.

[EROFS]

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

[EEXIST]

The named file exists.

[EFAULT}

Path points outside the process's allocated address space.

[ELOOP]

Too many symbolic links were encountered in translating the pathname.

[EIO]

An 110 error occured while writing to the file system.

SEE ALSO

chmod (2), stat (2), umask (2)

4th Berkeley Distribution

27 July 1983

1

UNIX

MKNOD (2)

Programmer~s

Manual

MKNOD (2)

NAME

mknod - make a special file
SYNOPSIS

mknod (path, mode, dev)
char .path;
lnt mode, dev;
DESCRIPTION

Mknod creates a new file whose name is path. The mode of the new file (including special file
bits) is initialized from mode. (The protection part of the mode is modified by the process's
mode mask~ see umask(2». The first block pointer of the i-node is initialized from devand is
used to specify which device the special file refers to.
If mode indicates a block or character special file, dev is a configuration dependent specification
of a character or block 110 device. If mode does not indicate a block special or character special
device, dev is ignored.

Mknod may be invoked only by the super-user.
RETURN VALUE

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

Mknod will fail and the file mode will be unchanged if:
[EPERM]

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

[EPERM]

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

[ENOTDIR]

A component of the path prefix is not a directory.

[ENOENT]

A component of the path prefix does not exist.

[EROFS]

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

[EEXIST]

The named file exists.

[EFAULT]

Path points outside the process's allocated address space.

[ELOOP]

Too many symbolic links were encountered in translating the pathname.

SEE ALSO

chmod(2), 5tat(2), umask(2)

4th Berkeley Distribution

2 July 1983

MOUNT (2)

UNIX Programmer's Manual

MOUNT(2)

NAME

mount, umount - mount or remove file system
SYNOPSIS

mount(special, name, rwflag)
char -special, -name;
int rwflag;
umount (special>
char -special;
DESCRIPTION

Mount announces to the system that a removable file system has been mounted on the blockstructured special file special; from now on. references to file name will refer to the root file on
the newly mounted file system. Special and name are pointers to null-terminated strings containing the appropriate path names.
Name must exist already. Name must be a directory. Its old contents are inaccessible while the
file system is mounted.
The rwflag argument determines whether the file system can be written on~ if it is 0 writing is
allowed, if non-zero no writing is done. Physically write-protected and magnetic tape file systems must be mounted read-only or errors will occur when access times are updated, whether
or not any explicit write is attempted.

Umount announces to the system that the special file is no longer to contain a removable file
system. The associated file reverts to its ordinary interpretation.
RETURN VALUE

Mount returns 0 if the action occurred. -1 if special is inaccessible or not an appropriate file, if
name does not exist, if special is already mounted, if name is in use, or if there are already too
many file systems mounted.

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

Mount will fail when one of the following occurs:
[NODEV]

The caller is not the super-user.

[NODEV]

Special does not exist.
Special is not a block device.

[ENOTBLK]
[ENXIO]

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

[EPERM]

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

[ENOTDIR]

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

[EROFS]
[EBUSY]

Name resides on a read-only file system.
Name is not a directory, or another process currently holds a reference to it.

[EBUSY]

No space remains in the mount table.

[EBUSY]

The super block for the file system had a bad magic number or an out of range
block size.

[EBUSY]

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

[EBUSY]

An i/o error occurred while reading the super block or cylinder group information.

4th Berkeley Distribution

27 July 1983

1

MOUNT (2)

UNIX Programmer's Manual

MOUNT (2)

Umount may fail with one of the following errors:
[NODEV]

The caller is not the super-user;

[NODEV]

Specia I does not exist.

[ENOTBLK]

Special is not a block device.

[ENXIO]

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

[EINVAL]

The requested device is not in the mount table.

[EBUSY]

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

SEE ALSO

mount(8), umount(8)

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

4th Berkeley Distribution

27 July 1983

2

OPEN (2)

UNIX Programmer's Manual

OPEN (2)

NAME

open - open a file for reading or writing, or create a new file
SYNOPSIS

#include < sys/file.h >
open (path, flags, mode)
char .path;
Int flags, mode;
DESCRIPTION

Open opens the file path for reading and/or writing, as specified by the flags argument and
returns a descriptor for that file. The flags argument may indicate the file is to be created if it
does not already exist (by specifying the 0_CREAT flag), in which case the file is created with
mode mode as described in chmod(2) and modified by the process' umask value (see
umask(2».
Path is the address of a string of ASCII characters representing a path name, terminated by a
null character. The flags specified are formed by oring the following values
O_RDONLY open for reading only
0_WRONL Y open for writing only
O_RDWR
open for reading and writing
O_NDELAY do not block on open
O_APPEND append on each write
0_CREA T
create file if it does not exist
O_TRUNC
truncate size to 0
_EXCL
error if create and file exists
Opening a file with O_APPEND set causes each write on the file to be appended to the end. If
O_TRUNC is specified and the file exists, the file is truncated to zero length. If O_EXCL is sel
with 0_CREAT, then if the file already exists. the open returns an error. This can be used to
implement a simple exclusive access locking mechanism. If the O_NDELA Y flag is specified
and the open call would result in the process being blocked for some reason (e.g. waiting for
carrier on a dialup line), the open returns immediately. The first time the process attempts to
perform i/o on the open file it will block (not currently implemented).
Upon successful completion a non-negative integer termed a file descriptor is returned. The file
pointer used to mark the current position within the file is set to the beginning of the file.
The new descriptor is set to remain open across execve system calls~ see c/ose(2).
No process may have more than {OPEN_MAX} file descriptors open simultaneously.

°

ERRORS

The named file
[EPERM1
[ENOTDIR1
[ENOENT1
[EACCES]
[EACCES]
[EISDIR1
[EROFS]

is opened unless one or more of the following are true:
The pathname contains a character with the high-order bit set.
A component of the path prefix is not a directory.
0_CREAT is not set and the named file does not exist.
A component of the path prefix denies search permission.
The required permissions (for reading and/or writing) are denied for the
named flag.
The named file is a directory, and the arguments specify it is to be opened for
writting.
The named file resides on a read-only file system, and the file is to be
modified.

4th Berkeley Distribution

2 July 1983

1

UNIX Programmer's Manual

OPEN (2)

OPEN (2)

[EMFILE]

{OPEN_MAX} file descriptors are currently open.

[ENXIO]

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

[ETXTBSY]

The file is a pure procedure (shared text) file that is being executed and the
open call requests write access.

[EFAULT]

Path points outside the process's allocated address space.

[ELOOP]

Too many symbolic links were encountered in translating the pathname.

[EEXIST]

o_EXCL was specified and the file exists.

[ENXIO]

The O_NDELA Y flag is given, and the file is a communications device on
which their is no carrier present.

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

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

4th Berkeley Distribution

2 July 1983

2

PIPE (2)

UNIX Programmer's Manual

PIPE (2)

NAME

pipe - create an interprocess communication channel
SYNOPSIS

plpe(flldes)
lnt flldeslll;
DESCRIPTION

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

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

The pipe call· will fail if:
[EMFILE]

Too many descriptors are active.

[EFAULT]

The fi/des buffer is in an invalid area of the process's address space.

SEE ALSO

shU), read(2), write(2), fork(2), socketpair(2)
BUGS

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

4th Berkeley Distribution

12 February 1983

1

PROFIL (2)

UNIX Programmer's Manual

PROFIL (2 )

NAME

profil - execution time profile
SYNOPSIS

profil (buff, bufsiz, offset, scale)
char -buff;
int bufsiz, offset, scale;
DESCRIPTION

BL{ffpoints to an area of core whose length (in bytes) is given by bUfsi:. After this call, the
user's program counter (pC> is examined each clock tick (IO milliseconds) ~ o.llset is subtracted
from it, and the result multiplied by scale. If the resulting number corresponds to a word
inside buff, that word is incremented.

The scale is interpreted as an unsigned. fixed-point fraction with binary point at the left:
OxIOOOO gives a 1-1 mapping of pc's to words in buff; Ox8000 maps each pair of instruction
words together. Ox2 maps all instructions onto the beginning of bL{ff (producing a noninterrupting core clock).
Profiling is turned off by giving a scale of 0 or 1. It is rendered ineffective by giving a bl(/si: of
O. Profiling is turned off when an execve is executed, but remains on in child and parent both
after a fork. Profiling is turned off if an update in bl(irwould cause a memory fault.
RETURN VALVE

A 0, indicating success, is always returned.
SEE ALSO

gprof(I), setitimed2), monitod3)

4th Berkeley Distribution

12 February 1983

PTRACE (2)

UNIX Programmer's Manual

PTRACE

(2)

NAME

ptrace - process trace
SYNOPSIS

#ioclude

< sigoal.h>

ptrace(request, pid, addr, data)
iot request, pid, *addr, data;
DESCRIPTION
Ptrace provides a means by which a parent process may control the execution of a child process,

and examine and change its core image. Its primary use is for the implementation of breakpoint debugging. There are four arguments whose interpretation depends on a request argument. Generally, pid is the process ID of the traced process, which must be a child (no more
distant descendant) of the tracing process. A process being traced behaves normally until it
encounters some signal whether internally generated like "illegal instruction" or externally generated like "interrupt". See sigl!ed2) for the list. Then the traced process enters a stopped
state and its parent is notified via wait(2). When the child is in the stopped state. its core
image can be examined and modified using ptrace. If desired, another ptrace request can then
cause the child either to terminate or to continue, possibly ignoring the signal.
The value of the request argument determines the precise action of the call:

o

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

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

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

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

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

7

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

8

The traced process terminates.

9

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

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

4th Berkeley Distribution

2 July 1983

PTRACE (2)

PTRACE (2)

UNIX Programmer's Manual

To forestall possible fraud, ptrace inhibits the set-user-id and set-group-id facilities on subsequent execve(2) calls. If a traced process calls execve, it will stop before executing the first
instruction of the new image showing signal SIGTRAP.
On a VAX-ll, "word" also means a 32-bit integer, but the '"even" restriction does not apply.
RETURN VALUE

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

[EINVAL]

The request code is invalid.

[EINVAL]

The specified process does not exist.

[EINVAL]

The given signal number is invalid.

[EFAULT]

The specified address is out of bounds.

[EPERM]

The specified process cannot be traced.

SEE ALSO

wait(2), sigved2), adb(l)
BUGS

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

value~ errl1o.

It should be possible to stop a process on occurrence of a system
controlled environment could be provided.

4th Berkeley Distribution

2 July 1983

see ;/lfro(2), can be used to
call~

in this way a completely

2

QUOTA (2)

UNIX Programmer's Manual

QUOTA

(2)

NAME

Quota - manipulate disk Quotas
SYNOPSIS

#include < sys/quota.h>
quota (cmd, uid, arg, addr)
int cmd, uid, arg;
caddr_t addr:
DESCRIPTION
The quota call manipulates disk Quotas for file systems which have had Quotas enabled with selquota(2). The cmd parameter indicates a command to be applied to the user 10 uid. A,g is a
command specific argument and addr is the address of an optional, command specific, data
structure which is copied in or out of the system. The interpretation of arg and add, is given

with each command below.
Q_SETOLIM
Set disc quota limits and current usage for the user with 10 uid. Arg is a major-minor
device indicating a particular file system. Addr is a pointer to a struct dqblk structure
(defined in < syslquota.h>). This caIl is restricted to the super-user.
Q_GETOLIM
Get disc quota limits and current usage for the user with ID llid. The remaining
parameters are as for Q_SETOLIM.
Q_SETOUSE
Set disc usage limits for the user with ID llid. A,g is a major-minor device indicating a
particular file system. Add, is a pointer to a struct dqusage structure (defined in
< syslquota.h> >. This call is restricted to the super-user.
Q_SYNC
Update the on-disc copy of quota usages. The uid, arg, and addr parameters are
ignored.
Q_SETUID
Change the calling process's quota limits to those of the user with 10 llid. The arg and
addr parameters are ignored. This call is restricted to the super-user.
Q_SETWARN
Alter the disc usage warning limits for the user with 10 uid. Arg is a major-minor device indicating a particular file system. Addr is a pointer to a struct dqwarn structure
(defined in < syslquota.h». This call is restricted to the super-user.
Q_DOWARN
Warn the user with user ID uid about excessive disc usage. This call causes the system
to check its current disc usage information and print a message on the terminal of the
caller for each file system on which the user is over quota. If the arg parameter is
specified as NODEV, all file systems which have disc quotas will be checked. Otherwise, arg indicates a specific major-minor device to be checked. This call is restricted to
the super-user.
RETURN VALlJE

A successful call returns 0 and, possibly, more information specific to the cmdperformed: when
an error occurs, the value -1 is returned and errllo is set to indicate the reason.
ERRORS

A quota call will fail when one of the following occurs:
[EINV AL]
Cmd is invalid.

4th Berkeley Distribution

7 July 1983

QUOTA (2)

UNIX Programmer's Manual

QUOTA (2)

[ESRCH]

No disc quota is found for the indicated user.

[EPERM]

The call is priviledged and the caller was not the super-user.

[EINVAL]

The arg parameter is being interpreted as a major-minor device and it indicates
an unmounted file system.

[EFAULT]

An invalid addr is
out of the kernel.

[EUSERS]

The quota table is full.

supplied~

the associated structure could not be copied in or

SEE ALSO
setquota(2), quotaon(8), quotacheck(8)

BUGS
There should be someway to integrate this call with the resource limit interface provided by
setrlimit(2) and getrlimit(2).
The Australian spelling of disk is used throughout the quota facilities in honor of the implementors.

4th Berkeley Distribution

7 July 1983

2

READ (2)

UNIX

Programmer~s

Manual

READ.C 2)

NAME

read, readv - read input
SYNOPSIS

cc = read (d, buf, nbytes)
int cc, d:
char -bur;
int nbytes;

#indude < sys/types.h>
#indude < sys/uio.h>
cc = readv (d, iov, iovcnt>
int cc, d:
struct iovec - iov;
int iovcnt;
DESCRIPTION

Read attempts to read nbytes of data from the object referenced by the descriptor d into the
buffer pointed to by bu! Readv performs the same action. but scatters the input data into the
iovcntbuffers specified by the members of the iovecarray: iovlOL iov{IL ... , iov[iovcnt - 11.
For readv, the

io~'ec structure

is defined as

struct iovec {
caddr _t iov _base~
int
iov Jen~
}~

Each iOl'ec entry specifies the base address and length of an area in memory where data should
be placed. Readv will always fill an area completely before proceeding to the next.
On objects capable of seeking. the read starts at a position given by the pointer associated with
d. see /seek<2>' Upon return from read. the pointer is incremented by the number of bytes
actually read.
Objects that are not capable of seeking always read from the current position. The value of the
pointer associated with such a object is undefined.
Upon successful completion, read and readv return the number of bytes actually read and placed
in the buffer. The system guarantees to read the number of bytes requested if the descriptor
references a file which has that many bytes left before the end-of-file. but in no other cases.
If the returned value is 0, then end-of-file has been reached.
RETURN VALUE

If successful, the number of bytes actually read is returned. Otherwise, a -1 is returned and
the global variable errno is set to indicate the error.
ERRORS

Readand readv will fail if one or more of the following are true:
[EBADF]
[EFAULT]
[EINTR]

Fildes is not a valid file descriptor open for reading.
Bu/points outside the allocated address space.
A read from a slow device was interrupted before any data arrived by the
delivery of a signal.

In addition, readv may return one of the following errors:
[EINVAL]
lovcntwas less than or equal to 0, or greater than 16.
[EINVAL]
One of the iov_lell values in the iovarray was negative.

4th Berkeley Distribution

27 July 1983

READ(2)

[EINVAL]

UNIX Programmer's Manual

READ

(2)

The sum of the im,-'ell values in the iovarray overflowed a 32-bit integer.

SEE >\LSO

dup(2), open(2), pipe(2). socket(2). socketpaid2)

4th Berkeley Distribution

27 July 1983

2

READLINK ( 2 )

UNIX Programmer's Manual

READLINK ( 2 )

NAME

readlink - read value of a symbolic link
SYNOPSIS
cc == readlink (path, buf, bufsiz)
int cc;
char -path, -buf;
int bufsiz;
DESCRIPTION
Readlink places the contents of the symbolic link name in the buffer bl{fwhich has size bl{/'si:.
The contents of the link are not null terminated when returned.

RETURN VALUE

The call returns the count of characters placed in the buffer if it succeeds. or a -I if an error
occurs, placing the error code in the global variable errllo.
ERRORS
Readlillk will fail and the file mode will be unchanged if:

[EPERM]

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

[ENOENT]
[ENOTOIR]

The pathname was too long.

[ENOENT]

The named file does not exist.

[ENXIO]

The named file is not a symbolic link.

[EACCES]

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

[EPERM]

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

[EINVAL]

The named file is not a symbolic link.

[EFAULT]

Bl{fextends outside the process's allocated address space.

[ELOOP]

Too many symbolic links were encountered in translating the pathname.

A component of the path prefix is not a directory.

SEE ALSO

stat (2), Istat(2), symlink (2)

4th Berkeley Distribution

2 July 1983

REBOOT (2)

UNIX Programmer's Manual

REBOOT(2)

NAME

reboot - reboot system or halt processor
SYNOPSIS

#include

< sys/reboot.h>

reboot (howto)
int howto;
DESCRIPTION

Reboot reboots the system, and is invoked automatically in the event of unrecoverable system
failures. Howto is a mask of options passed to the bootstrap program. The system call interface
permits only RB_HAL T or RB_AUTOBOOT to be passed to the reboot program: the other flags
are used in scripts stored on the console storage media, or used in manual bootstrap procedures. When none of these options (e.g. RB_AUTOBOOT) is given, the system is rebooted
from file Hvmunix" in the root file system of unit 0 of a disk chosen in a processor specific
way. An automatic consistency check of the disks is then normally performed.
The bits of howlO are:
RB HALT
the processor is simply halted: no reboot takes place. RB_HAL T should be used with
caution.
RB_ASKNAME
Interpreted by the bootstrap program itself. causing it to inquire as to what file should
be booted. Normally, the system is booted from the file "xx(O.O)vmunix" without
asking.
RB_SINGLE
Normally. the reboot procedure involves an automatic disk consistency check and then
multi-user operations. RB_SINGLE prevents the consistency check, rather simply
booting the system with a single-user shell on the console. RB_SINGLE is interpreted
by the illit(8) program in the newly booted system. This switch is not available from
the system call interface.
Only the super-user may reboot a machine.
RETllRN VALUES

If successful, this call never returns. Otherwise, a -1 is returned and an error is returned in
the global variable errllo.
ERRORS

[EPERM]

The caller is not the super-user.

SEE ALSO

crash(8), halt(S), init(8). reboot(8)
BUGS

The notion of "console medium", among other things, is specific to the VAX.

4th Berkeley Distribution

18 July 1983

RECV (2)

UNIX Programmer's Manual

RECV (2)

NAME

recv. recvfrom. recvrnsg - receive a message from a socket
SYNOPSIS

# j nelude
#inelude

< sy sl types. h>
< sys/socket.h>

cc= reCl' (s, buf, len, flags)
int cc. s;
char -buf;
int len. flags;
cc = recvfrom(s, buf, len, flags, from, fromlen}
int cc, s:
char -buf:
int len, flags;
struct sockaddr -from;
int -fromlen:
cc = recvmsg (s, msg, flags)
int cc, s:
struct msghdr msglJ;
int flags:
DESCRIPTION

Ren'. recvfrom. and recvmsg are used to receive messages from a socket.
The recv call may be used only on a cOl1l1ected socket (see c0I111ect(2» , while ren:!;om and
recvmsg may be used to receive data on a socket whether it is in a connected state or not.
If f;om is non-zero, the source address of the message is filled in. Fromlell is a value-result
parameter, initialized to the size of the butTer associated with from. and modified on return to
indicate the actual size of the address stored there, The length of the message is returned in ('('.
If a message is too long to fit in the supplied butTer. excess bytes may be discarded depending
on the type of socket the message is received from~ see socker(2 >.
If no messages are available at the socket. the receive call waits for a message to arrive, unless
the socket is nonblocking (see ;octl(2» in which case a cc of -I is returned with the external
variable errno set to EWOULDBLOCK.
The select(2) call may be used to determine when more data arrives,
The ,/fags argument to a send call is formed by or'ing one or more of the values.
#defineMSG_PEEK
Oxl
/. peek at incoming message ./
#defineMSG_OOB
Ox2
/. process out-of-band data ./
The recvmsg call uses a msghdr structure to "minimize the number of directly supplied
ters. This structure has the following form, as defined in < syS/socker. h> :
struct msghdr {
caddr_t msg_name~
/. optional address ./
int
msg_namelen~
/. size of address ./
struct iov ·msgjov~
/. scatter/gather array ./
int
msg_iovlen~
/. # elements in msgjov ./
caddr_t msg_accrights~
/. access rights sent/received ./
int
msg_accrightslen~
}~

4th Berkeley Distribution

7 July 1983

p~rame­

RECV (2)

UNIX Programmer's Manual

RECV

(2)

Here msg name and msg name/en specify the destination address if the socket is unconnected:
msg name may be given as a null pointer if no names are desired or required. The msg im' and
msg- iov/en describe the scatter gather locations. as described in read(2)' Access rights to be
sentalong with the message are specified in msg_QccrigJus. which has length msg_accriglllslell.
RETURN VALUE

These calls return the number of bytes received, or - 1 if an error occurred.
ERRORS

The calls fail if:
[EBADF]

The argument s is an invalid descriptor.

[ENOTSOCK]

The argument s is not a socket.

[EWOULDBLOCK]

The socket is marked non-blocking and the receive operation would
block.

[EINTR]

The receive was interrupted by delivery of a signal before any data was
available for the receive.

[EFAULT]

The data was specified to be received into a non-existent or protected
part of the process address space.

SEE ALSO

read(2). send(2), socket(2)

4th Berkeley Distribution

7 July 1983

2

RENAME (2)

UNIX Programmer's Manual

RENAME (2)

NAME

rename - change the name of a file
SYNOPSIS

rename (from, to)
char ·from, • to;
DESCRIPTION

Rename causes the link named j;om to be renamed as to. If to exists, then it is first removed.
Both /rom and to must be of the same type 

nfound - select (nfds, readfds, wrltefds, execptfds, timeout)
lnt nfound, nfds, .re.dfds, .wrltefds, .execptfds;
strud tlmeval .tlmeout;
DESCRIPTION

Select examines the i/o descriptors specified by the bit masks reaq[ds, write/ds, and execptfds to
see if they are ready for reading, writing, or have an exceptional condition pending, respectively. File descriptor / is represented by the bit "1 < 
#include 
cc == send (s, msg, len, flags)
int cc, s;
char .msg;
int len, flags;
cc == sendto(s, msg, len, flags, to, tolen)
int cc, s;
char .msg;
int len, flags;
struct sockaddr -to;
int tolen;
cc == sendmsg (s, msg, flags)
int cc, s;
struct msghdr msgll;
int flags;
DESCRIPTION

Send, sendro, and sendmsg are used to transmit a message to another socket. Send may be used
only when the socket is in a connected state, while sendto and sendmsg may be used at any time.
The address of the target is given by to with tolen specifying its size. The length of the message
is given by len. If the message is too long to pass atomically through the underlying protocol.
then the error EMSGSIZE is returned, and the message is not transmitted.
No indication of failure to deliver is implicit in a send. Return values of -1 indicate some
locally detected errors.
If no messages space is available at the socket to hold the message to be transmitted. then send
normally blocks, unless the socket has been placed in non-blocking i/o mode. The select(2) call
may be used to determine when it is possible to send more data.
The flags parameter may be set to SOF_OOB to send "out-of-band" data on sockets which support this notion (e.g. SOCK_STREAM).
See recv(2) for a description of the msghdr structure.
RETURN VALUE

The call returns the number of characters sent, or -1 if an error occurred.
ERRORS

[EBADF]

An invalid descriptor was specified.

[ENOTSOCK]

The argument s is not a socket.

[EFAUL T]

An invalid user space address was specified for a parameter.

[EMSGSIZE]

The socket requires that message be sent atomically, and the size of the
message to be sent made this impossible.

[EWOULDBLOCK]

The socket is marked non-blocking and the requested operation would
block.

SEE ALSO

recv(2), socket(2)

4th Berkeley Distribution

20 September 1983

SETG ROUPS ( 2 )

UNIX Programmer's Manual

SETGROUPS ( 2 )

NAME

setgroups - set group access list
SYNOPSIS

#include < sys/param.h>
setgroups(ngroups, gidset>
int ngroups, .gidset;
DESCRIPTION

Setgroups sets the group access list of the current user process according to the array gidsel. The
parameter ngroups indicates the number of entries in the array and must be no more than
NGRPS, as defined in < syslparam.h>.
Only the super-user may set new groups.
RETVRN VALUE

A 0 value is returned on success, -Ion error, with a error code stored in nnw.
ERRORS

The setgroups call will fail if:
[EPERM]
The caller is not the super-user.
[EFAULT]
The address specified for gidset is outside the process address space.
SEE ALSO

getgroups(2), initgroups(3X)

4th Berkeley Distribution

7 July 1983

SETPGRP (2)

UNIX Programmer's Manual

SETPGRP (2)

NAME

setpgrp - set process group
SYNOPSIS

setpgrp(pid, pgrp)
iot pid, pgrp;
DESCRIPTION
Setpgrp sets the process group of the specified process pid to the specified pgrp. If pid is zero,
then the call applies to the current process.

If the invoker is not the super-user, then the affected process must have the same effective
user-id as the invoker or be a descendant of the invoking process.
RETURN VALUE
Setpgrp returns when the operation was successful. If the request failed, -1 is returned and the
global variable errllo indicates the reason.

ERRORS
Setpgrp will

fail and the process group will not be altered if one of the following occur:

[ESRCH]

The requested process does not exist.

[EPERM]

The effective user ID of the requested process is different from that of the
caller and the process is not a descendent of the calling process.

SEE ALSO

getpgrp(2)

4th Berkeley Distribution

12 February 1983

SETQUOT A (2 )

UNIX Programmer's Manual

SETQUOT A ( 2 )

NAME

setquota - enable/disable quotas on a file system
SYNOPSIS

setquota (special, file)
char ·special, -file;
DESCRIPTION

Disc quotas are enabled or disabled with the setquota call. Special indicates a block special device on which a mounted file system exists. If .tile is nonzero. it specifies a file in that file system
from which to take the quotas. If .tile is 0, then quotas are disabled on the file system. The
quota file must exist~ it is normally created with the chec:kquota(S) program.
Only the super-user may turn quotas on or off.
SEE ALSO

quota(2), quotacheck(S). quotaon(S)
RETURN VALUE

A 0 return value indicates a successful call. A value of -I is returned when an error occurs
and errllo is set to indicate the reason for failure.
ERRORS
Setquota

will fail when one of the following occurs:

[NODEV]

The caller is not the super-user.

[NODEV]
[ENOTBLK]

Special does
Special is

not exist.

not a block device.

[ENXIO]

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

[EPERM1

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

[ENOTDIR1
[EROFS]

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

resides on a read-only file system.

[EACCES1

File

resides on a file system different from special.

[EACCES]

File is not a plain file.

BUGS

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

4th Berkeley Distribution

7 July 1983

SETREGIO (2)

UNIX Programmer's Manual

SETREGIO ( 2 )

NAME

setregid - set real and effective group 10
SYNOPSIS

setregld SJ

SIGPAUSE (2 )

UNIX Programmer's Manual

SIGPAUSE (2 )

NAME

sigpause - atomically release blocked signals and wait for interrupt
SYNOPSIS

sigpause(sigmask)
int sigmask;
DESCRIPTION
Sigpause assigns sigmask to the set of masked signals and then waits for a signal to arrive~ on
return the set of masked signals is restored. Sigmask is usually 0 to indicate that no signals are
now to be blocked. Sigpause always terminates by being interrupted, returning EINTR.

In normal usage, a signal is blocked using sigblock(2) , to begin a critical section, variables
modified on the occurance of the signal are examined to determine that there is no work to be
done, and the process pauses awaiting work by using sigpause with the mask returned by sigblock.
SEE ALSO

sigblock (2), sigve(2)

4th Berkeley Distribution

7 July 1983

SIGSETMASK ( 2 )

UNIX

Programmer~s

Manual

SIGSETM ASK ( 2 )

NAME

sigsetmask - set current signal mask
SYNOPSIS

sigsetmask (mask);
int mask;
DESCRIPTION

Sigsetmask sets the current signal mask 

struct sigstack (
caddr_t ss_sp;
int
ss_onstack;
};
sigstack (ss, oss);
struct sigstack ·SS, ·OSs;
DESCRIPTION
Sigsfack allows users to define an alternate stack on which signals are to be processed. If ss is
non-zero. it specifies a sigllal stack on which to deliver signals and tells the system if the process
is currently executing on that stack. When a signal's action indicates its handler should execute
on the signal stack (specified with a sigved2) calJ), the system checks to see if the process is
currently executing on that stack. If the process is not currently executing on the signal stack.
the system arranges a switch to the signal stack for the duration of the signal handler's execution. If oss is non-zero. the current signal stack state is returned.

NOTES

Signal stacks are not "grown" automatically. as is done for the normal stack.
overflows unpredictable results may occur.

If the stack

RETlJRN VALtlE
Upon successful completion, a value of 0 is returned. Otherwise, a value of - 1 is returned and
errno is set to indicate the error.
ERRORS
Sigsfack will fail and the signal stack context will remain unchanged if one of the following

occurs.
[EFAULT)

Either ss or oss points to memory which is not a valid part of the process
address space.

SEE ALSO
sigve(2). setjmp (3)

4th Berkeley Distribution

15 June 1983

SIGVEC (2)

SIGVIC (2)

UNIX Programmer's Manual

NAME
sigvec - software signal facilities
SYNOPSIS

#Include 
struct sllvee (
(*sv_handler) () ;
Int
Int
sv_mask;
Int
sv_oDstaek;

);
sllvec (511, vee, ovee)
Int sll;
struct silVec *vee, *ovec;
DESCRIPTION

The system defines a set of signals that may be delivered to a process. Signal delivery resembles the occurence of a hardware interrupt: the signal is blocked from further occurrence, the
current process context is saved, and a new one is built. A process may specify a handler to
which a signal is delivered, or specify that a signal is to be blocked or ignored. A process may
also specify that a default action is to be taken by the system when a signal occurs. Normally,
signal handlers execute on the current stack of the process. This may be changed, on a perhandler basis, so that signals are taken on a special signal stack.
All signals have the same priority. Signal routines execute with the signal that caused their
invocation blocked, but other signals may yet occur. A global signal mask defines the set of signals currently blocked from delivery to a process. The signal mask for a process is initilized
from that of its parent (normally 0). It may be changed with a sigblock(2) or sigsetmask(2) call,
or when a signal is delivered to the process.
When a signal condition arises for a process, the signal is added to a set of signals pending for
the process. If the signal is not currently blocked by the process then it is delivered to the process. When a signal is delivered, the current state of the process is saved, a new signal mask is
calculated (as described below), and the signal handler is invoked. The call to the handler is
arranged so that if the signal handling routine returns normally the process will resume execution in the context from before the signal's delivery. If the process Wishes to resume in a
different context, then it must arrange to restore the previous context itself.
When a signal is delivered to a process a new signal mask is installed for the duration of the
process' signal handler (or until a sigblock or sigsetmask call is made). This mask is formed by
taking the current signal mask, adding the signal to be delivered, and or'ing in the signal mask
associated with the handler to be invoked.

Sigvec assigns a handler for a specific signal. If vec is non-zero, it specifies a handler routine
and mask to be used when delivering the specified signal. Further, if sv...onstack is 1, the system will deliver the signal to the process on a signal stack, specified with sigstack(2). If ovec is
non-zero, the previous handling information for the signal is returned to the user.
The following is a list of all signals with names as in the include file
SIGHUP
SIGINT
SIOQUIT
SIGILL
SIGTRAP
SIGIOT
SIGEMT
SIGFPE

1

2
3.
4.
5.
6.
7.
8.

4th Berkeley Distribution

< signal. h >:

hangup
interrupt
quit
illegal instruction
trace trap
lOT instruction
EMT instruction
floating point exception

7 July 1983

1

SIOVEC (2)

SIGKILL
SIOBUS
SIGSEGV
SIGSYS
SIGPIPE
SIGALRM
SIGTERM
SIGURG
SIGSTOP
SIGTSTP
SIGCONT
SIGCHLD
SIGTTIN
SIGTTOU
SIGIO
SIGXCPU
SIGXFSZ
SIGVT ALRM
SIGPROF

UNIX Programmer's Manual

9
10.
11.
12.
13
14
15
1617t
18t
192021 t
22t
2324
25
26
27

SIGVEC (2)

kill (cannot be caught, blocked, or ignored)
bus error
segmentation violation
bad argument to system call
write on a pipe with no one to read it
alarm clock
software termination signal
urgent condition present on socket
stop (cannot be caught, blocked, or ignored)
stop signal generated from keyboard
continue after stop (cannot be blocked)
child status has changed
background read attempted from control terminal
background write attempted to control terminal
i/o is possible on a descriptor (see fcnt/(2»
cpu time limit exceeded (see setrlimit(2»
file size limit exceeded (see setrlimit(2»
virtual time alarm (see setitimer(2»)
profiling timer alarm (see setitimer(2»

The starred signals in the list above cause a core image if not caught or ignored.
Once a signal handler is installed, it remains installed until another sigvec call is made, or an
exeeve(2) is performed. The default action for a signal may be reinstated by setting sv_handler
to SIG_DFL; this default is termination (with a core image for starred signals) except for signals marked with - or t. Signals marked with - are discarded if the action is SIG_DFL; signals
marked with t cause the process to stop. If sv_handler is SIG_IGN the signal is subsequently
ignored, and pending instances of the signal are discarded.
If a caught signal occurs during certain system calls, causing the call to terminate prematurely,
the call is automatically restarted. In particular this can occur during a read or write(2) on a
slow device (such as a terminal; but not a file) and during a wait(2).
After a !ork(2) or vfork(2) the child inherits all signals, the signal mask, and the signal stack.

Exeeve(2) resets all caught signals to default action; ignored signals remain ignored; the signal
mask remains the same; the signal stack state is reset.
NOTES

The mask specified in vee is not allowed to block SIGKILL, SIGSTOP, or SIGCONT. This is
done silently by the system.
RETURN VALUE

A 0 value indicated that the call succeeded. A -1 return value indicates an error occured and
errno is set to indicated the reason.
ERRORS

Sigvec will fail and no new signal handler will be installed if one of the following occurs:
[EFAULT]
Either vee or ovee points to memory which is not a valid part of the process
address space.
[EINVAL]
Sig is not a valid signal number.
[EiNVAL]
An attempt is made to ignore or supply a handler for SIGKILL or SIGSTOP.
[EINVAL]
An attempt is made to ignore SIGCONT (by default SIGCONT is ignored).
SEE ALSO

kill(l) , ptrace(2) , ki11(2) , sigblock(2) , sigsetmask(2) , sigpause(2) sigstack(2) , sigved2),
setjmp(3), tty(4)

4th Berkeley Distribution

7 July 1983

2

SIGVEC (2)

UNIX Programmer's Manual

SIGVEC (2)

NOTES (VAX·H)
The handler routine can be declared:

handler(sig, code, scp)
int sig, code;
struct sigcontext .scp;
Here sig is the signal number, into which the hardware faults and traps are mapped as defined
below. Code is a parameter which is either a constant as given below or, for compatibility mode
faults, the code provided by the hardware (Compatibility mode faults are distinguished from the
other SIGILL traps by having PSL_CM set in the psI). Scp is a pointer to the sigconlexl structure (defined in < signal.h », used to restore the context from before the signal.
The following defines the mapping of hardware traps to signals and codes. All of these symbols
are defined in < signal.h >:
Hardware condition

Signal

Arithmetic traps:
SIGFPE
Integer overflow
SIGFPE
Integer division by zero
Floating overflow trap
SIGFPE
Floating/decimal division by zero SIGFPE
Floating underflow trap
SIGFPE
SIGFPE
Decimal overflow trap
SIGFPE
Subscript-range
Floating overflow fault
SIGFPE
Floating divide by zero fault
SIGFPE
Floating underflow fault
SIGFPE
SIGSEGV
Length access control
SIGBUS
Protection violation
SIGILL
Reserved instruction
Customer-reserved instr.
SIGEMT
SIGILL
Reserved operand
SIGILL
Reserved addressing
Trace pending
SIGTRAP
Bpt instruction
SIGTRAP
Compatibility-mode
SIGILL
SIGSEGV
Chme
SIGSEGV
Chms
SIGSEGV
Chmu

Code
FPE_INTOVF_TRAP
FPE_INTDIV_TRAP
FPE_FLTOVF_TRAP
FPE_FLTDIV_TRAP
FPE_FLTUND_TRAP
FPE_DECOVF_TRAP
FPE_SUBRNG_TRAP
FPE_FLTOVF_FAULT
FPE_FLTDIV_FAULT
FPE_FLTUND_FAULT
ILL_RESAD_FAULT
ILL_PRIVIN_FAULT
ILL_RESOP_FAULT
hardware supplied code

BUGS
This manual page is confusing.

4th Berkeley Distribution

7 July 1983

3

SOCKET (2)

UNIX Programmer's Manual

SOCKET (2)

NAME

socket - create an endpoint for communication
SYNOPSIS

#include < sys/types.h>
#include < sys/socket.h>
s = socket. The currently understood formats are
AF UNIX
(UNIX path names),
AF INET
(ARPA Internet addresses),
AF PUP
(Xerox PUP-I Internet addresses), and
(IMP "host at IMP" addresses).
AFJMPLINK
The socket has the indicated type which specifies the semantics of communication. Currently
defined types are:
SOCK STREAM
SOCK_OGRAM
SOCK RAW
SOCK_SEQPACKET
SOCK ROM
A SOCK_STREAM type provides sequenced, reliabl\;!, two-way connection based byte streams
with an out-of-band data transmission mechanism. A SOCK OGRAM socket supports
datagrams (connection less, unreliable messages of a fixed (typicaliy small) maximum length>.
SOCK_RAW sockets provide access to internal network interfaces. The types SOCK_RAW.
which is available only to the super-user, and SOCK_SEQPACKET and SOCK_ROM. which
are planned, but not yet implemented, are not described here.
The protocol specifies a particular protocol to be used with the socket. Normally only a single
protocol exists to support a particular socket type using a given address format. However. it is
possible that many protocols may exist in which case a particular protocol must be specified in
this manner. The protocol number to use is particular to the "communication domain" in
which communication is to take place~ see ser vices (3 N) and prolocols(3 N >.
Sockets of type SOCK_STREAM are full-duplex byte streams, similar to pipes. A stream
socket must be in a connected state before any data may be sent or received on it. A connection
to another socket is created with a cOlll1ecr(2) call. Once connected, data may be transferred
using read(2) and write(2) calls or some variant of the send(2) and recl'(2) calls. When a session has ,been completed a c1ose(2) may be performed. Out-of-band data may also be transmitted as described in send(2) and received as described in ren'(2).
The communications protocols used to implement a SOCK_STREAM insure that data is not
lost or duplicated. If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time. then the connection is considered broken and calls will indicate an error with -1 returns and with ETIMEOOUT as the specific code
in the global variable errno. The protocols optionally keep sockets "warm" by forcing
transmissions roughly every minute in the absence of other activity. An error is then indicated
if no response can be elicited on an otherwise idle connection for a extended period (e.g. 5
minutes). A SIGPIPE signal is raised if a process sends on a broken stream~ this causes naive

4th Berkeley Distribution

18 July 1983

SOCKET (2)

UNIX Programmer's Manual

SOCKET (2)

processes. which do not handle the signal. to exit.
SOCK DGRAM and SOCK RAW sockets allow sending of datagrams to correspondents named
in send(2) calls. It is also possible to receive datagrams at such a socket with recl'(2).
An !cnt/(2) call can be used to specify a process group to receive a SIGURG signal when the
out-of-band data arrives.
The operation of sockets is controlled by socket level options. These options are defined in the
file < syslsocket.h> and explained below. Setsockopr and getsockopr(2) are used to set and get
options. respectively.
SO DEBUG
SO REUSEADDR
SO KEEPALIVE
SO_DONTROUTE
SO_LINGER
SO_DONTLINGER

turn on recording of debugging information
allow local address reuse
keep connections alive
do no apply routing on outgoing messages
linger on close if data present
do not linger on close

SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR indicates the rules used in validating addresses supplied in a billd(2) call should allow reuse of local
addresses. SO _KEEPALIVE enables the periodic transmission of messages on a connected
socket. Should the connected party fail to respond to these messages. the connection is considered broken and processes using the socket are notified via a SIGPIPE signal.
SO _DONTROUTE indicates that outgoing messages should bypass the standard routing facilities. Instead. messages are directed to the appropriate network interface according to the network portion of the destination address. SO LINGER and SO DONTLINGER control the
actions taken when unsent messags are queued on socket and a ;/ose(2) is performed. If the
socket promises reliable delivery of data and SO_LINGER is set. the system will block the process on the close attempt until it is able to transmit the data or until it decides it is unable to
deliver the information (a timeout period. termed the linger interval. is specified in the setsockopt call when SO_LINGER is requested). If SO_DONTLINGER is specified and a close is
issued. the system will process the close in a manner which allows the process to continue as
quickly as possible.
RETURN VALVE

A -1 is returned if an error occurs, otherwise the return value is a descriptor referencing the
socket.
ERRORS

The socket call fails if:
[EAFNOSUPPORT] The specified address family is not supported in this version of the system.
[ESOCKTNOSUPPORT]
The specified socket type is not supported in this address family.
[EPROTONOSUPPORT]
The specified protocol is not supported.
[EMFILE]
The per-process descriptor table is full.
[ENOBUFS]

No buffer space is available. The socket cannot be created.

SEE ALSO

accept(2), bind(2), connect(2), getsockname(2), getsockopt(2). ioctH2), Iisten(2), recv(2).
select(2), send(2), shutdown(2), socketpaid2)
A 4.2BSD Interprocess Communication Primer".
H

4th Berkeley Distribution

18 July 1983

2

SOCKET (2)

UNIX Programmer's Manual

SOCKET (2)

BUGS
The use of keepalives is a questionable feature for this layer.

4th Berkeley Distribution

18 July 1983

3

SQCKETPAIR (2)

UNIX Programmer's Manual

SOCKETPAIR ( 2 )

NAME

socketpair - create a pair of connected sockets
SYNOPSIS

#include < sysltypes.h>
#include < sys/socket.h>
socketpair(d, type, protocol, sv)
int d, type, protocol:
int sv121;
DESCRIPTION

The socketpair call creates an unnamed pair of connected sockets in the specified domain d. of
the specified type. and using the optionally specified protocol. The descriptors used in referencing the new sockets are returned in sr[O] and sv[l J. The two sockets are indistinguishable.
DIAGNOSTICS

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

The call succeeds unless:
[EMFILE]

Too many descriptors are in use by this process.

[EAFNOSUPPORT] The specified address family is not supported on this machine.
[EPROTONOSUPPORT]
The specified protocol is not supported on this machine.
[EOPNOSUPPORT] The specified protocol does not support creation of socket pairs.
[EFAULT]

The address sl'does not specify a valid part of the process address space.

SEE ALSO

read(2), write(2). pipe(2)
Bt.:GS

This call is currently implemented only for the UNIX domain.

4th Berkeley Distribution

27 July 1983

UNIX Programmer's Manual

STAT (2)

STAT (2)

NAME

stat, Istat, fstat - get file status
SYNOPSIS

#include < sys!types.h>
#include < sys/stat.h>
stat(path, buf)
char .path;
struct stat • buf;
)stat(path, buf)
char .path;
struct stat • buf;
fstat(fd, buf)
int fd;
struct stat • buf;
DESCRIPTION

Stat obtains information about the file path. Read. write or execute permission of the named
file is not required. but all directories listed in the path name leading to the file must be reachable.
Lstat is like stat except in the case where the named file is a symbolic link. in which case Istal
returns information about the link. while stat returns information about the file the link references.
Fstat obtains the same information about an open file referenced by the argument descriptor.
such as would be obtained by an open call.
Bl{f is a pointer to a stal structure into which information is placed concerning the file. The
contents of the structure pointed to by bl{f

struct stat (
dev_t
ino t
u_short
short
short
short
dev_t
otT t
time_t
int
time_t
int
time t
int
long
long
long

st_dev~

st_ino~
st_mode~
st_nlink~
st_uid~
st_gid~

st_rdev~

st_size~
st_atime~

I * device inode resides on *1
I * this inode's number */
/ * protection *1
/ * number or hard links to the file */
1* user-id of owner *1
1* group-id of owner *1
1* the device type. for inode that is device */
/ * total size of file *1
/ * file last access time */

st_spare 1~
st_mtime~

I'" file last modify time *1

st_spare2:
st_ctime~

I * file last status change time *1

st_spare3~

st_blksize~
I * optimal blocksize for file system i/o ops *1
st blocks~ 1* actual number of blocks allocated *1
st-spare4 [2L

Time when file data was last read or modified. Changed by the following system
calls: mknod(2). utimes(2) , read(2) , and write(2). For reasons of efficiency.
st_atime is not set when a directory is searched. although this would be more logical.

4th Berkeley Distribution

27 July 1983

STAT (2)

UNIX Programmer's Manual

STAT (2)

Time when data was last modified. It is not set by changes of owner, group, link
count, or mode. Changed by the following system calls: mkl1od(2), Ulimes(2).
write(2).

Time when file status was last changed. It is set both both by writing and changing the i-node. Changed by the following system calls: chmod(2) chowl1(2).
link(2), mknod(2), unlink(2) , Ulimes(2), write(2).

The status information word sLmode has bits:
#define SJFMT
0170000
/ * type of file */
#define S IFDIR
0040000
/ * directory */
#define S)FCHR
0020000
/ * character special */
#define S IFBLK
0060000
/ * block special */
#define S)FREG
0 I 00000
/ * regular */
#define SJFLNK
0120000
/* symbolic link */
#define SJFSOCK
0140000
/* socket */
#define S_ISUID
0004000
/* set user id on execution */
#define SJSGID
0002000
/* set group id on execution */
#define S ISVTX
0001000
/* save swapped text even after use */
#define S)READ
0000400
/* read permission, owner */
#define S IWRITE
0000200
/ * write permission, owner */
#define S)EXEC
0000100
/* execute/ search permission, owner */
The mode bits 0000070 and 0000007 encode group and others permissions (see chmod(2».
When /d is associated with a pipe, /stat reports an ordinary file with an i-node number. restricted permissions. and a not necessarily meaningful length.
RETURN VALVE

Upon successful completion a value of 0 is returned. Otherwise. a value of -1 is returned und
err no is set to indicate the error.
ERRORS
Stat and ISlal will fail if one or more of the following are true:

[ENOTDIR]

A component of the path prefix is not a directory.

[EPERM]

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

[ENOENT]

The pathname was too long.

[ENOENT]

The named file does not exist.

[EACCES]

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

[EF AUL T]

Bli/or

name points to an invalid address.

FSlal will fail if one or both of the following are true:

[EBADF]

Fildes is not a valid open file descriptor.

[EFAULT]

Bu/points to an invalid address.

[ELOOP]

Too many symbolic links were encountered in translating the pathname.

CAVEAT

The fields in the stat structure currently marked sLspareJ, sLspare2, and sLspare3 are present
in preparation for inode time stamps expanding to 64 bits. This, however, can break certain
programs which depend on the time stamps being contiguous (in calls to ulimes(2»,
SEE ALSO

chmod(2), chown(2), utimes(2)

4th Berkeley Distribution

27 July 1983

2

STAT (2)

UNIX Programmer's Manual

STAT (2)

BUGS
Applying /stat to a socket returns a zero'd buffer.
The list of calls which modify the various fields should be carefully checked with reality.

4th Berkeley Distribution

27 July 1983

3

SWAPON (2)

UNIX Programmer's Manual

SWAPON (2)

NAME

swapon - add a swap device for interleaved paging/swapping
SYNOPSIS

swapon (special)
char .special;
DESCRIPTION
Swapon makes the block device special available to the system for allocation for paging and
swapping. The names of potentially available devices are known to the system and defined at
system configuration time. The size of the swap area on special is calculated at the time the
device is first made available for swapping.

SEE ALSO
swapon(8), config(8)

BUGS
There is no way to stop swapping on a disk so that the pack may be dismounted.
This call will be upgraded in future versions of the system.

4th Berkeley Distribution

27 July 1983

1

SYMLINK (2)

UNIX Programmer's Manual

SYMLINK (2)

NAME

symlink - make symbolic link to a file
SYNOPSIS

symlink (namel, name2)
char *namel, .name2;
DESCRIPTION

A symbolic link name2 is created to name] (name2 is the name of the file created, name} is the
string used in creating the symbolic link). Either name may be an arbitrary path name~ the files
need not be on the same file system.
RETURN VALUE

Upon successful completion, a zero value is returned. If an error occurs, the error code is
stored in errno and a -1 value is returned.
ERRORS

The symbolic link is made unless on or more of the following are true:
[EPERM]

Either name] or name2 contains a character with the high-order bit set.

[ENOENT]

One of the path names specified was too long.

[ENOTDIR]

A component of the name2 prefix is not a directory.

[EEXIST]

Name2 already exists.

[EACCES]

A component of the name] path prefix denies search permission.

[EROFS]

The file name2 would reside on a read-only file system.

[EFAULT]

Name} or name2 points outside the process's allocated address space.

[ELOOP]

Too may symbolic links were encountered in translating the pathname.

SEE ALSO

Iink(2), In(1), unlink(2)

4th Berkeley Distribution

27 July 1983

SYNC (2)

UNIX Programmer's Manual

SYNC (2)

NAME

sync - update super-block
SYNOPSIS

syncO
DESCRIPTION
Sync causes all information in core memory that should be on disk to be written out. This

includes modified super blocks, modified i-nodes, and delayed block 110.
Sync should be used by programs which examine a file system, for example fsck. df, etc. Sync is
mandatory before a boot.
SEE ALSO

fsync(2), synd8), update(8)

BUGS
The writing, although scheduled, is not necessarily complete upon return from sync.

4th Berkeley Distribution

12 February 1983

SYSCALL(2)

UNIX Programmer's Manual

SYSCALL (2)

NAME

syscall - indirect system call
SYNOPSIS

syscalHnumber,

arc, ...) (VAX-In

DESCRIPTION

Syscall performs the system call whose assembly language interface has the specified number,
register arguments rO and r1 and further arguments argo
The rO value of the system call is returned.
DIAGNOSTICS

When the C-bit is set, syscall returns -1 and sets the external variable errno (see intro(2».
BUGS

There is no way to simulate system calls such as pipe (2) , which return values in register rl.

4th Berkeley Distribution

12 February 1983

1

TRUNCATE (2)

UNIX Programmer's Manual

TRUNCATE (2)

NAME

truncate - truncate a file to a specified length
SYNOPSIS

truncate(path, length)
char .path;
int length;
ftruncate (fd, length)
int fd, length;
DESCRIPTION

Truncate causes the file named by path or referenced by fd to be truncated to at most length
bytes in size. If the file previously was larger than this size, the extra data is lost. With ftruncate, the file must be open for writing.
RETURN VALUES

A value of 0 is returned if the call succeeds. If the call fails a -1 is returned, and the global
variable errno specifies the error.
ERRORS

Truncate succeeds unless:
[EPERM]

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

[ENOENT]

The pathname was too long.

[ENOTDIR]

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

[ENOENT]

The named file does not exist.

[EACCES]

A component of the path prefix denies search permission.

[EISDIR]

The named file is a directory.

[EROFS]

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

[ETXTBSY]

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

[EFAULT]

Name points outside the process's allocated address space.

Ftruncate succeeds unless:
[EBADF]

The fd is not a valid descriptor.

[EINVAL]

The fd references a socket, not a file.

SEE ALSO

open(2)

BUGS
Partial blocks discarded as the result of truncation are not zero
files which do not read as zero.

filled~

this can result in holes in

These calls should be generalized to allow ranges of bytes in a file to be discarded.

4th Berkeley Distribution

7 July 1983

1

UMASK(2)

UNIX Programmer's Manual

UMASK(2)

NAME

umask - set file creation mode mask
SYNOPSIS

oumask - umask (numask)
int oumask, numask;
DESCRIPTION

Umask sets the process's file mode creation mask to numask and returns the previous value of
the mask. The low-order 9 bits of numask are used whenever a file is created, clearing
corresponding bits in the file mode (see chmod(2». This clearing allows each user to restrict
the default access to his files.
The value is initially 022 (write access for owner only). The mask is inherited by child
processes.
RETURN VALUE

The previous value of the file mode mask is returned by the call.
SEE ALSO

chmod(2), mknod(2), open(2)

4th Berkeley Distribution

12 February 1983

1

UNLINK (2)

UNIX Programmer's Manual

UNLINK (2)

NAME

unlink - remove directory entry
SYNOPSIS

unlink (path)
char .path;
DESCRIPTION
Unlink removes the entry for the file path from its directory. If this entry was the last link to

the file, and no process has the file open. then all resources associated with the file are
reclaimed. If, however, the file was open in any process, the actual resource reclamation is
delayed until it is closed, even though the directory entry has disappeared.
RETURN VALUE

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

The unlink succeeds unless:
[EPERM]
The path contains a character with the high-order bit set.
[ENOENT]
The path name is too long.
[ENOTDIR]
A component of the path prefix is not a directory.
[ENOENT]
The named file does not exist.
[EACCES]
Search permission is denied for a component of the path prefix.
[EACCES]
Write permission is denied on the directory containing the link to be removed.
[EPERM]
The named file is a directory and the effective user ID of the process is not the
super-user.
[EBUSY]
The entry to be unlinked is the mount point for a mounted file system.
[EROFS]
The named file resides on a read-only file system.
[EFAULT]
Path points outside the process's allocated address space.
[ELOOP]
Too many symbolic links were encountered in translating the pathname.
SEE ALSO

c1ose(2), link(2), rmdir(2)

4th Berkeley Distribution

2 July 1983

UN IX ProgramlTlcr's

UTIMES(2)

UTlivl1 ~S (2)

~t1a1lL1

utillll'S(fllc, hll)
dlar *liIc;
stmd timl~'/al

l"p[21;

DESCl~IVI'ION

The ul;lIl/,s c(1I1 uses the ":lccessed" and "lIpdated" times in that
corresponding rccorded times for file.

ord~r

from the

f~'P

vector to set the

Thc c(lller ITlllst he the owner of the file or lhc super··L1scr. The "inode-changcd' tillle of the
set to the ClilTclltlime.
HETlmN VALUE

Upon slicces"flli completion, a v,litle
is set to iIldicatc the error.

or 0

me is

is returned. Otherwise, a valt!c of _. I is rcttlmcd and

('!TIIO
EI~n()HS

lflill1{,

will f:til if one or more

or the

following arc true:

[FPFIU'vlj

The r;llhnallle contained a chllr
pid
wait (status)
int pid;
union wait -status;
pid = wait (0)
int pld;

=

#include 
#include < sys/resource.h >
pid = wait3 (status, options, rusage)
Int pid;
union wait *status;
lnt options;
struct rusage -rusage;
DESCRIPTION
Wait causes its caller to delay until a signal is received or one of its child processes terminates.
If any child has died since the last wait, return is immediate, returning the process id and exit

status of one of the terminated children. If there are no children, return is immediate with the
value - 1 returned.
On return from a successful wait call, status is nonzero, and the high byte of status contains the
low byte of the argument to exit supplied by the child process~ the low byte of status contains
the termination status of the process. A more precise definition of the status word is given in
< syslwait.h>.
Wait3 provides an alternate interface for programs which must not block when collecting the
status of child processes. The status parameter is defined as above. The options parameter is
used to indicate the call should not block if there are no processes which wish to report status
(WNOHANG), and/or that only children of the current process which are stopped due to a
SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal should have their status reported (WUNTRACED). If rusage is non-zero, a summary of the resources used by the terminated process
and all its children is returned (this information is currently not available for stopped
processes) .

When the WNOHANG option is specified and no processes wish to report status, wait3 returns
a pid of O. The WNOHANG and WUNTRACED options may be combined by or'ing the two
values.
NOTES

Seesigvec(2) for a list of termination statuses (signals) ~ 0 status indicates normal termination.
A special status (0177) is returned for a stopped process which has not terminated and can be
restarted~ see ptrace(2). If the 0200 bit of the termination status is set, a core image of the
process was produced by the system.

If the parent process terminates without waiting on its children, the initialization process (process ID :II: 1) inherits the children.
Wait and wait3 are automatically restarted when a process receives a signal while awaiting termination of a child process.
RETURN VALUE
If wait returns due to a stopped or terminated child process, the process ID of the child is
returned to the calling process. Otherwise, a value of - 1 is returned and errno is set to

4th Berkeley Distribution

27 July 1983

1

WAIT (2)

UNIX Programmer's Manual

WAIT (2)

indicate the error.

Wait3 returns -1 if there are no children not previously waited
WNOHANG is specified and there are no stoppeu or exited chiidren.

for~

0 is returned if

ERRORS

Wait will fail and return immediately if one or more of the following are true:
[ECHILD]

The calling process has no existing unwaited-for child processes.

[EFAULT]

The status or rusage arguments point to an illegal address.

SEE ALSO

exit(2)

4th Berkeley Distribution

27 July 1983

2

WRITE (2)

UNIX Programmer's Manual

WRITE (2)

NAME

write, writev - write on a file
SYNOPSIS

write(d, buf, nbytes)
int d;
char -buf;
int nbytes;
#include
#include

< sys/types.h >
< sys/uio.h >

writev (d, iov, ioveclen)
int d;
struct iovec -iov;
int ioveclen;
DESCRIPTION

Write attempts to write nbytes of data to the object referenced by the descriptor d from the
buffer pointed to by buf Writev performs the same action, but gathers the output data from
the iovlen buffers specified by the members of the iovec array: iov [0], iov [1], etc.
On objects capable of seeking. the write starts at a position given by the pointer associated with
d, see Iseek(2). Upon return from write, the pointer is incremented by the number of bytes
actually written.
Objects that are not capable of seeking always write from the current position. The value of the
pointer associated with such an object is undefined.
If the real user is not the super-user, then write clears the set-user-id bit on a file. This
prevents penetration of system security by a user who "captures" a writable set-user-id file
o··vned by the super-user.
RETURN VALUE

Upon successful completion the number of bytes actually writen is returned. Otherwise a -I is
returned and errno is set to indicate the error.
ERRORS

Write will fail and the file pointer will remain unchanged if one or more of the following are
true:
[EBADF]
D is not a valid descriptor open for writing.
[EPIPE]
An attempt is made to write to a pipe that is not open for reading by any process.
[EPIPE]
An attempt is made to write to a socket of type SOCK_STREAM which is not
connected to a peer socket.
[EFBIG]
An attempt was made to write a file that exceeds the process's file size limit or
the maximum file size.
[EFAULT]
Part of iov or data to be written to the file points outside the process's allocated
address space.
SEE ALSO

Iseek(2), open(2), pipe(2)

4th Berkeley Distribution

27 July 1983

INTRO(3)

UNIX Programmer's Manual

INTRO (3)

NAME

intro - introduction to library functions
DESCRIPTION

This section describes functions that may be found in various libraries. The library functions
are those other than the functions which directly invoke UNIX system primitives, described in
section 2. This section has the libraries physically grouped together. This is a departure from
older versions of the UNIX Programmer's Reference Manual, which did not group functions by
library. The functions described in this section are grouped into various libraries:
(3) and (35)
The straight "3" functions are the standard C library functions. The C library also
includes all the functions described in section 2. The 35 functions comprise the standard
110 library. Together with the (3N), (3X), and (3C) routines, these functions constitute
library libc, which is automatically loaded by the C compiler cc(1), the Pascal compiler
pc(1), and the Fortran compiler .177(1). The link editor Id(I) searches this library under
the '-lc' option. Declarations for some of these functions may be obtained from
include files indicated on the appropriate pages.
(3F) The 3F functions are all functions callable from FORTRAN. These functions perform
the same jobs as do the straight "3" functions.
(3M) These functions constitute the math library, libm. They are automatically loaded as
needed by the Pascal compiler pe(1) and the Fortran compiler .177(1). The link editor
searches this library under the '-1m' option. Declarations for these functions may be
obtained from the include file < math. h > .
(3N) These functions constitute the internet network library,
(35) These functions constitute the 'standard 110 package', see intro (35). These functions
are in the library libc already mentioned. Declarations for these functions may be
obtained from the include file .
(3X) Various specialized libraries have not been given distinctive captions. Files in which
such libraries are found are named on appropriate pages.
(3C) Routines included for compatibility with other systems. In particular, a number of system call interfaces provided in previous releases of 4B5D have been included for source
code compatibility. The manual page entry for each compatibility routine indicates the
proper interface to use.
FILES

llib/libc.a

lusrIlib/Hbm.a
lusr Ilib/Hbcy.a
lusrllib/libmy.a
SEE ALSO

intro(3C), intro(35), intro(3F), intro(3M), intro(3N), nm(1), IdO), ccO), n7(l), intro(2)
DIAGNOSTICS

Functions in the math library (3M) may return conventional values when the function is
undefined for the given arguments or when the value is not representable. In these cases the
external variable errno (see intro(2» is set to the value EDOM (domain error) or ERANGE
(range error). The values of EDOM and ERANGE are defined in the include file < math.h >.
LIST OF FUNCTIONS
Name

abort
abort

4th Berkeley Distribution

Appears on Page

abort. 3
abort.3f

Description

generate a fault
terminate abruptly with memory image

2 April 1983

1

INTRO(3)

abs
access
acos
alarm
alarm
alloca
arc
asctime
asin
assert
atan
atan2
atof
atoi
atol
bcmp
bcopy
bessel
bit
bzero
cabs
calloc
ceil
chdir
chmod
circle
c1earerr
closedir
c1oselog
c10sepl
cont
cos
cosh
crypt
ctime
clime
curses
dbminit
delete
dffrac
dflmax
dflmax
dflmin
dflmin
drand
dtime
ecvt
edata
encrypt
end
endfsent
endgrent

4th Berkeley Distribution

UNIX Programmer's Manual

abs.3
access.3f
sin.3m
alarm.3c
alarm.3f
malloc.3
plot.3x
ctime.3
sin.3m
assert.3x
sin. 3m
sin.3m
atof.3
atof.3
atof.3
bstring.3
bstring.3
bessel.3f
bit.3f
bstring.3
hypot.3m
malloc.3
floor. 3m
chdir.3f
chmod.3f
plot.3x
ferror.3s
directory. 3
syslog.3
plot.3x
plot.3x
sin.3m
sinh.3m
crypt. 3
ctime.3
time.3f
curses.3x
dbm.3x
dbm.3x
flmin.3f
fimin.3f
range.3f
tlmin.3f
range.3f
rand.3f
etime.3f
ecvt.3
end. 3
crypt. 3
end.3
getfsent.3x
getgrent.3

INTRO(3)

integer absolute value
determine accessability of a file
trigonometric functions
schedule signal after specified time
execute a subroutine after a specified time
memory allocator
graphics interface
convert date and time to ASCII
trigonometric functions
program verification
trigonometric functions
trigonometric functions
convert ASCII to numbers
convert ASCII to numbers
convert ASCII to numbers
bit and byte string operations
bit and byte string operations
of two kinds for integer orders
and, or, xor, not, rshift, Ishift bitwise functions
bit and byte string operations
Euclidean distance
memory allocator
absolute value, floor, ceiling functions
change default directory
change mode of a file
graphics interface
stream status inquiries
directory operations
control system log
graphics interface
graphics interface
trigonometric functions
hyperbolic functions
DES encryption
convert date and time to ASCII
return system time
screen functions with "optimal" cursor motion
data base subroutines
data base subroutines
return extreme values
return extreme values
return extreme values
return extreme values
return extreme values
return random values
return elapsed execution time
output conversion
last locations in program
DES encryption
last locations in program
get file system descriptor file entry
get group file entry

2 April 1983

2

INTRO(3)

endhostent
endnetent
endprotoent
endpwent
endservent
environ
erase
etext
etime
exec
exece
execl
execle
execlp
exect
execv
execvp
exit
exit
exp
fabs
fclose
fcvt
fdate
feof
ferror
fetch
mush
ffrac
ffs
fgetc
fgetc
fgets
fileno
firstkey
flmax
flmax
flmin
flmin
floor
flush
fork
fpecnt
fprintf
fputc
fputc
fputs
fread
free
frexp
fscanf
fseek

4th Berkeley Distribution

UNIX Programmer's Manual

gethostent.3n
getnetent.3n
getprotoent.3n
getpwent.3
getservent.3n
execl.3
plot.3x
end.3
etime.3f
execl.3
execl.3
execl.3
.execl.3
execl.3
execl.3
execl.3
execl.3
exit. 3
exit.3f
exp.3m
floor.3m
fclose.3s
ecvt.3
fdate.3f
ferror.3s
ferror.3s
dbm.3x
fclose.3s
flmin.3f
bstring.3
getc.3f
getc.3s
gets.3s
ferror.3s
dbm.3x
flmin.3f
range.3f
flmin.3f
range.3f
floof.3m
flush.3f
fork.3f
trpfpe.3f
printf.3s
putc.3f
putc.3s
puts.3s
fread.3s
malloc.3
frexp.3
scanf.3s
fseek.3f

INTRO(3)

get network host entry
get network entry
get protocol entry
get password file entry
get service entry
execute a file
graphics interface
last locations in program
return elapsed execution time
execute a file
execute a file
execute a file
execute a file
execute a file
execute a file
execute a file
execute a file
terminate a process after flushing any pending output
terminate process with status
exponential, logarithm, power, square root
absolute value, floor, ceiling functions
close or flush a stream
output conversion
return date and time in an ASCII string
stream status inquiries
stream status inquiries
data base subroutines
close or flush a stream
return extreme values
bit and byte string operations
get a character from a logical unit
get character or word from stream
get a string from a stream
stream status inquiries
data base subroutines
return extreme values
return extreme values
return extreme values
return extreme values
absolute value, floor, ceiling functions
flush output to a logical unit
create a copy of this process
trap and repair floating point faults
formatted output conversion
write a character to a fortran logical unit
put character or word on a stream
put a string on a stream
buffered binary input/output
memory allocator
split into mantissa and exponent
formatted input conversion
reposition a file on a logical unit

2 April 1983

3

INTRO(3)

fseek
fstat
ftell
ftell
ftime
fwrite
gamma
gcvt
gerror
getarg
getc
getc
getchar
getcwd
getdiskbyname
getenv
getenv
getfsent
getfsfile
getfsspec
getfstype
getgid
getgrent
getgrgid
getgrnam
gethostbyaddr
gethostbyname
gethostent
getlog
getlogin
getnetbyaddr
getnetbyname
getnetent
getpass
getpid
getprotobyname
getprotobynumber
getprotoent
getpw
getpwent
getpwnam
getpwuid
gets
getservbyname
getservbyport
getservent
getuid
getw
getwd
gmtime
gmtime
gtty

4th Berkeley Distribution

UNIX Programmer's Manual

fseek.3s
stat.3f
. fseek.3f
fseek.3s
time.3c
fread.3s
gamma.3m
ecvt.3
perror.3f
getarg.3f
getc.3f
getc.3s
getc.3s
getcwd.3f
getdisk.3x
getenv.3
getenv.3f
getfsent.3x
getfsent.3x
getfsent.3x
getfsent.3x
getuid.3f
getgrent.3
getgrent.3
getgrent.3
gethostent.3n
gethostent.3n
gethostent.3n
getlog.3f
getlogin.3
getnetent.3n
getnetent.3n
getnetent.3n
getpass.3
getpid.3f
getprotoent.3n
getprotoent.3n
getprotoent.3n
getpw.3
getpwent.3
getpwent.3
getpwent.3
gets.3s
getservent.3n
getservent.3n
getservent.3n
getuid.3f
getc.3s
getwd.3
ctime.3
time.3f
stty.3c

INTRO (3)

reposition a stream
get file status
reposition a file on a logical unit
reposition a stream
get date and time
buffered binary input/output
log gamma function
output conversion
get system error messages
return command line arguments
get a character from a logical unit
get character or word from stream
get character or word from stream
get pathname of current working directory
get disk description by its name
value for environment name
get value of environment variables
get file system descriptor file entry
get file system descriptor file entry
get file system descriptor file entry
get file system descriptor file entry
get user or group ID of the caller
get group file entry
get group file entry
get group file entry
get network host entry
get network host entry
get network host entry
get user's login name
get login name
get network entry
get network entry
get network entry
read a password
get process id
get protocol entry
get protocol entry
get protocol entry
get name from uid
get password file entry
get password file entry
get password file entry
get a string from a stream
get service entry
get service entry
get service· entry
get user or group ID of the caller
get character or word from stream
·get current working directory pathname
convert date and time to ASCII
return system time
set and get terminal state (defunct)

2 April 1983

4

INTRO(3)

hostnm
htonl
htons
hypot
iargc
idate
ierrno
index
index
inet addr
inet)naof
inet_makeaddr
inet_netof
inet_network
initgroups
initstate
inmax
inmax
insque
ioinit
irand
isalnum
isalpha
isascii
isatty
isatty
iscntrl
isdigit
islower
isprint
ispunct
isspace
isupper
itime
jO
jl

jn
kill
label
Idexp
len
lib2648
line
linemod
link
lnblnk
loc
local time
log
log10
long
longjmp

4th Berkeley Distribution

UNIX Programmer's Manual

hostnm.3f
byteorder.3n
byteorder.3n
hypot.3m
getarg.3f
idate.3f
perror.3f
index.3f
string. 3
inet.3n
inet.3n
inet.3n
inet.3n
inet.3n
initgroups.3x
random.3
flmin.3f
range.3f
insque.3
ioinit.3f
rand.3f
ctype.3
ctype.3
ctype.3
ttynam.3f
ttyname.3
ctype.3
ctype.3
ctype.3
ctype.3
ctype.3
ctype.3
ctype.3
idate.3f
jO.3m
jO.3m
jO.3m
kill.3f
plot.3x
frexp.3
index.3f
lib2648.3x
plot.3x
plot.3x
link.3f
index.3f
loc.3f
ctime.3
exp.3m
exp'3m
long.3f
setjmp.3

INTRO (3)

get name of current host
convert values between host and network byte order
convert values between host and network byte order
Euclidean distance
return command line arguments
return date or time in numerical form
get system error messages
tell about character objects
string operations
Internet address manipulation routines
Internet address manipulation routines
Internet address manipulation routines
Internet address manipulation routines
Internet address manipulation routines
initialize group access list
better random number generator
return extreme values
return extreme values
insert/remove element from a queue
change f77 I/O initialization
return random values
character classification macros
character classification macros
character classification macros
find name of a terminal port
find name of a terminal
character classification macros
character classification macros
character classification macros
character classification macros
character classification macros
character classification macros
character classification macros
return date or time in numerical form
bessel functions
bessel functions
bessel functions
send a signal to a process
graphics interface
split into mantissa and exponent
tell about character objects
subroutines for the HP 2648 graphics terminal
graphics interface
graphics interface
make a link to an existing file
tell about character objects
return the address of an object
convert date and time to ASCII
exponential, logarithm, power, square root
exponential, logarithm, power, square root
integer object conversion
non-local goto

2 April 1983

5

INTRO (3)

Istat
Itime
malloc
mktemp
modf
moncontrol
monitor
monstartup
move
nextkey
nice
nlist
ntohl
ntohs
opendir
openlog
pause
pclose
perror
perror
plot: openpl
point
popen
pow
printf
psignal
putc
putc
putchar
puts
putw
qsort
qsort
rand
rand
random
rcmd
re_comp
re_exec
readdir
realloc
remque
rename
rewind
rewinddir
rexec
rindex
rindex
rresvport
ruserok
scandir
scanf

4th Berkeley Distribution

UNIX Programmer's Manual

stat.3f
time.3f
malloc.3
··mktemp.3
frexp.3
monitor.3
monitor.3
monitor. 3
plot.3x
dbm.3x
nice.3c
nUst.3
byteorder.3n
byteorder.3n
directory. 3
syslog.3
·pause.3c
popen.3
perror.3
perror.3f
plot.3x
plot.3x
popen.3
exp.3m
printf.3s
psigna1.3
putc.3f
putc.3s
putc.3s
puts.3s
. putc.3s
qsort.3
qsort.3f
rand.3c
rand.3f
random. 3
rcmd.3x
regex.3
regex.3
directory .3
malloc.3
insque.3
rename.3f
fseek.3s
directory .3
rexec.3x
index.3f
string. 3
rcmd.3x
rcmd.3x
scandir.3
scanf.3s

INTRO (3)

get file status
return system time
memory allocator
make a unique file name
split into mantissa and exponent
prepare execution profile
prepare execution profile
prepare execution profile
graphics interface
data base subroutines
set program priority
get entries from name list
convert values between host and network byte order
convert values between host and network byte order
directory operations
control system log
stop until signal
initiate I/O to/from a process
system error messages
get system error messages
graphics interface
graphics interface
initiate 110 to/from a process
exponential, logarithm, power, square root
formatted output conversion
system signal messages
write a character to a fortran logical unit
put character or word on a stream
put character or word on a stream
put a string on a stream
put character or word on a stream
quicker sort
quick sort
random number generator
return random values
better random number generator
routines for returning a stream to a remote command
regular expression handler
regular expression handler
directory operations
memory allocator
insert/remove element from a queue
rename a file
reposition a stream
directory operations
return stream to a remote command
tell about character objects
string operations
routines for returning a stream to a remote command
routines for returning a stream to a remote command
scan a directory
formatted input conversion

2 Apri11983

6

INTRO (3)

seekdir
setbuf
setbuffer
setegid
seteuid
setfsent
setgid
setgrent
sethostent
setjmp
setkey
setlinebuf
setnetent
setprotoent
setpwent
setrgid
setruid
setservent
setstate
setuid
short
signal
signal
sin
sinh
sleep
sleep
space
sprintf
sqrt
srand
srandom
sscanf
stat
stdio
store
strcat
strcmp
strcpy
strlen
stmcat
stmcmp
strncpy
stty
swab
sys_errlist
sys_nerr
sys_siglist
syslog
system
system
tan

4th Berkeley Distribution

UNIX Programmer's Manual

directory.3
setbuf.3s
setbuf.3s
setuid.3
setuid.3
getfsent.3x
setuid.3
getgrent.3
gethostent.3n
setjmp.3
crypt. 3
setbuf.3s
getnetent.3n
getprotoent.3n
getpwent.3
setuid.3
setuid.3
getservent.3n
random. 3
setuid.3
long.3f
signal. 3
signal.3f
sin.3m
sinh.3m
sleep 3
sleep.3f
plot.3x
printf.3s
exp.3m
rand.3c
random. 3
scanf.3s
stat.3f
intro.3s
dbm.3x
string. 3
string. 3
string. 3
string. 3
string. 3
string. 3
string.3
stty.3c
swab. 3
perror.3
perror.3
psigna1.3
syslog.3
system.3
system.3f
sin.3m

INTRO (3)

directory operations
assign buffering to a stream
assign buffering to a stream
set user and group ID
set user and group ID
get file system descriptor file entry
set user and group ID
get group file entry
get network host entry
non-local goto
DES encryption
assign buffering to a stream
get network entry
get protocol entry
get password file entry
set user and group ID
set user and group ID
get service entry
better random number generator
set user and group ID
integer object conversion
simplified software signal facilities
change the action for a signal
trigonometric functions
hyperbolic functions
suspend .execution for interval
suspend execution for an interval
graphics interface
formatted output conversion
exponential, logarithm, power, square root
random number generator
better random number generator
formatted input conversion
get file status
standard buffered input/output package
data base subroutines
string operations
string operations
string operations
string operations
string operations
string operations
string operations
set and get terminal state (defunct)
swap byt
system e
system e
system s
control:
issue a l
execute
trigonol

2 April 1983

7

INTRO(3)

tanh
tclose
telldir
tgetent
tgetfiag
tgetnum
tgetstr
tgoto
time
time
times
timezone
topen
tputs
traper
trapov
tread
trewin
trpfpe
tskipf
tstate
ttynam
ttyname
ttyslot
twrite
ungetc
unlink
utime
valloc
varargs
vlimit
vtimes
wait
yO

yl
yn

4th Berkeley Distribution

UNIX Programmer's Manual

sinh. 3m
topen.3f
directory. 3
termcap.3x
termcap.3x
termcap.3x
termcap.3x
termcap.3x
time.3c
time.3f
times.3c
ctime.3
topen.3f
termcap.3x
traper.3f
trapov.3f
topen.3f
topen.3f
trpfpe.3f
topen.3f
topen.3f
ttynam.3f
ttyname.3
ttyname.3
topen.3f
ungetc.3s
unlink.3f
utime.3c
valloc.3
varargs.3
vlimit.3c
vtimes.3c
wait.3f
jO.3m
jO.3m
jO.3m

INTRO(3)

hyperbolic functions
n7 tape I/O
directory operations
terminal independent operation routines
terminal independent operation routines
terminal independent operation routines
terminal independent operation routines
terminal independent operation routines
get date and time
return system time
get process times
convert date and time to ASCII
n7 tape 1/0
terminal independent operation routines
trap arithmetic errors
trap and repair floating point overflow
n7 tape 1/0
n7 tape 1/0
trap and repair floating point faults
n7 tape I/O
n7 tape I/O
find name of a terminal port
find name of a terminal
find name of a terminal
n7 tape I/O
push character back into input stream
remove a directory entry
set file times
aligned memory allocator
variable argument list
control maximum system resource consumption
get information about resource utilization
wait for a process to terminate
bessel functions
bessel functions
bessel functions

2 April 1983

8

ABORT (3)

UNIX Programmer's Manual

ABORT (3)

NAME

abort - generate a fault
DESCRIPTION

Abort executes an instruction which is illegal in user mode. This causes a signal that normally
terminates the process with a core dump, which may be used for debugging.
SEE ALSO

adb(1), sigvec(2), exit(2)
DIAGNOSTICS

Usually 'lOT trap - core dumped' from the shell.
BUGS

The abortO function does not flush standard I/O butTers. Use ffiush (3S).

7th Edition

18 January 1983

1

ABS(3)

UNIX Programmer's Manual

ABS (3)

NAME
abs - integer absolute value
SYNOPSIS.

abs(l)
lot I;
DESCRIPTION

Abs returns the absolute value of its integer operand.
SEE ALSO

Ooor(3M) for labs

BUGS
Applying the abs function to the most negative integer generates a result which is the most
negative integer. That is,
abs(Ox80000000)
returns Ox80000000 as a result.

7th Edition

18 January 1983

1

ATOF(3)

UNIX Programmer's Manual

ATOF(3)

NAME

atof, atoi, atol - convert ASCII to numbers
SYNOPSIS

double atof(nptr)
char *nptrj
atol(nptr)
char .nptrj
1001 atoHnptr)
char .optr;
DESCRIPTION

These functions convert a string pointed to by nptr to floating, integer, and long integer
representation respectively. The first unrecognized character ends the string.
Ato/recognizes an optional string of spaces, 'then an optional sign, then a string of digits optionally containing a decimal point, then an optional 'e' or 'E' followed by an optionally signed
integer.
Atoi and atol recognize an optional string of spaces, then an optional sign, then a string of
digits.
SEE ALSO

scanf(3S)

BUGS
There are no provisions for overflow.

7th Edition

19 January 1983

1

BSTRING(3)

UNIX Programmer's Manual

BSTRING (3)

NAME
bcopy, bcmp, bzero, trs - bit and byte string operations
SYNOPSIS

bcopy(bl, b2, length)
char -bl, -b2;
Int length;
bcmp(bl, b2, length)
char -bl, *b2;
Int length;
bzero(b, length)
char -b;
lnt length;
ft'sO)

Int I;
DESCRIPTION

The functions bcopy, bcmp, and bzero operate on variable length strings of bytes. They do not
check for null bytes as the routines in string(3) do.
Beopy copies length bytes from string bl to the string b2.
Bemp compares byte string bl against byte string b2, returning zero if they are identical, nonzero otherwise. Both strings are assumed to be length bytes long.
Bzero places length 0 bytes in the string bl.
Ffs find the first bit set in the argument passed it and returns the index of that bit. Bits are
numbered starting at 1. A return value of -1 indicates the value passed is zero.

BUGS
The bemp and beopy routines take parameters backwards from stremp and strepy.

4th Berkeley Distribution

4 March 1983

1

CRYPT (3)

UNIX Programmer's Manual

CRYPT (3)

NAME
crypt, setkey, encrypt - DES encryption
SYNOPSIS

char -crypt (key, salt)
char -key, -salt;
setkey(key)
char -key;
encrypt (block, edflag)
char -block;
DESCRIPTION

Crypt is the password encryption routine. It is based on the NBS Data Encryption Standard,
with variations intended (among other things) to frustrate use of hardware implementations of
the DES for key search.
The first argument to crypt is normally a user's typed password. The second is a 2-character
string chosen from the set [a-zA-ZO-9.11. The salt string is used to perturb the DES algorithm
in one of 4096 different ways, after which the password is used as the key to encrypt repeatedly
a constant string. The returned value points to the encrypted password, in the same alphabet as
the salt. The first two characters are the salt itself.
The other entries provide (rather primitive) access to the actual DES algorithm. The argument
of setkey is a character array of length 64 containing only the characters with numerical value 0
and 1. If this string is divided into groups of 8, the low-order bit in each group is ignored,
leading to a 56-bit key which is set into the machine.
The argument to the encrypt entry is likewise a character array of length 64 containing O's and
1'so The argument array is modified in place to a similar array representing the bits of the argument after having been subjected to the DES algorithm using the key set by setkey. If eqjiag is
0, the argument is encrypted; if non-zero, it is decrypted.
SEE ALSO

passwd(l), passwd(5), 10gin(1), getpass(3)
. BUGS

The return value points to static data whose content is overwritten by each call.

7th Edition

25 February 1983

1

UNIX Programmer's Manual

CrIME(3)

CTIME(3)

NAME

ctime, local time, gmtime, asctime, timezone -- convert date and time to ASCII
SYNOPSIS

char *ctimc(clock)
long *clock;
# include (sys/timc.h)
struct tm *Iocaltime(clock)
long *clock;
struct tm *gmtimc(c1ock)

long *clock;

char

*~lsctime(tm)

struct tm *hll;

char *timcl.onc(zonc, dst)
DESCnll'TION

Clilllc converts a time pointed to by clock slIch as returned by limc(3) into ASCII and returns a
pointer to a 26-charactcr string in the following form. All the fields have constant width.
Sun Sep 16 01:03:52 .1973\n\0

Loca/lime and gnilillle return pointers to structures containing the broken-down time. I,oea/lime
corrects for the time zone and possible daylight savings time; gmlimc converts directly to GMT,
which is the time UN IX uses. Asc:limc converts a broken-down time to ASCII and returns a
pointer to a 26-character string.
The structure dec1aration rrom the include file is:
~truct

tm. {
int
int
int
illt
int
int
int
int
int

tlll.,...sec;
tlll_lllin;
tmJlOur;
. tm_mday;
tm_mon;
till_year;
tlll_wday;
tlll_yday;
tm_isdst;

};

These quantities give the time on a 24-hour clock, day of month (1-30, month of year (0-11), day
of week (Sunday = 0), year - 1900, day of year (0-365), and a nag that is nOllzero if daylight saving time is in clfect.
When local time is called for, the program consults the system to determine the time zone and
whether the U.S./\, Australian, Eastern European, Middle European, or Western European dayJight saving time adjustment is appropriatc. The program knows about various peculiarities in time
conversion over the past 10··20 years: if necessary, this understanding can be extended.
Timezone returns the name of the time zone associated with il<; first argument, which is measured in
minutes westward from Greenwich. If the second argument is 0, Ule standard name is used, otherwise the Daylight Saving version. If the required name docs not appear in a table built into the
routine, the difference from GMT is produced: e.g. in Alghanistan tilllczO,llc(-(60*4 -/- 30), 0) is
appropriate because it is 4:30 ahead of.GMT and the string GMT+4:30 is'produced.

4th Berkeley Distrihution

26 J unc 1983 .

I

CTIME(3)

UNIX Programmer's Manual

CTIME(3)

SEE ALSO

gcttimeofday(2), time(3)
BUGS

The return values point to static data whose content is overwritten by each call.

4th Berkeley Distribution

26 June 1983

2

CTYPE(3)

UNIX Programmer's Manual

CTYPE(3)

NAME
isalpha, isupper, islower, isdigit, isalnum, isspace, ispunct, isprint, iscntrl, isascii - character
classification macros
SYNOPSIS

#lnclude < etype.h >
lsalpha(c)
DESCRIPTION

These macros classify ASCII-coded integer values by table lookup. Each is a predicate returning nonzero for true, zero for false. lsascii is defined on all integer values; the rest are defined
only where isascii is true and on the single non-ASCII value EOF (see stdio(3S».

isalpha
isupper
is/ower
isdigit
isalnum
isspace
'ispunct
isprint
iscntrl
isascii

c is a letter
c is an upper case letter
c is a lower case letter
c is a digit
c is an alphanumeric character

c is a space, tab, carriage return, newline, or formfeed
c is a punctuation character (neither control nor alphanumeric)
c is a printing character, code 040(8) (space) through 0176 (tilde)
c is a delete character (0177) or ordinary control character (less than 040).
c is an ASCII character, code less than 0200

SEE ALSO

ascii (7)

7th Edition

2S February 1983

1

DIRECTORY (3)

UNIX Programmer's Manual

DIRECTORY (3 )

NAME

opendir, readdir, telldir, seekdir, rewinddir, closedir- directory operations
SYNOPSiS

#lnelude < sys/dlr.h >
DIR .opendir(fllename)
ebar .fllename;
strud dlreet .readdlr(dlrp)
DIR .dlrp;
lonl telldlr(dlrp)
DIR .dlrp;
seekdlr (dlrp, loe)
DIR .dlrp;
lonlloe;
rewlnddlr(dlrp)
DIR .dlrp;
elosedlr(dlrp)
DIR .dlrp;

DESCRIPTION

Opendir opens the directory named by filename and associates a directory stream with it. Opendir
returns a pointer to be used to identify the directory stream in subsequent operations. The
pointer NULL is returned if filename cannot be accessed, or if it cannot malloc(3) enough
.
memory to hold the whole thing.
Readdir returns a pointer to the next directory entry. It returns NULL upon reaching the end
of the directory or detecting an invalid seekdir operation.
Telldir returns the current location associated with the named directory stream.
Seekdir sets the position of the next readdir operation on the directory stream. The new. position
reverts to the one associated with the directory stream when the telldir operation was performed.
Values returned by telldir are good only for the lifetime of the DIR pointer from which they are
derived. If the directory is closed and then reopened, the telldir value may be invalidated due
to undetected directory compaction. It is safe to use a previous telldir value immediately after a
call to opendir and before any calls to readdir.
Rewinddir resets the position of the named directory stream to the beginning of the directory.
Closedir closes the named directory stream and frees the structure associated with the DIR
pointer.
Sample code which searchs a directory for entry "name" is:
len - strlen(name);
dirp - opendir(".");
for (dp - readdir(dirp); dp !- NULL; dp - readdir(dirp»
if (dp->d_namlen - - len &,&, !strcmp(dp->d_name, name» (
closedir (dirp) ;
return FOUND;
}
closedir(dirp) ;
return NOT_FOUND;
SEE ALSO

open(2), close(2), read(2), Iseek(2), dir(S)

4th Berkeley Distribution

2S February 1983

1

ECVT(3)

UNIX Programmer's Manual

ECVT(3)

NAME

ecvt, fcvt, gcvt - output conversion
SYNOPSIS

char -eert (value, ndlgit, deept, slln)
double value;
Int ndillt, -deept, -silo;
dlar -fcvt(value, Dclllit, deept, slln)
double value;
Int Ddillt, -deept, -sliD;
char -Icvt(value, ncllglt, but)
double value;
char -buf;
DESCllIPTION

Ecvt converts the value to a null-terminated string of ndigit ASCII digits and returns a pointer
thereto. The position of the decimal point relative to the beginning of the string is stored
indirectly through deept (negative means to the left of the returned digits). If the sign of the
result is negative, the word pointed to by sign is non-zero, otherwise it is zero. The low-order
digit is rounded.
Fevt is identical to eev~ except that the correct digit has been rounded for Fortran F-format output of the number of digits specified by ndigits.
Gevt converts the value to a null-terminated ASCII string in but and returns a pointer to b,q. It
attempts to produce ndigit significant digits in Fortran F format if possible, otherwise E format,
ready for printing. Trailing zeros may be suppressed.
SEE ALSO

printf(3)

BUGS
The return values point to static data whose content is overwritten by each call.

7th Edition

19 January 1983

1

END(3)

UNIX Programmer's Manual

END (3)

NAME

end, etext, edata - last locations in program
SYNOPSIS

extem end;
extem etext;
extem edata;
DESCRIPTION

These names refer neither to routines nor to locations with interesting contents. The address
of etext is the first address above the program text, edata above the initialized data region, and
end above the uninitialized data region.
When execution begins, the program break coincides with end, but it is reset by the routines
brk(2), ma//oc(3), standard input/output (stdio(3», the profile (-p) option of ccO), etc. The
current value of the program break is reliably returned by 'sbrk(O)', see brk(2).
SEE ALSO

brk(2), malloc(3)

7th Edition

19 Janull)' 1983

1

EXCEIY1'(3)

UN IX Programmer's Manual

EXCEPT(J)

NAME

(except) raise, raise_sysO - C exception handling
SYNOPSIS

# include (except.h>

misc(code, msg)
iut code;
ch~1r *msg;
misc_sysO
cc ... -Iexcept
~:XTENDED

C SYNTAX

DUnlNG statementl

ni\NnL~~n

slatement2 li:ND_IIANIlLII:lt

KJHi:TlJRN_ VOID
DESCRIPTION

The macros and functions in this package provide a limited amount of exception handling for pro-

gramming in C. They provide the ability to associate an exception handler to be invoked if an
~xccplion is raised during the execution of a statement.
C syntax is extended by several macros that al10w the programmer to
handler with a statement. The "syntax" for this is:

as..~ociate

an exception

DURING statementl HANDLER statement2 END_HANDLER

Either or both statement may be a compound statement. If an exception is raised using the raiseO
function during stat(,lIIellIl (or during any functions called by stat('lIIelltl), the stack wHi be
unwound and statemenl2 wilt be invokt'tl in the Cllrrcllt context. Ilowcvcr, if the exception handler
is redeclared in a dynamically cnclosed statement, the current cxception handler wilt be inactive
during the execution of the enclosed statement.
During the exccution or stat~lIleIl12, two preddined values may be used: Hxccplioll. Code , an
integer,is the value of code passcd to the raiseO call which invoked the handler, and
ExcepliOli.Alessage is the value of IIIsg. It is up to the user to define the values used fl)r the exception codes~ by convention, small positive integers are interpreted il c()~c~as an argument.
The dcfault value for h'xcepll\lode is zero.
RESTIHCTIONS

TI-IESll: nESTIUCTIONS AHE IMPOI{TANT; YOU WILL SUFFER IF YOU DISOBEY
THEM.

During the execution of slalcmelltl. no transfers out of the statement are allowed, except as noted
here. Execution of a compound sfatemellll must "llin oil' the end" of the block. This means that
slalemcllll may not iilclude a rcturn or goto, or a brcak or continuc t.hat would "flect " loop enclosing the DUfUNG ... HNIJ_IIANIJI,HR block. The slatemf'nll may include a call to raiseO (but
not RFR AI,\'H), exil(3), and any statement at all may be used in a functioll ca11ed.
If' you wish to use a rl'lufI1 within slalrllll'llll, you must instead lise f~'-RFTURNO to return a
value, or 1~'-R/~7'URN_VOII) if thc enclosing function is declared void. These two macros Illay be
used ollly in the (lexically) outermost slu/ell/rllli of a function, and nowhere clse.

There are no restrictions on what may be done inside the slalement2 part of Cl handler hlock, except
that it is subject lo lile above constraints if it is lexically enclosed in lhe sllllell/f'lIlf parl of another
handler.
As an aid to Ullix programmers, the raise_.~)'sO function is provided. It is lIs~d exactly as raisrO is,
except that it lIses the global crmo(3) to produce t.he cxception code and mcssage.
SEI~

AlBO

errnoO ),' selj III pO)
AUTI-IOn'

Jeffrey Mogul (Stantbrd)
BU(~S

Due toa limitation of the s£'(illlp(3) implementation, rcgist'cr variables which are actually stored in
registers (and this is not always easy to dct.ennine. and e$pecially is not portable) arc restored to the
values they had upon entering slalell/f'1I11 whcn th(' handler (slt/femeIl12) is invoked. 1\11 other data
keeps whatever values they were assigned during the (illh.'lTlipted) execution or sIll lelllCII I I. ;\ good
rule to 1{}lIow is that you should not rely Oil the values or variables dec1areu l'l'gislcl' (in the current
block) atler an exception has been caught.

7th Edition

Stanford

2

EXECL(3)

UNIX Programmer's Manual

EXECL(3)

NAME

execl, execv, execle, execlp, execvp, exec, exece, exect, environ - execute a file
SYNOPSIS

execl (name, argO, argl, ••• , aran, 0)
ehar -Dame, -argO, -argl, ••• , -8I'ID;
execv (name, arav)
ehar -name, -argvll;
exeele(name, argO, a1'l1, .•• , argn, 0, envp)
ehar -name, -argO, -argl, ••• , -argn, -envpll;
exeet (name, argv, envp)
char -name, -argvll, -envp();
extern ehar --environ;
DESCRIPTION

These routines provide various interfaces to the execve system call. Refer to execve(2) for a
description of their properties; only brief descriptions are provided here.

Exec in all its forms overlays the calling process with the named file, then transfers to the entry
point of the core image of the file. There can be no return from a successful exec; the calling
core image is lost.
The name argument is a pointer to the name of the file to be executed. The pointers Qfg[O]'
arg[J] ... address null-terminated strings. Conventionally arg(O] is the name of tbe file.
Two interfaces are available. execl is useful when a known file with known arguments, is being
called; .the arguments to execl are the character strings constituting the file and the arguments~
the first argument is conventionally the same as the file name (or its last component). A 0
argument must end the argument list.
The execv version is useful when the number of arguments is unknown in advance; the arguments to execv are the name of the file to be executed and a vector of strings containing the
arguments. The last argument string must be followed by a 0 pointer.
The exect. version is used when the executed file is to be manipulated with ptrace(2). The program is forced to single step a single instruction giving the parent an opportunity to manipulate
its state. On the VAX-II this is done by setting the trace bit in the process stat.us longword.
When a C program is executed, it is called as follows:
main(argc, argv, envp)
int argc;
char ••argv, ••envp;
where orgc is the argument count and arIV is an array 01 character pointers to the argu,ments
themselves. As indicated, argc is conventionally at least one and tbe first member of the array
points to a string containing the name of the file.

Argv is directly usable in another execv because argv(argcl is O.
Envp is a pointer to an array of strings that constitute the en:viron.ment' of the f)·recess.. Each
string consists of a name, an "-", and a. null-terminated. ~altle. The: array of pointers is; terminated by a null pointer. The shell shU) passes an environment entry for each global shell
variable defined when the program is called. See environ (1) for some con:ventionally used
names. The C run-time start-off routine places· a copy of envp in tbe global cell en:vilon, whkh
is used by execvand exec! to pass the environment to any subprolrams executed by tile current
.program.

4th Berkeley Distribution

1 April 1981

1

EXECL(3)

UNIX Programmer's Manual

EXECL(3)

Exec!p and execvp are called with the same arguments as exec! and execv, but duplicate the
shell's actions in searching for an executable file in a list of directories. The directory list is
obtained from the environment.
FILES

Ibin/sh shell, invoked if command file found by execlp or execvp
SEE ALSO

execve(2), fork(2), environ (7) , csh(1)
DIAGNOSTICS

If the file cannot be found, if it is not executable, if it does not start with a valid magic number
(see a.out(S», if maximum memory is exceeded, or if the arguments require too much space,
a return constitutes the diagnostic; the return value is -1. Even for the super-user, at least
one of the execute-permission bits must be set for a file to be executed.
BUGS

If execvp is called to execute a file that turns out to be a shell command file, and if it is impossible to execute the shell, the values of argv[01 and argyl -11 will be modified before return.

4th Berkeley Distribution

1 Apri11981

2

EXIT (3)

UNIX Programmer's Manual

EXIT (3)

NAME
exit - terminate a process after flushing any pending output
SYNOPSIS

exit (status)
lnt status;
DESCRIPTION
Exit terminates a process after calling the Standard 1/0 library function _cleanup to flush any

buffered output. Exit never returns.
SEE ALSO

exit (2) , intro(3S)

4th Berkeley Distribution

1 Apri11983

1

FREXP (3)

UNIX Programmer's Manual

FREXP(3)

NAME

frexp, ldexp, modf - split into mantissa and exponent
SYNOPSIS

double frexp (value, eptr)
double value;
lnt .eptr;
double
double
double
double

Idexp (value, exp)
value;
modf(value, Iptr)
value, .Iptr;

DESCRIPTION

Frexp returns the mantissa of a double value as a double quantity, x, of magnitude less than 1
.
and stores an integer n such that value - x- 2 n indirectly through eptr.
Ldexp returns the quantity value- Pp.
Modi returns the positive fractional part of value and stores the integer part indirectly through
iplr.

7th Edition

19 January 1983

1

GETBANNER(3)

UNIX Programmer's Manual

GETBANNI~I{ (3)

NAME

getbanner - get system login banner string
SYNOI)SIS

char *gdhanncr();
cc files ... - Igctty .
DI~~CI{IPTION

Gelballller tries to extract the im (initial message) field from the default entry in letc/gettytab (see
gNI),lab(S». It then decodes the initial message according to the gellylab specifications (including

possible hostname substitution and alteration via the 1m and he fields),. and returns a pointer to the
static string. If letc/gcttytab docs not exist or the default entry can not be found, a default banner
is substituted.
FILES

lusrlstanfi>rd/lib/libgclly.a
Ictc/gettY~lb

SEE ALSO
gcttytab(5)
AUTHOR

Bill Blirgess

7th Edition

6 September 1984

1 .

GETENV(3)

UNIX Programmer's Manual

GETENV(3) .

NAME

getenv - value for environment name
SYNOPSIS

char -Ieteny(name)
char -name;
DESCRIPTION

Getenv searches the environment list (see environ(7» for a string of the form name-value and
returns a pointer to the string value if such a string is present, otherwise getenv returns the
value 0 (NULL).
.
SEE ALSO

environ (7), execve (2)

7th Edition

19 January 1983

1

GETGRENT (3 )

UNIX Programmer's Manual

GETGRENT ( 3 )

NAME
getgrent, getgrgid, getgrnam, setgrent, endgrent - get group file entry
SYNOPSIS

#lnclude < pp.h >
stnd poup -Ietlrent 0
stnd Iroup -Ietlqid (lid)
lnt lid;
stnct 1I'0up -Ietlmam (name)
char -name;
setlrentO
endlrentO
DESCIUPTION

Getgrent, getgrgid and getgrnam each return pointers to an object with the following structure
containing the broken-out fields of a line in the group file.
struct group
char
char
int
char
};

{ I- see getgrent(3) -/
.gr_name;
-gr..,passwd;
gr.Jid;
.-gr_mem;

struct group .getgrent 0, .getgrgid 0, -getgrnam 0;
The members of this structure are:
gr_name
gr..,passwd
gr..lid
gr_mem

The name of the group.
The encrypted password of the group.
The numerical group-ID.
Null-terminated vector of pointers to the individual member names.

Getgrent simply reads the next line while getgrgid and getgrnam search until a matching gid or
name is found (or until EOF is encountered). Each routine picks up where the others leave off
so successive calls may be used to search the entire file.
A call to setgrent has the effect of rewinding the group file to allow repeated searches. Endgrent
may be called to close the group file when· processing is complete.
FILES

letclgroup
SEE ALSO

getlogin(3), getpwent(3), group(S)
DIAGNOSTICS

A null pointer (0) is returned on EOF or error.

BUGS
All information is contained in a static area so it must be copied if it is to be saved.

7th Edition

19 January 1983

1

GETLOGIN (3 )

UNIX Programmer's Manual

GETLOGIN ( 3 )

NAME
getlogin - get login name
SYNOPSIS

char *Ietlolln 0
DESCRIPTION

Get/ogin returns a pointer to the login name as found in letclutmp. It may be used in conjunction with getpwnam to locate the correct password file entry when the same use rid is shared by
several login names.
If get/ogin is called within a process that is not attached to a typewriter, it returns NULL. The
correct procedure for determining the login name is to first call get/ogin and if it fails, to call
getpw(getuidO) .
FILES

letc/utmp
SEE ALSO

getpwent(3), getgrent(3) , utmp(S), getpw(3)
DIAGNOSTICS

'Returns NULL (0) if name not found.

BUGS
The return values point to static data whose content is overwritten by each call.

7th Edition

19 January 1983

1

GETPASS (3)

UNIX Programmer's Manual

GETPASS (3)

NAME

getpass - read a password
SYNOPSIS

char .Ietpsss (prompt)
char .prompt;
DESCRIPTION

Getpass reads a password from the file Idevltry, or if that cannot be opened, from the standard
input, after prompting with the null-terminated string prompt and disabling echoing. A pointer
is returned to a null-terminated string of at most 8 characters.
FILES

Idev/tty
SEE ALSO

crypt (3)

BUGS
The return value points to static data whose content is overwritten by each call.

7th Edition

19 January 1983

1

GETPWENT (3 )

UNIX Programmer's Manual

GETPWENT ( 3 )

NAME

getpwent, getpwuid, getpwnam, setpwent, endpwent - get password file entry
SYNOPSIS

#Include < p"d.h >
struct passwd -getpwentO
struet passwd -getpwuld (uld)
Int uld;
struet passwd -getpwnam (name)
char -name;
Int setpwentO
Int endpwentO
DESCRIPTION

Getpwent, getpwuid and getpwnam each return a pointer to an object with the following structure
containing the broken-out fields of a line in the password file.
struct passwd ( /- see getpwent(3) ./
char
.pw_name;
char
.pw-passwd;
int
pw_uid;
int
pW...Jid;
int
pw_quota;
char
.pw_comment;
char
.pw...Jecos;
char
.pw_dir;
.pw_shell;
char

};
struct passwd -getpwent (), .getpwuid (), .getpwnam 0 ;
The fields pw_quota and pw_comment are unused; the others have meanings described in
passwd(S).

Getpwent reads the next line (opening the file if necessary); setpwent rewinds the file; endpwent
closes it.
Getpwuid and getpwnam search from the beginning until a matching uid or name is found (or
until EOF is encountered).
FILES

/etc/passwd
SEE ALSO

getlogin(3), getgrent(3), passwd(S)
DIAGNOSTICS

Null pointer (0) returned on EOF or error.

BUGS
All information is contained in a static area so it must be copied if it is to be saved.

7th Edition

19 January 1983

1

GETWD(3)

UNIX Proarammer's Manual

GETWD(3)

NAME·

letwd - let current woran, directory pathname
SYNOPSIS

char ..etwd (p.tha.....)
char .p.thaame;
DESCRIPTION

Getwd copies. the absolute pathname of the current working directory to pathname and returns a
pointer to the result.
LIMITATIONS

Maximum pathname leqth is MAXPATHLEN characters (1024).
DIAGNOSTICS

Getwd returns zero and places a message in pathname if an error occurs.
BUGS

Getwd may fail to return to the current directory if an error occurs.

4th Berkeley Distribution

25 February 1983

1

INSQUE(3)

UNIX Programmer's Manual

INSQUE (3)

NAME

insque, remque - insert/remove element from a queue
SYNOPSIS

struct qelem (
struct qelem *qJonv;
struct qelem *CLback;
char CLdatall;
);
insque (elem, prect)
struct qelem .elem, *pred;
remque(elem)
struct qelem .elem;
DESCRIPTION

Insque and remque manipulate queues built from doubly linked lists. Each element in the
queue must in the form of "struct qelem". Insque inserts elem in a queue imediately after
pred; remque removes an entry elem from a queue.
SEE ALSO

"VAX Architecture Handbook", pp. 228-235.

4th Berkeley Distribution

18 July 1983

1

MALLOC(3)

UNIX Programmer's Manual

MALLOC(3)

NAME

malice, free, realloc, calloc, alloca - memory allocator
SYNOPSIS

char -malloc(size)
unsigned size;
free (ptr)
char -ptr;
char -realloc(ptr, size}
char -ptr;
unsigned size;
char -calloc(nelem, elsize}
unsigned nelem, elsize;
char -alloca {size}
Int size;
DESCRIPTION

Mal/oc and free provide a simple general-purpose memory allocation package. Mal/oc returns a
pointer toa block of at least size bytes beginning on a word boundary.
The argument to free is a pointer to a block previously allocated by mal/oc; this space is made
available for further allocation, but its contents are left undisturbed.
Needless to say, grave disorder will result if the space assigned by malloc is overrun or if some
random number is handed to free.

Malloc maintains multiple lists of free blocks according to size, allocating space· from the
appropriate list. 1.t calls sbrk (see brk(2» to get more memory from the system when there is
no suitable space already free.
Realloc changes the size of the block pointed to by plr to size bytes and returns a pointer to the
(possibly moved) block. The contents will be unchanged up to the lesser of the new and old
sizes.
In order to be compatible with older versions, realloe also works if plr points to a block freed
since the last call of malloc, realloc or calloe; sequences of free, malloc and realloc were previously used to attempt storage compaction. This procedure is no longer recommended.

Cal/oc allocates space for an array of nelem elements of size elsize. The space is initialized to
zeros.

Alloca allocates size bytes of space in the stack frame of the caller. This temporary space is
automatically freed on return.
Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer
coercion) for storage of any type of object.
DIAGNOSTICS

Malloc, realloc and cal/oc return a null pointer (0) if there is no available .memory or if the
arena has been detectably corrupted by storing outside the bounds of a bloCk. Mal/oc may be
recompiled to check the arena very stringently on every transaction; those sites with a source
code license may check the source code to see how this can be done.
BUGS

When realloc returns 0, the block pointed to by plr may be destroyed.

AI/oca is machine dependent; it's use is discouraged.

4th Berkeley Distribution

19 January 1983

1

MKTEMP(3)

UNIX Programmer's Manual

MKTEMP(3)

NAME

mktemp -- make a unique file name
SYNOPSIS

char -mktemp(template)
char -template;
DESCRIPTION
Mktemp replaces template by a unique file name, and returns the address of the template. The

template should look like a file name with six trailing X's, which will be replaced with the
current process id and a unique letter.
SEE ALSO

getpid(2)

7th Edition

19 January 1983

1

MONITOR (3)

UNIX Programmer's Manual

MONITOR (3)

NAME

monitor, monstartup, moncontrol - prepare execution profile
SYNOPSIS

monltor(Iowpc, hlahpc, buffer, bufslze, nfune}
lnt .(*lowpc) 0, (*h1abpc) 0;
short bufferII ;
mObstartup (Iowpc, hlahpe)
Int (*lowpc}O, (*highpe)();
moncontrol (mode)
DESCRIPTION

There are two different forms of monitoring available: An executable program created by:
cc -p ...
automatically includes calls for the proj(l) monitor and includes an initial call to its start-up
routine monstartup with default parameters; monitor need not be called explicitly except to gain
fine control over profil buffer allocation. An executable program created by:
cc -pg ...
a~tomatically

includes calls for the gproj(I) monitor.

Monstartup is a high level interface to projil(2). Lowpc and highpc specify the address range that
is to be sampled; the lowest address sampled is that of lowpc and the highest is just below
highpc. Monstartup allocates space· using sbrk(2) and passes it to monitor (see below) to record a
histogram of periodically sampled values of the program counter, and of counts of calls of certain functions, in the buffer. Only calls of functions compiled with the profiling option -p of
cc (1) are recorded.
To profile the entire program, it is sufficient to use
extern etext 0;
monstartup «int) 2, etext);

Etext lies just above all the program text, see end(3).
To stop execution monitoring and write the results on the file mon.out, use
monitor (0) ;
then proj(l) can be used to examine the results.

Moncontrol is used to selectively control profiling within a program. This works with either
proj(l) or gproj(l) type profiling. When the program starts, profiling begins. To stop the collection of histogram ticks and call counts use moneontro/(O); to resume the collection of histogram ticks and call counts use moneontro/( 1). This allows the cost of particular operations to be
measured. Note that an output file will be produced upon program exit irregardless of the state
of moneontrol.
Monitor is a low level interface to projil(2). Lowpc and highpc are the addresses of two func·
tions; btd/'er is the address of a (user supplied) array of bujsize short integers. At most nfunc
call counts can be kept. For the results to be Significant, especially where there are small,
heavily used routines, it is suggested that the buffer be no more than a few times smaller than
the range of locations sampled. Monitor divides the buffer into space to record the histogram of
program counter samples over the range lowpc to highpc, and space to record call counts of
functions compiled with the -p option to ceO).
.

4th Berkeley Distribution

19 January 1983

1

UNIX Programmer's Manual

MONITOR (3)

MONITOR (3)

To profile the entire program, it is sufficient to use
extern etext 0;
monitor ( (int) 2, etext, buf, bufsize, nfunc);
FILES

mon.out
SEE ALSO

cc (1), prof(1), gprof(1), profiI(2), sbrk (2)

4th Berkeley Distribution

19 January 1983

2

NLIST(3)

UNIX Programmer's Manual

NLIST (3)

NAME

nlist - get entries from name list
SYNOPSIS

#include < nlist.h >
nUst (fllename, nO
char -fllename;
struct nUst nl II;

DESCRIPTION

Nlist examines the name list in the given executable output file and selectively extracts a list of
values. The name list consists of an array of structures containing names, types and values.
The list is terminated with a null name. Each name is looked up in the name list of the file. If
the name is found, the type and value of the name are inserted in the next two fields. If the
name is not found, both entries are set to O. See a.out(S) for the structure declaration.
This subroutine is useful for examining the system name list kept in the file /vmunix. In this
way programs can obtain system addresses that are up to date.
SEE ALSO

a.out(S)
DIAGNOSTICS

All type entries are set to 0 if the file cannot be found or if it is not a valid name list.

4th Berkeley Distribution

19 January 1983

1

PERROR (3)

PERROR(3)

UNIX Programmer's Manual

NAME

perror, sys_errlist, sys_nerr - system error messages
SYNOPSIS

perror(s)
char .s;
lnt sys_Derr;
char .sys_errlist(J;
DESCRIPTION

Perror produces a short error message on the standard error file describing the last error
encountered during a call to the system from a C program. First the argument string s is
printed, then a colon, then the message and a new-line. Most usefully, the argument string is
the name of the program which incurred the error. The error number is taken from the external variable errno (see intro(2», which is set when errors occur but not cleared when nonerroneous calls are made.
To simplify variant formatting of messages, the vector of message strings sys_errlist is provided;
errno can be used as an index in this table to get the message string without the newline.
Sys_nerr is the number of messages provided for in the table; it should be checked because new
error codes may be added to the system before they are added to the table.
SEE ALSO

intro (2), psignal (3)

J

4th Berkeley Distribution

19 January 1983

1

PSIGNAL (3)

UNIX Programmer's Manual

PSIGNAL (3)

NAME

psignal, sys_siglist - system signal messages
SYNOPSIS

psignal (sig, s)
unsigned sig;
char -s;
char -sys_siglist(J;
DESCRIPTION
Psignal produces a short message on the standard error file describing the indicated signal. First

the argument string s is printed, then a colon, then the name of the signal and a new-line.
Most usefully, the argument string is the name of the program which incurred the signal. The
signal number should be from among those found in .
To simplify variant formatting of signal names, the vector of message strings sys_siglist is provided; the signal number can be used as an index in this table to get the signal name without
the newline. The define NSIG defined in  is the number of messages provided for
in the table; it should be checked because new signals may be added to the system before they
are added to the table.
SEE ALSO

sigvec(2), perror(3)

4th Berkeley Distribution

25 February 1983

1

QSORT(3)

UNIX Programmer's Manual

QSORT (3)

NAME

qsort - quicker sort
SYNOPSIS

qsort (base, nel, width, compar)
char -base;
int (-compar) 0;
DESCRIPTION

Qsort is an implementation of the quicker-sort algorithm. The first argument is a pointer to the
base of the data; the second is the number of elements; the third is the width of an element in
bytes; the last is the name of the comparison routine to be called with two arguments which are
pointers to the elements being compared. The routine must return an integer less than, equal
to, or greater than 0 according as the first argument is to be considered less than, equal to, or
greater than the second.
SEE ALSO

sortO)

4th Berkeley Distribution

19 January 1983

1

RANDOM (3)

UNIX Programmer's Manual

RANDOM (3)

NAME

random, srandom, initstate, setstate - better random number generator; routines for changing
generators
SYNOPSIS

long random 0
srandom (seed)
lnt seed;
char -initstate (seed, state, n)
unsigned seed;
char -state;
Int n;
char -setstate (state)
char -state;
DESCRIPTION

Random uses a non-linear additive feedback random number generator employing a default
table of size 31 long integers to return successive pseudo-random numbers in the range from 0
to 231 _1. The period of this random number generator is very large, approximately
16*(2 31 - O.
Random/srandom have (almost) the same calling sequence and initialization properties as
rand/srand. The difference is that rand(3) produces a much less random sequence -- in fact, the
low dozen bits generated by rand go through a cyclic pattern. All the bits generated by random
are usable. For example, "randomO&Ol" will produce a random binary value.
Unlike srand, srandom does not return the old seed; the reason for this is that the amount of
state information used is much more than a single word. (Two other routines are provided to
deal with restarting/changing random number generators). Like rand(3), however, random will
by default produce a sequence of numbers that can be duplicated by calling srandom with J as
the seed.
The initstate routine allows a state array, passed in as an argument, to be initialized for future
use. The size of the state array (in bytes) is used by initstate to decide how sophisticated a random number generator it should use -- the more state, the better the random numbers will be.
(Current "optimal" values for the amount of state information are 8, 32, 64, 128, and 256
bytes; other amounts will be rounded down to the nearest known amount. Using less than 8
bytes will cause an error). The seed for the initialization (which specifies a starting point for
the random number sequence, and provides for restarting at the same point) is also an argument. Initstate returns a pointer to the previous state information array.
Once a state has been initialized, the setstate routine provides for rapid switching between
states. Setstate returns a pointer to the argument state array is used for further random number
generation until the next call to initstate or setstate.
Once a state array has been initialized, it may be restarted at a different point either by calling
initstate (with the desired seed, the state array, and its size) or by calling both setstate (with the
state array) and srandom (with the desired seed). The advantage of calling both setstate and
srandom is that the size of the state array does not have to be remembered after it is initialized.
With 256 bytes of state information, the period of the random number generator is greater than
269, which should be sufficient for most purposes.
AUTHOR

Earl T. Cohen

4th Berkeley Distribution

19 January 1983

1

RANDOM (3)

UNIX Programmer's Manual

RANDOM (3)

DIAGNOSTICS

If initstate is called with less than 8 bytes of state information, or if setstate detects that. the state
information has been garbled, error messages are printed on the standard error output.
SEE ALSO

rand (3)
BUGS

About 2/3 the speed of rand(3C).

4th Berkeley Distribution

19 January 1983

2

REGEX(3)

UNIX Programmer's Manual

REGEX(3)

NAME
re_comp, re_exec - regular expression handler
SYNOPSIS

char .re_comp(s)
char .s;
re_exee(s)
char .s;
DESCRIPTION

Re_comp compiles a string into an internal form suitable for pattern matching. Re_exec checks
the argument string against the last string passed to re_comp.
Re_comp returns 0 if the string s was compiled successfully; otherwise a string containing an error message is returned. If re_comp is passed 0 or a null string, it returns without changing the
currently compiled regular expression.

Re_exec returns 1 if the string s matches the last compiled regular expression, 0 if the string s
failed to match the last compiled regular expression, and - 1 if the compiled regular expression
was invalid (indicating an internal error).
The strings passed to both re_comp and re_exec may have trailing or embedded newline characters; they are terminated by nulls. The regular expressions recognized are described in the
manual entry for ed(1), given the above difference.
SEE ALSO

ed(1), ex(l), egrep(t), fgrep(l), grep(1)
DIAGNOSTICS

Re_exec returns -1 for an internal error.
Re_comp returns one of the following strings if an error occurs:
No previous regular expreSSion,
Regular expression too long,
unmatched \ (,
missing ],
too many \ f\) pairs,
unmatched \).

4th Berkeley Distribution

29 February 1980

1

SCANDIR(3)

UNIX Programmer's Manual

SCANDIR(3)

NAME

scandir - scan a directory
SYNOPSIS

#lnclude < sys/types.h >
#lnclude < sys/dlr.h >
scandlr(dlrname, namellst, select, compar)
char .dlmame;
struct direct _(enamellstll>;
lnt (.select> ();
Int (.compar> ();
alphasort(dt, dl)
struct direct eedt, e.dl;

DESCRIPTION

Scandir reads the directory dirname and builds an array of pointers to directory entries using
malloc(3). It returns the number of entries in the array and a pointer to the array through
name/ist.
The select parameter is a pointer to a user supplied subroutine which is called by scandir to
select which entries are to be included in the array. The select routine is passed a pointer to a
directory entry and should return a non-zero value if the directory entry is to be included in the
array. If select is null, then all the directory entries will be included.
The compar parameter is a pointer to a user supplied subroutine which is passed to qsort(3) to
sort the completed array. If this pointer is null, the array is not sorted. A /phasort is a routine
which can be used for the compar parameter to sort the array alphabetically.
The memory allocated for the array can be deallocated with free (see malloc(3» by freeing each
pointer in the array and the array itself.
SEE ALSO

directory (3) , malloc(3), qsort(3), dir(S)
DIAGNOSTICS

Returns -1 if the directory cannot be opened for reading or if malloc(3) cannot allocate
enough memory to hold all the data structures.

4th Berkeley Distribution

19 January 1983

1

SETJMP(3)

UNIX Programmer's Manual

SETJMP (3)

NAME

setjmp, longjmp - non-local goto
SYNOPSIS

#include 
setJmp(env)
Jmp_buf env;
longJmp(env, val)
Jmp_buf env;
_setJmp(env)
Jmp_buf env;
_longJmp(env, val)
Jmp_buf env;
DESCRIPTION

These routines are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program.
Setjmp saves its stack environment in env for later use by longjmp. It returns value O.
Longjmp restores the environment saved by the last call of setjmp. It then returns in such a way
that execution continues as if the call of setjmp had just returned the value val to the function
that invoked setjmp, which must not itself have returned in the interim. All accessible data
have values as of the time longjmp was called.
Setjmp and longjmp save and restore the signal mask sigmask(2), while _setjmp and _Iongjmp

manipulate only the C stack and registers.
SEE ALSO

sigvec (2), sigstack (2), signal (3)

BUGS
Setjmp does not save current notion of whether the process is executing on the signal stack.
The result is that a longjmp to some place on the signal stack leaves the signal stack state incorrect.

4th Berkeley Distribution

19 January 1983

1

SETUID (3)

UNIX Programmer's Manual

SETUID (3)

NAME

setuid, seteuid, setruid, setgid, setegid, setrgid - set user and group ID
SYNOPSIS
setuid (uld)
seteuid (euid)
setruid (ruid)

setgid (gid)
setegid (egid)
setrgid (rgid)
DESCRIPTION
Setuid (setgid) sets both the real and effective· user ID (group ID) of the current process to as

specified.
Seteuid (setegid) sets the effective user ID (group 1D) of the current process.
Setruid (setruid) sets the real user ID (group ID) of the current process.

These calls are only permitted to the super-user or if the argument is the real or effective ID.
SEE ALSO

setreuid (2), setregid (2), getuid (2), getgid (2)
DIAGNOSTICS

Zero is returned if the user (group) ID is set; -1 is returned otherwise.

4th Berkeley Distribution

1 April 1983

1

SLEEP (3)

UNIX Programmer's Manual

SLEEP (3)

NAME

sleep - suspend execution for interval
SYNOPSIS

sleep (seconds)
unsigned seconds;
DESCRIPTION

The current process is suspended from execution for the number of seconds specified by the
argument. The actual suspension time may be up to I second less than that requested, because
scheduled wakeups occur at fixed I-second intervals, and an arbitrary amount longer because of
other activity in the system.
The routine is implemented by setting an interval timer and pausing until it occurs. The previotis state of this timer is saved and restored. If the sleep time exceeds the time to the expiration of the previous timer, the process sleeps only until the signal would have occurred, and the
signal is sent 1 second later.
SEE ALSO

setitimer(2), sigpause(2)

BUGS
An interface with finer resolution is needed.

4th Berkeley Distribution

19 January 1983

STRCMPFOLD( 3)

UN IX Programmer's Manual

STRCMPI;OlJ)(J)

NAME
strcmpfbld, strncmpfold - case-folded string compaJison operations
SYNOPSIS

strcmpfold(s I, s2)
char *sl, *s2;
strncmpfoJd(s I, s2, n)
clw r *sl, *s2;
[)1~ScnIP·rl.ON

These functions operate 011 null-terminated strings. They ignore case in comparisons; e.g., "CAT"
and "Cat" compare equal, and "cat" collates before "DOG". Otherwise, they are the same as the
slrcmp and slmcl11p functions described in slring(.3)..
.
StrcmpjiJld compares its arglllllenL<) and returns an integer greater than, equal to, or less than 0,
according as sl is lexicogmphically greater tlwn. equal to, or less than s2. Slmcmpji>/d makes the
same comparison but looks at at most 11 characters.
SEl!: ALSO

slring(3)
BUGS

The name of stmcmpjhld is not unique in its first seven characters, and thus cannot be ported to
some implementations of C.
These functions arc currently unique to Stanford, and so programs using them may not he portable.

4th Berkeley Distribution

Stallfbrd

1

STRING (3)

UNIX Programmer's Manual

STRING (3)

NAME

strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, index, rindex - string operations
SYNOPSIS

#include

< strings.h >

char *strcat
openlog (ident, logstat)
char .ident~
syslog (priority, message, parameters ... )
char .message~
closelog 0
DESCRIPTION

Syslog arranges to write the message onto the system log maintained by syslog(S). The message
is tagged with priority. The message looks like a print/OJ string except that %m is replaced by
the current error message (collected from errno). A trailing newline is added if needed. This
message will be read by syslog(8) and output to the system console or files as appropriate.
If special processing is needed, open log can be called to initialize the log file. Parameters are
ident which is prepended to every message, and logstat which is a bit field indicating special
status~ current values are:

LOG_PID

log the process id with each message: useful for identifying instantiations of daemons.

Openiog returns zero on success. If it cannot open the file /devliog, it writes on Idevlconsole
instead and returns -1.
Closelog can be used to close the log file.
EXAMPLES

syslog(LOG_SALERT, "who: internal error

23")~

openlog ("serverftp", LOG_PID);
syslog(LOG_INFO, "Connection from host %d", CallingHost);
SEE ALSO

syslog(S)

7th Edition

1

SYSTEM (3)

UNIX Programmer's Manual

SYSTEM (3)

NAME

system - issue a shell command
SYNOPSIS

s,stem (striDI)
char estrlnl;
DESCRIPTION

System causes the string to be given to shU) as input as if the string had been typed as a command at a terminal. The current process waits until the shell has completed, then returns the
exit status of the shell.
SEE ALSO

popen (3S), execve (2), wait (2)
DIAGNOSTICS

Exit status 127 indicates the shell couldn't be executed.

7th Edition

19 January 1983

1

TIYNAME(3)

UNIX Programmer's Manual

TIYNAME(3)

NAME

ttyname, isatty, ttyslot - find name of a terminal
SYNOPSIS

char -ttyname (flledes)
Isatty (flledes)
ttyslotO
DESCRIPTION

Ttyname returns a pointer to the, null-terminated path name of the terminal device' associated
with file descriptor JUedes (this is a system file descriptor and has nothing to do with the standard I/O FILE typedeO.
lsatty returns 1 if JUedes is associated with a terminal device, 0 otherwise.
Ttyslot returns the number of the entry in the ttys(S) file for the control terminal of the current
process.
FILES

/dev//etc/ttys
SEE ALSO

ioctl(2), ttys(5)
DIAGNOSTICS

Ttyname returns a null pointer (0) if JUedes does not describe a terminal device in directory
'/dev'.

Ttyslot returns 0 if '/etc/ttys' is inaccessible or if it cannot determine the control terminal.
BUGS

The return value points to static data whose 'content is overwritten by each call.

7th Edition

19 January 1983

1

VALLOC(3)

UNIX Programmer's Manual

VALLOC(3)

NAME
valloc - aligned memory allocator
SYNOPSIS

ehar *"alloe(size)
uDsilDed size;
DESCRIPTION

Yalloe allocates size bytes aligned on a page boundary. It is implemented by calling mal/oc(3)
with a slightly larger request, saving the true beginning of the block allocated, and returning a
properly aligned pointer.
DIAGNOSTICS

Yalloc returns a null pointer (0) if there is no available memory or if the arena has been detectably corrupted by storing outside the bounds of a block.
BUGS

Yfree isn't implemented.

3rd Berkeley Distribution

19 January 1983

1

VARARGS(3)

VARARGS(3}

UNIX Programmer's Manual

NAME

varargs - variable argument list
SYNOPSIS

#lnelude

< varargs.h >

jUnction( va_allst>

va_del
va_list pvar;
va_start(pvar);
f - va_ara(pvar, type);

va_end(pvar);
DESCRIPTION

This set of macros provides a means of writing portable procedures that accept variable argument lists. Routines having variable argument lists (such as prinif(3)} that do not use varargs
are inherently nonportable, since different machines use different argument passing conventions.
va_allst is used in a function header to. declare a variable argument list.
va_del is a declaration for va_alist. Note that there is no semicolon after va_del.
va_list is a type which can be used for the variable pvar, which is used to traverse the list. One
such variable must always be declared.
va_start(pvar) is called to initialize pvar to the beginning of the list.
va_llI'I(pvar, type} 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, since it cannot be determined at runtime.
va_end(pvar) is used to finish up.

Multiple traversals, each bracketed by va_start ... va_end, are possible.
EXAMPLE

#lnelude < varargs.h >
execl (va_allst>
va del

(

-

va_list ap;
ehar .file;
ehar .args[100];
lnt argno - 0;
va_start(ap);
file - va_ara(ap, ehar .);
while (argsllll'lno+ +J - va_aq(ap, ehar
;
va_end(ap);
retum exeev (lie, arlls);

.»

}
BUGS
It is up· to the calling routine to determine how many arguments there are, since it is not possible to determine this from the stack frame. For example, exec/ passes a 0 to signal the end of
the list. Prinifcan tell how many arguments are supposed to be there by the format.

7th Edition

19 January 1983

1

INTRO(3F)

UNIX Programmer's Manual

INTRO (3F)

NAME

intro - introduction to FORTRAN library functions
DESCRIPTION

This section describes those functions that are in the FORTRAN run time library. The functions listed here provide an interface from j77 programs to the system in the same manner as
the C library does for C programs. They are automatically loaded as needed by the Fortran
compiler j77( 1) .
Most of these functions are in libU77.a. Some are in UbF77.a or libI77.a. A few intrinsic functions are described for the sake of completeness.
For efficiency, the SCCS 10 strings are not normally included in the a.out file. To include them,
simply declare
external n7lid
in any j77 module.
LIST OF FUNCTIONS

Name

abort
access
alarm
bessel
bit
chdir
chmod
ctime
dffrac
dflmax
dflmin
drand
dtime
etime
exit
fdate
ffrac
fgetc
flmax
flmin
flush
fork
fpecnt
fputc
fseek
fstat
ftell
gerror
getarg
getc
getcwd
getenv
getgid
getlog

Appears on Page

abort.3f
access.3f
alarm.3f
besse1.3f
bit.3f
chdir.3f
chmod.3f
time.3f
flmin.3f
flmin.3f
flmin.3f
rand.3f
etime.3f
etime.3f
exit.3f
fdate.3f
flmin.3f
getc.3f
flmin.3f
flmin.3f
flush.3f
fork.3f
trpfpe.3f
putc.3f
fseek.3f
stat.3f
fseek.3f
perror .3f
getarg.3f
getc.3f
getcwd.3f
getenv.3f
getuid.3f
getlog.3f

4th Berkeley Distribution

Description

terminate abruptly with memory image
determine accessability of a file
execute a subroutine after a specified time
of two kinds for integer orders
and, or, xor, not, rshift, lshift bitwise functions
change default directory
change mode of a file
return system time
return extreme values
return extreme values
return extreme values
return random values
return elapsed execution time
return elapsed execution time
terminate process with status
return date and time in an ASCII string
return extreme values
get a character from a logical unit
return extreme values
return extreme values
flush output to a logical unit
create a copy of this process
trap and repair floating point faults
write a character to a fortran logical unit
reposition a file on a logical unit
get file status
reposition a file on a logical unit
get system error messages
return command line arguments
get a character from a logical unit
get pathname of current working directory
get value of environment variables
get user or group 10 of the caller
get user's login name

26 July 1983

1

INTRO(3F)

getpid
getuid
gmtime
hostnm
iargc
idate
ierrno
index
inmax
intro
ioinit
irand
isatty
itime
kill
len
link
lnblnk
loc
long
Istat
ltime
perror
putc
qsort
rand
rename
rindex
short
signal
sleep
stat
system
tclose
time
topen
traper
trapov
tread
trewin
trpfpe
tskipf
tstate
ttynam
twrite
unlink
wait

UNIX Programmer's Manual

getpid.3f
getuid.3f
time.3f
hostnm.3f
getarg.3f
idate.3f
perror.3f
index.3f
flmin.3f
intro.3f
ioinit.3f
rand.3f
ttynam.3f
idate.3f
kill.3f
index.3f
link.3f
index.3f
loc.3f
long.3f
stat.3f
time.3f
perror.3f
putc.3f
qsort.3f
rand.3f
r~name.3f

index.3f
long.3f
signa1.3f
sleep.3f
stat.3f
system.3f
topen.3f
time.3f
topen.3f
traper.3f
trapov.3f
topen.3f
topen.3f
trpfpe.3f
topen.3f
topen.3f
ttynam.3f
topen.3f
unlink.3f
wait.3f

4th Berkeley Distribution

INTRO (3F)

get process id
get user or group ID of the caller
return system time
get name of current host
return command line arguments
return date or time in numerical form
get system error messages
tell about character objects
return extreme values
introduction to FORTRAN library functions
change n7 I/O initialization
return random values
find name of a terminal port
return date or time in numerical form
send a signal to a process
tell about character objects
make a link to an existing file
tell about character objects
return the address of an object
integer object conversion
get file status
return system time
get system error messages
write a character to a fortran logical unit
quick sort
return random values
rename a file
tell about character objects
integer object conversion
change the action for a signal
suspend execution for an interval
get file status
execute a UNIX command
n7 tape 110
return system time
n7 tape 110
trap arithmetic errors
trap and repair floating point overflow
n7 tape I/O
n7 tape I/O
trap and repair floating point faults
n7 tape I/O
n7 tape I/O
find name of a terminal port
n7 tape I/O
remove a directory entry
wait for a process to terminate

26 July 1983

2

ABORT (3F)

UNIX Programmer's Manual

ABORT (3F)

NAME

abort - terminate abruptly with memory image
SYNOPSIS

subroutine abort (striog)
character- (-) string
DESCRIPTION

Abort cleans up the 110 buffers and then aborts producing a core file in the current directory. If
string is given, it is written to logical unit 0 preceeded by "abort:".
FILES

lusrllib/libF77.a
SEE ALSO

abort (3)

BUGS
String is ignored on the PDPll.

4th Berkeley Distribution

18 July 1983

1

ACCESS (3F)

UNIX Programmer's Manual

ACCESS (3F)

NAME

access - determine accessability of a file
SYNOPSIS

integer function access (name, mode)
character- (-) name, mode
DESCRIPTION

Access checks the given file, name, for accessability with respect to the caller according to mode.
Mode may include in any order and in any combination one or more of:
r
w
x

(blank)

test
test
test
test

for
for
for
for

read permission
write permission
execute permission
existence

An error code is returned if either argument is illegal, or if the file can not be accessed in all of
the specified modes. 0 is returned if the specified access would be successful.
FILES

lusr llib/libU77.a
SEE ALSO

access (2) , perror(3F)

BUGS
Pathnames can be no longer than MAXPATHLEN as defined in .

4th Berkeley Distribution

26 July 1983

1

ALARM (3F)

UNIX Programmer's Manual

ALARM (3F)

NAME

alarm - execute a subroutine after a specified time
SYNOPSIS

integer function alarm (time, proc)
integer time
external proc
DESCRIPTION

This routine arranges for subroutine proc to be called after time seconds. If time is "0", the
alarm is turned off and no routine will be called. The returned value will be the time remaining
on the last alarm.
FILES

lusr/lib/libU77.a
SEE ALSO

alarm(3C), sleep(3F), signaH3F)
BUGS

Alarm and sleep interact. If sleep is called after alarm, the alarm process will never be called.
SIGALRM will occur at the lesser of the remaining alarm time or the sleep time.

4th Berkeley Distribution

18 July 1983

1

BESSEL (3F)

UNIX Programmer's Manual

BESSEL (3F)

NAME

bessel functions - of two· kinds for integer orders
SYNOPSIS

function besjO (x)
function besjl (x)
function besjn (n, x)
function besyO (x)
function besyl (x)
function besyn (n, x)
double precision function dbesjO (x)
double precision x
double precision function dbesjl (x)
double precision x
double precision function dbesjn (n, x)
double precision x
double precision function dbesyO (x)
double precision x
double precision function dbesyl (x)
double precision x
double precision function dbesyn (n, x)
double precision x
DESCRIPTION

These functions calculate Bessel functions of the first and second kinds for real arguments and
integer orders.
DIAGNOSTICS

Negative arguments cause besyO, besyJ, and besyn to return a huge negative value. The system
error code will be set to EDOM (33).
FILES

lusrIlib/libF77.a
SEE ALSO

jO(3M), perror(3F)

4th Berkeley Distribution

18 July 1983

1

BIT (3F)

UNIX Programmer's Manual

BIT (3F)

NAME

bit - and, or, xor, not, rshift, lshift bitwise functions
SYNOPSIS

{intrinsic} function and (wordt, word2)
(intrinsic) function or hvordl, word2)
{Intrinsic} function xor (wordt, word2)
(intrinsiC> function not (word)
(intrinsic) function rshift (word, nbits)
(intrinsic) function Ishift (word, nbits)
DESCRIPTION

These bitwise functions are built into the compiler and return the data type of their
argument(s). It is recommended that their arguments be integer values; inappropriate manipulation of real objects may cause unexpected results.
The bitwise combinatorial functions return the bitwise "and" (and), "or" (or), or "exclusive
or" (xor) of two operands. Not returns the bitwise complement of its operand.
Lshift, or rshift with a negative nbits, is a logical left shift with no end around carry. Rshift, or
Ishift with a negative nbits, is an arithmatic right shift with sign extension. No test is made for a
reasonable value of nbits.
FILES

These functions are generated in-line by the f77 compiler.

4th Berkeley Distribution

13 June 1983

1

CHDIR(3F)

CHOIR (3F)

UNIX Programmer's Manual

NAME

chdir - change default directory
SYNOPSIS

integer function chdir (dirname)
character- (-) dirname
DESCRIPTION

The default directory for creating and locating files will be changed to dirname. Zero is returned
if successful~ an error code otherwise.
FILES

lusrIlib/libU77.a
SEE ALSO

chdir(2), cd(I), perror(3F)

BUGS
Pathnames can be no longer than MAXP ATHLEN as defined in
Use of this function may cause inquire by unit to fail.

4th Berkeley Distribution

18 July 1983

< sys/param. h > .

1

CHMOD(3F)

CHMOD (3F)

UNIX Programmer's Manual

NAME

chmod - change mode of a file
SYNOPSIS

integer function chmod (name, mode)
character- (.) name, mode
DESCRIPTION

This function changes the filesystem mode of file name. Mode can be any specification recognized by chmodO). Name must be a single path name.
The normal returned value is O. Any other value will be a system error number.
FILES

lusr/lib/libU77.a
Ibin/chmod

exec'ed to change the mode.

SEE ALSO

chmod(l)

BUGS
Pathnames can be no longer than MAXP ATHLEN as defined in

4th Berkeley Distribution

18 July 1983

< sys/param. h > .

1

ETIME (3F)

UNIX Programmer's Manual

ETIME (3F)

NAME

etime, dtime - return elapsed execution time
SYNOPSIS

function etime 
character char
DESCRIPTION

These routines return the next character from a file associated with a fortran logical unit,
bypassing normal fortran 110. Getc reads from logical unit 5, normally connected to the control
terminal input.
The value of each function is a system status code. Zero indicates no error occured on the read;
-1 indicates end of file was detected. A positive value will be either a UNIX system error
code or an f77 110 error code. See perror(3P).
FILES

lusr/lib/libU77.a
SEE ALSO

.getc(3S), intro(2), l'error(3P)

4th Berkeley Distribution

13 June 1983

1

GETCWD(3F)

UNIX Programmer's Manual

GETCWD(3F)

NAME

getcwd - get pathname of current working directory
SYNOPSIS

integer funetion getcwd (dirname)
character. (.) dimame
DESCRIPTION

The pathname of the default directory for creating and locating files will be returned in dirname.
The value of the function will be zero if successful; an error code otherwise.
FILES

lusr/lib/libU77.a
SEE ALSO

chdir(3F), perror(3F)

BUGS
Pathnames can be no longer than MAXPATHLEN as defined in .

4th Berkeley Distribution

18 July 1983

1

GETENV(3F)

UNIX Programmer's Manual

GETENV (3F)

NAME

getenv - get value of environment variables
SYNOPSIS

sub..outine getenv (ename, evalue)
character- (.) ename, evalue
DESCRIPTION

Getenv searches the environment list (see environ(7» for a string of the form ename= va!ue and
returns va!ue in eva!ue if such a string is present, otherwise fills eva!ue with blanks.
FILES

lusr/lib/libU77.a
SEE ALSO

environ (7), execve (2)

4th Berkeley Distribution

18 July 1983

1

UNIX Programmer's Manual

GETFSENT (3X)

GETFSENT (3X)

NAME

getfsent, getfsspec, getfsfile, getfstype, setfsent, endfsent - get file system descriptor file· entry
SYNOPSIS

#include

< fstab.h >

strud fstab *getfsentO
strud fstab *getfsspec (spec)
char *spec;
strud fstab *getfsflle(ftle)
char *flle;
strud fstab -aetfstype.
struct fstab{
char
char
char
int
int

*fs_spec;
*fs_file;
*fs_type;
fs_freq;
fs-passno;

};
The fields have meanings described in jstab(S).

Get/sent reads the next line of the file, opening the file if necessary.
Se(jSent opens and rewinds the file.
Endj'sent closes the file.
Getfsspec and get/wle sequentially search from the beginning of the file until a matching special
file name or file system file name is found, or until EOF is encountered. Getfstype does likewise, matching on the file system type field.
FILES

letc/fstab
SEE ALSO

fstab(S)
DIAGNOSTICS

Null pointer (0) returned on EOF or error.
BUGS

All information is contained in a static area so it must be copied if it is to be saved.

4th Berkeley Distribution

19 January 1983

1

GETLOG (3F)

UNIX Programmer's Manual

GETLOG (3F)

NAME

getlog - get user's login name
SYNOPSIS

subroutine getlog (name)
character- (-) name
character- (-) function getlog ()
DESCRIPTION

Getlog will return the user's login name or all blanks if the process is running detached from' a
terminal.
FILES

lusr/Ub/libU77.a
SEE ALSO

getlogin (3)

4th Berkeley Distribution

13 June 1983

1

GETPID (3F)

UNIX Programmer's Manual

GETPID (3F)

NAME

getpid - get process id
SYNOPSIS

integer function getpld ()
DESCRIPTION

Getpid returns the process ID number of the current process.
FILES

lusrllib/libU77.a
SEE ALSO

getpid(2)

4th Berkeley Distribution

13 June 1983

1

GETUID(3F)

UNIX Programmer's Manual

GETUID (3F)

NAME

getuid, getgid - get user or group ID of the caller
SYNOPSIS

integer function getuld ()
integer function getgid ()
DESCRIPTION

These functions return the real user or group 10 of the user of the process.
FILES

lusrIlib/libU77.a
SEE ALSO

getuid(2)

4th Berkeley Distribution

13 June 1983

1

HOSTNM(3F)

UNIX Programmer's Manual

HOSTNM (3F)

NAME

hostnm - get name of current host
SYNOPSIS

integer function hostnm (name)
character- (-) name
DESCRIPTION

This function puts the name of the current host into character string name. The return value
should be 0; any other value indicates an error.
FILES

lusr Ilib/libU77.a
SEE ALSO

gethostname (2)

4th Berkeley Distribution

13 June 1983

1

IDATE(3F)

UNIX Programmer's Manual

IDATE (3F)

NAME

idate, itime - return date or time in numerical form
SYNOPSIS

suhroutine idate (larray)
integer iarray (3)
suhroutine itlme (larray)
integer iarray(3)
DESCRIPTION

Idate returns the current date in iarray. The order is: day, mon, year. Month will be in the
range 1-12. Year will be ~ 1969.
Itime returns the current time in iarray. The order is: hour, minute, second.
FILES

lusrIlib/libU77.a
SEE ALSO

ctime(3F), fdate(3F)

4th· Berkeley Distribution

13 June 1983

1

INDEX (3F)

UNIX Programmer's Manual

INDEX (3F)

NAME

index, rindex, lnblnk, len - tell about character objects
SYNOPSIS

(intrinsic) function index (string, substr>
character.(.) string, substr
integer function rindex (striDg, substr>
character.(.) string, substr
function lnblnk (string)
character. (.) string
(intrinsic) function len (string)
charader. (.) string
DESCRIPTION

Index (rindex) returns the index of the first (last) occurrence of the substring substr in string, or
zero if it does not occur. Index is an n7 intrinsic function; rindex is a library routine.
Lnblnk returns the index of the last non-blank character in string. This is useful since all n7
character objects are fixed length, blank padded. Intrinsic function len returns the size of the
character object argument.
FILES

lusrIlib/libF77 .a

4th Berkeley Distribution

13 June 1983

1

10INIT(3F)

UNIX Programmer's Manual

IOINIT(3F)

NAME
ioinit - change f77 1/0 initialization
SYNOPSIS
logical function loin It (eetl,bzro, apod, prefix, vrbose)
logical cdl, bzro, apod, vrbose
character- (-) prefix
DESCRIPTION
This routine will initialize several global parameters in the f77 110 system, and attach externally
defined files to logical units at run time. The effect of the Rag arguments applies to logical
units opened after ioinit is called. The exception is the preassigned units, S and 6, to which eetl
and bzro will apply at any time. /oinit is written in Fortran-77.
By default, carriage control is not recognized on any logical unit. If eetl is. true. then· carriage
control will be recognized on formatted output to all logical units except unit 0, the diagnostic
channel. Otherwise the default will be restored.
By default, trailing and embedded blanks in input data fields are ignored. If bzro is .true. then
such blanks will be treated as zero's. Otherwise the default will be restored.
By default, all files opened for sequential access are positioned at their beginning. It is sometimes necessary or convenient to open at the END-OF-FILE so that a write will append to the
existing data. If apnd is .true. then files opened subsequently on any logical unit will be posi'tioned at their end upon opening. A value of .false. will restore the default behavior.
Many systems provide an automatic association of global names with fortran logical units when
a program is run. There is no such automatic association in f77. However, if the argument
prefix is a non-blank string, then names of the form prefixNN will be sought in the program
environment. The value associated with each such name found will be used to open logical unit
NN for formatted sequential access. For example, if f77 program myprogram included the call
call ioinit (.true., .false., .false., 'FORT', .false.>
then when the following sequence
0/0 setenv FORTOI mydata
0/0 setenv FORT12 myresults
0/0 myprogram
would result in logical unit 1 opened to file mydata and logical unit 12 opened to file myresults.
Both files would be positioned at their beginning. Any formatted output would have column I
removed and interpreted as carriage control. Embedded and trailing blanks would be ignored
on input.
If the argument vrbose is .true. then ioinit will report on its activity.
The effc5ct of
call ioinit (.true., .true., .false., 1/, .false.)
ean be achieved without the actual call by including "-1166" on the j77 command line. This
gives carriage control on all logical units except 0, causes files to be opened at their beginning,
and causes blanks to be irlterpreted as zero's.
The internal flags are stored in a labeled common block with the following definition:
integer-2 ieof, ictt, ibzr

4th Berkeley Distribution

13 June 1983 .

1

IOINIT (3F)

UNIX Programmer's Manual

lOIN IT (3F)

common lioingl ieof, ictl, ibzr
FILES

lusrIlib/libI77.a
lusrIlib/libI66.a

f77 110 library
sets older fortran I/O modes

SEE ALSO

getarg(3F), getenv(3F), "Introduction to the f77 110 Library"

BUGS
Prefix can be no longer than 30 characters. A pathname associated with an environment name
can be no longer than 255 characters.
The U +" carriage control does not work.

4th Berkeley Distribution

13 June 1983

2

KILL (3F)

UNIX Programmer's Manual

KILL (3F)

NAME

kill - send a signal to a process
SYNOPSIS

function kill (pld, sllnum)
Integer pld, sllnum
DESCRIPTION
Pid must be the process id of one of the user's processes. Signum must be a valid signal
number (see sigvec(2». The returned value will be 0 if successful; an error code otherwise.
FILES

lusrIlib/libU77.a
SEE ALSO

kilI(2), sigvec(2), signal(3F), fork(3F), perror(3F)

4th Berkeley Distribution.

LINK (3F)

LINK (3F)

UNIX Programmer's Manual

NAME

link - make a link to an existing file
SYNOPSIS

function link (namel, namel)
character-(-) namel, name2
integer function symlnk (namel, n·ame2)
character-(-) namel, name2
DESCRIPTION

Namel must be the pathname of an existing file. Name} is a pathname to be linked to file
namel. Name} must not already exist. The returned value will be Oif successful; a system
error code otherwise.
Symlnk creates a symbolic link to name1.
FILES

lusr/lib/libU77.a
SEE ALSO

link(2), symlink(2), perror(3F), unlink(3F)
BUGS

Pathnames can be no longer than MAXPATHLEN as defined in

4th Berkeley Distribution

18 July 1983

< sys/param. h > .

1

LOC (3F)

UNIX Programmer's Manual

LOC (3F)

NAME

loe - return the address of an object
SYNOPSIS

function loc: (aq)
DESCRIPTION

The returned value will be the address of argo
FILES

lusrIlib/libU77.a

·4th Berkeley ;Distribution

13 June 1983

1

LONG (3F)

UNIX Programmer's Manual

LONG (3F)

NAME

long, short - integer object conversion
SYNOPSIS

integer.4 function IODg (lntl)
integer.l lntl
integer.l function short (tnt4)
integer.4 int4
DESCRIPTION

These functions provide conversion between short and long integer objects. Long is useful
when constants are used in calls to library routines and the code is to be compiled with H-i2".
Short is useful in similar context when an otherwise long object must be passed as a short
integer.
FILES

lusr Ilib/libF77.a

4th Berkeley Distribution

26 July 1983

1

PERROR(3F)

UNIX Programmer's Manual

PERROR(3F)

NAME

perror, gerror, ierrno - get system error messages
SYNOPSIS

subroutine perror (string)
character- (-) string
subroutine gerror (string)
character- (-) string
character-(-) function gerrorO
function ierrno ()
DESCRIPTION

Perror will write a message to fortran logical unit 0 appropriate to the last detected system error.
String will be written preceding the standard error message.
Gerror returns the system error message in character variable string. Gerror may be called either
as a subroutine or as a function.
Ierrno will return the error number of the last detected system error. This number is updated
. only when an error actually occurs. Most routines and I/O statements that might generate such
errors return an error code after the call; that value is a more reliable indicator of what caused
the error condition.
FILES

/usr /lib/lib U77 .a
SEE ALSO

intro(2), perror(3)
D. L. Wasley, Introduction to the}77 110 Library

BUGS
String in the call to perror can be no longer than 127 characters.
The length of the string returned by gerror is determined by the calling program.
NOTES

UNIX system error codes are described in intro (2). The f77 110 error codes and their meanings are:
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

4th

Berkel~y

Distribution

"error in format"
"illegal unit number"
"formatted io not allowed"
"unformatted io not allowed"
"direct io not allowed"
Hsequential io not allowed"
"can't backspace file"
"off beginning of record"
"can't stat file"
"no • after repeat count"
"off end of record"
"truncation failed"
"incomprehensible list input"
"out of free space"
"unit not connected"
"read unexpected character"

13 June 1983

1

PERROR(3F)

UNIX Programmer's Manual

116
117
118
119
120
121
122
123

4th Berkeley Distribution

PERROR (3F)

"blank logical input field"
'''new' file exists"
"can't find 'old' file"
"unknown system error"
"requires seek ability"
"illegal argument"
"negative repeat count"
"illegal operation for unit"

13 June 1983

2

PUTC (3F)

UNIX Programmer's Manual

PUTC (3F)

NAME

putc, fputc - write a character to a fortran logical unit
SYNOPSIS

integer function putc (char)
character char
integer function fputc Hunit, char)
character char
DESCRIPTION

These funtions write a character to the file associated with a fortran logical unit bypassing normal fortran 110. Pule writes to logical unit 6, normally connected to the control terminal output.
The value of each function will be zero unless some error occurred; a system error code otherwise. See perror(3F).
FILES

lusr/lib/libU77.a
SEE ALSO

putc(3S), intro(2), perror(3F)

4th Berkeley Distribution

13, JUne 1983

1

QSORT(3F)

UNIX Programmer's Manual

QSORT(3F)

NAME

qsort - quick sort
SYNOPSIS

subroutine q~ort (array, len, lslze, compar)
external compar
integer-l compar
DESCRIPTION

One dimensional array contains the elements to be sorted. len is the number of elements in the
array. isize is the size of an element, typically 4 for lnteaer and real
8 for double,preeislon or complex
16 for double complex
(length of character object) for character arrays
Compar is the name of a user supplied integer.2 function that will determine the sorting order.
This function will be called with 2 arguments that will be elements of array. The function must
return -

negative if arg 1 is considered to precede arg 2
zero if arg 1 is equivalent to arg 2
positive if arg 1 is considered to follow arg 2
On return, the elements of array will be sorted.
FILES

lusrllib/libU77.a
SEE ALSO

qsort(3)

4th Berkeley Distribution

13 June 1983

1

RAND (314')

UNIX Proarammer's Manual

RAND (3F)

N~ME

rand, drand, irand - return random values
SYNOPSIS

funetion irand (ttlal>
funetion rand (ltlal)
double precision funetion drand (ttla,)
DESCRIPTION

These functions use rand(3C) to generate sequences of random. numbers. If i/lag is '1', the
generator is restarted and the first random value is returned. If ilia, is othel'Wise non-zero, it is
used as a new seed for the random number aenerator, mel the fttst new random value is'returned.
lrand returns positive integers in the range 0 tbrouab 2147413647. Rand and dtand retotrt
values in the range O. through 1.0.
FILES

lusrIlib/libF77.a
SEE ALSO

'rand(3C)

BUGS
The algorithm returns a IS bit quantity on the 'Drl(l;: at 31 bit ~tify' on the VAX..
the PDPtl calls rand(3C) twice to form a 31 bit .

4th Berkeley Distribution

18 July 1983

1

SIGNAL (3F)

UNIX Programmer's Manual

SIGNAL (3F)

NAME

signal - change the action for a signal
SYNOPSIS

integer function signal (signum, proc, flag)
integer signum, flag
external proc
DESCRIPTION

When a process incurs a signal (see signal(3C» the default action is usually to clean up and
abort. The user may choose to write an alternative signal handling routine. A call to signal is
the way this alternate action is specified to the system.
Signum is the signal number (see signa/(3C». If flag is negative, then proc must be the name
of the user signal handling routine. If flag is zero or positive, then proc is ignored and the
value of flag is passed to the system as the signal action definition. In particular, this is how
previously saved signal actions can be restored. Two possible values for flag have specific
meanings: 0 means "use the default action" (See NOTES beloW), 1 means "ignore this signal".
A positive returned value is the previous action definition. A value greater than 1 is the address of a routine that was to have been called on occurrence of the given signal. The returned
value can be used in subsequent calls to signal in order to restore a previous action definition.
A negative returned value is the negation of a system error code. (See perror(3F»
FILES

lusr/lib/libU77.a
SEE ALSO

signal(3C),
NOTES

ki1l(3F)~

kill(I)

n7

arranges to trap certain signals when a process is started. The only way to restore the default n7 action is to save the returned value from the first call to signal.
If the user signal handler is called, it will be passed the signal number as an integer argument.

4th Berkeley Distribution

18 July 1983

1

STAT (3F)

UNIX Programmer's Manual

STAT (3F)

NAME

stat, Istat, fstat - get file status
SYNOPSIS

integer function stat (name, statb)
character. (.) name
inteler statb (12)
integer function 1stat (name, statb)
character.(.) name
integer statb (12)
integer function fstat (Iunit, statb)
integer statb (12)
DESCRIPTION

.

These routines return detailed information about a file. Stat and Istat return information about
file name; /stat returns information about the file associated with fortran logical unit lunit. The
order and meaning of the information returned in array statb is as described for the structure
stat under stat(2). The "spare" values are not included.
The value of either function will be zero if successful; an error code otherwise.
FILES

lusr/lib/libU77.a
SEE ALSO

stat (2) , access (3F) , perror(3F), time(3F)

BUGS

Pathnames can be no longer than MAXP ATHLEN as defined in < sys/parom. h > .

4th Berkeley Distribution

18 July 1983

1

SLEEP (3F)

UNIX Programmer's Manual

SLEEP (3F)

NAME

sleep - suspend execution for an interval
SYNOPSIS

subroutine sleep (ltlme)
DESCRIPTION

Sleep causes the calling process to be suspended for itime seconds. The actual time can be up to
1 second less than itime due to granularity in system timekeeping.
FILES

lusrIlib/libU77.a
SEE ALSO

sleep (3)

4th Berkeley Distribution

13 June 1983

1

SYSTEM (3F)

.- UNIX Programmer's M~ual

SYSTEM (3F)

NAME

system - execute a UNIX command
SYNOPSIS·

Inteaer function system (string)
character- (-) string
DESCRI.PTION

System causes string to be given to your shell as input· as if the string had been typed as a command. If environment variable SHELL is found, its value will be used as the command interpreter (shell); otherwise sh (t) is used.
The current process waits until the command terminates. The returned value will be the exit
status of the shell. See wait(2) for an explanation of this value.
FILES

lusr/lib/libU77.a
SEE ALSO

exec(2), wait(2), system(3)

BUGS
String can not be longer than NCARGS - SO characters, as defined in

4th Berkeley 'Distribution

1'8 JUlyi9.83

< sys/param. h >.

SYSLOO(3)

UNIX Programmer's Manual

SYSLOG (3)

NAME

syslog, openlog, c1oselog - control system log
SYNOPSIS

#Include 
open101 (ldent, logstad
char -ldent;
syslol (priority, message, parameters ••• )
char -message;
closelogO
DESCRIPTION
Sys/og arranges to write the message onto the system log maintained by sys/og(S). The message

is tagged with priority. The message looks like a printj(3) string except that '10m is replaced by
the current error message (collected from errno). A trailing newline is added if needed. This
message will be read by sys/og(S) and output to the system console or files as appropriate.
If special processing is needed, open/og can be called to initialize the log file. Parameters are
ident which is prepended to every message, and /ogstat which is a bit field indicating special
status; current values are:
LOG_PID log the process id with each message: useful for identifying instantiations of daemons.
Open/og returns zero on success. If it cannot open the file Idevllog, it writes on Idev/console
instead and returns -1.
C/ose/og can be used to close the log file.
EXAMPLES

syslog(LOG_SALERT, "who: internal error 23");
openlog("serverftp", LOG_PIO);
syslog (LOG_INFO, "Connection from host %d", CallingHost);
SEE ALSO

syslog(S)

7th Edition

14 November 19S2

1

TIME (3F)

UNIX Programmer's Manual

TIME (3F)

NAME

time, ctime, ltime, gmtime - return system time
SYNOPSIS

integer function timeO
character- (.) function ctime (stime)
integer stime
subroutine Itime (stime, tarray)
integer stime, tarray(9)
subroutine gmtime (stime, tarray)
integer stime, tarray(9)
DESCRIPTION

Time returns the time since 00:00:00 GMT, Jan. 1, 1970, measured in seconds. This is the
value of the UNIX system clock.
Ctime converts a system time to a 24 character ASCII string. The format is described under
ctime(3). No 'newline' or NULL will be included.
Ltime and gmtime disect a UNIX time into month, day, etc., either for the local time zone or as
. GMT. The order and meaning of each element returned in tarray is described under ctime(3).
FILES

lusr/lib/libU77.a
SEE ALSO

ctime(3), itime(3F), idate(3F), fdate(3F)

4th Berkeley Distribution

13 June 1983

1

TOPEN(3F)

UNIX Programmer's Manual

NAME

topen, tclose, tread, twrite, trewin, tskipf, tstate -

TOPEN (3F)

n7 tape 110

SYNOPSIS

integer function topen (tlu, devnam, label)
integer tlu
character. (.) devnam
logical label
integer function tclose (tlu)
integer tlu
integer function tread (tlu, buffer)
integer tlu
character. (.) buffer
integer function twrite (tlu, buffer)
integer tlu
character.(.) buffer
integer function trewin (tlu)
integer tlu
integer function tskipf (tlu, nfiles, nrecs)
integer tlu, nfiles, nrecs
integer function tstate (tlu, fileno, recno, errf, eoff, eotf, tcsr)
integer tlu, fileno, recno, tcsr
logical errf, eoff, eotf
DESCRIPTION

These functions provide a simple interface between n7 and magnetic tape devices. A' "tape
logical unit", tlu, is "topen"ed in much the same way as a normal n7 logical unit is Hopen"ed.
All other operations are performed via the tlu. The tJu has no relationship at all to any normal
n7 logical unit.

Topen associates a device name with a tJu. Tlu must be in the range 0 to 3. The logical argument label should indicate whether the tape includes a tape label. This is used by trewin below.
Topen does not move the tape. The normal returned value is O. If the value of the function is
negative, an error has occured. See perror(3F) for details.
Tclose closes the tape device channel and removes its association with tlu. The normal returned
value is O. A negative value indicates an error.
Tread reads the next physical record from tape to brQfer. BrQfer must be of type character.
The size of brQfer should be large enough to hold the largest physical record to be read. The
actual number of bytes read will be returned as the value of the function. If the value is 0, the
end-of-file has been detected. A negative value indicates an error.
Twrite writes a physical record to tape from brQfer. The physical record length will be the size
of b,qrer. Buffer must be of type character. The number of bytes written will be returned. A
value of 0 or negative indicates an error.
Trewin rewinds the tape associated with tlu to the beginning of the first data file. If the tape is a
labelled tape (see topen above) then the label is skipped over after rewinding. The normal
returned value is O. A negative value indicates an error.

4th Berkeley Distribution

18 July 1983

1

TOPEN (3F)

UNIX Programmer's Manual

TOPEN (3F)

Tskipf allows the user to skip over files and lor records. First, rdiles end-of-file marks are
skipped. If the current file is at EOF, this counts as 1 file to skip. (Note: This is the way to
reset the EOF status for a tlu.) Next, nrees physical records are skipped over. The normal
returned value is O. A negative value indicates an error.
Finally, tstate allows the user to determine the logical state of the tape 1/0 channel and to see
the tape drive control status register. The values of fileno and reeno will be returned and indicate the current file and record number. The logical values err/, eol/, and eoifindicate an error
has occurred, the current file is at EOF, or the tape has reached logical end-of-tape. End-of..
tape (EOT) is indicated by an empty file, often referred to as a double EOF mark. It is not
allowed to read past EOT although it is allowed to write. The value of tesr will reflect the tape
drive control status register. See ht(4) for details.
FILES

lusr/lib/libU77.a
SEE ALSO

ht(4), perror(3F), rewindO)

4th Berkeley Distribution

18 July 1983

2

TRAPER(3F)

UNIX Programmer's Manual

TRAPER (3F)

NAME

traper - trap arithmetic errors
SYNOPSIS

integer function traper (mask)
DESCRIPTION

NOTE: This routine applies only to the VAX. It is ignored on the PDPll.
Integer overflow and floating point underflow are not normally trapped during execution. This
routine enables these traps by setting status bits in the process status word. These bits are reset
on entry to a subprogram, and the previous state is restored on return. Therefore, this routine
must be called inside each subprogram in which these conditions should be trapped. If the condition occurs and trapping is enabled, signal SIGFPE is sent to the process. (See signa/(3C»
The argument has the following meaning:
value meaning
o do not trap either condition
1 trap integer overflow only
2
trap floating underflow only
3
trap both the above
The previous value of these bits is returned.
FILES

lusrIlib/UbF77 .a
SEE ALSO

signal (3C), signal (3F)

4th Berkeley Distribution

18 July 1983

1

TRAPOV(3F)

UNIX Programmer's Manual

TRAPOV(3F)

NAME

trapov - trap and repair floating point overflow
SYNOPSIS

subroutine trapov (numesg, rtnvan
double precision rtnval
DESCRIPTION

NOTE: This routine applies only to the older VAX 11/780's. V AX computers made or
upgraded since sprinl 1983 handle errors differently. See trpfpe(3F) for the newer error
handler. This routine has always been ineffective on the VAX 11/750. It is a null routine on
the PDP11.
This call sets up signal handlers to trap arithmetic exceptions and the use of illegal operands.
Trapping arithmetic exceptions allows the user's program to proceed from instances of floating
point overflow or divide by zero. The result of such operations will be an illegal floating point
value. The subsequent use of the illegal operand will be trapped and the operand replaced by
the specified value.
The first numesg occurrences of a floating point arithmetic error will cause a message to be written to the standard error file. If the resulting value is used, the value given for rtnva/ will
replace the illegal operand generated by the arithmetic error. Rtnva/ must be a double precision
value. For example, "OdO" or "dflmax 0".
FILES'

lusr/lib/libF77.a
SEE ALSO

trpfpe(3F), signaH3F), range(3F)
BUGS
Other arithmetic exceptions can be trapped but not repaired.
There is no way to distinguish between an integer value of 32768 and the illegal floating point
form. Therefore such an integer value may get replaced while repairing the use of an illegal
operand.

4th Berkeley Distribution

.18 July 1983

1

TRPFPE (3F)

UNIX Programmer's Manual

TRPFPE (3F)

NAME

trpfpe, fpecnt - trap and repair floating point faults
SYNOPSIS

subroutine trpfpe (nurnesl, rtnva))
double precision rtnval
integer function fpecnt ()
common Ifpefttl fperr
loaical fperr
DESCRIPTION

NOTE: This routine appUes only to Vax computers. It is a null routine on the PDPl!.
Trplpe sets up a signal handler to trap arithmetic exceptions. If the exception is due to a floating point arithmetic fault, the result of the operation is replaced with the rtnval specified.
Rtnval must be a double precision value. For example, "OdO" or "dflmaxO".
The first numesg occurrences of a floating point arithmetic error will cause a message to be written to the standard error file. Any "exception that can't be repaired will result in the default
action, typically an abort with core image.

Fpecnt returns the number of faults since the last call to trplpe.
The logical value in the common block labelled fpeftt will be set to •true. each time a fault
occurs.
FILES

lusr/lib/libF77.a
SEE ALSO

signaH3F), range(3F)

BUGS
This routine works only for laults, not traps. This is primarily due to the Vax architecture.
If the operation involves changing the stack pointer, it can't be repaired. This seldom should
be a problem with the f77 compiler, but such an operation might be produced by the optimizer.
The POLY and EMOD opcodes are not dealt with.

4th Berkeley Distribution

26 July 1983

1

ITYNAM(3F)

UNIX Programmer's Manual

TTYNAM(3F)

NAME

ttynam, isatty - find name of a terminal port
SYNOPSIS

character- (-) function ttynam (Iunit)
logical function isatty Qunit)
DESCRIPTION

Ttynam returns a blank padded path name of the terminal device associated with logical unit
lunit.
lsatty returns .true. if lunit is associated with a terminal device, .false. otherwise.
FILES

/dev/.
/usr/lib/libU77.a
DIAGNOSTICS

Ttynam returns an empty string (all blanks) if lunit is not associated with a terminal device in
directory '/dev'.

4th Berkeley Distribution

13 June 1983

1.

UNLINK (3F)

UNIX Programmer's Manual

UNLINK (3F)

NAME

unlink - remove a directory entry
SYNOPSIS

integer function unlink (name)
character- (-) name
DESCRIPTION

Unlink causes th~ directory entry specified by pathname name to be removed. If this was the
last link to the file, the contents of the file are lost. The returned value will be zero if successful; a system error code otherwise.
FILES

lusrIlib/libU77 .a
SEE ALSO

unlink(2), link(3F), filsys(S), perror(3F)
BUGS

Pathnames can be no

4th Berkeley Distribution

lo~ger

than MAXPATHLEN as defined in .

18 July 1983

1

WAIT (3F)

UNIX Programmer's Manual

WAIT (3F)

NAME

wait - wait for a process to terminate
SYNOPSIS

integer function wait (status)
integer status
DESCRIPTION
Wait causes its caller to be suspended until a signal is received or one of its child processes terminates. If any child has terminated since the last wait, return is immediate; if there are no

children, return is immediate with an error code.

.

If the returned value is positive, it is the process ID of the child and status is its termination
status (see wait(2». If the returned value is negative, it is the negation of a system error code.
FILES

lusrIlib/libU77.a
SEE ALSO

wait(2), signaI(3F), kill(3F), perror(3F)

4th Berkeley Distribution

13 June 1983

1

INTRO(3M)

UNIX Programmer's Manual

INTRO(3M)

NAME

intro - introduction to mathematical library functions
DESCRIPTION

These functions constitute the math library, libm. They are automatically loaded as needed by
the Fortran compiler .177(1). The link editor searches this library under the "-1m" option.
Declarations for these functions may be obtained from the include file < math.h >.
LIST OF FUNCTIONS

Name Appears on Page
acos
sin.3m
asin
sin.3m
atan
sin.3m
atan2
sin.3m
hypot.3m
cabs
ceil
floor.3m
cos
sin.3m
cosh
sinh.3m
exp
exp.3m
fabs
floor.3m
floor
floor.3m
gamma gamma.3m
hypot
hypot.3m
jO
jO.3m
jl
jO.3m
jn
jO.3m
log
exp.3m
log10
exp.3m
pow
exp.3m
sin
sin.3m
sinh
sinh.3m
sqrt
exp.3m
tan
sin.3m
tanh
sinh.3m
yO
jO.3m
y1
jO.3m
yn
jO.3m

4th Berkeley Distribution

Description
trigonometric functions
trigonometric functions
trigonometric functions
trigonometric functions
Euclidean distance
absolute value, floor, ceiling functions
trigonometric functions
hyperbolic functions .
exponential, logarithm, power, square root
absolute value, floor, ceiling functions
absolute value, floor, ceiling functions
log gamma function
Euclidean distance
bessel functions
bessel functions
bessel functions
exponential, logarithm, power, square root
exponential, logarithm, power, square root
exponential, logarithm, power, square root
trigonometric functions
hyperbolic functions
exponential, logarithm, power, square root
trigonometric functions
hyperbolic functions
bessel functions
bessel functions
bessel functions

8 July 1983

1

UNIX Programmer's Manual

EXP (3M)

EXP (3M)

NAME

exp, log, log10, pow, sqrt - exponential, logarithm, power, square root
SYNOPSIS'

#include

< matb.b >

double exp (x)
double x;
double log (x)
double x;
double log10 (x)
double x;
double pow (x, y)
double x, y;
double sqrt (x)
double x;
DESCRIPTION

Exp returns the exponential function of x.
Log returns the natural logarithm of x; /oglO returns the base 10 logarithm.
Pow returns ;('.
Sqrt returns the square root of x.
SEE ALSO

hypot(3M), sinh(3M), intro(3M)
DIAGNOSTICS

Exp and pow' return a huge value when the correct value would overflow; errno is set to
ERANGE. Pow returns 0 and sets errno to EDOM when the second argument is negative and
non-integral and when both arguments are O.
Log returns 0 when x is zero or negative; errno is set to EDOM.
Sqrt returns 0 when x is negative; errno is set to EDOM.

7th Edition

18 July 1983

1

FLOOR (3M)

UNIX Programmer's Manual

FLOOR (3M)

NAME

fabs, floor, ceil - absolute value, floor, ceiling functions
SYNOPSIS

#lndude 
double 8oor(x)
double Xi
double eell (x)
double Xi
double fabs (x)
double X;
DESCRIPTION
Fobs returns the absolute value Ix~

Floor returns the largest integer not greater than x.
Ceil returns the smallest integer not less than x.
SEE ALSO

abs(3)

7th Edition

19 January 1983

1

UNIX Programmer's Manual

GAMMA (3M)

GAMMA (3M)

NAME

gamma - log gamma function
SYNOPSIS

#lnelude < math.h >
double lamma (x)
double x;

DESCRIPTION

.

Gamma returns In Ir(lxI) I. The sign of r(lxl) is returned in the external integer signgam.
The following C program might be used to calculate r:
y - gamma (x) ;
if (y > 88.0)
error();
y - exp(y);
if(signgam)
y - -y;

DIAGNOSTICS
A huge value is returned for negative integer arguments.
BUGS

There should be a positive indication of error.

7th Edition

19 January 1983

1

HYPOT(3M)

UNIX Programmer's Manual

NAME

hypot,

~bs

- Euclidean distance

SYNOPSIS

#lnelude 
double hJPOt(s, J)
double s, J;
double eabs(z)
stru~ ( double s, J;) z;
DESCRIPTION
Hypot and cabs return

sqrt(x.x + y.y),
taking precautions against unwarranted overflows.
SEE ALSO

exp(3M) for sqrt

7th Edition

19 January 1983

HYPOT(3M)

JO (3M)

UNIX Programmer's Manual

JO (3M)

NAME
jO, jI, jn, yO, yI, yn - bessel functions
SYNOPSIS

#lodude 
double JO (x)
double X;
double Jl (x) .
double x;
double Jo (0, x)
double x;
double yO (x)
double X;
double' yl (x)
double x;
double yo (0, x)
double x;
DESCR.IPTION

These functions calculate Bessel functions of the first and second kinds for real arguments and
integer orders.
DIAGNOSTICS

Negative arguments cause yO, yl. and yn to return a huge negative value and set errno to

EDOM.

7th Edition

19 January 1983

1

SIN (3M)

UNIX Programmet's Manual

SIN(3M)

NAME
sin, cos, tan, asin, acos, atan, atan2 - trigonometric functions
SYNOPSIS

#Include < math.h >
douhle sin (x)
douhle x;
double eos(x)
douhle X;

douhle
douhle
douhle
douhle

as In (x)
X;
aeos (x)
X;
double atan (x)
douhle x;
double atanl(x, y)
douhle x, y;
DESCRIPTION

Sin, eos and tan return trigonometric functions of radian arguments. The magnitude of the arm
gument should be checked by the caller to make sure the result is meaningful.
Asin returns the arc sin in the range -fr/2 to fr/2.
Aeos returns the arc cosine in the range 0 to fr.
Atan returns the arc tangent of x in the range -fr/2 to fr/2.
Atan2 returns the arc tangent of xIy in the range -11" to fr.
DIAGNOSTICS

Arguments of magnitude greater than 1 cause asin and aeos to return value 0; errno is set to
EDOM. The value of tan at its singular points is a huge number, and errno is set to ERANGE.
BUGS

The value of tan for arguments greater than about 2•• 31 is garbage.

7th Edition

19 January 1983

1

sINH (3M)

UNIX Prol1'ammer's Manual

SINH (3M)

NAME

sinh, cosh, tanh - hyperbolic functions
SYNOPSIS

#Include 
double sinh (x)
double cosh (x)
double x;
double tanh (x)
double x;
DESCRIPTION

These functions compute the designated hyperbolic functions for real arguments.
DIAGNOSTICS

Sinh and cosh return a huge value of appropriate sign when the correct value would overflow.

7th Edition

19 January 198'3

1

BYTEORDER(3N)

UNIX Programmer's Manual

BYTEORDER(3N)

NAME

htonl, htons, ntohl, ntohs - convert values between host and network byte order
SYNOPSIS

#IDelade < s,s/types.h >
#IDelade < DetIBet/ID.h >
DetloDI - htonl (hostloDI) ;
a_loDI DetloDI, hostlonl;
netshort - btOBS {hostshort) ;
u_short Detshort, hostshort;
bostlonl - Dtohl (netlonl) ;
a_IoDI hostlODI, Detlonl;
hostshort - ntohs (netshort> ;
u_short hostshort, Detshort;
DESCRIPTION

These routines convert 16 and 32 bit quantities between network byte order and host byte
order. On machines such as the SUN these routines are defined as null macros in the include
file < netinet/in. h > .
These routines are most often used in cof\junction with Internet addresses and ports as returned
by gethostent(3N) and getse,vent(3N).
SEE ALSO

gethostent(3N), getservent(3N)

BUGS
The VAX handles bytes backwards from most everyone else in the world. This is not expected
to be fixed in the near future.

4th Berkeley Distribution

4 March 1983

1

GETHOSTENT(3N)

UNIX Programmer's Manual

GETHOSTENT ( 3N )

NAME

gethostent, gethostbyaddr, gethostbyname, sethostent, endhostent - get network host entry
SYNOPSIS

#lnelude < netdb.h >
struet hostent -Iethostent 0
struet hostent -Iethostbyname(name)
ehar -name;
struet hostent -Iethostbyaddr(addr, len, type)
ehar -addr; lnt len, type;
sethostent (stayopen)
lnt stayopen
endhostent 0

DESCRIPTION

Gethostent, gethostbyname, and gethostbyaddr each return a pointer to an object with the following structure containing the broken-out fields of a line in the network host data base, letclhosts.
struct hostent (
char -h_name;
I- official name of host -I
char -.h_aliases;
/- alias list -I
int
h_addrtype;
/. address type ./
int
hJength;
I- length of address -/
char -h_addr;
/- address -/

);

The members of this structure are:
h_name
Official name of the host.
h_aliases
A zero temrlnated array of alternate names for the host.
h_addttype The type of address being returned; currently always AF_!NET.
The length, in bytes, of the address.
A pointer to the network address for the host. Host addresses are returned in network byte order.
Gethostent reads the next line of the file, opening the file if necessary.
Sethostent opens and rewinds the file. If the stayopen flag is non-zero, the host data base wiD
not be closed after each call to gethostent (either directly, or indirectly through one' of the othe'r
"gethost" calls).
Endhostent closes the file.
Gethostbyname and gethostbyaddr sequentially search from the begilmiul of tbe file ulltil a
matching host name or host address is found, or until BOF is encountered. HQSt addresses: are
supplied in network order.
FILES

/etc/hosts
SEE ALSO

hosts(S)
DIAGNOSTICS

Null pointer (0) returned on EOF or error.

4th Berkeley Distribution

9 February 1983'

1

GETHOSTENT ( 3N)

UNIX Programmer's Manual

GETHOSTENT(3N)

BUGS
All information is contained in a static area so it must be copied if it is to be saved. Only the
Intemet address format is currently understood.

4th Berkeley Distribution

9 February 1983

2

GETNETENT(3N)

UNIX Programmer's Manual

GETNETENT ( 3N)

NAME
getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent - get network entry
SYNOPSIS

#Inelude

< netdb.h >

strud Detent -letnetentO
stmd Detent -Ietnetbyname(name)
ehar -name;
stmd Detent -letnetbyaddr(Det)
10DI Det;
setDeteDt (sta)"opeD)
IDt sta)"opeD
eDdneteDtO
DESCRIPTION

Getnetent, getnetbyname, and getnetbyaddr each return a pointer to an object with the following
structure containing the broken-out fields of a line in the network data base, letc/networks.
struct

netent
char
char
int
long

(
-n_name;
--n_aliases;
n_addrtype;
n_net;

////-

official name of net -I
alias list -/
net number type -I
net number -/

);

The members of this structure are:
n_name
The official name of the network.
n_aliases
A zero terminated list of alternate names for the network.
n_addrtype The type of the network number returned; currently only AF_INET.
n_net
The network number. Network numbers are returned in machine byte order.

Getnetent reads the next line of the file, opening the file if necessary.
Setnetent opens and rewinds the file. If the stayopen Oag is non-zero, the net data base will not
be closed after each call to getnetent (either directly, or indirectly through one of the other
"getnet" calls).

Endnetent closes the file.
Getnetbyname and getnetbyaddr sequentially search from the beginning of the file until a matching net name or net address is found, or until EOP is encountered. Network numbers are supplied in host order.
FILES

/ etc/networks
SEE ALSO

networks(S)
DIAGNOSTICS

Null pointer (0) returned on EOP or error.

BUGS
All information is contained in a static area so it must be copied if it is to be saved. Only Internet network numbers are currently understood. Expecting network numbers to fit in no more
than 32 bits is probably naive.

4th Berkeley Distribution

9 February 1983

1

UNIX Programmer's Manual

GETPROTOENT ( 3N)

GETPROTOENT (3N)

NAME

getprotoent, getprotobynumber, getprotobyname, setprotoent, endprotoent - get protocol entry
SYNOPSIS

#lnclude < netdb.h >
struet protoent *Ietprotoent ()
struet protoent *getprotobyname(name)
char *name;
struct protoent *Ietprotobynumber (proto)
lnt proto;
setprotoent (stayopen)
lnt stayopen

endprotoent ()
DESCRIPTION

Getprotoent, getprotobyname, and getprotobynumber each return a pointer to an object with the
following structure containing the broken-out fields of a line in the network protocol data base,
/etc/protocoIs.
struct

protoent {
char
-p_name;
char
--p_aliases;
long
p-proto;

/- official name of protocol -/
/- alias list */
/- protocol number -/

};
The members of this structure are:
p name The official name of the protocol.
p_aliases A zero terminated list of alternate names for the protocol.
p-proto The protocol number.
Getprotoent reads the next line of the file, opening the file if necessary.
Setprotoent opens and rewinds the file. If the stayopen flag is non-zero, the net data base will
not be closed after each call to getprotoent (either directly, or indirectly through one of the other
"getproto" calls).
Endprotoent closes the file.
Getprotobyname and getprotobynumber sequentially search from the beginning of the file until a
matching protocol name or protocol number is found, or until EOF is encountered.
FILES

/ etc/protocols
SEE ALSO

protocols (5)
DIAGNOSTICS

Null pointer (0) returned on EOF or error.
BUGS

All information is contained in a static area so it must be copied if it is to be saved. Only the
Internet protocols are currently understood.

4th Berkeley Distribution

9 February 1983

1

GETSERVENT (3N)

UNIX Programmer's Manual

GETSERVENT ( 3N)

NAME

getservent, getservbyport, getservbyname, setservent, endservent - get service entry
SYNOPSIS

#lndude

< netdb.h >

struet se"ent *getservent 0
struet se"ent *getservbyname(name, proto)
char *name, *proto;
struet se"ent *getservbyport (port, proto)
lnt port; char *proto;
setse"ent (stayopen)
lnt st.yopen
endse"entO
DESCRIPTION

Getservent, getservbyname, and getservbyport each return a pointer to an object with the following
structure containing the broken-out fields of a line in the network services data base,
/etc/services.
struct

servent (
char
.s_name;
•• s_aliases;
char
s-port;
long
char
.5"proto;

/.
/.
/.
/.

official name of service ./
alias list ./
port service resides at ./
protocol to use • /

);
The members of this structure are:
s_name

The official name of the service.

s_aliases A zero terminated list of alternate names for the service.
s..p0rt

The port number at which the service resides. Port numbers are returned in network
byte order.

s"proto

The name of the protocol to use when contacting the service.

Getservent reads the next line of the file, opening the file if necessary.
Setservent opens and rewinds the file. If the stayopen flag is non-zero,thenet data base will not
be closed after each call to getservent (either directly, or indirectly through one of the other
"getserv" calls).

Endservent closes the file.
Getservbyname and getservbyport sequentially search from the beginning of the file until a matching protocol name or port number is found,or until EOF is encountered. Ifaprotoeol name is
also supplied (non-NULL), searches must also match the protocol.
FILES

/ etc/services
SEE ALSO

getprotoent(3N), services,(S)
DIAGNOSTICS

Null pointer (0) returned on EOF or error.
BUGS

All information is contained in a static area so it must be copied if it is to besav:ed. Expecting
port numbers to fit in a32 bit quantity is probably naive.

4th Berkeley Distribution

9 February 1983

1

INET(3N)

UNIX Programmer's Manual

INET (3N)

NAME

inet_addr, inet_network, jnet_ntoa, inet_makeaddr, inetJnaof, inet_netof - Internet address
manipulation routines
SYNOPSIS

#include < sys/socket.h >
#include < netinet/lo.h >
#include < arpa/lnet.h >
struct In_addr inet_addr(cp)
char .cp;
Int Inet_network (cp)
. char .cp;
char .inet_ntoa (in)
struct Inet_addr In;
struct In_addr inet_makeaddr(net, Ina}
int net, Ina;
lnt Inet_lnaofOn)
struct in_addr in;
int inet_netof(in)
struct in_addr in;

DESCRIPTION

The routines inet_addr and ineLnetwork each interpret character strings representing numbers
expressed in the Internet standard "." notation, returning numbers suitable for use as Internet
addresses and Internet network numbers, respectively. The routine ineLntoa takes an Internet
address and returns an ASCII string representing the address in "." notation. The routine
ineLmakeaddr takes an Internet network number and a local network address and constructs an
Internet address from it. The routines ineLneto! and ineLinao/ break apart Internet host
addresses, returning the network number and local network address part, respectively. .
All Internet address are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values.
INTERNET ADDRESSES

Values specified using the "." notation take one of the following forms:
a.b.c.d
a.b.c
a.b
a
When four parts are specified, each is interpreted as a byte of data and assigned, from left to
right, to the four bytes of an Internet address. Note that when an Internet address is viewed as
a 32-bit integer quantity on the VAX the bytes referred to above appear as "d.c.b.a". That is,
VAX bytes are ordered from right to left.
When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed
in the right most two bytes of the network address. This makes the three part address format
convenient for specifying Class B network addresses as "128.net.host".
When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed
in the right most three bytes of the network address. This makes the two part address format
convenient for specifying Class A network addresses as "net. host" .
When only one part is given, the value is stored directly in the network address without any
byte rearrangement.

4th Berkeley Distribution

18 July 1983

1

INET(3N)

UNIX Programmer's Manual

INET (3N)

All numbers supplied as Uparts" in a "." notation may be decimal, octal, or hexadecimal, as
specified in the C language (Le. a leading Ox or OX implies hexadecimal; otherwise, a leading 0
implies octal; otherwise, the number is interpreted as decimal).
SEE ALSO

gethostent(3N), getnetent(3N), hosts(S), networks(S),
DIAGNOSTICS

The value -1 is returned by ineLaddr and ineLnetwork for malformed requests.
BUGS

The problem of host byte ordering versus network byte ordering is confusing. A simple way to
specify Class C network addresses in a manner similar to that for Class B and Class A is
needed. The string returned by ineLntoa resides in a static memory area.

4th Berkeley Distribution

18 July 1983

2

UNIX Programmer's Manual

INTRO (3S)

INTRO (3S)

NAME

stdio - standard buffered input/output package
SYNOPSIS

#include < stdio.h >
FILE -stdin;
FILE -stdout;
FILE -stderl;

DESCRIPTION

The functions described in section 3S constitute a user-level buffering scheme. The in-line
macros gete and pute(3S) handle characters quickly. The higher level routines gets, /gets, scan/,
/scan!, /read, puts, /puts, print/, /print/, /write all use gete and pute; they can be freely intermixed.
A file with associated buffering is called a stream, and is declared to be a pointer to" a defined
type FILE. Fopen (3S) creates certain descriptive data for a stream and returns a pointer to
designate the stream in all further transactions. There are three normally open streams with
constant pointers declared in the include file and associated with the standard open files:
stdin
standard input file
stdout
standard output file
stden
standard error file
A constant 'pointer' NULL (0) designates no stream at all.
An integer constant EOF (-1) is returned upon end of file or error by integer functions that
deal with streams.
Any routine that uses the standard input/output package must include the header file
< stdio.h > of pertinent macro definitions. The functions and constants mentioned in sections
labeled 3S are declared in the include file and need no further declaration. The constants, and
the following 'functions' are implemented as macros; redeclaration of these names is perilous:
gete, getehar, pute, putehar, feo!, /error, fileno.
SEE ALSO

open(2), close(2), read(2), write(2), fread(3S), fseek(3S), f-(3S)
DIAGNOSTICS

The value EOF is returned uniformly to indicate that a FILE pointer has not been initialized
with /open, input (output) has been attempted on an output (input) stream, or a FILE pointer
designates corrupt or otherwise unintelligible FILE data.
For purposes of efficiency, this implementation of the standard library has been changed to line
buffer output to a terminal by "default and attempts to do this transparently by flushing the output whenever a read(2) from the standard input is necessary. This is almost always transparent, but may cause confusion or malfunctioning of programs which use standard iI 0 routines but use read(2) themselves to read from the standard input.
In cases where a large amount of computation is done after printing part of a line on an output
terminai, it is necessary to fflush (3S) the standard output before going off and computing so
that the output will appear.
BUGS

The standard buffered functions do not interact well with certain other library and system functions, especially v/ork and abort.
LIST OF FUNCTIONS

Name
clearerr
fclose

Appears on Page
ferror .3s
fclose.3s

4th Berkeley Distribution

Description

stream status inquiries
close or flush a stream

18 July 1983

1

INTRO(3S)

feof
ferror
ftlush
fgetc
fgets
fileno
fprintf
fputc
fputs
fread
fscanf
fseek
ftell
fwrite
getc
getchar
gets
getw
printf
putc
putchar
puts
putw
rewind
scanf
setbuf
setbuffer
setlinebuf
sprintf
sscanf
ungetc

UNIX Programmer's Manual

ferror.3s
ferror.3s
fclose.3s
getc.3s
gets.3s
ferror.3s
printf.3s
putc.3s
puts.3s
fread.3s
scanf.3s
fseek.3s
fseek.3s
fread.3s
getc.3s
getc.3s
gets.3s
getc.3s
printf.3s
putc.3s
putc.3s
puts.3s
putc.3s
fseek.3s
scanf.3s
setbuf.3s
. setbuf.3s
setbuf.3s
printf.3s
scanf.3s
ungetc.3s

4th Berkeley Distribution

INTRO (3S)

stream status inquiries
stream status inquiries
close or flush a stream
get character or word from stream
get a string from a stream
stream status inquiries
formatted output conversion
put character or word on a stream
put a string on a stream
buffered binary input/output
formatted input conversion
reposition a stream
reposition a stream
buffered binary input/output
get character or word from stream
get character or word from stream
get a string from a stream
get character or word from stream
formatted output conversion
put character or word on a stream
put character or word on a stream
put a string on a stream
put character or word on a stream
reposition a stream
formatted input conversion
assign buffering to a stream
assign buffering to a stream
assign buffering to a stream
formatted output conversion
formatted input conversion
push character back into input stream

18 July 1983

2

UNIX Programmer's Manual

FCLOSE(3S)

FCLOSE (3S)

NAME

fclose, mush - close or flush a stream
SYNOPSIS
#lnclude

< stdlo.h >

fclose (stream)
FILE -stream;
fIlush (stream)
FILE -stream;
DESCRIPTION
Fclose causes any buffers for the named stream to be emptied, and the file to be closed. Buffers
allocated by the standard input/output system are freed.

Fclose is performed automatically upon calHng exit (3) .
Ff/ush causes any buffered data for the named output stream to be written to that file. The
stream remains open.
SEE ALSO
. close(2), fopen(3S), setbuf(3S)
DIAGNOSTICS
These routines return EOF if stream is not associated with an output file, or if buffered data
cannot be transferred to that file.
.

7th Edition

19 January 1983

1

FERROR(3S)

UNIX Programmer's Manual

FERROR(3S)

NAME

ferror, feof, clearerr, fileno - stream status inquiries
SYNOPSIS
#lnelude < stdlo.h >
feof(stream)
FILE *stream;
ferror(stream)
FILE *stream
elearerr{stream)
FILE *stream
flleno (stream)
FILE *stream;
DESCRIPTION
Feo/returns non-zero when end of file is read on the named input stream, otherwise zero.

Ferror returns non-zero when an error has occurred reading or writing the named stream, otherwise zero. Unless cleared by clearerr, the error indication lasts until the stream is closed.
Clrerr resets the error indication on the named stream.
Fileno returns the integer file descriptor associated with the stream,see open(2).
These functions are implemented as macros; they cannot be redeclared.
SEE ALSO
fopen(3S), open(2)

4th Berkeley Distribution

19 January 1983

1

FOPEN (3S)

UNIX Programmer's Manual

FOPEN (3S)

NAME
fopen, freopen, fdopen - open a stream
SYNOPSIS
#include

< stdio.h >

FILE -fopen (fllename, type)
char -filename, -type;
FILE -freopen (fllename, type, stream)
char -fllename, -type;
FILE -stream;
FILE -fdopen (fildes, type)
char -type;
DESCRIPTION
Fopen opens the file named by filename and associates a stream with it. Fopen returns a pointer
to be used to identify the stream in subsequent operations.

Type is a character string having one of the following values:
"r"

open for reading

"w"

create for writing

"a"

append: open for writing at end of file, or create for writing

In addition, each type may be followed by a '+' to have the file opened for reading and writing.
"r+" positions the stream at the beginning of the file, "w+" creates or truncates it, and "a+"
positions it at the end. Both reads and writes may be used on read/write streams, with the limitation that an /seek, rewind, or reading an end-of-filemust be used between a read and a write
or vice-versa.

Freopen substitutes the named file in place of the open stream. It returns the original value of
stream. The original stream is closed.
Freopen is typically used to attach the preopened constant names, stdin, stdout,. stderr, to
specified files.

Fdopen associates a stream with a file descriptor obtained from open, dup, creat, or pipe (2) . The
type of the stream must agree with the mode of the open file.
SEE ALSO
open(2), fclose(3)
DIAGNOSTICS
Fopen and /reopen return the pointer NULL if filename cannot be accessed.
BUGS

Fdopen is not portable to systems other than UNIX.
The read/write types do not exist on all systems. Those systems without read/write modes will
probably treat the type as if the '+' was not present. These are unreliable in any event.

4th Berkeley Distribution

1 April 1981

1.

FREAD (3S)

UNIX Programmer's Manual

FREAD (3S)

NAME

fread, fwrite - buffered binary input/output
SYNOPSIS

#lnclude < stdl0.h >
fread(ptr, slzeof(*ptrl, nitems, stream)
FILE *stream;
fwrlte(ptr, slzeof(*ptr), nitems, stream)
nLE *stream;

DESCIUPTION

Fread reads, into a block beginning at ptr, nitems of data of the type of .plr from the named
input stream. It returns the number of items actually read.
If stream is stdln and the standard output is line buffered, then any partial output line will be
flushed before any call to read(2) to satisfy the /read.
Fwrite appends at most nilems of data of the type -of .ptr beginning at plr to the named output
stream. It returns the number of items actually written.
SEE ALSO

read (2) , write (2) , fopen (3S), getc(3S), putc(3S), gets (3S) , puts (3S) , printf(3S), scanf(3S)
DIAGNQSTICS

Fread and /write return 0 upon end of file or error.

4th Berkeley Distribution

19 January 1983

1

FSEEK(3S)

UNIX Programmer's Manual

FSEEK (3S)

NAME

fseek, ftell, rewind - reposition a stream
SYNOPSIS
#include < stdio.h >
fseek (stream, offset, ptrname)
FILE *stream;
lonl offset;
lonl ftell (stream)
FILE *stream;
rewind (stream)
DESCRIPTION
Fseek sets the position of the next input or output operation on the stream. The new position is
at the signed distance offset bytes from the beginning, the current position, or the end of the
file, according as ptrname has the value 0, 1, or 2.

Fseek undoes any effects of ungetc(3S).
Ftell returns the current value of the offset relative to the beginning of the file associated with
the named stream. It is measured in bytes on UNIX; on some other systems it is a magic
cookie, and the only foolproof way to obtain an offset for /seek.
Rewind(stream) is equivalent to /seek(stream, OL, 0).
SEE ALSO
Iseek(2), fopen(3S)
DIAGNOSTICS
Fseek returns -1 for improper seeks.

7th Edition

19 January 1983

1

GETC (3S)

UNIX Programmer's Manual

GETC (3S)

NAME

getc, getchar, fgetc, getw - get character or word from stream
SYNOPSIS

#lnclude < stdlo.h >
lnt letc(stream)
FILE -stream;
Int letcharO
Int fletc (stream)
FILE -stream;
Int letw (stream)
FILE -stream;
DESCRIPTION

Getc returns the next character from the named input stream.
GetcharO is identical to getc(stdin).
Fgetc behaves like getc, but is a genuine function, not a macro; it may be used to save object
text.

Getw returns the next word (in a 32-bit integer on a VAX-II) from the named input stream. It
returns the constant Eor upon end of file or error, but since that is· a good integer value, leol
and !error(3S) should be used to check the success of getw. Getw assumes no special alignment
in the file.
SEE ALSO

fopen(3S), putc(3S), gets(3S), scanf(3S), fread(3S), ungetc(3S)
DIAGNOSTICS

These functions return the integer constant EOr at end of file or upon read error.
A stop with message, 'Reading bad file', means an attempt has been made to read from a
stream that "has not been opened for reading by lopen.
BUGS

The end-of-file return from getchar is incompatible with that in UNIX editions 1-6.
Because it is implemented as a macro, getc treats a stream argument with side effects incorrectly.
In particular, 'getc(-f+
doesn't work sensibly.

+);'

7th Edition

19 January 1983

1

GETS (3S)

UNIX Programmer's Manual

GETS (3S)

NAME

gets, fgets - get a string from a stream
SYNOPSIS

#IDclude < stdlo.h >
char -aets (s)
char -s;
char -faets (5, D, stream)
char -S;
FILE -stream;

DESCRIPTION

Gets reads a string into s from the standard input ~tream stdlD. The string is terminated by a
newline character, which is replaced in s by a null character. Gets returns its argument.
Fgets reads n -1 characters, or up to a newline character, whichever comes first, from the
stream into the string s. The last character read into s is followed by a null character. Fgets
returns its first argument.
SEE ALSO

puts (3S) , getc(3S), scanf(3S), fread(3S), ferror(3S)
DIAGNOSTICS

Gets and /gets return the constant pointer NULL upon end of file or error.
BUGS

Gets deletes a newline, !gets keeps it, all in the name of backward compatibility.

7th Edition

19 January 1983

1

PRINTF(3S)

UNIX Programmer's Manual

PRINTF (3S)

NAME

printf, fprintf, sprintf - formatted output conversion
SYNOPSIS

#include < stdio.h >
printf(format [, arg ] ... )
char .format;.
fprintf(stream, format [, arg ] ... )
FILE .stream;
char .format;
sprintf(s, format [, arg ] ... )
char .s, format;
#include 
_doprnt(format, args, stream)
char .format;
va_list .args;
FILE .stream;
DESCRIPTION

Print! places output on the standard output stream stdout. Fprint! places output on the named
output stream. Sprint! places 'output' in the string s, followed by the character '\0'. All of
these routines work by calling the internal routine _doprnt, using the variable-length argument
facilities of varargs(3).
Each of these functions converts, formats, and prints its arguments after the first under control
of the first argument. The first argument is a character string which contains two types of
objects: plain characters, which are simply copied to the output stream, and conversion
specifications, each of which causes conversion and printing of the next successive arg print/.
Each conversion specification is introduced by the character 0/0. Following the %, there may be
•

an optional minus sign '-' which specifies left adjustment of the converted value in the
indicated field;

•

an optional digit string specifying a field width; if the converted value has fewer characters than the field width it will be blank-padded on the left (or right, if the leftadjustment indicator has been given) to make up the field width; if the field width
begins with a zero, zero-padding will be done instead of blank-padding;

•

an optional period '.' which serves to separate the field width from the next digit

•

an optional digit string specifying a precision which specifies the number of digits to
appear after the decimal point, for e- and f-conversion, or the maximum number of
characters to be printed from a string;

•

an optional '#' character specifying that the value should be converted to an "alternate
form". For c:, d, s, and u, conversions, this option has no effect. For 0 conversions,
the precision of the number is increased to force the first character of the output string
to a zero. For x(X) conversion, a non-zero result has the string Ox(OX) prepended to
it. For e, E, f, II, and G, conversions, the result will always contain a decimal point,
even if no digits follow the point (normally, a decimal point only appears in the results
of those conversions if a digit follows the decimal point). For II and G conversions,
trailing zeros are not removed from the result as they would otherwise be.
the character I specifying that a following· d, 0, x, or u corresponds to a long integer
argo

•
•

7th Edition

string~

a character which indicates the type of conversion to be applied.

1 Apri11981

1

UNIX Programmer's Manual

PRINTF(3S)

PRINTF (3S)

A field width or precision may be '.' instead of a digit string. In this case an integer arg supplies the field width or precision.
The conversion characters and their meanings are
dox

The integer arg is converted to decimal, octal, or hexadecimal notation respectively.

f

The float or double arg is converted to decimal notation in the style '[ - ]ddd.ddd'
where the number of d's after the decimal point is equal to the precision specification
for the argument. If the precision is missing, 6 digits are given; if the precision is
explicitly 0, no digits and no decimal point are printed.

e

The float or double arg is converted in the style ,[ - ]d.ddde±dd' where there is one
digit before the decimal point and the number after is equal to the precision
specification for the argument; when the precision is missing, 6 digits are produced.

g

The float or double arg is printed in style d, in style f, or in style e, whichever gives full
precision in minimum space.

c:

The character arg is printed.

s

Arg is taken to be' a string (character pointer) and characters from the string are printed

until a null character or until the number of characters indicated by the precision
specification is reached; however if the precision is 0 or missing all characters up to a
null are printed.
u

The unsigned integer arg is converted to decimal and printed (the result will be in the
range 0 through MAXUINT, where MAXUINT equals 4294967295 on a VAX-ll and
65535 on a PDP-l 1).

0/0

Print a '%'; no argument is converted.

In °no case does a non-existent or small field width cause truncation of a field; padding takes
place only if the specified field width exceeds the actual width. Characters generated by print!
are printed by putc(3S}.
Examples
To print a date and time in the form 'Sunday, July 3, 10:02', where weekday and month are
pointers to null-terminated strings:
printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min);
To print

1t'

to 5 decimals:

printf("pi == %.5f', 4.atan(1.0»;
SEE ALSO

putc(3S}, scanf(3S), ecvt(3)

BUGS
Very wide fields (> 128 characters) fail.

7th Edition

1 April 1981

2

PUTC (3S)

UNIX Programmer's Manual

PUTC (3S)

NAME

putc, putchar, fputc, putw - put character or word on a stream
SYNOPSIS

#lnclude < stdlo.h >
lnt putc (c, stream)
char c; .
FILE -stream;
putchar(c)
fputc(c, stream)
FILE -stream;
putw (1t' t stream)
FILE -stream;

DESCRIPTION

Pute appends the character e to the named output stream. It returns the character written.
Putehar(c) is defined as pute(c, stdout).
Fpute behaves like pute, but is a genuine function rather than a ma~o.
p,utw appends word (that is, lnt) w to the output stream. It returns the word written. Putw neither assumes nor causes special alignment in the file.
SEE ALSO

fopen(3S), fclose(3S), getc(3S), puts(3S), printf(3S), fread(3S)
DIAGNOSTICS

These functions return the constant EOF upon error. Since this is a good integer, /error(3S)
should be used to detect putw errors.
BUGS

Because it is implemented as a macro, pule treats a stream argument with side effects improperly. In particular
putc(c, .f+ +);
doesn't work sensibly.
Errors can occur long after the call to pute.

7th Edition

19 January 1983

1

PUTS (3S)

UNIX Programmer's Manual

PUTS (3S)

NAME
puts, fputs - put a string on a stream
SYNOPSIS
#lndude
puts(s)
char -S;

< stdlo.h >

fputs (St stream)

char -s;
FILE -stream;
DESCRIPTION
Puts copies the null-terminated string s to the standard output stream stdout and appends a
newline character.

Fputs copies the null-terminated string s to the named output stream.
Neither routine copies the terminal null character.
SEE ALSO
fopen(3S), gets (3S) , putc(3S), printf(3S), ferror(3S)
fread(3S) for /write

BUGS
Puts appends a newline, /puts does not, all in the name of backward compatibility.

7th Edition

19 January 1983

1

SCANF(3S)

UNIX Programmer's Manual

SCANF(3S)

NAME

scanf, fseanf, sscanf - formatted input conversion
SYNOPSIS
#include < stdio.h >
scanf(format [ , pointer ] . .. )
char .format;,
fscanf(stream t format [ , pointer ] . .. )
FILE .stream;
char .format;
sscanf(s, format [ , pointer] '. .. )
char .St .format;
DESCRIPTION
Scan/ reads from the standard input stream stdin. Fscan/ reads from the named input stream.
Sscanf reads from the character string s. Each function reads characters, interprets them according to a format, and stores the results in its arguments. Each expects as arguments a control string format, described below, and a set of pointer arguments indicating where the converted input should be stored.
The control string usually contains conversion specifications, which are used to direct interpretation of input sequences. The control string may contain:
1. Blanks, tabs or newlines, which match optional white space in the input.
2. An ordinary character (not %) which must match the next character of the input stream.
3. Conversion specifications, consisting of the character %, an optional assignment suppressing character ., an optional numerical maximum field width, and a conversion character.
A conversion specification directs the conversion of the next input field; the result is placed in
the variable pointed to by the corresponding argument, unless assignment suppression was indicated by •. An input field is defined as a string of non-space characters; it extends to the next
inappropriate character or until the field width, if specified, is exhausted.
The conversion character indicates the interpretation of the input field; the corresponding
pointer argument must usually be of a restricted type. The following conversion characters are
legal:
0/0
d
o
x

a single '%' is expected in the input at this point; no assignment is done.
a decimal integer is expected; the corresponding argument should be an integer pointer.
an octal integer is expected; the corresponding argument should be a integer pointer.
a hexadecimal integer is expected; the corresponding argument should be an integer
pointer.

s

a character string is expected; the corresponding argument should be a character pointer
pointing to an array of characters large enough to accept the string and a terminating '\0',
which will be added. The input field is terminated by a space character or a newline.
a character is expected; the corresponding argument should be a character pointer. The
normal skip over space characters is suppressed in this case; to read the next non-space
character, try '%ls'. If a field width is given, the corresponding argument should refer to a
character array, and the indicated number of characters is read.
a floating point number is expected; the next field is converted accordingly and stored
through the corresponding argument, which should be a pointer to a ./Ioat. The input format for floating point numbers is an optionally signed string of digits possibly containing a
decimal point, followed by an optional exponent field consisting of an E or e followed by

c

e
f

7th Edition

19 January 1983

1

SCANF(3S)

UNIX Programmer's Manual

SCANF(3S)

an optionally signed integer.
indicates Il string not to be delimited by space characters. The left bracket is followed by a
set of characters and a right bracket; the characters between the brackets define a set of
characters making up the string. If the first character is not circumflex ("), the input field
is all characters until the first character not in the set between the brackets; if the first character after the left bracket is ", the input field is all characters until the first character which
is in the remaining set of characters between the brackets. The corresponding argument
must point to a character array.
The conversion characters d, 0 and x may be capitalized or preceded by I to indicate that a
pointer to lonl rather than to lnt is in the argument list. Similarly, the conversion characters e
or f may be capitalized or preceded by I to indicate a pointer to double rather than to float. The
conversion characters d, 0 and x may be preceded by h to indicate a pointer to short rather than
to Int.
The scaliffunctions return the number of successfully matched and assigned input items. This
can be used to decide how many input items were found. The constant Eor is returned upon
end of input; note that this is different from 0, which means that no conversion was done; if
conversion was intended, it was frustrated by an inappropriate character in the input.
For example, the call
int i; float x; char name(50);
scanf("%d%f%s", &i, &x, name);
with the input line
25 54.32E-1 thompson
will assign to ithe value 25, x the value 5.432, and name will contain 'thompson\O'. Or,
int i; float x; char name [50) ;
scanf("%2d%fO/o*d%[1234567890)", &i, &x, name);
with input
56789 0123 56a72
will assign 56 to i, 789.0 to x, skip '0123', and place the string '56\0' in name. The next call to
getchar will return 'a'.
SEE ALSO

atof(3), getc (3S), printf(3S)
DIAGNOSTICS

The scalif functions return Eor on end of input, and a short count for missing or illegal data
items.
BUGS

The success of literal matches and suppressed assignments is not directly determinable.

7th Edition

19 January 1983

2

SETBUF(3S)

UNIX Programmer's Manual

SETBUF(3S)

NAME

setbuf, setbuffer, setlinebuf - assign buffering to a stream
SYNOPSIS

#include < stdio.h >
setbuf(stream, but)
FILE -stream;
char -buf;
setbuffer(stream, bUf, size}
FILE -stream;
char -buf;
Int size;
setlinebuf(stream)
FILE -stream;

DESCRIPTION

The three types of buffering available are unbuffered, block buffered, and line buffered. When
an output stream is unbuffered, information appears on the destination file or terminal as soon
as written; when it is block buffered. many characters are saved up and written as a block; when
it is line buffered characters are saved up until a newline is encountered or input is read from
stdin. Fflush (see /c1ose(3S» may be used to force the block out early. Normally all files are
block buffered. A buffer is obtained from mal/oc(3) upon the first getc or putc(3S) on the file.
Ir"the standard stream stdout refers to a terminal it is line buffered. The standard stream stderr
is always unbuffered.

Setbu/is used after a stream has been opened but before it is read or written. The character array bu/is used instead of an automatically allocated buffer. If bu/is the constant pointer NULL,
input/output will be completely unbuffered. A manifest constant BUFSIZ tells how big an array
is needed:
char buf[BUFSIZ];
Setbt.dfer, an alternate form of setbu/, is used after a stream has been opened but before it is
read or written. The character array bu/whose size is determined by the size argument is used
instead of an automatically allocated buffer. If bu/is the constant pointer NULL, input/output
will be completely unbuffered.
Setlinebu/ is used to change stdout or stderr from block buffered or unbuffered to line buffered.
Unlike setbu/and setbtiffer it can be used at any time that the file descriptor is active.
A file can be changed from unbuffered or line buffered to block buffered by using /reopen (see
/open(3S». A file can be changed from block buffered or line buffered to unbuffered by using
/reopen followed by setbu/with a buffer argument of NULL.
SEE ALSO

fopen(3S), getc(3S), putc(3S), malloc(3), fclose(3S), puts(3S), printf(3S), fread(3S)
BUGS

The standard error stream should be line buffered by default.
The setbt.dfer and setlinebu/functions are not portable to non 4.2 BSD versions of UNIX.

4th Berkeley Distribution

19 January 1983

1

UNGETC(3S)

UNIX Programmer's Manual

UNGETC (3S)

NAME

ungetc - push character back into input stream
SYNOPSIS

#IDclude < stdlo.h >
uDletc(c, stream)
FILE -stream;

DESCRIPTION

Ungetc pushes the character c back on an input stream. That character will be returned by the
next getc calion that stream. Ungetc returns c.
One character of pushback is guaranteed provided something has been read from the stream
and the stream is actually buffered. Attempts to push EOP are rejected.
Fseek(3S) erases all memory of pushed back characters.
SEE ALSO

getc(3S), setbuf(3S), fseek(3S)
DIAGNOSTICS

Ungetc returns EOF if it can't push a character back.

7th Edition

19 January 1983

1

INTRO(3X)

UNIX Programmer's Manual

INTRO (3X)

NAME

intro - introduction to miscellaneous library functions
DESCRIPTION

These functions constitute minor libraries and other miscellaneous run-time facilities. Most are
available only when programming in C. The list below includes libraries which provide device
independent plotting functions, terminal independent screen management routines for two
dimensional non-bitmap display terminals, functions for managing data bases with inverted
indexes, and sundry routines used in executing commands on remote machines. The routines
getdiskbyname, rcmd, rresvport, ruserok, and rexec reside in the standard C run-time library
"-lc". All other functions are located in separate libraries indicated in each manual entry.
FILES

llib/libc.a
lusr/lib/libdbm.a
lusr/lib/libtermcap.a
lusrIUb/libcurses.a
lusr/lib/lib2648.a
lusr llib/libplot.a
LIST OF FUNCTIONS

Name

Appears on Page

arc
assert
circle
close pi
cont
curses
dbminit
delete
endfsent
erase
fetch
first key
getdiskbyname
getfsent
getfsfile
getfsspec
getfstype
initgroups
label
lib2648
line
linemod
move
nextkey
plot: open pI
point
rcmd
rexec
rresvport
ruserok
setfsent
space

4th Berkeley Distribution

plot.3x
assert.3x
plot.3x
plot.3x
plot.3x
curses.3x
dbm.3x
dbm.3x
getfsent.3x
plot.3x
dbm.3x
dbm.3x
getdisk.3x
getfsent.3x
getfsent.3x
getfsent.3x
getfsent.3x
initgroups.3x
plot.3x
lib2648.3x
plot.3x
plot.3x
plot.3x
dbm.3x
plot.3x
plot.3x
rcmd.3x
rexec.3x
rcmd.3x
rcmd.3x
getfsent.3x
plot.3x

Description
graphics interface
program verification
graphics interface
graphics interface
graphics interface
screen functions with "optimal" cursor motion
data base subroutines
data base subroutines
get file system descriptor file entry
graphics interface
data base subroutines
data base subroutines
get disk description by its name
get file system descriptor file entry
get file system descriptor file entry
get file system descriptor file entry
get file system descriptor file entry
initialize group access list
graphics interface
subroutines for the HP 2648 graphics terminal
graphics interface
graphics interface.
graphics interface
data base subroutines
graphics interface
graphics interface
routines for returning a stream to a remote command
return stream to a remote command
routines for returning a stream to a remote command
routines for returning a stream to a remote command
get file system descriptor file entry
graphics interface

8 July 1983

1

INTRO(3X)

store
tgetent
tgetflag
tgetnum
tgetstr .
tgoto
tputs

4th Berkeley Distribution

INTRO(3X)

UNIX Programmer's Manual

dbm.3x
termcap.3x
termcap.3x
termcap.3x
termcap.3x
termcap.3x
termcap.3x

data base subroutines
terminal independent operation
terminal independent operation
terminal independent operation
terminal independent operation
terminal independent operation
terminal independent operation

8 July 1983

routines
routines
routines
routines
routines
routines

2

ASSERT (3X)

UNIX Programmer's Manual

ASSERT (3X)

NAME

assert - program verification
SYNOPSIS

#lnclude < assert.h >
assert (expression)

DESCRIPTION

Assert is a macro that indicates expression is expected to be true at this point in the program. It
causes an exit(2) with a diagnostic comment on the standard output when expression is false (0).
Compiling with the ceO) option - DNDEBUG effectively deletes assert from the program.
DIAGNOSTICS

'Assertion failed: file f line n.' F is the source file and n the source line number of the assert
statement.

7th Edition

19 January 1983

1

CURSES (3X)

UNIX Programmer's Manual

CURSES (3X)

NAME

curses - screen functions with "optimal" cursor motion
SYNOPSIS

cc [ flags ] files -lcurses -Itermcap [ libraries ]
DESCRIPTION

These routines give the user a method of updating screens with reasonable optimization. They
keep an image of the current screen, and the user sets up an image of a new one. Then the
rejreshO tells the routines to make the current screen look like the new one. In order to initialize the routines, the routine· initscrO must be called before any of the other routines that deal
with windows and screens are used. The routine endwinO should be called before exiting.
SEE ALSO

Screen Updating and Cursor Movement Optimization: A Library Package, Ken Arnold,
ioctl(2), getenv(3), tty (4) , termcap(S)
AUTHOR

Ken Arnold
FUNCTIONS

addch(ch)
addstr (str)
box (win, vert,hor)
crmodeO
clear 0
clearok (scr, boolf)
clrtobotO
clrtoeolO
delchO
delete In 0
delwin (win)
echo 0
endwinO
erase 0
getchO
getcap(name)
getstr (str)
gettmodeO
getyx (win,y ,x)
inch 0
initscrO
insch(c)
insertlnO
leaveok (win, boolf)
longname(termbuf,name)
move (y,x)
mvcur(lasty,lastx,newy ,newx)
newwin(lines,cols,beginy,begin_x)
nlO
nocrmodeO
noechoO
nonlO
norawO
overlay (win 1,win2)
overwrite (win 1,win2)

4th Berkeley Distribution

add a character to stdscr
add a string to stdscr
draw a box around a window
set cbreak mode
clear stdscr
set clear flag for scr
clear to bottom on stdscr
clear to end of line on stdscr
delete a character
delete a line
delete win
set echo mode
end window modes
erase stdscr
get a char through stdscr
get terminal capability name
get a string through stdscr
get tty modes
get (y,x) co-ordinates
get char at current (y,x) co-ordinates
initialize screens
insert a char
insert a line
set leave flag for win
get long name from termbuf
move to (y,x) on stdscr
actually move cursor
create a new window
set newline mapping
unset cbreak mode
unset echo mode
unset newline mapping
unset raw mode
overlay winl on win2
overwrite winl on top of win2

19 January 1983

1

CURSES (3X)

UNIX Programmer's Manual

printw(fmt,arg1 ,arg2, .. .)
raw 0
refresh 0
resetty()
savetty()
scanw(fmt,argl,arg2, .. .)
scroll (win)
scrollok (win, booIf)
setterm (name)
standend()
standout()
subwin(win,lines,cols,beginJ,begin_x)
touchwin (win)
unctrl(ch)
waddch (win,ch)
waddstr(win,str)
wclear(win)
wclrtobot (win)
wclrtoeol (win)
wdelch(win,c)
wdeleteln (win)
werase (win)
wgetch (win)
wgetstr(win,str)
winch (win)
winsch (win,c)
winsertln (win)
wmove (wins ,x)
wprintw(win,fmt,argl,arg2, .. .)
wrefresh (win)
wscanw(win,fmt,argl,arg2, .. .)
wstandend (win)
wstandout (win)

CURSES (3X)

printf on stdscr
set raw mode
make current screen look like stdscr
reset tty flags to stored value
stored current tty flags
seanf through stdscr
scroll win one line
set scroll flag
set term variables for name
end standout mode
start standout mode
create a subwindow
"change" all of win
printable version of ch
add char to win
add string to win
clear win
clear to bottom of win
clear to end of line on win
delete char from win
delete line from win
erase win
get a char through win
get a string through win
get char at current (y,x) "in win
insert char into win
insert line into win
set current (y,x) co-ordinates on win
printf on win
make screen look like win
scanf through win
end standout mode on win
start standout mode on win

BUGS

4th Berkeley Distribution

19 January 1983

2

DBM(3X)

UN IX Programmer's Manual

DBMt3X)

NAJ\stE
dbminit, fetch, storc, delete, firstkcy, nextkey -- data base subroutines
SYNOPSIS

typcdcf struct {
char *dptr.;
iut dsize;
} datum;

dbminit{fiIe)
char *file;
d.ltUfll fctch(key)
datum key;
storc(key, content)
datum ){cy, content;
dc!ctc(kcy)
datum key;
datum Hrstkcy()
datum nextkey(key)
d:itum key;
DESCRIPTION

These functions maint.1in key/content pairs in a data base. The functions will handle very large (a
biHion blocks) databases and will access a keyed item in one or two fIle system accesses. The functions arc obtained with the loader option -Idbm.
Keys and cOil/ellIs are described by
pointed to by dpll: Arbitrary binary
base is stored in two nIes. One file
The second file contains all data and

the dalulII typedef. /\ dalulIl specifics a string of d'Jize bytes
elata, as well as normal ASCII strings, are allowed. The data
is {l directory containing a bit m

struet dlsktab letdlskbyname(name)
char -name;
DESCRIPTION

Getdiskbyname takes a disk name (e.g. rm03) and returns a structure describing its geometry
information and the standard disk partition tables. All information obtained from the disktab(S) file.
 has the following form:

/*

@(#)disktab.h 4.2 (Berkeley) 3/6/83 */

/*
- Disk description table, see disktab(S)

-/
#defineDISKTAB
struct

"/etc/disktab"

disktab {
char
*d_name;
/- drive name -I
char
*d_type;
/* drive type -/
int
d_secsize;
/- sector size in bytes */
int
. d_ntracks;
/- # tracks/cylinder -/
int
d_nsectors;
/- # sectors/track -I
int
d_ncylinders;
/- # cylinders -/
int
d_rpm;
/- revolutions/minute -/
struct partition {
/- #sectors in partition -/
int
p_size;
short p_bsize;/- block size in bytes -/
short p_fsize; /- frag size in bytes -I
} dJ'artitions[8];

};
struct

disktab -getdiskbyname () ;

SEE ALSO

disktab(S)

BUGS
This information shoulc; be obtained from the system for locall) lvailable disks (in particular,
the disk partition tables).

4th Berkeley Distribution

4 March 1983

1

INITGROUPS ( 3X)

UNIX Programmer's Manual

INITGROUPS ( 3X )

NAME

initgroups - initialize group access list
SYNOPSIS

initgroups (name, basegid)
char -name;
lnt basegid;
DESCRIPTION

Initgroups reads through the group file and sets up, using the setgroups(2) call, the group access
list for the user specified in name. The basegid is automatically included in the groups list.
Typically this value is given as the group number from the password file.
FILES

letclgroup
SEE ALSO

setgroups (2)
DIAGNOSTICS

Initgroups returns -1 if it was not invoked by the super-user.
BUGS

Initgroups uses the routines based on getgrent(3). If the invoking program uses any of these
routines, the group structure will be overwritten in the call to initgroups.
Noone seems to keep letclgroup up to date.

4th Berkeley Distribution

25 February· 1983

1

LIB2648 ( 3X)

UNIX Programmer's Manual

LIB2648 (3X )

NAME

lib2648 - subroutines for the HP 2648 graphics terminal
SYNOPSIS

#lnclude 
typedef char -bltmat;
FILE -trace;
cc file.c -12648
DESCRIPTION

Lib2648 is a general purpose library of subroutines useful for interactive graphics on the
Hewlett-Packard 2648 graphics terminal. To use it you must call the routine ttyinitO at the
beginning of execution, and. done 0 at the end of execution. All terminal input and output
must go through the routines rawchar, readline, outchar, and outstr.
Lib2648 does the necessary "ErF handshaking if getenv("TERM'') returns "hp2648", as it will
if set by tset(1). Any other value, including for example "2648", will disable handshaking.
Bit matrix routines are provided to model the graphics memory of the 2648. These routines are
generally useful, but are specifically useful for the update function which efficiently changes
what is on the screen to what is supposed to be on the screen. The primative bit matrix routines are newmat, mat, and setmat.
The file trace, if non-null, is expected to be a file descriptor as returned by lopen. If so, lib2648
will trace the progress of the output by writing onto this file. It is provided to make debugging
output feasible for graphics programs without messing up the screen or the escape sequences
being sent. Typical use of trace will include:
switch (argv[l] U]) {
case'T':
trace - fopen ("trace", "w");
break;
If (trace)
fprintf(trace, "x is %d, y is %s\n", x, y);
dumpmat("before update", xmat);
ROUTINES

aloto(x,1}
Move the alphanumeric cursor to position (x, y), measured from th r . iJpl-,er left comer
of the screen.
aofl'() Tum the alphanumeric display off.
aOD () Tum the alphanumeric display on.
areaclear (rmln, cmln, rmax, cmax)
Clear the area on the graphics screen bordered by the four arguments. In normal mode
the area is set to all black, in inverse video mode it is set to all white.
beep () Ring the bell on the terminal.
bltcoP1(dest, src, rows, cols} bltmat dest,
Copy a rows by cols bit matrix from src to (user provided) dest.
clearaO
Clear the alphanumeric display.
clearaO

4th Berkeley Distribution

1 March 1980

1

UNIX Programmer's Manual

LIB2648 (3X)

LIB2648 ( 3X )

Clear the graphics display. Note that the 2648 will only clear the part of the screen that
is visible if zoomed in.
curoff()
Tum the graphics cursor off.
curonO
Turn the graphics cursor on.
dlspmsi (str, x, y, maxlen) char -str;
Display the message str in graphics text at position (x, y). The maximum message
length is given by maxlen, and is needed to for dispmsg to know how big an area to
clear before drawing the message. The lower left corner of the first character is at (x.
y).

done() Should be called before the program exits. Restores the tty to normal, turns otT graphics screen, turns on alphanumeric screen, flushes the standard output, etc.
draw(x, y)
Draw a line from the pen location to '(x, y). As with all graphics coordinates, (x. y) is
measured from the bottom left comer of the screen. (x, y) coordinates represent the
first quadrant of the usual Cartesian system.
drawbox (r, c, color, rows, cols)
Draw a rectangular box on the graphics screen. The lower left corner is at location (r.
c). The box is rows rows high and cols columns wide. The box is drawn if color is 1,
erased if color is O. (r, c) absolute coordinates represent row and column on the screen,
with the origin at the lower left. They are equivalent to (x, y) except for being reversed
in order.
dumpmat (msl, m, rows, cols) char -msl; bltmat m;
If trace is non-null, write a readable ASCII representation of the matrix m on trace. Msg
is a label to identify the output.
emptyrow(m, rows, cols, r) bitmat m;
Returns 1 if row r of matrix m is all zero, else returns O. This routine is prpvided
because it can be implemented more efficiently with a knowledge of the internal
representation than a series of calls to mat.
error(msl} char -msl;
Default error handler. Calls message(msg) and returns. This is called by certain routines in lib2648. It is also suitable for calling by the user program. It is probably a
good idea for a fancy graphics program to supply its own error procedure which uses
seymp(3) to restart the program.
IdefaultO
Set the terminal to the default graphics modes.
10ffO Tum the graphics display off.
Ion 0 Turn the graphics display on.
koffO Turn the keypad otT.
kon 0 Turn the keypad on. This means that most special keys on the terminal (such as the
alphanumeric arrow keys) will transmit an escape sequence instead of doing their function locally.
lIne(x1, y1, xl, y2)
Draw a line in the current mode from (xl. yl) to (x2. y2). This is equivalent to
mOlle(xl, yl); draw(x2. y2); except that a bug in the terminal involving repeated lines
from the same point is compensated for.

4th Berkeley Distribution

1 March 1980

2

LIB2648 (3X)

UNIX Programmer's Manual

LIB2648 ( 3X )

10wieftO
Move the alphanumeric cursor to the lower left (home down) position.
mat(m, rows, cols, I, c) bUmat m;
Used to retrieve an element from a bit matrix. Returns 1 or 0 as the value of the fr, cl
element of the rows by colsmatrix m. Bit matrices are numbered (r, c) from the upper
left corner of the matrix, beginning at (0, 0). R represents the row, and c represents
the column.
messale(str) char -str;
Display the text message str at the bottom of the graphics screen.
min max (I, rows, cols, rmln, cmln, rmax, cmax) bltmat I;
Int -rmin, -cmin, -rmax, -cmax;
Find the smallest· rectangle that contains all the 1 (on) elements in the bit matrix g.
The coordinates are returned in the variables pointed to by rmin, cmin, rmax, cmax.
move(x, y)
Move the pen to location (x, y). Such motion is internal and will not cause output until
a subsequent syncO.
movec:urs (x, y)
Move the graphics cursor to location (x, y).
bltmat newmat (rows, cols)
Create (with ma/Joc(3» a new bit matrix of size rows by cots. The value created (e.g. a
pointer to the first location) is returned. A bit matrix can be freed directly with free.
outchar (c) char c;
Print the character c on the standard output. All output to the terminal should go
through this routine or outstr.
outstr(str) ·char -str;
Print the string str on the standard output by repeated calls to outchar.
printlO
Print the graphics display on the printer. The printer must be configured as device 6
(the default) on the HPIB.
char rawcharO
Read one character from the terminal and return it. This routine or readline should be
used to get all input, rather than getchar(3).
rboffO Turn the rubber band line off.
rbon 0 Turn the rubber band line on.
char -rdchar(c) char c;
Return a readable representation of the character c. If c is a printing character it returns
itself, if a control character it is shown in the "X notation, if negative an apostrophe is
prepended. Space returns ''', rubout returns A1.
NOTE: A pointer to a static place is returned. For this reason,it will not work to pass
rdchar twice to the same fprint/I sprint! call. You must instead save one of the values in
your own buffer with strcpy.
readllne(prompt, mSl, maxlen) cliar -prompt, -mSI;
Display prompt on the bottom line of the graphics display and read one line of text from
the user, terminated by a newline. The line is placed in the buffer msg, which has size
maxien characters. Backspace processing is supported.
setdear 0

4th Berkeley Distribution

1 March 1980

3

UNIX Programmer's Manual

LIB2648 (3X)

LIB2648 ( 3X )

Set the display to draw lines in erase mode. (This is reversed by inverse video mode.)
setmat(m, rows, cols, r, c, vaI) bltmat m;
The basic operation to store a value in an element of a bit matrix. The {r, cl element
of m is set to val, which should be either 0 or 1.
setsetO
Set the display to draw lines in normal (solid) mode. (This is reversed by inverse video
mode.)
setxorO
Set the display to draw lines in exclusive or mode.
syncO Force all accumulated output to be displayed on the screen. This should be followed by
mush (stdout). The cursor is not affected by this function. Note that it is normally
never necessary to call sync, since rawchar and readline call sync() and fflush(stdout)
automatically.
tOlvldO
Toggle the state of video. If in normal mode, go into inverse video mode, and vice
versa. The screen is reversed as well as the internal state of the library.
ttylnltO
Set up the terminal for processing. This routine should be called at the beginning of
execution. It places the terminal in CBREAK mode, turns off echo, sets the proper
modes in the terminal, and initializes the library.
update(mold, mnew, rows, cols, baser, based bitmat mold, mnew;
Make whatever changes are needed to make a window on the screen look like mnew.
Mold is what the window on the screen currently looks like. The window has size rows
by cols, and the lower left comer on the screen of the window is {baser, based. Note:
update was not intended to be used for the entire screen. It would work but be very
slow and take 64K bytes of memory just for mold and mnew. It was intended for 100
by 100 windows with objects in the center of them, and is quite fast for such windows.
vldlnvO
Set inverse video mode.
vldnormO
Set normal video mode.
zermat (m, rows, cols) bUmat m;
Set the bit matrix m to all zeros.
zoomn (size)
Set the hardware zoom to value size, which can range from 1 to 15.
zoomotfO
Turn zoom off. This forces the screen to zoom level 1 without affecting the current
internal zoom number.
zoomonO
Turn zoom on. This restores the screen to the previously specified zoom size.
DIAGNOSTICS

The routine error is called when an error is detected. The only error currently detected is
overflow of the buffer provided to readline.
Subscripts out of bounds to setmat return without setting anything.
FILES

lusr/lib/lib2648.a

4th Berkeley Distribution

1 March 1980

4

LIB2648 (3X)

UNIX Programmer's Manual

LIB2648 (3X)

SEE ALSO
fedO)

AUTHOR
Mark Horton

BUGS
This library is not supported. It makes no attempt to use all of the features of the terminal,
only those needed by fed. Contributions from users will be accepted for addition to the library.
The HP 2648 terminal is somewhat unreliable at speeds over 2400 baud, even with the AErF
handshaking. In an effort to improve reliability, handshaking is done every 32 characters. (The
manual claims it is only necessary every 80 characters.) Nonetheless, 1/0 errors sometimes still
occur.
There is no way to control the amount of debugging output generated on trace without modifying the source to the library.

4th Berkeley Distribution

1 March .1980

5

PLOT (3X)

UNIX Programmer's Manual

PLOT (3X)

NAME

plot: openpl, erase, label, line, circle, arc, move, cont, point, linemod, space, closepl - graphics interface
SYNOPSIS

openplO
erase 0
label(s)
ehar sU;
line(xl, yl, xl, yl)
eircle (x, y, r)
are(x, y, xO, yO, xl, y1)
move(x, y)
eont(x, y)
point(x, y)
linemod(s)
ehar s(];
spaee(xO, yO, xl, y1)
eloseplO
DESCRIPTION

These subroutines generate graphic output in a relatively device-independent manner. See
plot(S) for a description of their effect. Openpl must be used before any of the others to open
the device for writing. Closepl flushes the output.
String arguments to label and linemod are null-terminated, and do not contain newlines.
Various flavors of these functions exist for different output devices. They are obtained by the
following Id(1) options:
-Iplot
-1300
-1300s
-1450
-14014

device-independent graphics stream on standard output for plot (1 ) filters
OSI 300 terminal
OSI 300S terminal
DASI 450 terminal
Tektronix 4014 terminal

SEE ALSO

plot(S), plot(1G), graph(10)

7th Edition

19 January 1983

1

RCMD (3X)

UNIX Programmer's Manual

RCMD (3X)

NAME

rcmd, rresvport, ruserok - routines for returning a stream to a remote command
SYNOPSIS

rem = rcmd(ahost, inport, locuser, remuser, cmd, fd2p);
char --ahost;
u_short inport;
char -locuser, -remuser, -cmd;
int -fd2p;
s = rresvport (port) ;
int -port;
ruserok ;
char -rhost;
int superuser;
char -ruser, -Iuser;
DESCRIPTION

Rcmd is a routine used by the super-user to execute a command on a remote machine using an
authentication scheme based on reserved port numbers. Rresvport is a routine which returns a
descriptor to a socket with an address in the privileged port space. Ruserok is a routine used by
servers to authenticate clients requesting service with rcmd. All three functions are present in
the same file and are used by the rshd(8C) server (among others).
Rcmd looks up the host -ahost using gethostbyname(3N), returning -1 if the host does not exist. Otherwise *ahost is set to the standard name of the host and a connection is established to
a server residing at the well-known Internet port inport.
If the call succeeds, a socket of type SOCK_STREAM is returned to the caller, and given to the
remote command as stdin and stdout. If /d2p is non-zero, then an auxiliary channel to a control process will be set up, and a descriptor for it will be placed in */d2p. The control process
will return diagnostic output from the command (unit 2) on this channel, and will also accept
bytes on this channel as being UNIX signal numbers, to be forwarded to the process group of
the command. If /d2p is 0, then the stderr (unit 2 of the remote command) will be made the
same as the stdout and no provision is made for sending arbitrary signals to the remote process,
although you may be able to get its attention by using out-of-band data.
The protocol is described in detail in rshd(8C).
The rresvport routine is used to obtain a socket with a privileged address bound to it. This socket is suitable for use by rcmd and sevral other routines. Privileged addresses consist of a port in
the range 0 to 1023. Only the super-user is allowed to bind an address of this sort to a socket.

Ruserok takes a remote host's name, as returned by a gethostent(3N) routine, two user names
and a flag indicating if the local user's name is the super-user. It then checks the files
letclhosts.equivand, possibly, .rhosts in the current working directory (normally the local user's
home directory) to see if the request for service is allowed. A 1 is returned if the machine
name is listed in the "hosts.equiv" file, or the host and remote user name are found in the
".rhosts" file; otherwise ruserok returns O. If the superuser flag is 1, the checking of the
"host.equiv" file is bypassed.
SEE ALSO

rlogin(IC), rsh(IC), rexec(3X), rexecd(8C), rlogind(8C), rshd(8C)

BUGS
There is no way to specify options to the socket call which rcmd makes.

4th Berkeley Distribution

17 March 1982

1

REXEC (3X)

UNIX Programmer's Manual

REXEC (3X)

NAME

rexec - return stream to a remote command
SYNOPSIS

rem = rexec(ahost, inport, user, passwd, cmd, fd2p);
char --ahost;
u_short inport;
char -user, -passwd, .cmd;
int -fd2p;
DESCRIPTION

Rexec looks up the host *ahost using gethostbyname(3N), returning -1 if the host does not exist. Otherwise *ahost is set to the standard name of the host. If a username and password are
both specified, then these are used to authenticate to the foreign host; otherwise the environment and then the user's .netrc file in his home directory are searched for appropriate information. If all this fails, the user is prompted for the information.
The port inport specifies which well-known DARPA Internet port to use for the connection~ it
will normally be the value returned from the call Ugetservbyname("exec", "tcp")" (see
getservent(3N». The protocol for connection is described in detail in rexecd(8C).
If the call succeeds, a socket of type SOCK_STREAM is returned to the caller, and given to the
remote command as stdin and stdout. If jd2p is non-zero, then a auxiliary channel to a control
process will be setup, and a descriptor for it will be placed in *jd2p. The control process will return diagnostic output from the command (unit 2) on this channel, and will also accept bytes
on this channel as being UNIX signal numbers, to be forwarded to the process group of the
command~ If jd2p is 0, then the stderr (unit 2 of the remote command) will be made the same
as the stdout and no provision is made for sending arbitrary signals to the remote process,
although you may be able to get its attention by using out-of-band data.
SEE ALSO

rcmd(3X), rexecd(8C)

BUGS
There is no way to specify options to the socket call which rexec makes.

3rd Berkeley Distribution

17 March 1982

1

TERMCAP (3X)

UNIX Programmer's Manual

TERMCAP ( 3X )

NAME

tgetent, tgetnum, tgetilag, tgetstr, tgoto, tputs - terminal independent operation routines
SYNOPSIS

char PC;
char eBC;
char eUP;
short ospeed;
tletent(bp, name)
char ebp, ename;
tletnam (ld)
char eld;
tlettial (ld)
char eld;
char e
tletstr (id, area)
char eld, eearea;
char e
tloto (cm, destcol, destline)
char ecm;
tputs (cp, dent, oate)
register char ecp;
lnt afrcnt;
lnt (eoute) () ;
DESCRIPTION

These functions extract and use capabilities from the terminal capability data base termcap(S).
These are low level routines; see curses(3X) for a higher level package.
Tgetent extracts the entry for terminal name into the buffer at bp. Bp should be a character
buffer of size 1024 and must be retained through all subsequent calls to tgetnum, tge(/iag, and
tgetstr. Tgetent returns -1 if it cannot open the termcap file, 0 if the terminal name given does
not have an entry, and 1 if all goes well. It will look in the environment for a TERMCAP variable. If found, and the value does not begin with a slash, and the terminal type name is the
same as the environment string TERM, the TERMCAP string is used instead of reading the
termcap file. If it does begin with a slash, the string is used as a path name rather than
letcltermcap. This can speed up entry into programs that call tgetent, as well as to help debug
new terminal descriptions or to make one for your terminal if you can't write the file
letcltermcap.
Tgetnum gets the numeric value of capability id, returning -1 if is not given for the terminal.
Tge{/lag returns 1 if the specified capability is present in the terminal's entry, 0 if it is not.
Tgetslr gets the string value of capability id, placing it in the buffer at area, advancing the area
pointer. It decodes the abbreviations for this field described in termeap(S), except for cursor
addressing and padding information.
Tgoto returns a cursor addressing string decoded from em to go to column desteol in line destline.
It uses the external variables UP (from the ap capability) and BC (if bc is given rather than bs)
if necessary to avoid placing \n, AD or A(I in the returned string. (Programs which call tgoto
should be sure to tum off the XTABS bit(s), since tgoto may now output a tab. Note that programs using termcap should in general turn off XTABS anyway since some terminals use controll for other functions, such as nondestructive space.) If a % sequence is given which is not
understood, then tgoto teturns "OOPS".

4th Berkeley Distribution

9 February 1983

1

TERMCAP ( 3X )

UNIX Programmer's Manual

TERMCAP ( 3X )

Tputs decodes the leading padding information of the string cp; qifcnt gives the number of lines
affected by the operation, or 1 if this is not applicable, outc is a routine which is called with
each character in tum. The external variable ospeed should contain the output speed of the terminal as encoded by st(y(3). The external variable PC should contain a pad character to be
used (from the pc: capability) if a null ("@) is inappropriate.
FILES

lusr/lib/libtermcap.a -ltermcap library
I etc/termcap
database
SEE ALSO

ex(1), curses(3X), termcap(S)
AUTHOR

William Joy

4th Berkeley Distribution

9 February 1983

2

INTRO(3C)

UNIX Programmer's Manual

INTRO (3C)

NAME

intro - introduction to compatibility library functions
DESCRIPTION

These functions constitute the compatibility library portion of libc. They are automatically
loaded as needed by the C compiler ccO). The· link editor searches this library under the
"-lc" option. Use of these routines should, for the most part, be avoided. Manual entries for
the functions in this library describe the proper routine to use.
LIST OF FUNCTIONS

Name

alarm
ftime
getpw
gtty
nice
pause
rand
signal
srand
stty
time
times
utime
vlimit
vtimes

Appears on Page

alarm.3c
time.3c
getpw.3c
stty.3c
nice.3c
pause.3c
rand.3c
signal.3c
rand.3c
stty.3c
time.3c
times.3c
utime.3c
vlimit.3c
vtimes.3c

4th Berkeley Distribution

Description

schedule signal after specified time
get date and time
get name from uid
set and get terminal state (defunct)
set program priority
stop until signal
random number generator
simplified software signal facilities
random number generator
set and get terminal state (defunct)
get date and time
get process times
set file times
control maximum system resource consumption
get information about resource utilization

18 July 1983

1

ALARM (3C)

UNIX Programmer's Manual

ALARM (3C)

NAME

alarm - schedule signal after specified time
SYNOPSIS

alarm (seconds)
unsigned seconds;
DESCRIPTION

This interface is obsoleted by setitimer(2).
Alarm causes signal SIGALRM, see signal(3C), to be sent to the invoking process in a number
of seconds given by the argument. Unless caught or ignored, the signal terminates the process.

Alarm requests are not stacked; successive calls reset the alarm clock. If the argument is 0, any
alarm request is canceled. Because of scheduling delays, resumption of execution of when the
signal is caught may be delayed an arbitrary amount. The longest specifiable delay time is
2147483647 seconds.
The return value is the amount of time previously remaining in the alarm clock.
SEE ALSO

sigpause(2), sigvec(2), signaI(3C), sleep(3)

7th Edition

18 July 1983

1

GETPW(3C)

UNIX Programmer's Manual

GETPW (3C)

NAME

getpw - get name from uid
SYNOPSIS

getpw (uid, buf)
char -buf;
DESCRIPTION

Getpw is obsoleted by getpwuid (3).
Getpw searches the password file for the (numerical) uid, and fills in bujwith the corresponding
line; it returns non-zero if uid could not be found. The line is null-terminated.
FILES

/etc/passwd
SEE ALSO

getpwent (3), passwd (5)
DIAGNOSTICS

Non-zero return on error.

7th Edition

19 January' 1983

1

NICE (3C)

UNIX Programmer's Manual

NICE (3C)

NAME

nice - set program priority
SYNOPSIS

nice (incr)
DESCRIPTION

This interface is obsoleted by setpriority (2) •
The scheduling priority of the process is augmented by incr. Positive priorities get less service
than normal. Priority 10 is recommended to users who wish to execute long-running programs
without flak from the administration.
Negative increments are ignored except on behalf of the super-user. The priority is limited to
the range - 20 (most urgent) to 20 (least).
The priority of a process is passed to a child process by fork(2). For a privileged process to
return to normal priority from an unknown state, nice should be called successively with arguments -40 (goes to priority -20 because of truncation), 20 (to get to 0), then 0 (to maintain
compatibility with previous versions of this call).
SEE ALSO

niceO), setpriority(2), fork(2), renice(S)

4th Berkeley Distribution

1 April 1983

1

PAUSE (3C)

UNIX Programmer's Manual

PAUSE (3C)

NAME

pause - stop until signal
SYNOPSIS

pause 0
DESCRIPTION
Pause never returns normally. It is used to give up control while waiting for a signal from
kill(2) or an interval timer, see setitimer(2). Upon termination of a signal handler started during a pause, the pause call will return.

RETURN VALUE

Always returns -1.
ERRORS
Pause always returns:

[EINTR]

The call was interrupted.

SEE ALSO

ki1l(2), select(2), sigpause(2)

4th Berkeley Distribution

18 July 1983

1

RAND (3C)

UNIX Programmer's Manual

RAND (3C)

NAME

rand, srand - random number generator
SYNOPSIS

srand (seed)
Int seed;
rand 0
DESCRIPTION

The newer random (3) should be used In new applications; rand remains for compatibilty.

Rand uses a multiplicative congruential random number ~enerator with period 232 to return successive pseudo-random numbers in the range from 0 to 2 1-1.
The generator is reinitialized by calling srand with 1 as argument. It can be set to a random
starting point by calling srand with whatever you like as argument.
SEE ALSO

random (3)

7th Edition

19 January 1983

1

SIGNAL (3C)

UNIX Programmer's Manual

SIGNAL (3C)

NAME

signal - simplified software signal facilities
SYNOPSIS

#lnclude < silnal.h >
(-silnal (sil, func» 0
void (-func) () ;

DESCRIPTION

Signal is a simplified interface to the more general sigvec(2) facility.
A signal is generated by some abnormal event, initiated by a user at a terminal (quit, interrupt,
stop), by a program error (bus error, etc.), by request of another program (kilO, or when a process is stopped because it wishes to access its control terminal while in the background (see
tty (4) ) . Signals are optionally generated when a process resumes after being stopped, when the
status of child processes changes, or when input is ready at the control terminal. Most signals
cause termination of the receiving process if no action is taken; some signals instead cause the
process receiving them to be stopped, or are simply discarded if the process has not requested
otherwise. Except for the SIGKILL and SIGSTOP Signals, the signal call allows signals either to
be ignored or to cause an interrupt to a specified location. The following is a list of all signals
with names as in the include file :
SIGHUP
1 hangup
SIGINT
2 interrupt
SIGQUIT
3. quit
SIGILL
4. illegal instruction
SIGTRAP
S. trace trap
SIGIOT
6. lOT instruction
SIGEMT
7. EMT instruction
SIGFPE
8. floating point exception
SIGKILL
9 kill (cannot be caught or ignored)
SIGBUS
10. bus error
SIGSEGV
11. segmentation violation
SIGSYS
12. bad argument to system call
SIGPIPE
13 write on a pipe with no one to read it
SIG ALRM
14 alarm clock
SIGTERM
15 software termination signal
SIGURG
16- urgent condition present on socket
SIGSTOP
17t stop (cannot be caught or ignored)
SIGTSTP
18t stop signal generated from keyboard
SIGCONT
19 - continue after stop
SIGCHLD
20 - child status has changed
SIGTTIN
21 t background read attempted from control terminal
SIGTTOU
22t background write attempted to control terminal
SIGIO
23- i/o is possible on a descriptor (see !cnt/(2»
SIGXCPU
24 cpu time limit exceeded (see setrlimit(2»
SIGXFSZ
25 file size limit exceeded (see setrlimit(2»
SIGVTALRM 26 virtual time alarm (see setitimer(2»
SIGPROF
27 profiling timer alarm (see setitimer(2»
The starred signals in the list above cause a core image if not caught or ignored.
If june is SIG_DFL, the default action for signal sig is reinstated; this default is termination
(with a core image for starred signals) except for signals marked with. or t. Signals marked
with - are discarded if the action is SIG_DFL; signals marked with t cause the process to stop.
If june is SIG_IGN the signal is subsequently ignored and pending instances of the signal are

4th Berkeley Distribution

15 June 1983

1

SIGNAL (3C)

UNIX Programmer's Manual

SIGNAL (3C)

discarded. Otherwise, when the signal occurs further occurences of the signal are automatically
blocked and June is called.
A return from the function unblocks the handled signal and continues the process at the point
it was interrupted. Unlike previous signal facUlties, the handler June remains installed after
a signal has been dellvered.

If a caught signal occurs during certain system calls, causing the call to terminate prematurely,
the call is automatically restarted. In particular this can occur during a read or write(2) on a
slow device (such as a terminal; but not a file) and during a wait(2).
The value of signal is the previous (or initial) value of June for the particular signal.
After a /ork(2) or v/ork(2) the child inherits all signals. Exeeve(2) resets all caught signals to
the default action; ignored signals remain ignored.
RETURN VALUE

The previous action is returned on a successful call. Otherwise, -1 is returned and errno is set
to indicate the error.
ERRORS

Signal will fail and no action will take place if one of the following occur:
[EINVAL]
Sig is not a valid signal number.
[EINV AL]
[EINVAL]

An attempt is made to ignore or supply a handler for SIGKlLL or SIGSTOP.
An attempt is made to ignore SIGCONT (by default SIGCONT is ignored).

SEE ALSO

killO), ptrace(2) , kill(2), sigvec(2) , sigblock(2) , sigsetmask(2) , sigpause(2), sigstack(2) ,
setjmp(3), tty(4)
NOTES (VAX-It)

The handler routine can be declared:
handler(sig, code, scp)
Here sig is the signal number, into which the hardware faults and traps are mapped as defined
below. Code is a parameter which is either a constant as given below or, for compatibility
mode faults, the code provided by the hardware. Sep is a pointer to the struet sigeontext used by
the system to restore the process context from before the signal. Compatibility mode faults are
distinguished from the other SIGILL traps by having PSL_CM set in the psI.
The following defines the mapping of hardware traps to signals and codes. All of these symbols
are defined in < signal. h > :
Hardware condition

Signal

Arithmetic traps:
Integer overflow
SIGFPE
Integer division by zero
SIGFPE
Floating overflow trap
SIGFPE
Floating/decimal division by zero SIGFPE
Floating underflow trap
SIGFPE
Decimal overflow trap
SIGFPE
Subscript-range
SIGFPE
Floating overflow fault
SIGFPE
Floating divide by zero fault
SIGFPE
Floating underflow fault
SIGFPE
Length access control
SIGSEGV
Protection violation
SIGBUS

4th Berkeley Distribution

15 June 1983

Code
FPE_INTOVF_TRAP
FPE_INTDIV_TRAP
FPE_FLTOVF_TRAP
FPE FLTDIV TRAP
FPE- FLTUND TRAP
FPE:DECOVF:TRAP
FPE_SUBRNG_TRAP
FPE_FLTOVF_FAULT
FPE_FLTDIV_FAULT
FPE_FLTUND_FAULT

2

SIGNAL (3C)

Reserved instruction
Customer-reserved instr.
Reserved operand
Reserved addressing
Trace pending
Bpt instruction
Compatibility-mode
ChIne
Chms
Chmu

4th Berkeley Distribution

UNIX Programmer's Manual

SIGILL
SIGEMT
SIGILL
SIGILL
SIGTRAP
SIGTRAP
SIGILL
SIGSEGV
SIGSEGV
SIGSEGV

15 June 1983

SIGNAL (3C>

IL L_RES AD_FAULT
ILL PRIVIN FAULT
ILL=RESOP_FAULT
hardware supplied code

3

STIY (3C>

UNIX Programmer's Manual

STIY (3C)

NAME

stty, gtty - set and get terminal state (defunct)
SYNOPSIS

#include

< sgtty.h >

stty (fd, bur>
int fd;
struct sgttyb *buf;
gtty (fd, buf)
int fd;
struct sgttyb .buf;
DESCRIPTION

This interface is obsoleted by ioctl (2).
Stty sets the state of the terminal associated with fd. Gtty retrieves the state of the terminal
associated with fd. To set the state of a terminal the call must have write permission.

The stty call is actually "ioctl(fd, TIOCSETP, buf)", while the gtty call is "ioctl(fd,
TIOCGETP, buf)". See ioct/(2) and tty(4) for an explanation.
DIAGNOSTICS

If the call is successful 0 is returned, otherwise -1 is returned and the global variable errno
contains the reason for the failure.
SEE ALSO

ioctl(2), tty(4)

4th Berkeley Distribution

1 Apri11983

1

TIME (3C)

TIME (3C)

UNIX Programmer's Manual

NAME

time, ftime - get date and time
SYNOPSIS

long time(O)
10Dg time (tloc)
10Dg .tloc;
#include < sys/types.h >
#include < sys/timeb.h >
ftime(tp)
strud timeb .tp;
DESCRIPTION

These interfaces are obsoleted by gettimeofday (2) •
Time returns the time since 00:00:00 GMT, Jan. 1, 1970, measured in seconds.

If tiDe is nonnull, the return value is also stored in the place to which tiDe points.
The ftime entry fills in a structure pointed to by its argument, as defined by

1*

< sysltimeb.h > :

timeb.h 6.183/07/29*1

/*

* Structure returned by ftime system call
./
struct timeb
{
time_t
unsigned
short
short
};

time;
short milli tm;
timezone;
dstflag;

The structure contains the time since the epoch in seconds, up to 1000 milliseconds of moreprecise interval, the local time zone (measured in minutes of time westward from Greenwich),
and a flag that, if nonzero, indicates that Daylight Saving time applies locally during the
appropriate part of the year.
SEE ALSO

date (1), gettimeofday (2), settimeofday (2), ctime (3)

4th Berkeley Distribution

1 April 1983

1

TIMES (3C)

UNIX Programmer's Manual

TIMES (3C)

NAME

times - get process times
SYNOPSIS

#include < sys/types.h >
#include < sys/times.h >
times (buffer)
strud tms -buffer;

DESCRIPTION

This interface is obsoleted by getrusage(2).
Times returns time-accounting information for the current process and for the terminated child
processes of the current process. All times are in 11HZ seconds, where HZ is 60.
This is the structure returned by times:
1*
times.h 6.1
83/07/29
/*

* Structure returned by timesO
*1
struct tms {
time_t
time_t
time_t
time_t

tms_utime;
tms_stime;
tms_cutime;
tms_cstime;

1* user time */
I * system time */
1* user time, children */
/* system time, children */

The children times are the sum of the children's process times and their children's times.
SEE ALSO

time(l), getrusage(2), wait3 (2), time(3)

4th Berkeley Distribution

1 April 1983

1

UTIME(3C)

UNIX Programmer's Manual

UTIME (3C)

NAME

utime - set file times
SYNOPSIS

#include 
utime (file, timep)
char -file;
time_t timep(2);
DESCRIPTION

This interface is obsoleted by utimes (2).
The utime call uses the 'accessed' and 'updated' times in that order from the timep vector to set
the corresponding recorded times for file.
The caller must be the owner of the file or the super-user. The 'inode-changed' time of the file
is set to the current time.
SEE ALSO

utimes(2), stat(2)

4th Berkeley Distribution

1 April 1983

1

VLIMIT(3C)

UNIX Programmer's Manual

VLIMIT (3C)

NAME

vlimit - control maximum system resource consumption
SYNOPSIS

#include < sys/vlimit.h >
vlimit(resource, value)

DESCRIPTION

This facility is superseded by getrlimit (2) •
Limits the consumption by the current process and each process it creates to not individually
exceed value on the specified resource. If value is specified as -1, then the current limit is
returned and the limit is unchanged. The resources which are currently controllable are:
LIM_NORAISE A pseudo-limit; if set non-zero then the limits may not be raised. Only the
super-user may remove the noraise restriction.
LIM_CPU
the maximum number of cpu-seconds to be used by each process
LIM_FSIZE
the largest single file which can be created
LIM_DATA
the maximum growth of the data+stack region via sbrk(2) beyond the end of
the program text
LIM_STACK the maximum size of the automatically-extended stack region
LIM_CORE
the size of the largest core dump that will be created.
LIM_MAXRSS a soft limit for the amount of physical memory (in bytes) to be given to the
program. If memory is tight, the system will prefer to take memory from
processes which are exceeding their declared LIM_MAXRSS.
Because this information is stored in the per-process information this system call must be executed directly ·by the shell if it is to affect all future processes created by the shell; limit is thus a
built-in command to csh(1).
The system refuses to extend the data or stack space when the limits would be exceeded in the
normal way; a break call fails if the data space limit is reached, or the process is killed when the
stack limit is reached (since the stack cannot be extended, there is no way to send a signal!).
A file i/o operation which would create a file which is too large will cause a signal SIGXFSZ to
be generated, this normally terminates the process, but may be caught. When the cpu time
limit is exceeded, a signal SIGXCPU is sent to the offending process; to allow it time to process
the signal it is given 5 seconds grace by raising the cpu time limit.
SEE ALSO

csh(1)

BUGS
If LIM_NO RAISE is set, then no grace should be given when the cpu time limit is exceeded.

There should be limit and unlimit commands in shU) as well as in csh.
This cail is peculiar to this version of UNIX. The options and specifications of this system call
and even the call itself are subject to change. It may be extended or replaced by other facilities
in future versions of the system.

4th Berkeley Distribution

18 July

198~

1

VTIMES (3C)

VTIMES (3C)

UNIX Programmer's Manual

NAME

vtimes - get information about resource utilization
SYNOPSIS

vtimes (par_vm, ch_vm)
struct vtimes .par_vm, *ch_vm;
DESCRIPTION

This facility is superseded by getrusage (2) .

Vtimes returns accounting information for the current process and for the terminated child
processes of the current process. Either par_vm or ch_vm or both may be 0, in which case only
the information for the pointers which are non-zero is returned.
After the call, each buffer contains information as defined by the contents of the include file

lusrlincludelsyslvtimes. h:
struct vtimes {
int
vm_utime;
/. user time (.HZ) -I
int
vm_stime;
/- system time (.HZ) .1
/- divide next two by utime+stime to get averages -/
unsigned vmJdsrss;
/- integral of d +s rss -/
unsigned vmJxrss;
/- integral of text rss -I
int
vm maxrss;
/- maximum TSS . /
int
vm- majflt;
I- major page faults -/
int
vm- minflt;
I- minor page faults
int
vm_nswap;
/- number of swaps -I
int
vmJnblk;
/. block reads ./
int
vm_oublk;
/- block writes -/
};

*'

The vm_utime and vm_stime fields give the user and system time respectively in 60ths of a
second (or 50ths if that is the frequency of wall current in your locality.) The vm_idrss and
vm_ixrss measure memory usage. They are computed by integrating the number o~ memory
pages in use each over cpu time. They are reported as though computed discretely, adding the
current memory usage (in 512 byte pages) each time the clock ticks. If a process used 5 core
pages over 1 cpu-second for its data and stack, then vm_idsrss would have the value 5-60, where
vm_utime+vm_stime would be the 60. Vm_idsrss integrates data and stack segment usage, while
vm_ixrss integrates text segment usage. Vm_maxrss reports the maximum instantaneous sum of
the text + data + stack core-resident page count.
The vm_mai/lt field gives the number of page faults which resulted in disk activity; the
vm_minflt field gives the number of page faults incurred in simulation of reference bits~
vm_nswap is the number of swaps which occurred. The number of file system input/output
events are reported in vm_inhlk and vm_oublk These numbers account only for real i/o; data
supplied by the caching mechanism is charged only to the first process to read or write the data .
. SEE ALSO

time (2), wait3 (2)

BUGS
This call is peculiar to this version of UNIX. The options and specifications of this system call
are subject to change. It may be extended to include additional information in future versions
of the system.

4th Berkeley Distribution

13 June 1983

1

INTRO (4)

UNIX Programmer's Manual

INTRO(4)

NAME

intro - introduction to special files and hardware support
DESCRIPTION

This section describes the special files, related driver functions, and networking support available in the system. In this part of the manual, the SYNOPSIS section of each configurable device gives a sample specification for use in constructing a system description for the co1t/ig(S)
program. The DIAGNOSTICS section lists messages which may appear on the console and in
the system error log /usr/adm/messages due to errors in device operation.
This section contains both devices which may be configured into the system, 444" entries, and
network related information, "4N", 444P", and "4F" entries; The networking support is introduced in intro(4N).
VAX DEVICE SUPPORT

This section describes the hardware supported on the DEC VAX-It. Software support for
these devices comes in two forms. A hardware device may be supported with a character or
block device driver, or it may be used within the networking subsystem and have a network interlace driver. Block and character devices are accessed through files in the file system of a special
type; c,c. mknod(S). Network interfaces are indirectly accessed through the interprocess communication facilities provided by the system; see socket (2) .
A hardware device is identified to the system at configuration time and the appropriate device
or network interface driver is then compiled into the system. When the resultant system is
booted, the autoconfiguration facilities in the system probe for the device on either the
UNIBUS or MASSBUS and, if found, enable the software support for it. If a UNIBUS device
does not respond at autoconfiguration time it is not accessible at any time afterwards. To
enable a UNIBUS device which did not autoconfigure, the system will have to be rebooted. If a
MASSBUS device comes "on-line" after the autoconfiguration sequence it will be dynamically
autoconfigured into the running system.
The autoconfiguration system is described in autocotif(4). VAX specific device support is
described in "4V" entries. A list of the supported devices is given below.
SEE ALSO

intro(4), intro(4N), autoconf(4), config(S)
LIST OF DEVICES

The devices listed below are supported in this incarnation of the system. Devices are indicated
by their functional interface. If second vendor products provide functionally identical interfaces
they should be usable with the supplied software. (Beware however that we promise the
software works ONLY with the hardware indicated on the appropriate manual page.)
acc
ad
css
ct
db
dmc
dmf
dn
dz

ec
en
kg
fl
hk

ACC LH/DH IMP communications interface
Data translation A/D interface
DEC IMP-IIA communications interface
C/ A/T phototypesetter
DH-ll emulators, terminal multiplexor
DEC DMC-1l/DMR-ll point-to-point communications device
DEC DMF-32 terminal multiplexor
DEC DN-ll autodialer interface
DZ-Il terminal multiplexor
3Com lOMbls Ethernet controller
Xerox 3Mb/s Ethernet controller (obsolete)
KL-ll/DL-11 W line clock
VAX-ll/7S0 console floppy interface
RK6-11/RK06 and RK07 moving head disk

4th Berkeley Distribution

27 July 1983

1

INTRO(4)

hp
ht
hy
ik
it
lp
mt
pel
ps

rx
tm
ts
tu

uda
un
up
ut

uu
va
vp

vv

UNIX Programmer's Manual

INTRO (4)

MASSBUS disk interface (with RP06, RM03, RMOS, etc.)
TM03 MASS BUS tape drive interface (with TE·16, TU·4S, TU·77)
DR·IIB or 01·13 interface to an NSC Hyperchannel
Ikonas frame buffer graphics device interface
Interlan lOMb/s Ethernet controller
LP·ll parallel line printer interface
TM78 MASSBUS tape drive interface
DEC PCL-l1 communications interface
Evans and Sutherland Picture System 2 graphics interface
DEC RX02 floppy interface
TM-l1/TE-IO tape drive interface
TS·l1 tape drive interface
VAX-I 1/730 TUS8 console cassette interface
DEC UDA-SO disk controller
DR·I1W interface to Ungermann-Bass
Emulex SC-21 V UNIBUS disk controller
UNIBUS TU-4S tape drive interface
TUS8 dual cassette drive interface (DLIO
Benson-Varian printer/plotter interface
Versatec printer/plotter interface
Proteon proNET 10Mb/s ring network interface

4th Berkeley Distribution

27 July 1983

2

INTRO (4N)

UNIX Programmer's Manual

INTRO (4N)

NAME

networking - introduction to networking facilities
SYNOPSIS

#Include 
#Include < net/route.h >
#lnclude < net/H.h >
DESCRIPTION

This section briefly describes the networking facilities available in the system. Documentation
in this part of section 4 is broken up into three areas: protocol-families, protocols, and network
interfaces. Entries describing a protocol-family are marked "4F", while entries describing protocol use are marked "4P". Hardware support for network interfaces are found among the
standard "4" entries.
All network protocols are associated with a specific protocol-family. A protocol-family provides
basic services to the protocol implementation to allow it to function within a specific network
environment. These services may include packet fragmentation and reassembly, routing,
addressing, and basic transport. A protocol-family may support multiple methods of addressing,
though the current protocol implementations do not. A protocol-family is normally comprised
of a number of protocols, one per socket(2) type. It is not required that a protocol-family support all socket types. A protocol-family may contain multiple protocols supporting the same
socket abstraction.
A protocol supports one of the socket abstractions detailed in socket(2). A specific protocol
may be accessed either by creating a socket of the appropriate type and protocol-family, or by
requesting the protocol explicitly when creating a socket. Protocols normally accept only one
type of address format, usually determined by the addressing structure inherent in the design of
the protocol-family/network architecture. Certain semantics of the basic socket abstractions are
protocol specific. All protocols are expected to support the basic model for their particular
socket type, but may, in addition, provide non-standard facilities or extensions to a mechanism.
For example, a protocol supporting the SOCK_STREAM abstraction may allow more than one
byte of out-of-band data to be transmitted per out-of-band message.
A network interface is similar to a device interface. Network interfaces comprise the lowest
layer of the networking subsystem, interacting with the actual transport hardware. An interface
may support one or more protocol families, and/or address formats. The SYNOPSIS section of
each network interface entry gives a sample specification of the related drivers for use in providing a system description to the co1ffig(8) program. The DIAGNOSTICS section lists messages which may appear on the console and in the system error log lusrladm/messages due to
errors in device operation.
PROTOCOLS

The system currently supports only the DARPA Internet protocols fully. Raw socket interfaces
are provided to IP protocol layer of the D ARP A Internet, to the IMP link layer (1822), and to
Xerox pUpal layer operating on top of 3Mb/s Ethernet interfaces. Consult the appropriate
manual pages in this section for more information regarding the support for each protocol family.
ADDRESSING

Associated with each protocol family is an address format. The following address formats are
used by the system:
#define
#define
#define
#define

AF_UNIX
AF_!NET
AF_IMPLINK
AF_PUP

4th Berkeley Distribution

1
2
3
4

I.
I.
I.
I.

local to host (pipes, portals) .1
internetwork: UDP, TCP, etc . • 1
arpanet imp addresses .1
pup protocols: e.g. asp .1

7 July 1983

1

lNTRO(4N)

INTRO(4N)

UNIX Programmer's Manual

ROUTING

The network facilities provided limited packet routing. A simple set of data structures comprise
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. A user process,
the routing daemon, maintains this data base with the aid of two socket specific ioctl(2) commands, SIOCADDRT and SIOCDELRT~ The commands allow the addition and deletion of a
single routing table entry, respectively. Routing table manipulations may only be carried out by
super-user.
A routing table entry has the following form, as defined in
struct rtentry {
uJong
struct
struct
short
short
UJODg

struct

< nedroute~h >;

rt_hash;
sockaddr rt_dst;
sockaddr rt-Bateway;
rt_Oags;
rt_refcnt;
rt_use;
ifnet -rtjfp;

};
with rt..flags defined from,
#define RTF_UP
#define RTF_GATEWAY
#define RTF_HOST

Ox}
Ox2
Ox4

I- route usable -I
I- destination is a gateway -I
I- host entry (net otherwise) -I

Routing table entries come in three flavors: for a specific host, for all hosts on a specific network, for any destination not matched by entries of the first two types (a wildcard route). When
the system is booted, each network interface autoconfigured installs a routing table entry when
it wishes to have packets sent through it. Normally the interface specifies the route through it
is a "direct" connection to the destination host or network. If the route is direct, the transport
layer of a protocol family usually requests the packet be sent to the same host specified in the
packet. Otherwise, tbe interface may be requested to address the packet to an entity different
from the eventual recipient (i.e. the packet is forwarded).
Routing table entries installed by a user process may not specify the hash, reference count, use,
or interface fields; these are filled in by the routing routines. If a route is in use when it is
deleted (r,-,ej'cnt is non-zero), the resources associated with it. will not be reclaimed until
further references to it are released.
The routing code returns EEXlST if requested to duplicate an existing. entry, ESRCH if
requested to delete a non-existant entry, or ENOBUFS if insufficient resources were available tC'
install a new route.
User processes read the routing tables through the Ide"lkmem 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.

4th Berkeley Distribution

7 July 1983

2

INTRO(4N)

UNIX Programmer's Manual

INTRO(4N)

INTERFACES
Each network interface in a system corresponds to a path through which messages may be sent
and received. A network interface usually has a hardware device associated with it, though certain interfaces such as the loop back interface, 10(4), do not.
At boot time each interface which has underlying hardware support makes itself known to the
system during the autoconfiguration process. Once the interface has acquired its address it is
expected to install a routing table entry so that messages may be routed through it. Most interfaces require some part of their address specified with an SIOCSIFADDR ioctl before they will
allow traffic to flow through them. On interfaces where the network-link layer address mapping
is static, only the network number is taken from the ioctl; the remainder is found in a hardware
specific manner. On interfaces which provide dynamic network-link layer address mapping
facilities (e.g. 10Mb/s Ethernets), the entire address specified in the ioctl is used.
The following ioetl calls may be used to manipulate network interfaces. Unless specified otherwise, the request takes an jfrequest structure as its parameter. This structure has the form
struct ifreq {
char
ifr name[16];
/- name of interface (e.g. "ecO") -/
union { struct sockaddr ifru_addr;
struct sockaddr ifru_dstaddr;
short ifruJlags;
} ifr ifru;
#defineifr_addrifrJfru.ifru_addr
/- address -/
#defineifr dstaddr
ifr ifru.ifru dstaddr
/- other end of p-to-p link -/
#defineifr=flagsifrJfru.ifruJlags /- flags -/
};
SIOCSIFAD DR
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.
SIOCGIFDST ADDR
Get point to point address for interface.
SIOCSIFFLAGS
Set interface flags field. If the interface is marked down, any processes currently routing packets through the interface are notified.
SIOCGIFFLAGS
get interface flags.
SIOCGIFCONF
Get interface configuration list. This request takes an i/eorif structure (see below) as a
value-result parameter. The i/c_len field should be initially set to the size of the buffer
pointed to by i/c_br,if. On return it will contain the length, in bytes, of the configuration
list.

/• Structure used in SIOCGIFCONF request.
- Used to retrieve interface configuration
- for machine (useful for programs which

4th Berkeley Distribution

7 July 1983

3

INTRO(4N)

UNIX Programmer's Manual

INTRO(4N)

- must know all networks accessible).
-/
struct ifconf {
int
ifcJen;
/- size of associated buffer -/
union {
caddr_t ifcu_buf;
struct ifreq -ifcu_req;
} ifcjfcu;
#defineifc buf ifc ifcu.ifcu buf
/- buffer address -/
#defineifc:req ifc)fcu.ifcu:req/- array of structures returned -/
};
SEE ALSO

socket(2), ioct1(2), intro(4), config(S), routed(SC)

4th Berkeley Distribution

7 July 1983

4

ACC (4)

UNIX Programmer's Manual

ACC (4)

NAME

acc - ACC LH/DH IMP interface
SYNOPSIS

pseudo-device imp
device accO at ubaO csr 167600 vector accrint accxint
DESCRIPTION

The ace device provides a Local Host/Distant Host interface to an IMP. It is normally used
when participating in the DARPA Internet. The controller itself is not accessible to users, but
instead provides the hardware support to the IMP interface described in imp(4). When
configuring, the imp pseudo-device must also be included.
DIAGNOSTICS

acc%d: not alive. The initialization routine was entered even though the device did not
autoconfigure. This indicates a system problem.
acc%d: can't initialize. Insufficient UNIBUS resources existed to initialize the device. This is
likely to occur when the device is run on a buffered data path on an 11/750 and other network
interfaces are also configured to use buffered data paths, or when it is configured to use
buffered data paths on an 11/730 (which has none).
accOfod: imp doesn't respond, icsr=Ofob. The driver. attempted to initialize the device, but the
IMP failed to respond after 500 tries. Check the cabling .
.acc%d: stray xmit interrupt, csr=Ofob. An interrupt occurred when no output had previously
been started.
acc%d: output error, ocsr=%b, icsr=%b. The device indicated a problem sending data on output.
acc%d: input error, csr=%b. The device indicated a problem receiving data on input.
acc%d: bad length =%d. An input operation resulted in a data transfer of less than 0 or more
than 1008 bytes of data into memory (according to the word count register). This should never
happen as the maximum size of a host-IMP message is 1008 bytes.

4th Berkeley Distribution

27 July 1983

AD(4)

UNIX Programmer's Manual

AD(4)

NAME

ad - Data Translation AID converter
SYNOPSIS

device adO at ubaO csr 0170400 vector adintr
DESCRIPTION

Ad provides the interface to the Data Translation AID converter. This is not a real-time driver.
but merely allows the user process to sample the board's channels one at a time. Each minor
device selects a different AID board.

The driver communicates to a user process by means of ioctls. The AD_CHAN ioctl selects
which channel of the board to read. For example,
chan = 5~ ioctJ(fd. AD_CHAN, &chan)~
selects channel 5. The AD_READ ioctl actually reads the data and returns it to the user process. An example is
ioctl(fd, AD_READ, &data)~
FILES

Idevlad
DIAGNOSTICS

None.

4th Berkeley Distribution

27 July 1983

1

~'lallllal

UNIX Progr(lll1l1ler's

ARP(4P)

ARP(4P)

NAME

arp

Address Rc~,olution Protocol

SYNOPSIS

pselldo-dcvicc dhcl'
I)I':SCI~II)'I'ION

t\ I{ P is " protocol w;cd to dYll;llllil';tll y Illap hel w('el1 nt\ R P/\ Illternet and 1()\1 b/s Fthet'llcl
r otllvr host) */

X

TIJr :Iddrl's~; 1;lIlJily 1'01' tile (/1/', J1i1 sock.lddr mllst hl' /\1: 1N FT: I<)t' tile /(1/', hil sock:lddr it Illllst he
AI: ,lINSPLC. Tile ollly ILtg hits which 11I:IY Ill' writtl'll ;11\' XIV,PIJUd ;IIHI ATF, ,PUBI ..
ATI:,PI':Rrvl calls<..'s the l'lltry to h ...' Iwrlll:tllcnt if till' jocll call Slll'Cl'cds, Till..' pl'culi:lr 1l;ltlire of the
A~\P t"()llly 1I1:lchille to talk to a non·;\RP 1l1;\chinc.
;\I\P W;ltC!1CS p;lssivl'ly I'or hUSh impersonatitlg the Im,.';11 host (i.l'. ;1 host which rl'sponds lo all AI{P
tnllpping reqllest I<)r the local h()st's lIddl'l'ss).

7th Fdilioll

II

.Llllilary

1')X4

I\RP(4P)

UNIX Progrdllllllcr's Mantlal

/\RP(4P)

1)IA(;r'J{)S'rICS
Sl'nt from l'lhl'rlh.1 :uldrl'ss: %x :%\:%\:%x:%\:% ..... /\ RI' h;I~\ dbcovcrcd
allothcr h()~1 Oil till' local \lt~t\\ork which n:spPlllis to llIappillg requcsts I()I' its own Intcl'1IcLH.ldress.

dupliratc IP addn.'ss!!

SEI': ALSO
cc(4), dc(4). il(·D, illcl(41·1 ;lrp(XC), ill:onfiF,O)(.')
;\11 Flhcrnel Addn.'ss Resolutioll Protlll'ul, RI'{ 'X76, Dave PllIIlIllK'I', MIT.
BU(;S
/\I{ I) p~ick('ls 011 till'

is (I() hyll's
will.

7th I~dilioll

(flO!

FtlH.'r/l\..,t IISl' only ~l} h~ ll.'S PI' dal;l, hm" C\'l'r, the sl1l;l1k~t leg;" Fth~~J'Ih.'1 p:lcket
illcluding ('Rt'). SOIllC sy ... tl'IIlS llIay \lot l'I!I()rCt~ the Illillillllllll pac~ct Si/C, others

II January 1984

2 .

AUTOCONF(4)

UNIX Programmer's Manual

AUTOCONF (4)

NAME

autoconf - diagnostics from the autoconfiguration code
DESCRIPTION
When UNIX bootstraps it probes the innards of the machine it is running on and locates controllers, drives, and other devices, printing out what it finds on the console. This procedure is
driven by a system configuration table which is processed by colt/ig(8) and compiled into each
kernel.

Devices in NEXUS slots are normally noted, thus memory controllers, UNIBUS and MASSBUS
adaptors. Devices which are not supported which are found in NEXUS slots are noted also.
MASSBUS devices are located by a very deterministic procedure since MASSBUS space is completely probe-able. If devices exist which are not configured they will be silently ignored~ if
devices exist of unsupported type they will be noted.
UNIBUS devices are located by probing to see if their control-status registers respond. If not,
they are silently ignored. If the control status register responds but the device cannot be made
to interrupt, a diagnostic warning will be printed on the console and the device will not be
available to the system.
A generic system may be built which picks its root device at boot time as the Hbest" available
device (MASSBUS disks are better than SMD UNIBUS disks are better than RK07's~ the device must be drive 0 to be considered.) If such a system is booted with the RB ASKNAME
option of (see reboot(2», then the name of the root device is read from the consoi'e terminal at
boot time, and any available device may be used.
SEE ALSO

intro(4), config(S)
DIAGNOSTICS
cpu type %d not configured. You tried to boot UNIX on a cpu type which it doesn't (or at least
this compiled version of UNIX doesn't) understand.

mba%d at tr%d. A MASSBUS adapter was found in tr%d (the NEXUS slot number). UNIX
will call it mba%d.
%d mba's not configured. More MASSBUS adapters were found on the machine than were
declared in the machine configuration~ the excess MASSBUS adapters will not be accessible.
uba%d at tr%d. A UNIBUS adapter was found in tr%d (the NEXUS slot number). UNIX will
call it uba%d.
dr32 unsupported (at tr %d). A DR32 interface was found in a NEXUS, for which UNIX does
not have a driver.
mcr%d at tr%d. A memnry controller was found in tr%d (the NEXUS slot number). UNIX
will call it mcr%d.
5 mer's unsupported. UNIX supports only 4 memory controllers per cpu.
mpm unsupported (at tr%d). Multi-port memory is unsupported in the sense that UNIX does
not know how to poll it for ECC errors.
Ofos%d at mba%d drive Ofod. A tape formatter or a disk was found on the MASSBUS~ for disks
%s%d will look like "hpO", for tape formatters like Hhtl". The drive number comes from the
unit plug on the drive or in the TM formatter (not on the tape drive~ see below).
%s%d at %s%d slave %d. (For MASSBUS de·!ices). Which would look like HtuO at htO slave
0", where tuO is the name for the tape device and htO is the name for the formatter. A tape
slave was found on the tape formatter at the indicated drive number (on the front of the tape
drive). UNIX will call the device, e.g., tuO.

4th Berkeley Distribution

27 July 1983

AUTOCONF (4)

UNIX Programmer's Manual

AUTOCONF(4)

%s%d at uba%d csr %0 vee %0 ipl %x. The device %s%d, e.g. dzO was found on uba%d at
control-status register address %0 and with device vector %0. The device interrupted at priority
level %x.
%s%d at uba%d esr %0 zero vector. The device did not present a valid interrupt vector. rather
presented 0 (a passive release condition) to the adapter.
%s%d at uba%d csr %0 didn't interrupt. The device did not interrupt, likely because it is broken, hung, or not the kind of device it is advertised to be.
%s%d at %s%d slave %d. (For UNIBUS devices). Which would look like HUpO at scO slave
0", where upO is the name of a disk drive and seO is the name of the controller. Analogous to
MASS BUS case.

4th Berkeley Distribution

27 July 1983

2

BK(4)

UNIX Programmer's Manual

BK (4)

NAME

bk - line discipline for machine-machine communication (obsolete)
SYNOPSIS

pseudo-device bk
DESCRIPTION

This line discipline provides a replacement for the old and new tty drivers described in tty (4)
when high speed output to and especially input from another machine is to be transmitted over
a asynchronous communications line. The discipline was designed for use by the Berkeley network. It may be suitable for uploading of data from microprocessors into the system. If you
are going to send data over asynchronous communications lines at high speed into the system,
you must use this discipline, as the system otherwise may detect high input data rates on terminal lines and disabl~s the lines~ in any case the processing of such data when normal terminal
mechanisms are involved saturates the system.
The line discipline is enabled by a sequence:
#include 
int Idisc
NETLDISC, fildes; ...
ioctl (fildes, TIOCSETD, &ldisc>;

=

A typical application program then reads a sequence of lines from the terminal port, checking
header and sequencing information on each line and acknowledging receipt of each line to the
sender, who then transmits another line of data. Typically several hundred bytes of data and a
smaller amount of control information will be received on each handshake.
The old standard teletype discipline can be restored by doing:

=

Idisc
OTTYDISC;
ioctl (fildes, TIOCSETD, &ldisC>;
While in networked mode, normal teletype output functions take place. Thus, if an 8 bit output data path is desired, it is necessary to prepare the output line by putting it into RAW mode
using ;oct/(2). This must be done before changing the discipline with TIOCSETD, as most
;octl(2) calls are disabled while in network line-discipline mode.
When in network mode, input processing is very limited to reduce overhead. Currently the
input path is only 7 bits wide, with newline the only recognized character, terminating an input
record. Each input record must be read and acknowledged before the next input is read as the
system refuses to accept any new data when there is a record in the buffer. The buffer is limited in length, but the system guarantees to always be willing to accept input resulting in 512
data characters and then the terminating newline.
User level programs should provide sequencing and checksums on the information to guarantee
accurate data transfer.
SEE ALSO

tty (4)
DIAGNOSTICS

None.
BUGS

The Purdue uploading line discipline, which provides 8 bits and uses timeout's to terminate
uploading should be incorporated into the standard system, as it is much more suitable for
mic;:roprocessor connections.

4th Berkeley Distribution

1 September 1981

CONS (4)

UNIX Programmer's Manual

CONS (4)

NAME

cons - VAX-II console interface
DESCRIPTION

The console is available to the processor through the console registers. It acts like a normal
terminal, except that when the local functions are not disabled, control-P puts the console in
local console mode (where the prompt is "> > > "). The operation of the console in this
mode varies slightly per-processor.
On an 11/780 you can return to the conversational mode using the command "set t p" (set terminal program) if the processor is still running or "continue" if it is halted. The latter command may be abbreviated "c". If you hit the break key on the console, then the console will
go into ODT (console debugger mode). Hit a "P" (upper-case letter p) to get out of this
mode.
On an 11/750 or an 11/730 the processor is halted whenever the console is not in conversational mode, and typing HC" returns to conversational mode. When in console mode on an
11/750 which has a remote diagnosis module, a "D will put you in remote diagnosis mode,
where the prompt will be "ROM>". The command "ret" will return from remote diagnosis
mode to local consoJe mode.
With the above proviso's the console works like any other UNIX terminal.
FILES

Idev/console
SEE ALSO
tty(4), reboot(8)

VAX Hardware Handbook
DIAG!'lOSTICS

None.

4th Berkeley Distribution

27 July 1983

1

ess (4)

UNIX Programmer's Manual

ess (4)

NAME

css - DEe IMP-IIA LH/DH IMP interface
SYNOPSIS

pseudo-device imp
device cssO at ubaO csr 167600 flags 10 vector cssrint cssxint
DESCRIPTION

The ess device provides a Local Host/Distant Host interface to an IMP. It is normally used
when participating in the DARPA Internet. The controller itself is not accessible to users, but
instead provides the hardware support to the IMP interface described in imp(4). When
configuring, the imp pseudo-device is also included.
DIAGNOSTICS

css%d: not alive. The initialization routine was entered even· though the device did not
autoconfigure. This is indicates a system problem.
css%d: can't initialize. Insufficient UNIBUS resources existed to initialize the device. This is
likely to occur when the device is run on a buffered data path on an 11/750 and other network
interfaces are also configured to use buffered data paths, or when it is configured to use
buffered data paths on an 11/730 (which has none).
css%d: imp doesn't respond, icsr=%b. The driver attempted to initialize the device, but the
IMP failed to respond after 500 tries. Check the cabling.
css%d: stray output interrupt csr=%b. An interrupt occurred when no output had previously
been started.
css%d: output error, ocsr=%b icsr=%b. The device indicated a problem sending data on output.
css%d: recv error, csr=%b. The device indicated a problem receiving data on input.
cssOfod: bad length =%d. An input operation resulted in a data transfer of less than 0 or more
than 1008 bytes of data into memory (according to the word count register). This should never
happen as the maximum size of a host-IMP message is 1008 bytes.

4th Berkeley Distribution

27 July 1983

CT (4)

UNIX Programmer's Manual

CT(4)

NAME

ct .- phototypesetter interface
SYNOPSIS

device ctO at ubaO csr 0167760 vector ctintr
DESCRIPTION

This provides an interface to a Graphic Systems C/ A/T phototypesetter. Bytes written on the
file specify font, size, and other control information as weI) as the characters to be flashed. The
coding is not described here.
Only one process may have this file open at a time. It is write-only.
FILES

/dev/cat
SEE ALSO

troff(l)
Phototypesetter interface specification
DIAGNOSTICS

None.

4th Berkeley Distribution

27 July 1983

1

DE ( 4 )

UN IX Programmer's Manual

DE(4)

NAME

de . DEC DEUN/\ 10 Mh/s Ftltemet

interf~\cc

SYNOPSIS

tlt'lkc cleO at Uh'10 csr 0174310 vedOf dcintr
DESCHIPTION

The t/(' illtcrfclce provides access to a 10 i\,lh/s Ftlwl"11el network through

it

DEl.ll'!':\ controller.

'1'11'.' llo:-;t\; Internct r 011 dn icc illitialil.alion.
Paeket~,

(lrc being I'ccci\'Cd hy tllc illte'rElee 1;lstcr t!l;11l Ihi.:Y

handll' af%t1. The illtl'r!;lcc was h:llltkd a

lIfbllit:lhlc dddrcss !;lI11ily; tile packet W;IS dropped.
SEE A.,SO
illll'({~N). ill~~l(41·').

;)rp(4P)

BUGS

'1'11\' PliP protocol 1;lIllily should he adtkd.

,11h Bcrkeky Dislribution

NYU

IlH:'SS:lgC

\·:ith

addrcssl..'~;

(;11\

hc ser-

I(>nllatleu in an

DH (4)

UNIX Programmer's Manual

DH(4)

NAME

dh .... DH'·ll/DM .. 11 communications multiptexer
SYNOPSIS

device dbOat ubaO csr 0160010 vector dhrint 'dbxint
devicedmO :at ubaOcsr 0170500 \'eetor dmintl'
D£SCRI·PT,)ON
A dh-llprovides 16communicalion lines; d'm-ll "s may be optionaUy paired with dh-ll's t'O
provide modemconttol for the lines.

Each lin'e attached t'O the DH-ll co'mmunicationsmultiplexer behaves as described in t{V (4).
InpUland output roreach line may independently be set to ru:n at any 'Of 16 speeds: see tty ( 4)
f'Or the encoding.
Bit i offiags may be specified fer a dh to sa}' that a line is 'nct properly connected, and thal the
line should be treated :as ha.rd.. wired with carrier always .present. Thus specifying Hflags
Ox0004~' in :.the specification of dhO would cause line uyh2 t6 be treated in this way.
The dh drivernormaUy uses input sitos and pons for input at each clock tick (10 milliseconds)
rather than taki-ogan interrupt en each input character .

FILES
Idev!tty[hi) [O-9a-f]
Idev/uyd{O-9a-f]
SEE ALSO

tty (4)
Dl,AtiNOSTICS
db%ci': NX~t NOte'sponse from UNIBUS ·on a dmatransfer within a timeout period. This is
'Often :.foUowed by a UN1SUS adapter e;rrOT. This eccursmOSl freqouentlywhen the UNIBUS is
heavily :ioadeda:;nd wben devices wbich hog tbe bus (su'chas -rk07's) are presenl. It i's not seri-

ous.
dh'lt/od:siio 'ovedlow . the <:ha:racter tnput silo :overftowed ibefo:re it could be serviced. This can
hap'pen it a harde.rror occutS when the :CPU is ru'nni'ng with elevated .priority, as the system
win then,dnl :a message on tbe:conso!le w:lth tnterrupls disabled. If the Berknel is running on
a :dh linea,t .highspeed (e.g. 9600 baud.), there is only llrSthof a secend 'of buffering 'capacity
in lhe 'silo, :and overran \Sp.
Each line attached to a DMF-32 serial line port behaves as described in tty(4). Input and output for each line may independently be set to run at any of 16 speeds~ see 10'(4) for the encoding.
Bit i of flags may be specified for a dm/to to say that a line is not properly connected, and that
the line should be treated as hard-wired with carrier always present. Thus specifying Hflags
Ox0004" in the specification of dmjO would cause line ttyh2 to be treated in this way.
The dmfdriver normally uses input silos and polls for input at each clock tick 00 milliseconds).
FILES

Idev/tty[hi] lO-9a-fl
Idev/ttyd [0-9a-fl
SEE ALSO

tty(4)
DIAGNOSTICS

dmf'lod: NXM line '/od. No response from UNIBUS on a dma transfer within a timeout period.
This is often followed by a UNIBUS adapter error. This occurs most frequently when the
UNIBUS is heavily loaded and when devices which hog the bus (such as rk07's) are present. It
is not serious.
dmf%d: silo overflow. The character input silo overflowed before it could be serviced. This
can happen if a hard error occurs when the CPU is running with elevated priority, as the system
will then print a message on the console with interrupts disabled. If the Berknet is running on
a dh line at high speed (e.g. 9600 baud), there is only II1Sth of a second of buffering capacity
in the silo, and overrun is possible. This may cause a few input characters to be lost to users
and a network packet is likely to be corrupted, but the network will recover. It is not serious.
dmfsrint.
dmfsxint.
dmfdaint.
dmldbint.
dmflint.
One of the unsupported parts of the dmf
vectors for a conflict with another device.

4th Berkeley Distribution

interrupted~

27 July 1983

something is amiss, check your interrupt

DN(4)

UNIX Programmer's Manual

DN (4)

NAME

dn - DN-Il autocall unit interface
SYNOPSIS

device dnO at uba? csr 0160020 vector dnintr
DESCRIPTION
The dn device provides an interface through a DEC DN-II (or equivalent such as the Able

Quadracall) to an auto-call unit (ACU). To place an outgoing call one forks a sub-process
which opens the appropriate call unit file, Idevlcua? and writes the phone number on it. The
parent process then opens the corresponding modem line Idevlcul? When the connection has
been established, the open on the modem line, Idevlcul? will return and the process will be connected. A timer is normally used to timeout the opening of the modem line.
The codes for the phone numbers are:
0-9
•

#

<
f

dial 0-9
dial· (':' is a synonym)
dial # ('~' is a synonym)
delay 20 milliseconds
end-of-number ('e' is a synonym)
delay for a second dial tone ("w' is a synonym)
force a hangup of any existing connection

The entire telephone number must be presented in a single write system call.
By convention, even numbered call units are for 300 baud modem lines. while odd numbered
units are for 1200 baud lines. For example, IdevlcuaO is associated with a 300 baud modem
line, Idevlcu/O, while Idevlcua 1 is associated with a 1200 baud modem line, Iderlcull. For devices such as the Quadracall which simulate multiple DN-II units, the minor device indicates
which outgoing modem to use.
FILES

/dev/cua?
/dev/cul?

call units
associated modem lines

SEE ALSO

tip(IC)
DIAGNOSTICS

Two error numbers are of interest at open time.
[EBUSY] The dialer is in use.
[ENXIO] The device doesn't exist, or there's no power to it.

4th Berkeley Distribution

27 July 1983

DR(4)

UNIX

Pr()gr
<~·;)sl d...11>

lI'TJON
;\ variety of

d\.'\'iccs 1ll;IY he (lI1th.'ctel! II) till' SySh.'1l1 '.ia J )RII-B or 1)1{ II··W gClltr;,ll'tlrposc
J);lla \\filh'1l tHlh\.:sl' ,k\ ices is tr;lIbkrrcd dir('Clly fj'OJll Illl' IlfJ{ II . ·\\' illlerf;ll'l'd lISl'r
spu:ilkdin Ihe dl'scriptillll
IIl;!t p;tl'licuLtI· <11..'\ in'.

or

<1,'\ in.'s tl11kss otherwise

The call

iHrtl(liliks.

I>HI(JC(~FTlt ,~drrt'~)

strurl "rfq,~ dnq~;

rdurns the l'olltl..'nh ·01' Ib\..' I(HII' I)RII-B (Iin~ I)R II-\V) dl'\ice n:gistl'rs ill Ill\.' 'Iupplied structure,
This stnll'Ull\' is d\..'/ilwd ill <.'.,r\'III1:/i) as:
strlld dIH'~

{
1'1 nord l'01l11t J'q.~i ... h.'l' *1
I·r. lilts adcln.'ss ft'gistl'f *1
1* s1atus .mel t'olUmaml n,'gistl'l' *1

d ....._"'t,·;
u.slwrt ,In J)a:

short

u.short drr__st;
u ,short c1u.clb;
tI_ short dn ..'.· .. ;

1* .i:tta hun",.. n'i!ish' .. *1
I J: t'HOr illformalioll f'l'gish'f

(al"~t)s Hltu' IHH I-U)

*1

};
'1'\,,0 "dditi(lll;tl l'alh pro\'hk
dl'\ icc fq.',i'lll'r~.;, Tht..'Y ~tn::

;t

IIU.'ch;l"i~,1l1 Itll' ~dl'ctivdy

iortl(lildl's. nnlO< 'S~d·a.

selling Ill\.' conk'ills

or n'rl
I)F~("I{IPTION

I )",:\'ices dr/II' prodde tht' inlerl;I(,:e fill' g\.'Il\.'I:d purpose lIs('r devices ('olllw('h:d to tlH.' system via a
1>1{ II-B or 1)1{ II-\V I )i\L\ illkrrace. I bt~, \\ritt\.'11 to thes\' ckvices is tr;III~;li,:I'I\:d dil\'ctly frolll the
process's btllli.'!' to the w,c!' d('\icl' alld d:II:1 I\':,d from thc:,~ devices is slIpplk:d dil\'ctly to the
proCl'SS's hlllkr hy lhe lIser <..kvicc.

B~: dcl~lllll, tlw sy~;t~'1l1 lI'i(''i till.' I :NeT I I;it I If IIh.' status <1111..1 contn>1 "q.;iSl\.'r to I.Tislinglli-;\1 Iwt ween
n.'(!d and ",rill' l"(lIIlI11;Jllds isslh:d hy the 1)1{ II til tile \I:-'t'r de\ icc (Ihe ollt\'r two rlillClioll hilS will
he /em), i\ "('clcI(.~) call will rk:lr tlH. ' bil helin·\.' begillning till: inptlt p{ll'r:HiuIl and :t It.'ri/('P) call
\\ i:! Sl't the hit hclill'l' hegillllill:' the output opl.'r:ltioll.
IOC TL (':\ LLS
..\Il iuCl1 Gills dl..'scrihed ill dd·\) IIlay Iw ;tpplicd to thesl' lk\"ilT:-'. Two 'ldditiol1al iocllcalls:

iorll{liltks. naBIl)( '(;VTP. &clrh(»
strurl (Irhi>ar~lm drhp;

and
iortl{!iIl\ts, I>HBIO{ 'SFTP. &drhll)
drhparam ilrhp:

~trul't

\\lli·Jl, 1\'Slwcti\cly. ktch ;"11..1 "il,.~t til\.' dl'\ in' p:!ralllctl'rs to/rl"lllH the Slljlpli\.'d slrllctllr~ ~II\~ also
(\\;tibhk. This IXIr as:

strlld drhj)arilm
{
II .short drtWJl'OIII;
tI_ .short "rhp. _.'t' l'OIll:
I()II~

drhll.III"J(()I~

1* fOlllltl:lIHI hils for rl'ael Olwratioll *1
1* l'OIllIll:llld hils rm' \i rill' Olll'l"atioll *1
1* H'~;nH'd for flllufl' l'\llllnsion *1
1* (Illust hl' Il'ro) *1

}:
TIH~

read 
II inducll' 

iocll(liIdl's, l'Olil', I)aram)
strurt l'niol'h -tparam;
where

J}(flWII

is defined in <.\)'s/ (,lIel.h> as:

sll'l1ct l'nioch
{"

Stallrord

u._ch:ll'

CH ..)Hldr:

lI_clwr

l~II __ llIaxnllcrs;

18 October )1)84

1

ENET(4)

ENE'I'(4)

u_l'har t.\n_m~l'(\\aiting:
u_l'har l'll_maxpriol'ity;
IOllg
cu_rlout;

};
with the clpplicabk codes heing:

'·:ltJCGI ~'I'I)
h:tl'il the parameters for this file.

I':IOCSEIV

Set till' par paranH.'kr i:..; till' l,th\.~rrwt 'H.ldl\'ss
tlK' "I,whine. IThis f1l'ld is
l'SSI..'lllially oh:;'.Iil'tc. bUI i'i illl.'ludl'ul{lr L'(llllP:llihilily \\itlJ II/lin code.1 The lllaximulIl Ijller lellgth
p;lr;!II\1.,'I\.'r illdicClIl'S tlw Illjl\:iiillllli p()~~ihk p~lch~t liltl.'!' ClIIIllIljllH.I Ii"t kll~~th (s..:c FJOCSI·:TF
hl'low). '1'1\\.' 11l;1:·:iIllIJllI illPUI \\ait qll~'lH.' ",ill.' P;II';III11..'II.'r illdir;lll.'s Ilw 1ll;I\ill1!!l1l Illllillh,'J' or p;lckcts
which 111;1) h\.' qll\.'lI\.'d /il!' ;111 \.:II1l'I'II1..'1 lik ;II Olll' tillll' (s\.'I.' I':IOCSFT\V below). '1'111..' m,l',illllllll
priority P;ll';lllIdl..'l' ilaliccll'..''i I II\.' l1iglll.'sl liltn pri'lrity \\ hicll 1lI;IY Ih.' set I()r lile !ill: (-;\'\" Lloc'SF'!'F
below). Till.' 1\';ld lill1\.'OIlI p;lr;lI11ctl'r spl't'i!k~; till' Illlllll>'~'r (If' c1()ck ticks l(l w
II illl:llIdt., 
iortl{lildt's. FIO( 'DF.YP. param)

s(rud

('I\(ll'll>
1I_.. l'har

1I._.rha..
lI_short
u...short
lI_rhal'
1I....(,'hal'

I
..lYllC:
rnd.:ulcl r_Jcn:
rllll_ hel r Jcn:
l'IHI.J' rn J:
l'lltl:uldrll-:NJ\J A \ .. ,\ I )I>R_.I ,EN I:
t'l1ct.i>roadaddrl EN_~ L\ X__ AI)Un_1 IFNI;
l'lHl.clt.'l

}:
The fields

arl'

as 1()lIows:
S,wcifk's the device lYPl': currently olle of I·:N IJI'_.JM B, I·:N DI'_.. BSJM B
or FN J)' l'_lOM B.

end_addrJcn

Specifics the address lellgth in hytes (c.g .• I or 6).

elHt.hdrJen
end_MTU

Specifics the toL.1I IW;I(kr length ill bytes (c.g., 4 or 14).

l'Jld_addr

The

Specifics the maximulll packct sil.t" incillding header, in bytes.
~Iddress

"ddl\'SS

clld_broadaddr

St;lI1rord

or this illlcrnlce: aligned so that the low order bytc or the
is thc first hyte ill the llrray.

The hardware destinal.ioll audrcss for bi'oadcasts

)8 Octoher 1984

01l

this Ilt'lwork.

2

l--:NF~T( 4)

ENET(4)

UNIX Programmer's Manual

The next two calls enable and disahk thc input pack<:t signal mcchanism

I(Jr

the

me and arc of the

form:

# include 
tt include 
ioctl(rIIdt's, (otIc, signp)
u_int *signp;
where sif:.!I1/J is a pointer to a word containing the ntllll\)er of the signet! to be s\.:nt whcn an input
packel arrivcs and witll lhe (lpplic:lhlc codes bcing:
FIOCI~NBS

Fndhlc the specirkd signal \-\h,,~n' ;1Ii iilp'l!i p;\ckel' is reC\:iv,~d I'llI' this f1k. hillher signals
arc autolll~\tk~t1ly dis;\hkd \\I\,,'\1e\er a signal is ';(,l1t tn pn.'\(,lll Ih.'stillg ;lIld 1l\.'liC~ musl be
spccillcally re-el1abled after pr<)c('\sillg (hut see I 01 0(' Ivl HIS helm",), \Vhell;i sigllal numher
or 0 is supplied. lhis call is cqui\'aklll to FIOCI NilS.
FIOCIN lIS
I )isablc :lI1y sign:" whcn :1Il input p;lckd is 1\:cl'i\Td for lilis file (the ,\iglll' p
II inrludl' (s:,'\/l'llcl.h)
iOl't I(tildes, rode, hits)
lI __ shorl *hils;

\v\1('re "(IS is a s\1()I·t work biHll;lsk sp~'Cij'yillg \A,hich hits to set or ck;lr. ('urn,'llll:;. the only hit
is 1'~NIIOI.I)SI(i, \\hicl! (it' st.:t) t,,'lIs the drin.'r 1I('/I() dis;lhk (kli\\.'rill~!, a signal
OJ1r:l' it has done so, Selling this hit 1ll"\\llS tl);lt YOll IHxd lise 1':IOlTN HS only onn', Tilt.: ;Ipplicahk codes ;Irl':
111;\\k n~coglli/.ed

":IOi\l HIS

Sets tlw Slwcirkd mode hits
I':IO( 'r,,1 BIC

Ckars the specified

1l1o(k

Another ill('11 call is lIsed to set
It is or th~ rorm:

hits

th\.~

1ll:lxilllUIll Sill' or

th\.~

pdckL't input qllL'Ul' I()r all opell

('IIl'1

file.

II inrhuh,' (sys/l)'l)l's.h>
II inrtudl' (s)'slt'IIl'l.h>

iOl't J(lildl's, VIO( 'SVr\". ma\ wail iJlgl»)
lI_jnl *111:1\ wait ingl);
is a poillter to a word C
II indudl' (syslt'Ill't.h>
icu:t I(lildl's, FIO( :FLlJSII. 0)

IX Octolwr IC)S4

J

ENI~T(

4)

UN IX Programmer's Manual

The final iu('11 call is llsed to sd lhe packet filler fI))' an open (,lIel

ENI·:'I'( 4)

me.

It is of the form:

it !Ildlldc (sys/(ypcs.h)

it inl'lmlc (sys/cllcLh)
. jodl(iilill'S, FIOCSFTF, filler)
~tl'lIl'l

l'llliltcriys/ ('/lcl. It) as:
slruct cllriltcr
{
u._.l'har clICPrinrity:
u_.. l'har l'lIt'. Xi Itl'rI ,l'lI:
u_short l'III~J'iltt'l"l FN!\ 1.\ X FII JTEI~SI:

};

:\ packet !ilter cOllsists or ;1 priority, lhl..' Iilt\.'!" Cllllllll;IIHI li"l kngth (ill "hortwon.is), and the Iilter
cOllllllalH.l li~.t ihl'lf. Fach liltl'r cort1I1l:l1Id list Slh.'l"ilics a ~\.·q\l\.'llce of ;lctiollS which opl'rak Oil an
inlernal stack, Each shorl'.\ord or tlk' COlIlIll;lIld list "Iwcilirs all ;I!;tion ('mm the set {
EN 1·'_J)llSIII.IT, VN F_ PUSII/,F IH), FN I'. PliSII\\'OI~ D + N l which rl'spccti n:ly pl.I':h the next
sh()l"Iword or the C0l1l111;IIHI li-;l. 1.1.'1'0, or -.;11I11"l\\ord N or til\.' incollling packet 011 the slack, and a
billary (llwr:ltor Ihun till' sct { FNF._H), VNI;J'n-:<), FNFLT. ENF.I.L ENF_'<~T. I':NF_GE,
FNF_AND, FNI"_OIt FNI;_XOH } which then operdll's Oil the top two ('lclllents or t.he stack and
replaces thelll \vith its result. \Vllell both :1Il action and olwr~ltor are spcdlkd in the ~,~lllle shortword. thc action is perli.lrIJll'd Il)lIm\l'd hy till' opl'ration.
The binary olH.'rator C;l1\ ;t1so he fro1ll the set { FNF__('Olt FNI"_(''\ND, FNF.J'NOI~,
E~V_(,i':\NI> }, Thc'\c arc "sIHlI'l-·cin:lIit" opn;ltors, in tll:lt tiley tcrlllillClte till' en'clIlion or the
filter illlllH.'diatcly if till' conditioll they ;11\'. lJll'ckilig I()r is Ir each open {'/lei file are ordered by the driver according to t.hdr priority (lowest priority is 0,
highest is 255). \Vhen processing incoming l'thertlel. packets, IiIlers a 1\' applied according to their.
priority (from highest to lowest) and ItH' identical priority values according to their rdative

I H Octoh<.'1' 1984

[~NI~T(4)

UN I~~ ProgralllJl1(,'r's rvlanual

ENET(4)

"bu.;;yncss" (the filler that h;lS previollsly matched the rnosl p~ld:cts is checked first) until one or
more filters accept the packet or ;111 i11lcrs reject it and it is di:~carded.
Filters at a priority of 2 or higher arc called "high priority" filters. Once a p;ldet is delivered to
one of t.hese "high priority" el1l'1 flks, no t'l.Inher fillers arc eXi:lmined, i.e. the p;!d:et is delivered
only to the first ene! fik \"lith a "high pi iority" [i Ill:l' which accepts til\: packet. /\ r,
FNF_AND
1*

1*
1*
1*
1*
1*
1*
1*
f..~&

priority and length *1
parkd typc = = PUP *1
llla~J. hi hyte *1
I'lIpT)'llc ) 0 *1
1lI;t<;k hi hytc *1
Pup'l'ypc < 0100 *1
0 < PupType <=.0100 *1
p:lrkl.'l t~I)C =
PUP *1

=

=

};
Note th:lt shorl\V()rds, slich (IS th\,..' p(lckl'l type f!l'Id, ;Irc hytc-sw;lpped ~ltHI so the literals you COIllpilre them to IlIlisl I>e hytc-swapped, Abo, (tlthough for this example the \vorLl onsets (Ire cOIl~tal1ls.
colle lhat must rlln \\ ilh eilller 31l1h or lOmh cll1l:rm:t~; must lISC oll"sl'ls that dCP~IH.I on the Llevice
type.

By tilk ing (H.lV -I- I. FNJ"_ PllSl1 LIT
ENI,'_.PlISII\YORI>+.', FNFJ)lJSIII.IT
EN FJ)l lSlll.FHO I EN F_,( ~T.
ENF_Pl JSII\YOHI>-I-J, Vr~lt',.YliSIILIT
ENF_PllSIILIT I FNF_LE. ()I 00.
ENF_ANI).
EN It'_ANI>

1*
1*
1*
1*
I FNlt'_ANI>. Oxl,'H10,
1*
1*
1*
/* ..~ ..~

I FN F__ EQ, 2.
I FNI'_AND, (lxFHHl.

priority allli Il'ngth */
= PU P */
111:1';1\ hi bytc *1
PupTYI)l' ) 0 *1
mask hi hyte *1
PUI1'i'JI)l' < ()tOO */
() < PUI)'i'ypc < 0100 */
packet tYl>l~ = = PUP *1
I):lrkd type

=

=

=

};
A dillcrent eX, 2

I~;

lidority an:!

k!lI~1h

*1

/."r. : ii \HHd o!' ~;od:.d */
1* I,{) word of soc!,d */

I:;'

l.i~:d\ct

type :;:;:::: Pup */

SEE ALSO

de( l), ecCD, el1(4), il(·l),

ell~.I(lt(S)

FrLK~

/t\('V /CI1Clr;I'III-{ (), 1.2 .... ,3 I}
BUGS
Th~ currcllt

arollnd

Ion

illlpklllel1t;llioll C;1Il only (iltl'l 011 words wilhill tl1\.' first "mhlll~' til' thl' iXll'k~l: this is
hill'S (or 50 wortls).

Bccausl' p;ickcts an: strc~IIIlS or h) tes. yl'l till' filters OI1l..'r;ltc on short words. ,lIld st~l11dard 111.~1 work
oHkr is IIslI;t1ly nppl,~,ilL' rroll1 V;IX hytl.' order, the rcLiliul1al O[H?r;ltop.; :':1\11"_1.'1'. FNF_LE,
Fi\lF_GT. :llld FNF_ ttl illrludc eX;\111p!cS.

17- No\'-X I
21)-Sl~p-X

I IVlike i\cel'll;1 (1l1j;,) ;It l'arnl.'~'.ic··!\ldl()n UniH'rsily
Ch, G\t HI(}( ';'\0\\"('. NULl.)

iOl'Ii{lihll's, (~i\IHIO("\\(,. NULL)
Till..' (~i\JI~I()(,~O\\'C c;III dis;lhks till' word COUllt clll'ck \\ililin the {kvicl' for usc wilh packl'dhytl' wrill,''', F.\UJH 'i\II':1\1, \l'rp)
long *H'rp

The f;i\lRIOCCIIL( '1\I\U:i\l elll 1\'SLT\("j Ihe Illl'llllll'Y chafllll'l ;dlocatioll hil \('ctor /<)(' the
CUITl'SPIlllding de\"iu.'.. II't.hl' Illl'lllory ;dl(lclti()11 \Tcll)r i"i not currcl1tl) 1\'scl'\e<.l II) '';()IIK' otiler d,,'v"
icc. it is rl·ser\'l.~d 1<11' the excillsih' II .... \..' or Ihl' CIII"I'l'llt dc\icc dlHI Ilh.' cOllklll'i or 111'.' hil vector is
retlll"lled in till' IOIl,~I.word poillted to hy \'('(p. ,\IlY (;i\lIUO('('III-:("I\i\IVI\J 01 (;i\iI~IO(,:\LLOC­
I\IVf\1 iocl! cdl Oil ;11l(lther (irilllll'll dl'\'icl' \\'ill hllld; llntil thl' 1Ill'llInry ;dloc(ltioll \L'Ctor is rdl';lsed
;1I1t! till' c;dl L';11I Iw ulIlIpkted. It' Ille Ilh'illlll'J :dl(l~';lti()1l \\.'ctor is ;drl':lti) rL'''"'I'\~'d hy . . Ollll· other
dL',ice, the l,;tli \\ ill hl\)ck !llllil till' \ ector i, Il'Iv;I<.;L·d ;I1HI L':111 hl' ds\iglll'd to the L'1Il'1\'llt device.
The (~;\II{IOC,\LI.O(,i\IFi\l c(lll ;t1llll'(ltl'S the 1IlL'lIHlry challllcis cnn\'sponding to the hits "Cl ill
the \'l.·dor poillted t() hy \'('('jJ. 11'111\' \'l'L!or i" lIot ;1I1\\I<.ly rl' . . el"\l·d h y tile l'ltrl\.'llt dc\ice it \\illlirsl
he n.'~;\.'nTd 1(11' tlle Cllrrl'llt tk\iL'l' LIS (Ihml'). II' ;IllY or tIll' illdiC:lk'd IIlL'lIlOry CILllIllcls (Ire ,t1I'L'"dy
.
hp%d: 9730 (direct>.
hp%d: 9300.
hp'lod: 9762.
hp%d: capricorn.
hp%d: eagle.
hp%d: ntracks IYod, nsectors "od: unknown device.

BUGS
In raw I/O read and write(2) truncate file offsets to S12-byte block boundaries, and write scribbles on the tail of incompiete blocks. Thus, in programs that are likely to access raw devices,
read, write and Iseek(2) should always deal in 512-byte multiples.
DEC-standard error logging should be supported.
A program to analyze the logged error information (even in its present reduced form) is
needed.
The partition tables for the file systems should be read off of each pack, as they are never quite
what any single installation would prefer, and this would make packs more portable.

4th Berkeley Distribution

27 July 1983

4

HT(4)

UNIX Programmer's Manual

HT(4)

NAME

ht - TM-03/TE-16,TU-4S,TU-77 MASSBUS magtape interface
SYNOPSIS

master htO at mba? drive?
tape tuO· at htO slave 0
DESCRIPTION

The tm-03/transport combination provides a standard tape drive interface as described in
mtio(4). All drives provide both 800 and 1600 bpi; the TE-16 runs at 4S ips, the TU-4S at 7S
ips, while the TU-77 runs at 12S ips and autoloads tapes.
SEE ALSO

mt(l), tar(l), tp(I), mtio(4), tm(4), ts(4), mt(4), ut(4)
DIAGNOSTICS

tuo/td: no write rlnl. An attempt was made to write on the tape drive when no write ring was
present; this message is written on the terminal of the user who tried to access the tape.
tu%d: not online. An attempt was made to access the tape while it was oftline; this message is
written on the terminal of the user who tried to access the tape.
tu%d: can't switch density In mid-tape. An attempt was made to write on a tape at a different
density than is already recorded on the tape. This message is written on the terminal of the
user who tried to switch the density.
tu%d: hard error bn%d mbsr-~b er-~b ds-~b. A tape error occurred at block bIT. the ht
error register and drive status register are printed in octal with the bits symbolically decoded.
Any error is fatal on non-raw tape; when possible the driver will have retried the operation
which failed several times before reporting the error.
BUGS

If any non-data error is encountered on non-raw tape, it refuses to do anything more until
closed.

4th Berkeley Distribution

27 July 1983

1

HY(4)

UNIX Programmer's Manual

HY (4)

NAME

hy - Network Systems Hyperchannel interface
SYNOPSIS

device hyO at ubaO csr 0172410 vector hyint
DESCRIPTION

The hy interface provides access to a Network Systems Corporation Hyperchannel Adapter.
The network to which the interface is attached is specified at boot time with an SIOCSIFADDR
ioctl. The host's address is discovered by reading the adapter status register. The interface will
not transmit or receive packets until the network number is known.
DIAGNOSTICS

hy%d: unit number Ox%x port %d type %x microcode level Ox%x. Identifies the device during
autoconfiguration.
hy%d: can't handle af%d. The interface was handed a message with addresses formatted in an
unsuitable address family; the packet was dropped.
hy%d: can't initialize. The interface was unable to allocate UNIBUS resources. This is usually
due to having too many network devices on an 11/750 where there are only 3 buffered data
paths.
hy%d: NEX - Non Existent Memory. Non existent memory error returned from hardware.
hy%d: BAR overflow. Bus address register overflow error returned from hardware.
hy%d: Power Off bit set, trying to reset. Adapter has lost power, driver will reset the bit and
see if power is still out in the adapter.
hy%d: Power Off Error, network shutdown. Power was really off in the adapter, network connections are dropped. Software does not shut down the network unless power has been off for
a while.
hy%d: RECVD MP > MPSIZE (%d). A message proper was received that is too big. Probable a driver bug. Shouldn't happen.
hy%d: xmit error - len> hy _olen (%d

>

%dJ. Probable driver error. Shouldn't happen.

hy%d: DRIVER BUG - INVALID STATE %d. The driver state machine reached a nonexistent state. Definite driver bug.
hy%d: watchdog timer expired. A command in the adapter has taken too long to complete.
Driver will abort and retry the command.
hy%d: adapter power restored. Software was able to reset the power off bit, indicating that the
power has been restored.
SEE ALSO

intro(4N), inet (4F)
BUGS

If the adapter does not respond to the status command issued during autoconfigure, the adapter
is assumed down. A reboot is required to recognize it.
The adapter power fail interrupt seems to occur sporadically when power has, in fact, not failed.
The driver will believe that power has failed only if it can not reset the power fail latch after a
"reasonable" time interval. These seem to appear about 2-4 times a day on some machines.
There seems to be no correlation with adapter rev level, number of ports used etc. and whether
a machine will get these "bogus powerfails". They don't seem to cause any real problems so
they have been ignored.

4th Berkeley Distribution

27 July 1983

IK(4)

UNIX Programmer's Manual

IK(4)

NAME

ik - Ikonas frame buffer, graphics device interface
SYNOPSIS

devlee lkO at uba? csr 0172460 vector lklntr
DESCRIPTION

lk provides an interface to an Ikonas frame buffer graphics device. Each minor device is a
different frame buffer interface board. When the device is opened, its interface registers are
mapped, via virtual memory, into the user processes address space. This allows the user process very high bandwidth to the frame buffer with no system call overhead.
Bytes written or read from the device are DMA'ed from or to the interface. The frame buffer
XY address, its addressing mode, etc. must be set up by the user process before calling write or
read.
Other communication with the driver is via ioctls. The IK GETADDR ioctl returns the virtual
address where the user process can find the interface -registers. The IK_W AITINT ioctl
suspends the user process until the ikonas device has interrupted (for whatever reason - the
user process has to set the interrupt enables).
FILES

/dev/ik
DIAGNOSTICS

None.
BUGS

An invalid access (e.g., longword) to a mapped interface register can cause the system to crash
with a machine check. A user process could possibly cause infinite interrupts hence bringing
things to a crawl.

4th Berkeley Distribution

27

Ju~y

1983

1

IL (4)

UNIX Programmer's Manual

IL (4)

NAME

il - Interlan 10 Mb/s Ethernet interface
SYNOPSIS

device 1I0 at ubaO csr 161000 vector llrlnt llclnt
DESCRIPTION
The iI interface provides access to a 10 Mb/s Ethernet network through an Interlan controller.

The host's Internet address is specified at boot time with an SIOCSIFADDR ioctl. The ec
interface employs the address resolution protocol described in arp(4P) to dynamically map
between Internet and Ethernet addresses on the local network.
The interface normally tries to use a "trailer" encapsulation to minimize copying data on input
and output. This may be disabled, on a per-interface basis, by setting the IFF_NOTRAILERS
nag with an SIOCSIFFLAGS ioctl.
DIAGNOSTICS

llo/Gd: Input error. The hardware indicated an error in reading a packet off the cable or an illegally sized packet.
llo/Gd: can't handle afOlod. The interface was handed a message with addresses formatted in an
unsuitable address family; the packet was dropped.
SEE ALSO

intro(4N), inet(4F), arp(4P)
BUGS

The PUP protocol family should be added.

4th Berkeley Distribution

27 July 1983

1

IMP (4)

UNIX Programmer's Manual

IMP(4)

NAME

imp - 1822 network interface
SYNOPSIS

pseudo-device Imp
DESCRIPTION

The imp interface, as described in BBN Report 1822, provides access to an intelligent message
processor normally used when participating in the Department of Defense ARPA network. The
network interface communicates through a device controller, usually an ACC LH/DH or DEC
IMP-IIA, with the IMP. The interface is "reliable" and "flow-controlled" by the host-IMP
protocol.
To configure IMP support, one of acc(4) and css(4) must be included. The network number on
which the interface resides is specified at boot time using the SIOCSIFADDR ioctl. The host
number is discovered through receipt of NOOP messages from the IMP.
The network interface is always in one of four states: up, down, initializing, or going down.
When the system is booted, the interface is marked down. If the hardware controller is successfully probed, the interface enters the initializing state and transmits three NOOP messages
to the IMP. It then waits for the IMP to respond with two or more NOOP messages in reply.
When it receives these messages it enters the up state. The going down state is entered only
when notified by the IMP of an impending shutdown. Packets may be sent through the interface only while it is in the up state. Packets received in any other state are dropped with the
error ENETDOWN returned to the caller.
DIAGNOSTICS

Imp%d: leader error. The IMP reported an error in a leader (1822 message header). This
causes the interface to be reset and any packets queued up for transmission to be purged.
Imp%d: lolnl down In 30 seconds.
Imp%d: lolnl down for hardware PM.
Imp%d: 10101 down for reload software.
Imp%d: lolnl down for emel'lency reset. The Network Control Center (NCC) is manipulating
the IMP. By convention these messages are reported to all hosts on an IMP.
Imp%d: reset (bost foci/imp ¥tel). The host has received a NOOP message which caused it to
reset its notion of its current address. This normally occurs at boot time, though it may also
occur while the system is running (for example, if the IMP-controller cable is disconnected,
then reconnected).
ImpO/Od: host dead. The IMP has noted a host, to which a prior packet was sent, is not up.
Imp'!.d: host unreachable. The IMP has discovered a host, to which a prior packet was sent, is
not accessible.
lmp%d: data error. The IMP noted an error in data transmitted. The host-IMP interface is
reset and the host enters the init state (awaiting NOOP messages).
Imp%d: interface reset. The reset process has been completed.
imp%d: marked down. After receiving a "going down in 30 seconds" message, and waiting 30
seconds, the host has marked the IMP unavailable. Before packets may be sent to the IMP
again, the IMP must notify the host, through a series of NOOP messages, that it is back up.
imp%d: can't handle I""d. The interface was handed a message with addresses formatting in
an unsuitable address family; the packet was dropped.
SEE ALSO

intro(4N), inet(4F), acc(4), css(4)

4th Berkeley Distribution

27 July 1983

1

IMP (4P)

UNIX Programmer's Manual

IMP (4P)

NAME

imp - IMP raw socket interface
SYNOPSIS

#include 
#include < netinet/in.h >
#include 
s = socket(AF_IMPLINK, SOCK_RAW, IMPLINK_IP);
DESCRIPTION
The raw imp socket provides direct access to the imp(4) network interface. Users send packets
through the interface using the send(2) calls, and receive packets with the recv(2), calls. All
outgoing packets must have space for an 1822 96-bit leader on the front. Likewise, packets
received by the user will have this leader on the front. The 1822 leader and the legal values for
the various fields are defined in the inel ude file < netimpliL imp. h > .

The raw imp interface automatically installs the length and destination address in the 1822
leader of all outgoing packets~ these need not be filled in by the user.
DIAGNOSTICS
An operation on a socket may fail with one of the following errors:

[EISCONN]

when trying 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~

[ENOTCONN] when trying to send a datagram, but no destination address is specified, and
the socket hasn't been connected~
[ENOBUFS]

when the system runs out of memory for an internal data structure;

[EADDRNOT A VAIL]
when an attempt is made to create a socket with a network address for which
no network interface exists.
SEE ALSO
intro(4N), inet(4F), imp(4)

4th Berkeley Distribution

26 March 1982

1

INET (4F)

UNIX Programmer's Manual

INET (4F)

NAME

inet - Internet protocol family
SYNOPSIS

#include < sys/types.h >
#include < netinet/in.h >
DESCRIPTION

The Internet protocol family is a collection of protocols layered atop the Internet Protocol (IP)
transport layer, and utilizing the Internet address format. The Internet family provides protocol
support for the SOCK_STREAM, SOCK_DGRAM, and SOCK_RAW socket types~ the
SOCK_RA W interface provides access to the IP protocol.
ADDRESSING

Internet addresses are four byte quantities, stored in network standard format (on the VAX
these are word and byte reversed). The include file  defines this address as a
discriminated union.
Sockets bound to the Internet protocol family utilize the following addressing structure,
struct sockaddr jn
short
u_short
struct
char
};

{
sin_family;
sin_port~

in addr sin addr;
sin_zero[8f

Sockets may be created with the address INADDR_ANY to effect Hwildcard" matching on
incoming messages.
PROTOCOLS

The Internet protocol family is comprised of the IP transport protocol, Internet Control Message Protocol (ICMP), Transmission Control Protocol (Tep), and User Datagram Protocol
(UDP). TCP is used to support the SOCK_STREAM abstraction while UDP is used to support
the SOCK_DGRAM abstraction. A raw interface to IP is available by creating an Internet
socket of type SOCK_RAW. The ICMP message protocol is not directly accessible.
SEE ALSO

tcp(4P), udp(4P), ip(4P)
CAVEAT

The Internet protocol support is subject to change as the Internet protocols develop. Users
should not depend on details of the current implementation, but rather the services exported.

4th Berkeley Distribution

19 March 1982

1

IP (4P)

UNIX Programmer's Manual

IP (4P)

NAME

ip - Internet Protocol
SYNOPSIS

#Include 
#Include 
s - socket(AF_INET, SOCK_RAW, 0);
DESCRIPTION

IP is the transport layer protocol used by the Internet protocol family. It may be accessed
through a "raw socket" when developing new protocols, or special purpose applications. IP
sockets are connectionless, and are normally used with the sendto and recvfrom calls, though the
connect(2) call may also be used to fix the destination for future packets (in which case the
read(2) or recv(2) and write(2) or send(2) system calls may be used).
Outgoing packets automatically have an IP header prepended to them (based on the destination
address and the protocol number the socket is created with). Likewise, incoming packets have
their IP header stripped before being sent to the user.
DIAGNOSTICS

A socket operation may fail with one of the following errors returned:
[EISCONN]
when trying 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;
[ENOTCONN] when trying to send a datagram, but no destination address is specified, and
the socket hasn't been connected;
[ENOBUFS]
when the system runs out of memory for an internal data structure;
[EADDRNOTAVAIL]
when an attempt is made to create a socket with a network address for which
no network interface exists.
SEE ALSO

send(2), recv(2), intro(4N), inet(4F)
BUGS

One should be able to send and receive ip options.
The protocol should be settable after socket creation.

4th Berkeley Distribution

2S March 1982

1

I PBRt)i\ I )( '/\S' I' (41))

UN IX Prllgrall1lll(:r's Mallual

II'BROi\ I )CAST (41')

NAME
iplml:ldcast ---. IlJ'O;I<.IGlstillg Int ...'rIIct Prlltocol p;lckels
SYNOPSIS

/1 includl,,' (sys/Iypl.'s.h> It inrhllk (IICtilwt/ill.h>
I>F~-i(,HlPTION

Nni,': '1'111,,' ;Iddl\~\',illt', C()IlH'llliolb dl..'S~,Tibl'd ill thi~, 1I1:IIlU;!1 p;I~~~ cOlllin'lll to til' .Ii/( I:) Internel stalld:,l!', IS. They do /i(!/l:{)rr\.'\p(llld In the l"OIl\ l'lll illll\ 1I~;I..'d hy IlH l'il Ikrkcky ·l:,BSI) illlpkl1leJ)Lllions.
ill.,'I\\prks IIl;lt Sllpport it. it i-; rtl';';ihk Itl ')I,,'lId :1Il Internct Prolucol (II» p:lch,t ;1''; a hroadca~t:
hy \'\1..'1')' !l()st Oil 111.11 1l1.·'lwork. i\ sci
hosl ;lddre'iSl'S i\ reserved to
lkl'ltlll' hro,ldc;ISIS: Ilh.'), 11:.1\'1,,' in COllllllOIi tll;lt riL'ld~, nonn;tlly 1I~I.'d 10 specified (\ Slk'(ific !lOSIS dre
!ilk:l \\ itb bits "II SI..'[ to 0111,,'.

Oil

or

111:11. i~" il \vill he i'l'Cci\'('d

Tll,,'re

;11\.'

tlm.'I..' kinds

Th i'; Ilctwork

or II) hr(l;Idl';!';1 dddl\";S\~s:
Tile di ... lill)',\Ii~lh'd ;lddl\:S~; I;'L\I)I )1(HROI\l )C'/\S'/' L»)5,~S).~55,})S)
1..1(,11011.::-; ;1 hro:II.h.:,I~,l t(l Ih..' sellt 011 lill..' Ill,'1 \" or:':' this IlOSI is dll;.lcil,:d to; i I' it
is illLlclwd to 1ll()I'I..' tl1;III OIH.' Ild\\'ork th:tt "llpporh hr(l;Idc;Isting, the syst('lll Illiglll nol s\.'IHI Ille P:Ich'l Oil all (lrthl'se nel\\'orks. ,\ packet with
this dcslin;lliPII ;lddl\.'S... \\illlH.,'\l'r I>l' I~)r\'.;tnkd by a g;Il('w;IY.

or

Till' l..iI.'still,IliulI ;Iddrl..'~s is C(llllpnsed
the Ildwork Illllllber f()J' the
(ksired ~II..'Slill;Ili()1l 1Ii.'1\\'llrk. wilh the rest or till' ;Iddri~'-," Iilkd wilh OIlC'S.
h,l' I..'X;llllpk. 10 hm:ldc;:'>t" ptll'ket on lid work 12~;.12,II,O (,I CI:lss B ncl\'Ol'k), ;Iddl\'SS it to 1,:~;.I.') ..:55,::S5. It Illay not he p(l',sihk to sl'nd this
sor! Ill' hro;Id~';ISI III \'\\'1) Ill'! \\'ork.

'I'll\..' tk\lilLIliPtl :tddrl'ss is cOIIIPosed or Illl' llet\\'orJ... tlllJllhl.'r

;\11<.1 slIbtlet
till' address
IHllllhl'1 1(11' tl1(' dl..'~;i rl'd deslillalioll ~;lIhlll'l, \\ illl the I\~~;t
lilies \\ illl IIlll'S. !-'til' cX;\Illpk. to hroadcast ;1 p;Ickl't Oil slIhncl 40
12.X,I.'.Il,O. :lddl\\~S it to I.?X.I.? .. I().~55. !-'Ilr;I nl'tw(lrk tlt;lt is lIot di\'ilkd
illlo IIll1n.' 111;111 o Ill' suhtle!, this kind or ;Iddre~s is i<.il'lltir;t1 ttl Ihe "Sl1l.'cilic
Nl'lw(\rk" ;Iddrl'~;s 1l11..'llti()lH.'d ;t1JOve.

or

Tlwn,' is

110

or

singk ;Iddl\.'\S 10 I..klHlle "hro:ldrasl to till' cluire IntnllcC', as Ihis cOllsidered a bad

tllillg to do.
addrc~.;s I'()J' Ill\.' Ildwork to which ;\11 intl'rf~lcc is "tLIehed, lise the
SI()('(iBRI);\I)I)1{ ioell. \\hich is l,,\;tctly Ihe salllc as tll(~ SIOC(ill:AI)I)R ioctl (SCI,,' illlro(4n»,
eXl'l'pl that it relurns the "Specific Sltlmct" broadclsl address I()r till' illterl~lcc. (If' the intcrf~lce
does !lot support broadcasts, thl,,' ioctl will 1~lil.)

To lilld oul the hn>;tdC;lst

TIll.' restriction th;ll only thc SlIIWI'-USI,,'r Illay scnd a broadcast has been rellloved.
hroadcast a TCP packet; it is not possible to do anylhing lise I'u I this way.

Il is possibk' lo

BUGS
Till' currclll il1lpkI1H.'llt~llioll of IP hro;aicasls in 4.) is deficicilt in scver;11 ways:
A broadcast Sl'llt to I(-'~ROA D(,AS'!' and to illdic;'Ite 1~liltire. This rcquires SOIll<.: caution Oil the p:lrl or the program Iller.

'/111 hlitio/\

KG(4)

UNIX Programmer's Manual

KG(4)

NAME

kg - KL·II/DL·IIW line clock
SYNOPSIS

device klO at abaO csr 0176500 vector kllock
DESCRIPTION

A kl·ll or dl·ll w can be used as an alternate real time clock source. When configured, certain
system statistics and, optionally, system profiling work will be coUected each time the clock
interrupts. For optimum accuracy in profiling, the dl·ll w should be configured to interrupt at
the highest possible priority level. The kg device driver automatically calibrates itself to the line
clock frequency.
SEE ALSO

kgmon(8), config(8)

4th Berkeley Distribution

27 July 1983

1

LO(4)

UNIX Programmer's Manual

LO(4)

NAME

10 - software loopback network interface
SYNOPSIS

pseudo-clevlce loop
DESCRIPTION

The loop interface is a software loopback mechanism which may be used for performance
analysis, software testing, and/or local communication. By default, the loopback interface is
accessible at address 127.0.0.1 (non-standard); this address may be changed with the SIOCSIFADDR ioctl.
DIAGNOSTICS
lo~:

can't bandle al%d. The interface was handed a message with addresses formatted in an
unsuitable address family; the packet was dropped.

SEE ALSO

intro(4N), inet(4F)
BUGS

It should handle all address and protocol families. An approved network address should be
reserved for this interface.

4th Berkeley Distribution

26 March 1982

1

LP(4)

UNIX Programmer's Manual

LP(4)

NAME

Ip - line printer
SYNOPSIS

device IpO at ubaO elr 0177514 vector Iplntr
DESCRIPTION

Lp provides the interface to any of the standard DEC line printers on an LP-l1 parallel interface. When it is opened or closed, a suitable number of page ejects is generated. Bytes written
are printed.
The unit number of the printer is specified by the minor device after removing the low 3 bits,
which act as per-device parameters. Currently only the lowest of the low three bits is interpreted: if it is set. the device is treated as having a 64-character set, rather than a full 96character set. In the resulting half-ASCII mode, lower case letters are turned into upper case
and certain characters are escaped according to the following table:

(
)

.

(
),

I

+

The driver correctly interprets carriage returns, backspaces, tabs, and form feeds. Lines longer
than the maximum page width are truncated. The default page width is 132 columns. This
may be overridden by specifying, for example, "flags 256" .
FILES

/dev/lp
SEE ALSO

Ipr(1)
DIAGNOSTICS

None.

4th Berkeley Distribution

27 July 1983

1

MEM(4)

UNIX Programmer's Manual

MEM (4)

NAME

mem, kmem - main memory
DESCRIPTION

Mem is a special file that is an image of the main memory of the computer. It may be used, for
example, to examine (and even to patch) the system.
Byte addresses in mem are interpreted as physical memory addresses. References to nonexistent 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 kmem is the same as mem except that kernel virtual memory rather than physical
memory is accessed.
On PDPll 's, the I/O page begins at location 0160000 of kmem and per-process data for the
current process begins at 0140000. On VAX 11/780 the I/O space begins at physical address
20000000(16); on an 11/750 110 space addresses are of the form fxxxxx(l6); on all VAX'en
per-process data for the current process is at virtual 7ffffOO0(16).
FILES

/dev/mem
Idev/kmem

BUGS
On PDP11 's and VAX's, memory files are accessed one byte at a time, an inappropriate
method for some device registers.

4th Berkeley Distribution

9 February 1983

1

MT(4)

UNIX Programmer's Manual

MT(4)

NAME

mt - TM78/TU-78 MASSBUS magtape interface
SYNOPSIS

master mtO at mba? drive ?
tape muO at mtO slave 0
DESCRIPTION

The tm78/tu-78 combination provides a standard tape drive interface as described in mtio(4).
Only 1600 and 6250 bpi are supported; the TU-78 runs at 125 ips and autoloads tapes.
SEE ALSO

mtH), tarO), tpO), mtio(4), tm(4), ts(4), ut(4)
DIAGNOSTICS

muO/od: no write ring. An attempt was made to write on the tape drive when no write ring was
present; this message is written on the terminal of the user who tried to access the tape.
muOfod: not online. An attempt was made to access the tape while it was offline; this message is
written on the terminal of the user who tried to access the tape.
muOfod: can't switch density In mid-tape. An attempt was made to write on a tape at a
different density than is already recorded on the tape. This message is written on the terminal
of the user who tried to switch the density.
muOfed: hard enor bnOfed mbsr-Ofob er-Ofox ds-Ofob. A tape error occurred at block bn:, the mt
error register and drive status register are printed in octal with the bits symbolically decoded.
Any error is fatal on non-raw tape; when possible the driver will have retried the operation
which failed several times before reporting the error.
muOfod: blank tape. An attempt was made to read a blank tape (a tape without even end-of-file
marks).
muOfod: oflline. During an i/o operation the device was set oftline. If a non-raw tape was used
in the access it is closed.
BUGS

If any non-data error is encountered on non-raw tape, it refuses to do anything more until
closed.

4th Berkeley Distribution

27 July 1983

1

MTIO(4)

UNIX Programmer's Manual

MTIO (4)

NAME

mtio - UNIX magtape interface
DESCRIPTION

The files mlO, ... , ml15 refer to the UNIX magtape drives, which may be on the MASSBUS
using the TM03 formatter hl(4), or TM78 formatter, ml(4), or on the UNIBUS using either
the TMll or TSII formatters Im(4), TU45 compatible formatters, uI(4), or ts(4). The following desc.ription applies to any of the transport/controller pairs~ . The files mlO, ... , ml7 are
800bpi, m18, ... , ml15 are 1600bpi, and mtl6, ... , ml2l are 6250bpL (But note that only 1600
bpi is available with the TSll.) The files mlO, ... , mtJ, m18, ... , mtll, and m116, •.. , ml19 are
rewound when closed; the others are not. When a file open for writing is closed, two end-offiles are written. If the tape is not to be rewound it is positioned with the head between the two
tapemarks.
A standard tape consists of a series of 1024 byte records terminated by an end-of-file. To the
extent possible, the system makes it possible, if inefficient, to treat the tape like any other file.
Seeks have their usual meaning and it is possible to read or write a byte at a time. Writing in
very small units is inadvisable, however, because it tends to create monstrous record gaps.
The ml files discussed above are useful when it is desired to access the tape in a way compatible
with ordinary files. When foreign tapes are to be dealt with, and especially when long records
are to be read or written, the 'raw' interface is appropriate. The associated files are named
rmlO, ... , rml2l, but the same minor-device considerations as for the regular files still apply. A
number of other ioctl operations are available on raw magnetic tape. The following definitions
are from < syslmtio. h > :
/

.

• Structures and definitions for mag tape io control commands
./
/. structure for MTIOCTOP - mag tape op command ./
struct mtop {
short mt_op;
/- operations defined below -/
/. how many of them ./
daddr_t mt_count;
};
/. operations ./
#define MTWEOF
#define MTFSF
#define MTBSF
#define MTFSR
#define MTBSR
#define MTREW
#define MTOFFL
#define MTNOP

o
1
2
3
4
5
6
7

/- write an end-of-file record -/
/- forward space file -/
/ - backward space file -/
/ - forward space record -/
/- backward space record -/
/- rewind -/
/- rewind and put the drive omine -/
/ - no operation, sets status only -/

/- structure for MTIOCGET - mag tape get status command -/
struct mtget {
/- type of magtape device -/
short mt_type;
/- the following two registers are grossly device dependent -/
short mt_dsreg;
/- "drive status" register -/
short mt_erreg;
/- "error" register -/
/- end device-dependent registers -/
short mt_resid;
/- residual count -/

4th Berkeley Distribution

27 July 1983

1

MTIO (4)

UNIX Programmer's Manual

MTIO (4)

/. the following two are not yet implemented ./
daddr t mt fileno;
/. file number of current position ./
daddr=t mt=blkno;
/. block number of current position ./
/. end not yet implemented ./

};
/

.

• Constants for mt_type byte

./
#defineMT_ISTS
#defineMT_ISHT
#define MT ISTM
#defineMT=ISMT
#define MT_ISUT
#define MT_ISCPC
#defineMT_ISAR

OxOI
Ox02
Ox03
Ox04
OxOS
Ox06
Ox07

/. mag tape io control commands ./
#defineMTIOCTOP
_IOW(m, 1, struct mtop)
#defineMTIOCGET _IOR(m, 2, struct mtget)
#ifndef KERNEL
#define DEFT APE
#endif

/. do a mag tape op ./
/. get tape status ./

"/dev/rmt12"

Each read or write call reads or writes the next record on the tape. In the write case the record
has the same length as the buffer given. During a read, the record size is passed back as the
number of bytes read, provided it is no greater than the buffer size; if the record is long, an
error is indicated. In raw tape I/O seeks are ignored. A zero byte count is returned when a
tape mark is read, but another read will fetch the first record of the new tape file.
FILES

/dev/mt?
/dev/rmt?
SEE ALSO

mt(1), tar(1), tp(1), ht(4), tm(4), ts(4), mt(4), ut(4)

BUGS
The status should be returned in a device independent format.

4th Berkeley Distribution

27 July 1983

2

NULL (4)

UNIX Programmer's Manual

NULL (4)

NAME

null - data sink
DESCRIPTION

Data written on a null special file is discarded.
Reads from a null special file always return 0 bytes.
FILES

/dev/null

7th Edition

9 February 1983

1

PCL(4)

UNIX Programmer's Manual

PCL(4)

NAME

pel - DEC CSS PCL-11 B Network Interface
SYNOPSIS

device pclO at uba? csr 164200 vector pclxlnt pclrlnt
DESCRIPTION

The pel device provides an IP-only interface to the DEC CSS PCL-ll time division multiplexed
network bus. The controller itself is not accessible to users.
The hosts's address is specified with the SIOCSIFADOR ioctl. The interface will not transmit
or receive any data before its address is defined.
As the PCL-11 hardware is only capable of having 15 interfaces per network, a single-byte
host-on-network number is used, with range [l .. 15J to match the TDM bus addresses of the
interfaces.
The interface currently only supports the Internet protocol family and only provides "natural"
(header) encapsulation.
DIAGNOSTICS

pcl%d: can't Intt. Insufficient UNIBUS resources existed to initialize the device. This is likely
to occur when the device is run on a buffered data path on an 11/750 and other network interfaces are also configured to use buffered data paths, or when it is configured to use buffered
data paths on an 111730 (which has none).
pcl%d: can't handle afO/od. The interface was handed a message with addresses formatted in an
unsuitable address family; the packet was dropped.
pcl%d: stray xmlt Interrupt. An interrupt occured when no output had previously been
started.
pcl%d: master. The TOM bus had no station providing "bus master" timing signals, so this
interface has assumed the "master" role. This message should only appear at most once per
UNIBUS INIT on a single system. Unless there is a hardware failure, only one station may be
master at at time.
pc:l%d: send error, ter-O/Ob, tsr-O/Ob. The device indicated a problem sending data on output.
If a "receiver offline" error is detected, it is not normally logged unless the option
PCL_TESTING has been selected, as this causes a lot of console chatter when sending to a
down machine. However, this option is quite useful when debugging problems with the PCl
interfaces.
pc:l%d: rev error, rer-%b rsr-O/Ob. The device indicated a problem receiving data on input.
pc:l%d: bad len -%d. An input operation resulted in a data transfer of less than 0 or more than
1008 bytes of data into memory (according to the word count register). This should never happen as the maximum size of a PCl message has been agreed upon to be 1008 bytes (same as
ArpaNet message).
SEE ALSO

intro(4N), inet (4F)

4th Berkeley Distribution

27 July 1983

1

PS(4)

UNIX Programmer's Manual

PS (4)

NAME

ps - Evans and Sutherland Picture System 2 graphics device interface
SYNOPSIS

device psO at uba? csr 0172460 vector psintr
DESCRIPTION

The ps driver provides access to an Evans and Sutherland Picture System 2 graphics device.
Each miner device is a new PS2. When the device is opened, its interface registers are
mapped, via virtual memory, into a user process's address space. This allows the user process
very high bandwidth to the device with no system call overhead.
DMA to and from the PS2 is not supported. All read and write system calls will fail. All data is
moved to and from the PS2 via programmed 110 using the device's interface registers.
Commands are fed to and from the driver using the following ioctls:
PSIOGETADDR
Returns the virtual address through which the user process can access the device's
interface registers.
PSIOAUTOREFRESH
Start auto refreshing the screen. The argument is an address in user space where the
following data resides. The first longword is a count of the number of static refresh
buffers. The next count longwords are the addresses in refresh memory where the
refresh buffers lie. The driver will cycle thru these refresh buffers displaying them one
by one on the screen.
PSIOAUTOMAP
Start automatically passing the display file thru the matrix processor and into the refresh
buffer. The argument is an address in user memory where the following data resides.
The first longword is a count of the number of display files to operate on. The next
count longwords are the address of these display files. The final longword is the address
in refresh buffer memory where transformed coordinates are to be placed if the driver
is not in double buffer mode (see below).
PSIODOUBLEBUFFER
Cause the driver to double buffer the output from the map that is going to the refresh
buffer. The argument is again a user space address where the real arguments are
stored. The first argument is the starting address of refresh memory where the two
double buffers are located. The second argument is the length of each double buffer.
The refresh mechanism displays the current double buffer, in addition to its static
refresh lists, when in double buffer mode.
PSIOSINGLEREFRESH
Single step the refresh process. That is, the driver does not continually refresh the
screen.
PSIOSINGLEMAP
Single step the matrix process. The driver does not automatically feed display files thru
the matrix unit.
PSIOSINGLEBUFFER
Turn off double buffering.
PSIOTIMEREFRESH
The argument is a count of the number of refresh interrupts to take before turning off
the screen. This is used to do time exposures.
PSIOW AITREFRESH
Suspend the user process until a refresh interrupt has occurred. If in TIMEREFRESH

4th Berkeley Distribution

27 July 1983

PS (4)

UNIX Programmer's Manual

PS (4)

mode, suspend until count refreshes have occurred.
PSIOSTOPREFRESH
Wait for the next refresh, stop all refreshes, and then return to user process.
PSIOWAITMAP
Wait until a map done interrupt has occurred.
PSIOSTOPMAP
Wait for a map done interrupt, do not restart the map, and then return to the user.
FILES

/dev/ps
DIAGNOSTICS

ps device intr.
ps dma intr. An interrupt was received from the device. This shouldn't happen, check your
device configuration for overlapping interrupt vectors.
BUGS

An invalid access (e.g., longword) to a mapped interface register can cause the system to crash
with a machine check. A user process could possibly cause infinite interrupts hence bringing
things to a crawl.

4th Berkeley Distribution

27 July 1983

2

PTY (4)

UNIX Programmer's Manual

PTY(4)

NAME

pty - pseudo terminal driver
SYNOPSIS

pseudo-device pty
DESCRIPTION
The pty driver provides support for a device-pair termed a pseudo terminal. A pseudo terminal
is a pair of character devices, a master device and a slave device. The slave device provides
processes an interface identical to that described in tty(4). However, whereas all other devices
which provide the interface described in tty(4) have a hardware device of some sort behind

them, the slave device has, instead, another process manipulating it through the master half of
the pseudo terminal. That is, anything written on the master device is given to the slave device
as input and anything written on the slave device is presented as input on the master device.
In configuring, if no optional "count" is given in the specification, 16 pseudo terminal pairs are
configured.
The following ioctl calls apply only to pseudo terminals:
TIOCSTOP
Stops output to a terminal (e.g. like typing "S). Takes no parameter.
TIOCSTART
Restarts output (stopped by TIOCSTOP or by typing "S). Takes no parameter.
TIOCPKT
Enable/disable packet mode. Packet mode is enabled by specifying (by reference) a
nonzero parameter and disabled by specifying (by reference) a zero parameter. When
applied to the master side of a pseudo terminal, each subsequent read from the terminal
will return data written on the slave part of the pseudo terminal preceded by a zero byte
(symbolically defined as TIOCPKT_DATA), or a single byte reflecting control status
information. In the latter case, the byte is an inclusive-or of zero or more of the bits:
TIOCPKT_FLUSHREAD
whenever the read queue for the terminal is flushed.
TIOCPKT_FLUSHWRITE
whenever the write queue for the terminal is flushed.
TIOCPKT STOP
whenever output to the terminal is stopped a la "s.
TIOCPKT_START
whenever output to the terminal is restarted.
TIOCPKT_DOSTOP
whenever ,-stope is "s and ,-startc is "Q.
TIOCPKT NOSTOP
whenever the start and stop characters are not "srQ.
This mode is used by rlogin(1C) and rlogind(8C) to implement a remote-echoed, locally
"srQ flow-controlled remote login with proper back-flushing of output; it can be used
by other similar programs.
TIOCREMOTE
A mode for the master half of a pseudo terminal, independent of TIOCPKT. This
mode causes input to the pseudo terminal to be flow controlled and not input edited
(regardless of the terminal mode). Each write to the control terminal produces a record
boundary for the process reading the terminal. In normal usage, a write of data is like
the data typed as a line on the terminal; a write of 0 bytes is like typing an end-of-file

4th Berkeley Distribution

7 July 1983

1

PTY (4)

UNIX Programmer's Manual

PTY(4)

character. TIOCREMOTE can be used when doing remote line editing in a window
manager, or whenever flow controlled input is required.
FILES

Idev/pty[p-r] [O-9a-f]
Idev/tty[p-r] [O-9a-f1

master pseudo terminals
slave pseudo terminals

DIAGNOSTICS

None.
BUGS

It is not possible to send an EOT.

4th Berkeley Distribution

7 July 1983

2

PUP (4F)

UNIX Programmer's Manual

PUP (4F)

NAME

pup - Xerox PUP-I protocol family
SYNOPSIS

#lnclude
#lnclude

< sys/types.h >
< netpup/pup.h >

DESCRIPTION

The PUP-I protocol family is a collection of protocols layered atop the PUP Level-O packet format, and utilizing the PUP Internet address format. The PUP family is currently supported
only by a raw interface.
ADDRESSING

PUP addresses are composed of network, host, and port portions.
< netpuplpup. h > defines this address as,
struct pupport {
pup_net;
u_char
pup_host;
u_char
pup_socket[4];
u_char

The include file

};
Sockets bound to the PUP protocol family utilize the following addressing structure,
struct sockaddr-pup {
short
spup_family;
short
spup_zero 1;
u_char
spup_net;
u_char
spup_host;
u_char
spup_sock[4];
char
spup_zer02[4];
};
HEADERS

The current PUP support provides only raw access to the 3Mb/s Ethernet. Packets sent
through this interface must have space for the following packet header present at the front of
the message,
struct pup header
u_short
u_char
u_char
uJong
u_char
u_char
u_char
u_char
u_char
u_char
);

(
pupJength;
pup_tcontrol;
pup_type;
pupjd;
ru~ _dnet;
pup_dhost;
pup_dsock[4];
pup_snet;
pup_shost;
pup_ssock[4];

IIII-

transport control -I
protocol type -I
used by protocols -I
destination -I

I- source -I

The sender should fill in the pup_tcontrol, pup_type, and pup_id fields. The remaining fields are
filled in by the system. The system checks the message to insure its size is valid and, calulates
a check.sum for the message. If no checksum should be calculated, the checksum field (the last
16-bit word in the message) should be set to PUP_NOCKSUM.

4th Berkeley Distribution

7 July 1983

1

PUP (4F)

UNIX Programmer's Manual

PUP (4F)

The pup_tcontro! field is restricted to be 0 or PUP_TRACE; PUP_TRACE indicates packet tracing should be performed. The pup_type field may not be O.
On input, the entire packet, including header, is provided the user. No checksum validation is
performed.
SEE ALSO

intro(4N), pup(4P), en(4)

BUGS
The only interface which currently supports use of pup's is the Xerox 3 Mb/s en(4) interface.
With the release of the second generation, PUP-II, protocols it is not clear what future PUP-I
has. Consequently, there has been little motivation to provide extensive kernel support.

4th Berkeley Distribution

7 July 1983

2

PUP(4P)

UNIX Programmer's Manual

PUP (4P)

NAME

pup - raw PUP socket interface
SYNOPSIS

#include < sys/socket.h>
#include < netpup/pup.h>
socket(AF_PUP, SOCK_RAW, PUPPROTO_BSP);
DESCRIPTION

A raw pup socket provides PUP-I access to an Ethernet network. Users send packets using the
sendto call. and receive packets with the ren:(rom call. All outgoing packets must have space
present at the front of the packet to allow the PUP header to be filled in. The header format is
described in pup(4F). Likewise. packets received by the user will have the PUP header on the
front. The PUP header and legal values for the various fields are defined in the include file

< netpuplpup. h> .
The raw pup interface automatically installs the length and source and destination addresses in
the PUP header of all outgoing packets~ these need not be filled in by the user. The only control bit that may be set in the tCOl11ro! field of outgoing packets is the "trace" bit. A checksum
is calculated unless the sender sets the checksum field to PUP _NOCKSUM.
DIAG!'lOSTICS

A socket operation may fail and one of the following will be returned:
[EISCONN]

when trying 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:

[ENOTCONN] when trying to send a datagram. but no destination address is specified. and
the socket hasn't been connected~
[ENOBUFS]
when the system runs out of memory for an internal data structure~
[EADDRNOT AVAll]
when an attempt is made to create a socket with a network address for which
no network interface exists.
A selldro operation may fail if one of the following is true:
[EINV AL]
[EINVAl]

Insufficient space was left by the user for the PUP header.
The pup_type field was 0 or the pup_tcomro! field had a bit other than
PUP_TRACE set.

[EMSGSIZE]

The message was not an even number of bytes, smaller than MINPUPSIZ. or
large than M AXPUPSIZ.
[ENETUNREACH]
The destination address was on a network which was not directly reachable
(the raw interface provides no routing support).
SEE ALSO

send(2), recv(2), intro(4N), pup(4F)
BUGS

The interface is untested against other PUP implementations.

4th Berkeley Distribution

7 July 1983

RX (4)

UNIX Programmer's Manual

RX (4)

NAME

rx - DEC RX02 floppy disk interface
SYNOPSIS

controller fxO at ubaO csr 0177170 vector rxintr
disk rxO at fxO slave 0
disk rxl at fxO slave 1
DESCRIPTION
The rx device provides access to a DEC RX02 floppy disk unit with M8256 interface module

(RX211 configuration). The RX02 uses 8-inch. single-sided. soft-sectored floppy disks (with
pre-formatted industry-standard headers) in either single or double density.
Floppy disks handled by the RX02 contain 77 tracks. each with 26 sectors (for a total of 2.002
sectors>. The sector size is 128 bytes for single density. 256 bytes for double density. Single
density disks are compatible with the RXOI floppy disk unit and with IBM 3740 Series Diskette
1 systems.
In addition to normal ('block' and 'raw') i/o, the driver supports formatting of disks for either
density and the ability to invoke a 2 for 1 interleaved sector mapping compatible with the DEC
operating system RT -11.
The minor device number is interpreted as follows:
Bit

Description
Sector interleaving (I disables interleaving)
1
Logical sector 1 is on track 1 (Q no, 1 yes)
2
Not used, reserved
Other Drive number

o

The two drives in a single RX02 unit are treated as two disks attached to a single controller.
Thus, if there are two RX02's on a system, the drives on the first RX02 are "rxO" and "rx I".
while the drives on the second are "rx2" and "rx3".
When the device is opened. the density of the disk currently in the drive is automatic,tlly determined. If there is no floppy in the device. open will fail.
The interleaving parameters are represented in raw device names by the letters 'a' through 'd'.
Thus. unit 0, drive 0 is called by one of the following names:
Mapping
interleaved
direct
interleaved
direct

De\'ice name Starting track
0
/dev/rrxOa
0
/dev/rrxOb
Idev/rrxOc
I
1
/dev/rrxOd

The mapping used on the 'c' device is compatible with the DEC operating system RT-Il. The
'b' device accesses the sectors of the disk in strictly sequential order. The 'a' device is the most
efficient for disk-to-disk copying.

110 requests must start on a sector boundary, involve an integral number of complete sectors,
and not go otT the end of the disk.
NOTES

Even though the storage capacity on a floppy disk is quite small, it is possible to make filesysterns on double density disks. For example, the command
% mkfs /dev/rxO 1001 13 1 4096 512 32 04
makes a file system on the double density disk in rxO with 436 kbytes available for file storage.
Using tar( 1) gives a more efficient utilization of the available space for file storage. Single density diskettes do not provide sufficient storage capacity to hold file systems.

4th Berkeley Distribution

27 July 1983

RX (4)

UNIX Programmer's Manual

RX

(4)

A number of ioctJ(2) calls apply to the rx devices, and have the form
#include < ~·axuba/rxreg.h>
ioctHfildes, code, arg)
int ·arg;
The applicable codes are:
RXIOC_FORMAT Format the diskette. The density to use is specified by the arg argument. 0
gives single density while non-zero gives double density.
RXIOC_GETDENS
Return :the density of the diskette (0 or ! =0 as above).
RXIOC WDDMK On the next write. include a deleted data address mark in the header of the
first sector.
RXIOC RDDMK Return non-zero if the last sector read contained a deleted data address mark
in its header. otherwise return O.
ERRORS

The following errors may be returned by the above ioctl calls:
[ENODEV] Drive not ready: usually because no disk is in the drive or the drive door is open.
[ENXIO]

Nonexistent drive (on open): offset is too large or not on a sector boundary or
byte count is not a multiple of the sector size (on read or write): or bad
(undefined) ioctl code.

[EIO]

A physical error other than "not ready". probably bad media or unknown format.

[EBUSY]

Drive has been opened for exclusive access.

[EBADF]

No write access (on format). or wrong density: the latter can only happen if the
disk is changed without closing the de\ ice (i.e .• calling c/ose(2) ).

FILES

/dev/rx '?
/dev/rrx? [a-d]
SEE ALSO

rxformad8V). newfs(8). mkfs(8). tar. The driver entered a bogus state. This should not happen.
BUGS

A floppy may not be formatted if the header info on sector 1. track 0 has been damageu.
Hence. it is not possible to format completely degaussed disks or disks with other formats than
the two known by the hardware.
If the drive subsystem is powered down when the machine is booted. the controller won't interrupt.

4th Berkeley Distribution

27 July 1983

2

TCP(4P)

UNIX Programmer's Manual

TCP(4P)

NAME

tcp - Internet Transmission Control Protocol
SYNOPSIS

#include < S}"s/socket.h>
#include < netinet/in.h>
s = socket(AF_INET, SOCK_STREAM, 0);
DESCRIPTION

The TCP protocol provides reliable. flow-controlled. two-way transmission of data. It is a bytestream protocol used to support the SOCK_STREAM abstraction. TCP uses the standard Internet address format and. in addition, provides a per-host collection of "port addresses". Thus.
each address is composed of an Internet address specifying the host and network. with a specific
TCP port on the host identifying the peer entity.
Sockets utilizing the tcp protocol are either "active" or "passive". Active sockets initiate connections to passive sockets. By default TCP sockets are created active~ to create a passive
socket the Iis{en(2) system call must be used after binding the socket with the billd(2) system
call. Only passive sockets may use the accepr(2) call to accept incoming connections. Only
active sockets may use the cOflllecr(2) call to initiate connections.
Passive sockets may "underspecify" their location to match incoming connection requests from
multiple networks. This technique. termed "wildcard addressing", allows a single server to
provide service to clients on multiple networks. To create a socket which listens on all networks, the Internet address INADDR_ANY must be bound. The TCP port may still be
specified at this time~ if the port is not specified the system will assign one. Once a connection
has been established the socket's address is fixed by the peer entity's location. The address
assigned the socket is the address associated with the network interface through which packets
are being transmitted and received. Normally this address corresponds to the peer entity's network.
DIAGNOSTICS

A socket operation may fail with one of the following errors returned:
[EISCONN]

when trying to establish a connection on a socket which already has one:

[ENOBUFS]

when the system runs out of memory for an internal data structure:

[ETIMEDOUT]

when a connection was dropped due to excessive retransmissions:

[ECONNRESET]

when the remote peer forces the connection to be closed:

[ECONNREFUSED] when the remote peer actively refuses connection establishment (usually
because no process is listening to the port> ~
[EADDRINUSE]

when an attempt is made to create a socket with a port which has already
been allocated:

[EADDRNOT AVAIL]
when an attempt is made to create a socket with a network address for
which no network interface exists.
SEE ALSO

intro(4N), ined4F)
BUGS

It should be possible to send and receive TCP options. The system always tries to negotiates
the maximum TCP segment size to be 1024 bytes. This can result in poor performance if an
intervening network performs excessive fragmentation.

4th Berkeley Distribution

7 July 1983

TM (4)

UNIX Programmer's Manual

TM

(4)

NAME

tm - TM-ll/TE-IO magtape interface
SYNOPSIS
controller tmO at uba? csr 0172520 vector tmintr
tape teO at tmO drhe 0
DESCRIPTION
The tm-Illte-l0 combination provides a standard tape drive interface as described in tnrio(4)'
Hardware implementing this on the V AX is typified by the Emulex TC-ll controller operating
with a Kennedy model 9300 tape transport, providing 800 and 1600 bpi operation at 125 ips.
SEE ALSO
md}), tarO), tp(l), mtio(4), ht(4), ts(4), mt(4), ut(4)
DIAGNOSTICS
te%d: no write ring. An attempt was made to write on the tape drive when no write ring was
present~ this message is written on the terminal of the user who tried to access the tape.

te%d: not online. An attempt was made to access the tape while it was omine: this message is
written on the terminal of the user who tried to access the tape.
tecYod: can't switch density in mid-tape. An attempt was made to write on a tape at a different
density than is already recorded on the tape. This message is written on the terminal of the
user who tried to switch the density.
te%d: hard error bn'Ytld er = IYllb. A tape error occurred at block bIT. the tm error register is
printed in octal with the bits symbolically decoded. Any error is fatal on non-raw tape: when
possible the driver will have retried the operation which failed several times before reponing
the error.
te%d: lost interrupt. A tape operation did not complete within a reasonable time. most likely
because the tape was taken off-line during rewind or lost vacuum. The controller should. but
does not, give an interrupt in these cases. The device will be made available again after this
message. but any current open reference to the device will return an error as the operation in
progress aborts.
Bl'GS

If any non-data error is encountered on non-raw tape. it refuses to do anything more until
closed.

4th Berkeley Distribution

27 July 1983

TS(4)

TS(4)

UNIX Programmer's Manual

NAME

ts - TS-ll magtape interface
SYNOPSIS

controller zsO at uba? csr 0172520 vector tsintr
tape tsO at zsO drive 0
DESCRIPTION

The ts-ll combination provides a standard tape drive interface as described in mtio(4). The ts11 operates only at 1600 bpi, and only one transport is possible per controller.
SEE ALSO

mt< 1), tar( n, tp(1), mtio(4), h(4), tm (4), m1(4), ut (4)

DIAGNOSTICS

ts%d: no write ring. An attempt was made to write on the tape drive when no write ring was
present~

this message is written on the terminal of the user who tried to access the tape.

ts%d: not online. An attempt was made to access the tape while it was
written on the terminal of the user who tried to access the tape.

omine~

this message is

ts%d: hard error bn'Ytld xsO =tV4lh. A hard error occurred on the tape at block bIT. status register

o is printed in octal and symbolically decoded as bits.
BUGS

If any non-data error is encountered on non-raw tape, it refuses to do anything more until
closed.
The device lives at the same address as a tm-ll (m(4)~ as it is very difficult to get this device to
interrupt, a generic system assumes that a ts is present whenever no tm-II exists but the csr
responds and a ts-l1 is configured. This does no harm as long as a non-existent ts-l1 is not
accessed.

4th Berkeley Distribution

27 July 1983

TTY (4)

TTY(4)

UNIX Programmer's Manual

NAME

tty - general terminal interface
SYNOPSIS

#include

< sgtt~·.h>

DESCRIPTION

This section describes both a particular special file Ide" Itty and the terminal drivers used for
conversational computing.
Line disciplines.

The system provides different line disciplines for controlling communications lines. In this version of the system there are three disciplines available:
old

The old (standard) terminal driver. This is used when using the standard shell sh( 1)
and for compatibility with other standard version 7 UNIX systems.

new

A newer terminal driver, with features for job

control~

this must be used when using

c:sh( 1).

net

A line discipline used for networking and loading data into the system over communications lines. It allows high speed input at very low overhead, and is described in
bk<4>.

Line discipline switching is accomplished with the TIOCSETD ioc[/:
int Idisc = LDISe: ioctHfiledes, TIOCSETD, &Idisc>:

where LDISe is OTTYDISC for the standard tty driver. NTTYDISC for the new driver and
NETLDISC for the networking discipline. The standard (currently old) tty driver is discipline 0
by convention. The current line discipline can be obtained with the TIOCG ETD ioct!. Pending
input is discarded when the line discipline is changed.
AU of the low-speed asynchronous communications ports can use any of the available line disciplines. no matter what hardware is involved. The remainder of this section discusses the
"old" and "new" disciplines.

The control terminal.

When a terminal file is opened. it causes the process to wait until a connection is established.
In practice. user programs seldom open these files~ they are opened by illi1(8) and become a
user's standard input and output file.
If a process which has no control terminal opens a terminal file. then that terminal file becomes
the control terminal for that process. The control terminal is thereafter inherited by a child
process during a /ork(2). even if the control terminal is closed.
The file Ide\-!tty is. in each process. a synonym for a c:olltrol terminal associated with that process. It is useful for programs that wish to be sure of writing messages on the terminal nJ
matter how output has been redirected. It can also be used for programs that demand a file
name for output. when typed output is desired and it is tiresome to find out which terminal is
currently in use.
Process groups.

Command processors such as csh( 1) can arbitrate the terminal between different jobs by placing
related jobs in a single process group and associating this process group with the terminal. A
terminals associated process group may be set using the TIOCSPG RP iOC1/(2):
iocti When 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 has drained down to some threshold the program is
resumed. Even parity is normally generated on output. The EOT character is not transmitted
in cooked mode to prevent terminals that respond to it from hanging up~ programs using raw or
cbreak mode should be careful.
The terminal drivers provide necessary processing for cooked and CBREAK mode output
including delay generation for certain special characters and parity generation. Delays are
available after backspaces AH, form feeds AL, carriage returns AM, tabs AI and newlines AJ. The
driver will also optionally expand tabs into spaces, where the tab stops are assumed to be set
every eight columns. These functions are controlled by bits in the tty flags word: see Summar)'
below.
The terminal drivers provide for mapping between upper and lower case on terminals lacking
lower case, and for other special processing on deficient terminals.
Finally, in the new terminal driver, there is a output flush character, normally AO, which
the LFLUSHO bit in the local mode word, causing subsequent output to be flushed until
cleared by a program or more input is typed. This character has effect in both cooked
CBREAK modes and causes pending input to be retyped if there is any pending input. An
to flush the characters in the input and output queues TIOCFLUSH, is also available.

sets
it is
and
ioctl

Upper case terminals and Hazeltines

If the LCASE bit is set in the tty flags, then all upper-case ietters are mapped into the
corresponding lower-case letter, The upper-case letter may be generated by preceding it by '\',
If the new terminal driver is being used, then upper case letters are preceded by a '\ . when
output. In addition, the following escape sequences can be generated on output and accepted
on input:
for
use

\.

\!

\

A

{

}

\{

\)

To deal with Hazeltine terminals, which do not understand that - has been made into an ASCII
character. the LTILDE bit may be set in the local mode word when using the new terminal
driver: in this case the character - will be replaced with the character' on output.
Flow control.

There are two ('haracter~  Access to the terminal by other processes
is then normally revoked. so any further reads will fail. and programs that read a terminal and
test for end-of-file on their input will terminate appropriately.
When using an ACU it is possible to ask that the phone line be hung up on the last close with
the TIOCHPCL ioctl~ this is normalJy done on the outgoing line.

I nterrupt characters.
There are several characters that generate interrupts in cooked and CBREAK mode~all are sent
the processes in the control group of the terminal. as if a TIOCGPGRP ioctl were done to get
the process group and then a killpg(2) system can were done. except that these characters also
flush pending input and output when typed at aterm.inal Ui 'fa TIOCFLUSH >. The characters
shown here are the defaults~ the field names in the structures (given below) are also shown.
The characters may be changed. although this is not often done.
A?

t_intrc (Delete) generates a SIGINT signal. This is the normal way to stop a process
which is no longer interesting, or to regain control inan interactive program.
t_quitc (FS) generates a SIGQUIT signal. This is used to cause a program to terminate
and produce a core image, if possible. in the file core in the current directory.
t_suspc (EM) generates a SIGTSTP signal. which is used to suspend the current process group.

t_dsuspc (SUB) generates a SIGTSTP signal as AZ does. but the signal is sent when a
program attempts to read the Ay, rather than when it is typed.
Job access control.
When using the new terminal driver, if a process which is not in the distinguished process
group of its control terminal attempts to read from that terminal its process group is sent a
SIGTTIN signal. This signal normally causes the members of that process group to stop. If,
however. the process is ignoring SIGTTIN. has SIGTTIN blocked. is an orphan process. oris in
the middle of process creation using vjork(2», it is instead returned an end-of-file. (An orphan
process is a process whose parent has exited and has been inherited by the init(8) process.)
Under older UNIX systems these processes would typically have had their input files reset to
/del-!null, so this .is a compatible change.
When using the new terminal driver with the LTOSTOP bit set in the local modes. a process is
prohibited from writing on its control terminal if it is not in the distinguished process group for
that terminal. Processes which are holding or ignoring SIGTTOUsignals. which are orphans. or
which are in the middle of a ~fork(2) are excepted .and allowed to produce output.

Summary of modes.
Unfortunately, due to the evolution of the terminal driver.. there are 4 different structures
which contain various portions of the driver data. The first of these (sgttyb) contains that part
of the information largely common between version 6 and version 7 UNIX systems. The
second contains additional control characters added in version 7. The third is a word of local
state peculiar to the new terminal driver, and the fourth is another structure of special characters added for the new driver. In the future a single structure may be made available to programs which need to access all this information~ most programs need not concern themselves
with all thi·s state.

4th Berkeley Distribution

9 February 1983

5

UNIX Programmer's Manual

TTY (4)

TTY (4)

Basic modes: Sgttv.
The basic ioctls use the structure defined in < sgtty. h> :
struct sgttyb {
char
char
char
char
short
};

sg_ispeed;
sg_ospeed;
sg_ erase;
sg_kill:
sg_ftags;

The sg_ispeed and sg_ospeed fields describe the input and output speeds of the device according
to the following table, which corresponds to the DEC DH-ll interface. If other hardware is
used, impossible speed changes are ignored. Symbolic values in the table are as defined in
< sgtty.h>.
(hang up dataphone)
BO
0
B50
1
50 baud
B75
2
75 baud
BII0 3
110 baud
B134 4
134.5 baud
B150 5
150 baud
B200 6
200 baud
B300 7
300 baud
B600 8
600 baud
B1200 9
1200 baud
B1800 10 1800 baud
B2400 11 2400 baud
B4800 12 4800 baud
B9600 13 9600 baud
EXT A 14 External A
EXTB 15 External B
In the current configuration, only 110, 150, 300 and 1200 baud are really supported on dial-up
lines. Code conversion and line control required for IBM 2741's (} 34.5 baud) must be implemented by the user's program. The half-duplex line discipline required for the 202 dataset
(1200 baud) is not supplied: full-duplex 212 datasets work fine.
The sg_erase and sg_kill fields of the argument structure specify the erase and kill characters
respectively. (Defaults are # and @,)
The sg-,!iags field of the argument structure contains several bits that determine the system's
treatment of the terminal:
ALLDELA Y 0177400
BSDELA Y 0100000
BSO
0
BSI
0100000
VTDELA Y 0040000
FFO
0
FFI
0100000
CRDELA Y 0030000
CRO
0
CRI
0010000
CR2
0020000
CR3
0030000

4th Berkeley Distribution

Delay algorithm selection
Select backspace delays (not implemented):
Select form-feed and vertical-tab delays:
Select carriage-return delays:

9 February 1983

6

TTY (4)

TBDELAY
TABO
TABI
TAB2
XTABS
NLDELAY
NLO
NLI
NL2
NL3
EVENP
ODDP
RAW
CRMOD
ECHO
LCASE
CBREAK
TANDEM

UNIX Programmer's Manual

TTY(4)

0006000 Select tab delays:

o
0001000
0004000
0006000
0001400 Select new-line delays:

o
0000400
0001000
0001400
0000200
OOOO} 00
0000040
0000020
0000010
0000004
0000002
0000001

Even parity allowed on input (most terminals)
Odd parity allowed on input
Raw mode: wake up on aU characters, 8-bit interface
Map CR into LF~ echo LF or CR as CR-LF
Echo (full duplex)
Map upper case to lower on input
Return each character as soon as typed
Automatic flow control

The delay bits specify how long transmission stops to allow for mechanical or other movement
when certain characters are sent to the terminal. In an cases a value of 0 indicates no delay.
Backspace delays are currently ignored but might be used for Terminet 300's.
If a form-feed/vertical tab delay is specified. it lasts for about 2 seconds.
Carriage-return delay type 1 lasts about .08 seconds and is suitable for the Terminet 300. Delay
type 2 lasts about .16 seconds and is suitable for the VT05 and the TI 700. Delay type 3 is suitable for the concept-} 00 and pads lines to be at least 9 characters at 9600 baud.
New-line delay type 1 is dependent on the current column and is tuned for Teletype model
37's. Type 2 is useful for the VT05 and is about .10 seconds. Type 3 is unimplemented and is

O.
Tab delay type 1 is dependent on the amount ·of movement and is tuned to the Teletype model
37. Type 3. called XT ABS. is not a delay at all but causes tabs to be replaced by the appropriate number of spaces on output.
Input characters with the wrong parity, as determined by bits 200 and 100. are ignored in
cooked and CBREAK mode.
RA W disables all processing save output flushing with LFLUSHO~ full 8 bits of input are given
as soon as it is available: all 8 bits are passed on output. A break condition in the input is
reported as a null character. If the input queue overflows in raw mode it is discarded: this
applies to both new and old drivers.
CRMOD causes input carriage returns to be turned into new-lines~ input of either CR or LF
causes LF-CR both to be echoed (for terminals with a new-line function).
CBREAK is a sort of half-cooked (rare?) mode. Programs can read each character as soon as
typed, instead of waiting for a full line: all processing is done except the input editing: character
and word erase and line kill. input reprint. and the special treatment of \ or EOT are disabled.
TANDEM mode causes the system to produce a stop character (default "5) whenever the input
queue is in danger of overflowing. and a start character (default "Q) when the input queue has
drained sufficiently. It is useful for flow control when the 4terminal' is really another computer
which understands the conventions.

4th Berkeley Distribution

9 February 1983

7

TTY (4)

UNIX Programmer's Manual

TTY(4)

Basic ioctls
In addition to the TIOCSETD and TIOCGETD disciplines discussed in Line disciplines above,
a large number of other ioctl(2) calls apply to terminals, and have the general form:
#include

< sgtty.h>

ioctHfildes, code, arg)
struct sgttyb ·arg:
The applicable codes are:
TIOCGETP

Fetch the basic parameters associated with the terminal. and store in the
pointed-to sguyb structure.

TIOCSETP

Set lhe parameters according to the pointed-to sgltyb structure. The interfuce
delays until output is quiescent. then throws away any unread churacters,
before changing the modes.

TIOCSETN

Set the parameters like TIOCSETP but do not delay or flush input. Input is
not preserved, however, when changing to or from RAW.

With the following codes the arg is ignored.
TIOCEXCL

Set "'exclusive-use" mode: no further opens are permitted until the file has
been closed.

TIOCNXCL

Turn off "exclusive-use" mode.

TIOCHPCL

\Vhen the file is closed for the last time. hang up the terminal. This is useful
when the line is associated with an ACU used to place outgoing culls.

TIOCFLUSH

All characters waiting in input or output queues are flushed.

The remaining calls are not available in vanilla version 7 UNIX. In cases where arguments are
required, they are described: arg should otherwise be given as O.
TIOCSTI

the argument is the address of a character which the system pretends was typed
on the terminal.

TIOCSBRK

the break bit is set in the terminal.

TIOCCBRK

the break bit is cleared.

TIOCSDTR

data terminal ready is set.

TIOCCDTR

data terminal ready is cleared.

TIOCGPGRP

arg is the address of a word into which is placed the process group number of
the control terminal.

TIOCSPG RP

arg i ... i.t word (typically a process id) which becomes the process group for the
control terminal.

FIONREAD

returns in the long integer whose address is arg the number of immediately
readable characters from the argument unit. This works for files, pipes. and
terminals. but not (yet> for multiplexed channels.

The second structure associated with each terminal specifies characters that are special in both
the old C!nd new terminal interfaces: The following structure is defined in < sys/;ocll.h>. which
is automatically included in < sgtty.h> :
struct tchars {
char
t_intrc;
char
t_quitc;

4th Berkeley Distribution

/. interrupt • /
/. quit ./

9 February 1983

8

TTY (4)

UNIX Programmer's Manual

char
char
char
char

t_startc;
t_stopc;
t_eofc;
t_hrkc;

////-

TTY(4)

start output -/
stop output-/
end-o.f-file -/
input delimiter Hiken» -/

};
The default values for these characters are"?, "\, "Q. "s. "D. and -1. A character value of
-1 eliminates the effect of that character. The Cbrkf character, by default -1. acts like a
new-line in that it terminates a 'line.' is echoed. and is passed to the program. The 'stop' and
'starf characters may be the same. to produce a toggle effect. It is probably counterproductive
to make other special characters (including erase and kill) identical. The applicable ioctl calls
are:
TIOCGETC Get the special characters and put them in the specified structure.
TIOCSETC Set the special characters to those given in the structure.
Local mode
The third structure associated with each terminal is a local mode word~ except for the
LNOHANG bit. this word is interpreted only when the new driver is in use. The bits of the
local mode word are:
LCRTBS
LPRTERA
LCRTERA
LTILDE
LMDMBUF
LLITOUT
LTOSTOP
LFLUSHO
LNOHANG
LETXACK
LCRTKIL
LINTRUP
LCTLECH
LPENDIN
LDECCTQ

000001
000002
000004
000010
000020
000040
000100
000200
000400
001000
002000
004000
010000
020000
040000

Backspace on erase rather than echoing erase
Printing terminal erase mode
Erase character echoes as backspace-space-backspace
Convert - to . on output (for Hazeltine terminals)
Stop/start output when carrier drops
Suppress output translations
Send SIGTTOU for background output
Output is being flushed
Don't send hangup when carrier drops
Diablo style buffer hacking (unimplemented)
BS-space-BS erase entire line on line kill
Generate interrupt SIGTINT when input ready to read
Echo input control chars as "X. delete as "?
Retype pending input at next read or input character
Only "Q restarts output after "S, like DEC systems

The applicable ioell functions are:
TIOCLBIS

arg is the address of a mask which is the bits to be set in the local mode word.

TIOCLBIC

arg is the address of a mask of bits to be cleared in the local mode word.

TIOCLSET

arg is the address of a mask to be placed in the local mode word.

TIOCLGET

arg is the address of a word into which the current mask is placed.

Local special chars
The final structure associated with each terminal is the Ilehars structure which defines interrupt
characters for the new terminal driver. Its structure is:

struct Itehars (
char
t_suspc;
t_dsuspc;
char
ehar
,-rprnte;
char
t_flushc;

4th Berkeley Distribution

////-

stop process signal -/
delayed stop process signal - /
reprint line -/
flush output I. constructing file Sy:-'ll' I liS, IH)\\c\\.'\" tl1-' p;lrtitiPlls SillS ;\1\' n.'quil\.'tl. Till' origin ;1111.1 Sill' (in s\.'ctOf"';) or the
p~;clld()-disks Oil l'utioll

1

unA (4)

ra'!h
ra'!c
ra'!d
ra'!c
ra'!l'
ra'!g
ra'!h
'1'111..'
til\.'
"'II.K~

lIDA (4)

UN IX Programmcr's I\buual

JJ4~O

15XX4
0
1313(H
.nl3tH
()IIlXX

XI) I 072
2(H)(H)()

?79X~'~
'279X~4

,~t)J!4

X~()X()

131~IO·t

75 1)()6X

1'.1'\1 pClnilioll is IlOnnally lIs\'d li)1' tht,' root fik S~\ll'l1l. llh' ra?h partition
ra'!c p;lrlitioll for p;ll'k-p;tck copyillg (illllaps Ill\.' elllire disk).

~tS (I prill <"Illirdy with the results or diskplII't(X).

. ~th Berkeley Distrihution

27 .!uly l'nO

2 '

UDP (4P)

UNIX Programmer's Manual

UDP (4P)

NAME

udp - Internet User Datagram Protocol
SYNOPSIS

#include < sys/socket.h>
#include < netinet/in.h>
s = socket(AF_INET, SOCK_DGRAM, 0);
DESCRIPTION

UDP is a simple, unreliable datagram protocol which is used to support the SOCK_DGRAM
abstraction for the Internet protocol family. UDP sockets are connectionless. and are normally
used with the sendto and reCl'/rom calls. though the connect(2) call may also be used to fix the
destination for future packets (in which case the reCl,(2) or read(2) and send(2) or write{]) system calls may be used).
UDP address formats are identical to those used by TCP. In particular UDP provides a port
identifier in addition to the normal Internet address format. Note that the UDP port space is
separate from the TCP port space (i.e. a UDP port may not be "connected" to a Tep port). In
addition broadcast packets may be sent (assuming the underlying network supports this) by
using a reserved "broadcast address"~ this address is network interface dependent.
DIAGNOSTICS

A socket operation may fail with one of the following errors returned:
[EISCONN]

when trying 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:

[ENOTCONN] when trying to· send a datagram. but no destination address is specified. and
the socket hasn't been connected:
[ENOBUFS]
when the system runs out of memory for an internal data structure:
[EADDRINUSE]
when an attempt is made to create a socket with a port which has already been
allocated~

[EADDRNOT AVAlL]
when an attempt is made to create a socket with a network address for which
no network interface exists.
SEE ALSO

send(2), recv(2). intro(4N). ined4F)

4th Berkeley Distribution

25 March 1982

UN (4)

UNIX Programmer's Manual

UN (4'

NAME

un - Ungermann-Bass interface
SYNOPSIS
device unO at ubaO csr 0160210 "ector unintr
DESCRIPTION
The un interface provides access to a 4 Mb/s baseband network. The hardware uses a standard
DEC DRII-W DMA interface in communicating with the host. The Ungermann-Bass
hardware incorporates substantial protocol software in the network device in an attempt to
offload protocol processing from the host.

The network number on which the interface resides must be specified at boot time with an
SIOCSIF AD DR ioctl. The host's address is discovered by communicating with the interfac~.
The interface will not transmit or receive any packets before the network number has been
defined.
DIAGNOSTICS
un'Yud: can't initialize. Insufficient UNIBUS resources existed for the device to complete initialization. Usually caused by having multiple network interfaces configured using butTered data
paths on a data path poor machine such as the 11/750.

unoAld: unexpected reset. The controller indicated a reset when none had been requested.
Check the hardware (but see the bugs section below).
un'Vr.d: stray interrupt. An unexpected interrupt was received. The interrupt was ignored.
un%d: input error csr=%b. The controller indicated an error on moving data from the device
to host memory.
un%d: bad packet type %d. A packet was received with an unknown packet type. The packet
is discarded.
un%d: output error csr=%b. The device indicated an error on moving data from the host to
device memory.
un'Ycld: invalid state utlld csr =%b. The driver found itself in an invalid internal state.
state is reset to a base state.

The

un%d: can't handle af%d. A request was made to send a message with an address format
which the driver does not understand. The message is discarded and an error is returned to the
user.
un%d: error limit exceeded. Too many errors were encountered in normal operation. The
driver will attempt to reset the device. desist from attempting any i/o for approximately 60
seconds. then reset itself to a base state in hopes of resyncing itself up with the hardware.
un'Yod: rest::rting.
ing operation.

\fter exceeding its error limit and resetting the device. the driver is restart-

SEE ALSO
intro(4N), inet (4F)
BUGS

The device does not reset itself properly resulting in the interface getting hung up in a state
from which the only recourse is to reboot the system.

4th Berkeley Distribution

27 July 1983

UP(4)

UNIX Programmer's Manual

UP(4)

NAME

up - unibus storage module controller/drives
SYNOPSIS

controller scO at uba? csr 0176700 vector upintr
disk upO at scO drive 0
DESCRIPTION

This is a generic UNIBUS storage module disk driver. It is specifically designed to work with
the Emulex SC-21 controller. It can be easily adapted to other controllers (although bootstrapping witt not necessarily be directly possible.)
Files with minor device numbers 0 through 7 refer to various portions of drive 0; minor devices 8 through 15 refer to drive 1, etc. The standard device names begin with "up" followed
by the drive numb~r and then a letter a-h for partitions 0-7 respectively. The character'? stands
here for a drive number in the range 0-7.
The block files access the disk via the system's normal buffering mechanism and may be read
and written without regard to physical disk records. There is also a 'raw' interface which provides for direct transmission between the disk and the user's read or write buffer. A single read
or write call results in exactly one I/O operation and therefore raw I/O is considerably morc
efficient when many words are transmitted. The names of the raw files conventionally begin
with an extra 'r.'
In raw I/O counts should be a multiple of 512 bytes (a disk sector>. Likewise seek calls should
specify a multiple of 512 bytes.
DISK Sl:PPORT

The driver interrogates the controller's holding register to determine the type of drive attached.
The driver recognizes four different drives: AMPEX 9300, CDC 9766, AMPEX Capricorn. and
FUJITSU 160. The origin and size of the pseudo-disks on each drive are as follows:
CDC 9766 300M
disk
up?a
up?b
up?c
up?d
up?e
up?f
up?g
up?h

drive partitions:
start
length
0
15884
33440
16416
0
500384
341696 15884
358112 55936
414048 861760
341696 158528
49856
291346

AMPEX 9300 300M drive
disk
slall
up?a
0
up?b
16416
up? c
0
up'?d
341696
up?e
358112
up?f
414048
up?g
341696
up?h
49856

partitions:
length
15884
33440
495520
15884
55936
81312
153664
291346

cyl
0-26
27-81
0-822
562-588
589-680
681-822
562-822
82-561
cyl
0-26
27-81
0-814
562-588
589-680
681-814
562-814
82-561

AMPEX Capricorn 330M drive partitions:
cyl
disk
start
length
hp?a
0
15884
0-31
hp?b
16384
33440
32-97

4th Berkeley Distribution

27 July 1983

UP(4)

UNIX Programmer's Manual

hp?c
hp?d
hp?e
hp?f
hp?g
hp?h
FUJrTSU 160M
disk
up?a
up?b
up?c
up?d
up?e
up?!
up?g

0

342016
358400
414720
342'016
50176

524288
15884
55936
109408
182112
291346

drive partitions:
start
length
0
15884
16000
33440
0
263360
4960()
15884
65600
55936
121600 141600
49600
213600

UP(4)

0-1023
668-699
700-809
810-1023
668-1023
98-667
cyl
0-49
50-154
0-822
155-204
205-379
380-822
155-822

It is unwise for all of these files to be present in one installa.tion. since there is overlap in
addresses and protection becomes a sticky matter. The up?a partition is normally used for the
root file system. the up?b partition as. a paging area. and the up?c partition for pack-pack copying (it maps the entire disk). On 160M drives the up?g pa.rtition. maps the rest of the pack. On
other drives both up'!g and up?h are used to map the remaining cyftnders.
FILES

I dev I up [0-71 [a- hI
Ide.vlrup[O-7Ha-hl

block files
raw files

SEE ALSO

hk (4). hp(4)i. uda (4)
DIAG~OSTICS

up6f6dOlitc: hard error sn'Yod cs2' =%·b erl =°lttb: er2 =I~tb. An unrecovera,ble error occurred during
transfer of the spedned: sector in the: s.pecified disk partiition. The content's of the cs2. er 1 and
er2 regis,ters are printed in octat and symbolicalJ'y wiith brts decoded. Th.e error was either unrecoverable, or a large number of retry attempts (including o.ffset positioning and drive recalibration) could not recover the error.
up%d: write· lot ked. The write protect swj;tch was set on the drive when a write was attempted.
The write operation is not recoverable.
upIYud.: not ready. The drive was spun down
is not recoverable.

Dr

off line when it was accessed. The i/o operation

up%di : not ready (ftake-y). The drive was not ready. but aftef printing the message about bei.ng
not ready (which takes a fraction of a second)' was ready. The' operation is recovered if no
further errors. occ.Ur.
up%d%c: so·ft ftC snlt/od; A rec.overable ECC error occurred on the' spedfied sector of the
specified disk partition. This happens normally a few time's- a; week. if it happens more frequently than this the sec.tors where the errors are occurring sbould be c.necked to see if certain
cylinders on the pack., spots on the carriage of the' ddv.e 0·J' beads are i,ndicated.
sc%d: lost interrupt A tim.er watching the controller det~.ting nD) i.nte:rrupt for an extended
period while an: operation was outstan and use the following
ioct/(2) call
ioctl (fileno(va). VSETST ATE, plotmd):
where p/ormd is defined to be
int plotmd[] =

I VPLOT,

0, 0

l:

and va is the result of a call to lopell on stdio. When you finish using the Benson-Varian in plot
mode you should advance to a new page by sending it a FF after putting it back into print
mode. i.e. by
int prtmd [] =

I VPRINT. O. 0 L

mush (va):
ioctl(fileno(va), VSETSTATE, prtmd):
write(fileno(va), "\f\0", 2):
N.B.: If you use

thf> ~t'I"dard

I/O library with the Benson-Varian you must do

setbuf( vp, vpbuf):
where vpbulis declared
char vpbur[BUFSIZ]~

otherwise the standard 1/0 library, thinking that the Benson-Varian is a terminal (since it is a
character special file) will not adequately buffer the data you are sending to the Benson-Varian.
This will cause it to run extremely slowly and tend to grind the system to a halt.
FILES

Idev/vaO
SEE ALSO

vfont(S), Ipr(I). Ipd(8), vtroff(l), vp(4)

4th Berkeley Distribution

27 March 1983

VA (4)

UNIX Programmer's Manual

VA (4)

DIAGNOSTICS

The following error numbers are significant at the time the device is opened.
[ENXIO] The device is already in use.
[EIO]

The device is omine.

The following message may be printed on the console.
va%d: npr timeout. The device was not able to get data from the UNIBUS within the timeout
period, most likely because some other device was hogging the bus. (But see BUGS below).
BUGS

The 1's (one's) and 1'5 Clower-case el's) in the Benson-Varian's standard character set look very
similar~ caution is advised.
The interface hardware is rumored to have problems which can play havoc with the UNIBUS.
We have intermittent minor problems on the UNIBUS where our "0 lives, but haven't ever
been able to pin them down completely.

4th Berkeley Distribution

27 March 1983

2

VP(4)

UNIX Programmer's Manual

VP(4)

NAME

vp - Versatec interface
SYNOPSIS

device vpO at ubaO csr 0177510 vector vpintr vpintr
DESCRIPTION

The Versatec printer/plotter is normally used with the programs vprO), vprilll(I) or
This description is designed for those who wish to drive the Versatec directly.

\'If(~tl(}

>.

To use the Versatec yourself, you must realize that you cannot open the device, /del'/\,pO if
there is a daemon active. You can see if there is a daemon active by doing a Ipq( 1), and seeing
if there are any files being sent.
To set the Versatec into plot mode you should include < s.vs/vcmd.h> and use the iocl/(2) call
ioctHfileno(vp), VSETSTATE,
where plolmd is defined to be
int plotmd [] == { VPLOT, 0, 0

plotmd)~

k

and vp is the result of a call to jopen on stdio. When you finish using the Versatec in plot mode
you should eject paper by sending it a EaT after putting it back into print mode, i.e. by
int prtmd[] = { VPRINT, 0, 0 }~
mush(vp)~

ioctl (fileno (vp), VSETST ATE, prt md) ~
write(fileno(vp), "\04", I)~
N.B.: If you use the standard I/O library with the Versatec you must do
setbuf( vp, vpbuf)~
where rpbufis declared
char vpbuf[BUFSIZL
otherwise the standard I/O library, thinking that the Versatec is a terminal 

DESCRIPTION
A.out is the output file of the assembler as(1) and the link editor IdO). Both programs make
a.out executable if there were no errors and no unresolved external references. Layout infor-

.
.

mation as given in the include file for the VAX-ll is:

/

• Header prepended to each
/
struct exec {
a_magic;
long
unsigned a_text;
unsigned a_data;
unsigned a_bss;
unsigned a_syms;
unsigned a_entry;
unsigned a_trsize;
unsigned a_drsize;

a.out file .
/.
/.
/.
/.
///.
/-

magic number ./
size of text segment ./
size of initialized data ./
size of uninitialized data -/
size of symbol table -/
entry point -/
size of text relocation -/
size of data relocation -/

};
#define OMAGIC 0407
#define NMAGIC0410
#define ZMAGIC 0413

/- old impure format -/
/. read-only text ./
/. demand load format ./

/.
- Macros which take exec structures as arguments and tell whether
• the file has a reasonable magic number or offsets to text Isymbols Istrings.
-/
#define N BADMAG(x) \
«(x).a_magic)!==OMAGIC && «x).a_magic)!-NMAGIC && «x).a_magic)!-ZMAGIC)
#define N TXTOFF(x) \
«x).a_magic== ==ZMAGIC ? 1024 : sizeof (struct exec»
#define N SYMOFF(x) \
(N TXTOFF(x) + (x).a text + (x).a data + (x).a trsize + (x).a drsize)
#define N STROFF(x) \
n~'_SYMOFF(x) + (x).a_syms)
The file has five sections: a header, the program text and data, relocation information, a symbol
table and a string table (in that order). The last three may be omitted if the program was
loaded with the '-s' option of /d or if the symbols and relocation have been removed by
strip(I) .

In the header the sizes of each section are given in bytes. The size of the header is not
included in any of the other sizes.
When an a.our file is executed, three logical segments are set up: the text segment, the data
segment (with uninitialized data, which starts off as all 0, following initialized), and a stack.
The text segment begins at 0 in the core image; the header is not loaded. If the magic number
in the header is OMAGIC (0407), it indicates that the text segment is not to be write-protected
and shared, so the data segment is immediately contiguous with the text segment. This is the

4th Berkeley Distribution

25 February 1983

1

A.OUT(S)

UNIX Programmer's Manual

A.OUT (S)

oldest kind of executable program and is rarely used. If the magic number is NMAGIC (0410)
or ZMAGIC (0413), the data segment begins at the first 0 mod 1024 byte boundary following
the text segment, and the text segment is not writable by the program; if other processes are
executing the same file, they will share the text segment. For ZMAGIC format, the text segment begins at a 0 mod 1024 byte boundary in the Q.out file, the remaining bytes after the
header in the first block are reserved and should be zero. In this case the text and data sizes
must both be multiples of 1024 bytes, and the pages of the file will be brought into the running
image as needed, and not pre-loaded as with the other formats. This is especially suitable for
very large programs and is the default format produced by Id(1).
The stack will occupy the highest possible locations in the core image: growing downwards from
Ox7ffffOOO. The stack is automatically extended as required. The data segment is only
extended as requested by brk(2).
After the header in the file follow the text, data, text relocation data relocation, symbol table
and string table in that order. The text begins at the byte 1024 in the file for ZMAGIC format
or just after the header for the other formats. The N_TXTOFF macro returns this absolute file
position when given the name of an exec structure as argument. The data segment is contiguous with the text and immediately followed by the text relocation and then the data relocation
information. The symbol table follows all this; its position is computed by the N_SYMOFF
macro. Finally, the string table immediately follows the symbol table at a position which can be
gotten easily using N_STROFF. The first 4 bytes of the string table are not used for string
storage, but rather contain the size of the string table; this size INCLUDES the 4 bytes, the
minimum string table size is thus 4.
The layout of a symbol table entry and the principal flag values that distinguish symbol types
are given in the include file as follows:
/.
• Format of a symbol table entry .
/
struct nlist {
union {
.n_name; /. for use when in-core ./
char
long
n_strx; /. index into file string table ./
} nun;
unsigned char n_type; /. type flag, i.e. N_TEXT etc; see below ./
char
n_other;
short
n_desc; /. see  ./
unsigned
n_value; /. value of this symbol (or offset> ./

.

};
#define n_hash

n_desc

/.
• Simple values for n_type .
/
.
OxO
#define N_UNDF
Ox2
#define N_ABS
Ox4
#define N_TEXT
Ox6
#define N_DATA
Ox8
#define N_BSS
Ox12
#define N_COMM
Oxlf
#define N_FN

.

01

4th Berkeley Distribution

/. used internally by Id ./

/.
/.
/.
/.
/.
/.
/.

undefined ./
absolute ./
text ./
data ./
bss ./
common (internal to ld) ./
file name symbol ./

/. external bit, or'ed in ./

2S February 1983

2

A.OUT(5)

#define N _TYPE

UNIX Programmer's Manual

Oxle

A.OUT(5)

/- mask for all the type bits -/

/- Othe! permanent symbol table entries have some of the N_STAB bits set.
- These are given in < stab.h >

-/
#define N_STAB

OxeO

/- if any of these bits set, don't discard -/

/- Format for namelist values.

-/
#define N_FORMAT "%08x"
In the a.out file a symbol's n_un.n_strx field gives an index into the string table. A n_strx
value of 0 indicates that no name is associated with a particular symbol table entry. The field
n_un.n_name can be used to refer to the symbol name only if the program sets this up using
n_strx and appropriate data from the string table.

If a symbol's type is undefined external, and the value field is non-zero, the symbol is interpreted by the loader Id as the name of a common region whose size is indicated by the value of
the symbol.
The value of a byte in the text or data which is not a portion of a reference to an undefined
external symbol is exactly that value which will appear in memory when the file is executed. If
a byte in the text or data involves a reference to an undefined external symbol, as indicated by
the relocation information, then the value stored in the file is an offset from the associated
external symbol. When the file is processed by the link editor and the external symbol
becomes defined, the value of the symbol will be added to the bytes in the file.

If relocation information is present, it amounts to eight bytes per relocatable datum as in the
following structure:

/- Format of a relocation datum.

-/
struct relocationJnfo {
int
r_address~
unsigned r_symbolnum:24,
r,J>crel: 1,
rJength:2,
r_extern: 1,
:4;
};

//////-

address which is relocated -/
local symbol ordinal -/
was relocated pc relative already -/
O-byte, I-word, 2-long -/
does not include value of sym referenced -/
nothing, yet -/

There is no relocation information if a trsize+a drsize- -0. If r extern is 0, then
r_symbolnum is actually a n_type for the relocation (i.e. N_TEXT meaning relative to segment
text origin.)
SEE ALSO

adb(I), as(I), IdO), nm(I), dbx(I), stab(5), strip(I)

BUGS
Not having the size of the string table in the header is a loss, but expanding the header size
would have meant stripped executable file incompatibility, and we couldn't hack this just now.

4th Berkeley Distribution

25 February 1983

3

ACCT(S)

UNIX Programmer's Manual

ACCT (5)

NAME

acct - execution accounting file
SYNOPSIS

#Include < sys/acct.h >
DESCRIPTION

The acct(2) system call makes entries in an accounting file for each process that terminates.
The accounting file is a sequence of entries whose layout, as defined by the include file is:
/-

acct.h

4.5

82/10/10-/

/- Accounting structures;
- these use a comp_t type which is a 3 bits base 8
- exponent, 13 bit fraction "floating point" number.
-/
typedef u_short comp_t;
struct
{

acct
ac_comm(10);
ac_utime;
ac_stime;
ac_etime;
ac_btime;
ac_uid;
aCJid;
ac_mem;
acjo;
ac_tty;
ac_flag;

/*
/*
/*
/*
/*
/*
/*
/*
///-

Accounting command name */
Accounting user time */
Accounting system time */
Accounting elapsed time */
Beginning time -/
Accounting user ID -/
Accounting group ID */
average memory usage */
number of disk 10 blocks -/
control typewriter -/
Accounting flag -/

#defineAFORK
#define ASU
#define ACOMPAT
#defineACORE
#defineAXSIG

0001
0002
0004
0010
0020

/////-

has executed fork, but no exec */
used super-user privileges */
used compatibility mode -/
dumped core -/
killed by a signal -/

#define ACCTLO
#defineACCTHI

30
100

/- acctg off when space < this -/
/- acctg resumes at this level -/

char
comp_t
comp_t
comp_t
time_t
short
short
short
comp_t
dev_t
char

};

#ifdef KERNEL
acctbuf;
struct acct
.acctp;
struct inode
#endif
If the process does an execve(2), the first 10 characters of the filename appear in ac_comm. The
accounting flag contains bits indicating whether execve(2) was ever accomplished, a:ld whether
the process ever had super-user privileges.
SEE ALSO

acct(2), execve(2), sa(8)

7th Edition

15 January 1983

1

ALIASES (5)

UNIX Programmer's Manual

ALIASES (5)

NAME

aliases - aliases file for sendmail
SYNOPSIS

lusrllibl aliases
DESCRIPTION

This file describes user id aliases used by lusrlliblsendmail. It is formatted as a series of lines of
the form
name: name_I, name2, name_3, ...
The name is the name to alias, and the name_n are the aliases for that name. Lines beginning
with white space are continuation lines. Lines beginning with '#' are comments.
Aliasing occurs only on local names. Loops can not occur, since no message will be sent to any
person more than once.
After aliasing has been done, local and valid recipients who have a ".forward" file in their
home directory have messages forwarded to the list of users defined in that file.
This is only the raw data file; the actual aliasing information is placed into a binary format in
the files lusrlliblaliases.dir and lusrlliblaliases.pag using the program newaliases(1). A newaliases
command should be executed each time the aliases file is changed for the change to take effect.
SEE ALSO

newaliases(1), dbm(3X), sendmail(S)
SENDMAIL Installation and Operation Guide.
SENDMAIL An Internetwork Mail Router.

BUGS
Because of restrictions in dbm(3X) a single alias cannot contain more than about 1000 bytes of
information. You can get longer aliases by "chaining"; that is, make the last name in the alias
be a dummy name which is a continuation alias.

7th Edition

15 January 1983

1

AR(S)

UNIX Programmer's Manual

AR(S)

NAME

ar - archive (library) file format
SYNOPSIS

#lnclude < ar.h >
DESCRIPTION

The archive command ar combines several files into one. Archives are used mainly as libraries
to be searched by the link-editor Id.
A file produced by ar has a magic string at the start, followed by the constituent files, each preceded by a file header. The magic number and header layout as described in the include file
are:
#define ARMAG "!\n"
#define SARMAG 8
#define ARFMAG "'\n"
struct ar_hdr (
char
char
char
char
char
char
char
};

ar name[16];
ar- date[I2);
ar-uid[6];
ar=gid[6] ;
ar model8];
ar-size[IO);
ar=fmag(2);

The name is a blank-padded string. The arJmag field contains ARFMAG to help verify the
presence of a header. The other fields are left-adjusted, blank-padded numbers. They are
decimal except for ar_mode, which is octal. The date is the modification date of the file at the
time of its insertion into the archive.
Each file begins on a even (0 mod 2) boundary; a new-line is inserted between files if necessary. Nevertheless the size given reflects the actual size of the file exclusive of padding.
There is no provision for empty areas in an archive file.
The encoding of the header is portable across machines. If an archive contains printable files,
the archive itself is printable.
SEE ALSO
ar(I), Id(I), nm(l)

BUGS
File names lose trailing blanks. Most software dealing with archives takes even an incl uded
blank as a name terminator.

7th Edition

1S January 1983

1

CORE (5)

UNIX Programmer's Manual

CORE (5)

NAME

core - format of memory image file
SYNOPSIS

#include

< machine/param.h>

DESCRIPTION

The UNIX System writes out a memory image of a terminated process when any of various
errors occur. See sigvec(2) for the list of reasons~ the most common are memory violations,
illegal instructions, bus errors, and user-generated quit signals. The memory image is called
'core' and is written in the process's working directory (provided it can be~ normal access controls apply).
The maximum size of a core file is limited by serrlimit(2). Files which would be larger than the
limit are not created.
The core file consists of the u. area, whose size (in pages) is defined by the UPAGES manifest
in the < machil1e/param.h> file. The u. area starts with a user structure as given in
< sys/user.h>. The remainder of the core file consists first of the data pages and then the stack
pages of the process image. The amount of data space image in the core file is given (in pages)
by the variable lI_dsize in the 1I. area. The amount of stack image in the core file is given (in
pages) by the variable lI_ssi:e in the u. area.
In general the debugger adb( 1) is sufficient to deal with core images.
SEE ALSO

adb(I), dbx(), sigved2), setrlimit(2)

7th Edition

27 July 1983

DIR (5)

UNIX Programmer's Manual

DIR (5)

NAME

dir - format of directories
SYNOPSIS

#Include < sys/types.b >
#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 Oag word of its i-node entry; see
fs(S). The structure of a directory entry as given in the include file is:

I- 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 (e.g. 512 bytes on most machines).

-- Each DIRBLKSIZ 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.

•

- The macro DIRSIZ(dp) gives the amount of space required to represent
• a directory entry. Free space in a directory is represented by
• entries which have dp->d_rec1en > DIRSIZ(dp). All DIRBLKSIZ bytes
• in a directory block are claimed by. the directory entries. This
- usually results in the last entry in a directory having a large
• dp->d_reclen. When entries are deleted from a directory, the
• space is returned to the previous entry in the same directory
• block by increasing its dp- > d_reclen. If the first entry of
• a directory block is free, then its dp->djno is set to O.
• Entries other than the first in a directory do not normally have
• dp- >djno set to O.
/
#~fdef KERNEL
#define DIRBLKSIZ DEV_BSIZE
#else
#define DIRBLKSIZ 512
#endif

.

#define MAXNAMLEN 255

/

.

•
-

The DIRSIZ macro gives the minimum record length which will hold
the directory entry. This requires the amount of space in struct direct
without the d_name field, plus enough space for the name with a terminating
null byte (dp- >d_namlen + 1), rounded up to a 4 byte boundary.
/
#undef DIRSIZ
#define DIRSIZ(dp) \
«sizeof (struct direct) - (MAXNAMLEN+1) + «(dp)->d_namlen+l + 3) Ie:

.

4th Berkeley Distribution

15 January 1983

3»
1

DIR (5)

UNIX Programmer's Manual

struct

direct (
uJong
djno;
short
d_reclen;
short
d_namlen;
char
d name [MAXNAMLEN
/- typically shorter -/

DIR (5)

+ 1];

);
struct _dirdesc {
int
long
long
char
};

dd_fd;
ddJoc;
dd size;
dd=buf(DIRBLKSIZ] ;

By convention, the first two entries in each directory are for'.' and' .. '. The first is an entry for
the directory itself. The second is for the parent directory. The meaning of ' .. ' is modified for
the root directory of the master file system (" /"), where ' .. ' has the same meaning as '.'.
SEE ALSO

fs(5)

4th Berkeley Distribution

15 January 1983

2

DISKTAB(S)

UNIX Programmer's Manual

DISKTAB(S)

NAME

disktab - disk description file
SYNOPSIS

#lnclude

< dlsktab.h >

DESCRIPTION
Disktab is a simple date base which describes disk geometries and disk partition characteristics.
The format is patterned after the termcap(S) terminal data base. Entries in disktab consist of a

number of ':' separated fields. The first entry for each disk gives the names which are known
for the disk, separated by 'I' characters. The last name given should be a long name fully identifying the disk.
The following list indicates the normal values stored for each disk entry.
Name
ns
nt
nc
ba
bd
be
bf
bg
bh
fa
fd
fe
ff
fg
fb
pa
pb
pc
pd
pe
pf
pg
ph
se
ty

Type
num
num
num
num
num
num
num
num
num
num
num
num
num
num
num
num
num
num
num
num
num
num
num
num
str

Description
Number of sectors per track
Number of tracks per cylinder
Total number of cylinders on the disk
Block size for partition 'a' (bytes)
Block size for partition 'd' (bytes)
Block size for partition 'e' (bytes)
Block size for partition 'f (bytes)
Block size for partition 'g' (bytes)
Block size for partition 'h' (bytes)
Fragment size for partition 'a' (bytes)
Fragment size for partition 'd' (bytes)
Fragment size for partition 'e' (bytes)
Fragment size for partition 'f (bytes)
Fragment size for partition 'g' (bytes)
Fragment size for partition 'h' (bytes)
Size of partition 'a' in sectors
Size of partition 'b' in sectors
Size of partition 'c' in sectors
Size of partition 'd' in sectors
Size of partition 'e' in sectors
Size of partition 'f in sectors
Size of partition 'g' in sectors
Size of partition 'h' in sectors
Sector size in bytes
Type of disk (e.g. removable, winchester)

Disktab entries may be automatically generated with the diskpart program.
FILES

I etcldisktab
SEE ALSO

newfs(S), diskpart(8)

BUGS
This file shouldn't exist, the information should be stored on each disk pack.

4th Berkeley Distribution

2 March 1983

1

DUMP (5)

UNIX Programmer's Manual

DUMP

(5)

NAME

dump, dumpdates - incremental dump format
SYNOPSIS

#include
#include
#include

< sysltypes.h>
< sys/iilode.h>
< dumprestor.h>

DESCRIPTION

Tapes used by dump and res/ore(8) contain:
a header record
two groups of bit map records
a group of r~(vrds describing directories
a group of records describing files
The format of the header record and of the first record of each description as given in the
include file < dumpreslOr,h> is:
#define NTREC
#define MLEN
#define MSIZ

10
16
4096

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

1
TS _TAPE
2
TSJNODE
3
TS_BITS
4
TS_ADDR
5
TS_END
TS_CLRI
6
(int) 60011
MAGIC
CHECKSUM (int) 84446

struct

spcl I
int
time_t
time_t
int
daddr _t
ino_t
int
int
struct
int
char

c_type:
c_date:
c_ddate:
c_volume:
c_tapea:
c_inumber:
c_magic:
c_checksum:
dinode
c_dinode:
l count:
c=adddBSIZEL

idates (
char
char
time_t

id_name [I 6):
idJncno:
id_ddute:

} spcl~
struct

k
#define DUMPOUTFMT

II(~h-16s

%c %s"

#define DUMPINFMT III1.I16s %c % [A\nl\n"

4th Berkeley Distribution

/* for printf */
/* name. incno. ctime (date) */
/* inverse for scanf */

18 July 1983

DUMP (5)

UNIX Programmer's Manual

DUMP (5)

NTREC is the number of 1024 byte records in a physical tape block. MLEN is the number of
bits in a bit map word. MSIZ is the number of bit map words.
The TS_ entries are used in the c_type field to indicate what sort of header this is. The types
and their meanings are as follows:
TS TAPE
TS INODE

Tape volume label
A file or directory follows. The c_dillocle field is a copy of the disk inode and
contains bits telling what sort of file this is.
TS BITS
A bit map follows. This bit map has a one bit for each inode that was dumped.
TS ADDR
A subrecord of a file description. See (:...addr below.
TS END
End of tape record.
TS CLRI
A bit map follows. This bit map contains a zero bit for all inodes that were
empty on the file system when dumped.
All header records have this number in c_magic.
MAGIC
CHECKSUM Header records checksum to this value.
The fields of the header structure are as follows:
c_type
c_date
c_ddate
c_ volume
c_tapea
cjnumber
c_magic
c_checksum
c_dinode
c_count
c_addr

The type of the header.
The date the dump was taken.
The date the file system was dumped from.
The current volume number of the dump.
The current number of this (1 024-byte) record.
The number of the inode being dumped if this is of type TSJNODE.
This contains the value MAGIC above. truncated as needed.
This contains whatever value is needed to make the record sum to CHECKSUM.
This is a copy of the inode as it appears on the file system: see .(s(S>'
The count of characters in c addr.
An array of characters desc;ibing the blocks of the dumped file. A character is
zero if the block associated with that character was not present on the file system. otherwise the character is non-zero. If the block was not present on the file
system. no block was dumped: the block will be restored as a hole in the file. If
there is not sufficient space in this record to describe all of the blocks in a file.
TS_ADDR records will be scattered through the file. each one picking up where
the last left otT.

Each volume except the last ends with a tape mark (read as an end of file>. The last volume
ends with a TS_END record and then the tapemark.
The structure idates describes an entry in the file letcldumpdates where dump history is kept.
The fields of the structure are:
id_name
idjncno
id_ddate

The dumped filesystem is '/dev/ id "am'.
The level number of the dump tape: see dump(SL
The date of the incremental dump in system format see fYpes(S).

FILES

/ etc/ dumpdates
SEE ALSO

dump(S), restore(S), fs(5), types(S)

4th Berkeley Distribution

18 July 1983

2

FS (5)

UNIX Programmer's Manual

FS (5)

NAME

fs, inode - format of file system volume
SYNOPSIS

#Include < sys/types.h >
#lnclude < sys/fs.h >
#lnclude < sys/lnode.h >
DESCRIPTION

Every file system storage volume (disk, nine-track tape, for instance> has a common format for
certain vital information. Every such volume is divided into a certain number of blocks. The
block size is a parameter of the file system. Sectors 0 to 15 on a file system are used to contain
primary and secondary bootstrapping programs.
The actual file system begins at sector 16 with the super block. The layout of the super block as
defined by the include file < sys/js.h > is:
#defineFS MAGIC
Ox0119S4
struct fs
struct fs -fsJink;
/- linked list of file systems -/
struct fs -fs rlink;
/used for incore super blocks -/
daddr t fs sbllmo;
/- addr of super-block in filesys -/
daddr_t fs_cblkno;
/- offset of cyl-block in filesys -/
daddr_t fsjblkno;
/- offset of inode-blocks in filesys -/
daddr_t fs_dblkno;
/- offset of first data after cg -/
long
fs_cgoffset;
/- cylinder group offset in cylinder -/
long
fs_cgmask;
/- used to calc mod fs ntrak -/
time t fs time;
/- last time written -/long - fs=size;
/- number of blocks in fs -/
long
fs_dsize;
/- number of data blocks in fs -/
long
fs_ncg;
/- number of cylinder groups -/
long
fs_bsize;
/- size of basic blocks in fs -/
long
fs_fsize;
/- size of frag blocks in fs -/
long
fs_frag;
/- number of frags in a block in fs -/
/- these are configuration parameters -/
long
fs_minfree;
/- minimum percentage of free blocks -/
long
fs_rotdelay;
/- num of ms for optimal next block -/
long
fs_rps;
/- disk revolutions per second -/
/- these fields can be computed from the others -/
long
fs_bmask;
/- "blkoff" calc of blk offsets -/
long
fs_fmask;
/- "fragoif" calc of frag offsets -/
long
fs_bshift;
/- "lblkno" calc of logical blkno -/
long
fs_fshift;
/- "numfrags" calc number of frags ./
/. these are configuration parameters -/
long
fs_maxcontig;
/- max number of contiguous blks -/
long
fs_maxbpg;
/- max number of blks per cyl group -/
/- these fields can be computed from the others -/
long
fs_fragshift;
/- block to frag shift ./
long
fs fsbtodb;
/- fsbtodb and dbtofsb shift constant -/
long
fs=sbsize;
/- actual size of super block ./
long
fs_csmask;
/- csum block offset -/
long
fs_csshift;
/- csum block number -/
long
fs_nindir;
/- value of NINDIR -/
long
fsjnopb;
/- value of INOPB -/
long
fs_nspf;
/- value of NSPF -/

r

4th Berkeley Distribution

18 July 1983

1

FS (5)

UNIX Programmer's Manual

FS (5)

long
fs_sparecon(6);
/- reserved for future constants -/
/- sizes determined by number of cylinder groups and their sizes -/
daddr_t fs _csaddr;
/- blk addr of cyl arp summary area -/
long
fs_cssize;
/- size of cyl grp summary area -/
long
fs_cgsize;
/- cylinder group size -/
/- these fields should be derived from the hardware -/
long
fs_ntrak;
/- tracks per cylinder -/
long
fs_nsect;
/- sectors per track -/
long
fs_spc;
/- sectors per cylinder -/
/- this comes from the disk driver partitioning -/
long
fs_neyl;
/- cylinders in file system -/
/- these fields can be computed from the others -/
long
fs_cpg;
/- cylinders per group -/
long
fsJpg;
/- inodes per group -/
long
fs_fpg;
/- blocks per group" fs_frag -/
/- this data must be re-computed after crashes -/
struct csum fs_cstota1;/- cylinder summary information -/
/- these fields are cleared at mount time -/
char
fs_fmod;
/- super block modified Oag -/
char
fs_clean;
/- file system is clean Oag -/
char
fs_ronly;
/- mounted read-only Oag -/
char
fsJIags;
/- currently unused Oag -/
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);I- list of fs cs info buffers -/
long
fs_cpc; /- cyl per cycle iD postbl -/
short fs-postbI[MAXCPGl [NRPOS1;/. head of blocks for each rotation -/
long
fs_magic;
/- magic number -/
u_char fs_rotbl[11;
/- list of blocks for each rotation -/
/- actually longer -/

};
Each disk drive contains some number of file systems. A file system consists of a number of
cylinder groups. Each cylinder group has inodes and data.
A file system is described by its super-block, which in tum describes the cylinder groups. The
super-block is critical data and is replicated in each cylinder group to protect against catastrophic
loss. This is done at file system creation time and the critical super-block data does not change,
so the copies need not be referenced further unless disaster strikes.
Addresses stored in inodes are capable of addressing fragments of 'blocks'. File system blocks
of at most size MAXBSIZE can be optionally broken into 2, 4, or 8 pieces, each of which is
addressable; these pieces may be DEV_BSIZE, or some multiple of a DEV_BSIZE unit.
Large files consist of exclusively large data blocks. To avoid undue wasted disk space, the last
data block of a small file is allocated as only as many fragments of a large block as are necessary. The file system format retains only a single pointer to such a fragment, which is a piece
of a single large block that has been divided. The size of such a fragment is determinable from
information in the inode, using the "blksize(fs, ip, Ibn)" macro.
The file system records space availability at the fragment level; to determine block availability,
aligned fragments are examined.

4th Berkeley Distribution

18 July 1983

2

FS (5)

UNIX Programmer's Manual

FS (5)

The root inode is the root of the file system. Inode 0 can't be usedJor normal purposes and
historically bad blocks were linked to inode 1, thus the root inode is 2 (inode 1 is no longer
used for this purpose, however numerous dump tapes make this assumption, so we are stuck
with it). The lost+found directory is given the next available inode when it is initially created
by mlifs.
fs_mirifree gives the minimum acceptable percentage of file system blocks which may be free. If

the freelist drops below this level only the super-user may continue to allocate blocks. This may
be set to 0 if no reserve of free blocks is deemed necessary, however severe performance
degradations will be observed if the file system is run at greater than 90% full; thus the default
value of fs_mirifree is 10%.
Empirically the best trade-off between block fragmentation and overall disk utilization at a loading of 90% comes with a fragmentation of 4, thus the default fragment size is a fourth of the
block size.
Cylinder group related limits: Each cylinder keeps track of the availability of blocks at different
rotational positions, so that sequential blocks can be laid out with minimum rotational latency.
NRPOS is the number of rotational positions which are distinguished. With NRPOS 8 the resolution of the summary information is 2ms for a typical 3600 rpm drive.
fs_rotdelay gives the minimum number of milliseconds to initiate another disk transfer on the

same cylinder. It is used in determining the rotationally optimal layout for disk blocks within a
file; the default value for fs_rotdelay is 2ms.
Each file system has a statically allocated number of inodes. An inode is allocated for each
NBPI bytes of disk space. The inode allocation strategy is extremely conservative.
MAXIPG bounds the number of inodes per cylinder group, and is needed only to keep the
structure simpler by having the only a single variable size element (the free bit map).
N .B.: MAXIPG must be a multiple of INOPB(fs).
MINBSIZE is the smallest allowable block size. With a MINBSIZE of 4096 it is possible to
create files of size 2 32 with only two levels of indirection. MINBSIZE must be big enough to
hold a cylinder group block, thus changes to (struct cg) must keep its size within MINBSIZE.
MAXCPG is limited only to dimension an array in (struct cg); it can be made larger as long as
that structure's size remains within the bounds dictated by MINBSIZE. Note that super blocks
are never more than size SBSIZE.
A

The path name on which the file system is mounted is maintained in fsJsmnt. MAXMNTLEN
defines the amount of space allocated in the super block for this name. The limit on the
amount of summary information per file system is defined by MAXCSBUFS. It is currently
parameterized for a maximum of two million cylinders.
Per cylinder group information is summarized in blocks allocated from the first cylinder group's
data blocks. These blocks are read in from fs_csaddr (size js_cssize) in addition to the super
block.
N.B.: size of (struct csum) must be a power of two in order for the "fs_cs" macro to work.
Super block jor a file system: MAXBPC bounds the size of the rotational layout tables and is limited by the fact that the super block is of size SBSIZE. The size of these tables is Inversely
proportional to the block size of the file system. The size of the tables is increased when sector
sizes are not powers of two, as this increases the number of cylinders included before the rotational pattern repeats (fs_cpc). The size of the rotational layout tables is derived from the
number of bytes remaining in (struct fs).

MAXBPG bounds the number of blocks of data per cylinder group, and is limited by the fact
that cylinder groups are at most one block. The size of the free block table is derived from the
size of blocks and the number of remaining bytes in the cylinder group structure (struct cg).

4th Berkeley Distribution

18 July 1983

3

FS (5)

UNIX Programmer's Manual

FS (5)

Inode: The inode is the focus of all file activity in the UNIX file system. There· is a unique
inode allocated for each active file, each current directory, each mounted-on file, text file, and
the root. An inode is 'named' by its device/i-number pair. For further information, see the
include file < syslinode. h > .

4th Berkeley Distribution

18 July 1983

4

FSTAD (5)

UNIX Programmer's Manual

FSTAD (5)

NAME

fstab - static information about the filesystems
SYNOPSIS

#lnclude

< fstab.h >

DESCRIPTION

The file letc/fstab contains descriptive information about the various file systems. letc/fstab is
only read by programs, and not written; it is the duty of the system administrator to properly
create and maintain this file. The order of records in letc/fstab is important because fsck, mount,
and umount sequentially iterate through letc/fstab doing their thing.
The special file name is the block special file name, and not the character special file name. If a
program needs the character special file name, the program must create it by appending a "r"
after the last "I" in the special file name.
If fs_type is "rw" or "ro" then the file system whose name is given in the fsJile field is normally mounted read-write or read-only on the specified special file. If fs_type is "rq", then the
file system is normally mounted read-write with disk quotas enabled. The IsJreq field is used
for these file systems by the dump(S) command to determine which file systems need to be
dumped. The fsJKlssno field is used by the fsck(S) program to determine the order in which
file system checks are done at reboot time. The root file system should be specified with a
fsyassno of 1, and other file systems should have larger numbers. File systems within a drive
should have distinct numbers, but file systems on different drives can be checked on the same
pass to utilize parallelism available in the hardware.
If Is_type is "sw" then the special file is made available as a piece of swap space by the
swapon(S) command at the end of the system reboot procedure. The fields other than Is_spec
and Is_type are not used in this case.
If Is_type is "rq" then at boot time the file system is automatically processed by the quotacheck(S) command and disk quotas are then enabled with quotaon (S). File system quotas are
maintained in a file "quotas", which is located at the root of the associated file system.

IC Is_type is specified as "xx" the entry is ignored. This is useful to show disk partitions which
are currently not used.
"rw"
#define FSTAB RW
I- read-write device -I
#defineFSTAD- RO
"ro"
I- read-only device -I
#defineFSTAB:RQ
"rq"
I- read-write with quotas -I
#define FST AB SW
"sw"
I- swap device -I
#define FST AD:XX
"xx"
I- ignore totally -I
struct fstab {
char -fs_spec; /- block special device name -I
char -fs_file; /- file system path prefix -/
char -fs_type; I- rw,ro,sw or xx -/
. int fs_freq;
I- dump frequency, in days -I
int fSJ)assno; I- pass number on parallel dump -I

};
The proper way to read records from letc/fstab is to use the routines getfsentO, getfsspecO,
getfstype 0, and getfsfile 0 .
FILES

letc/fstab

4th Berkeley Distribution

26 June 19S3

1

FSTAB (S)

UNIX Programmer's Manual

FSTAB(S)

SEE ALSO

getfsent(3X)

4th Berkeley Distribution

26 June 1983

2

GETIYTAB (5)

UNIX Programmer's Manual

GETIYTAB ( 5 )

NAME

gettytab - terminal configuration data base
SYNOPSIS
letc/gettytab
DESCRIPTION
Gettytab is a simplified version of the termcap(S) data base used to describe terminal lines. The
initial terminal login process getty(S) accesses the gettytab file each time it starts, allowing
simpler reconfiguration of terminal characteristics. Each entry in the data base is used to
describe one class of terminals.

There is a default terminal class, default, that is used to set global defaults for all other classes.
(That is, the default entry is read, then the entry for the class required is used to override particular settings.)
CAP ABILITIES
Refer to termcap(S) for a description of the file layout. The default column below lists defaults
obtained if there is no entry in the table obtained, nor one in the special default table.

Name
ap
bd
bk
cb
cd
ce
ck
cl
co
ds
ec
ep
er
et
ev
fO
f1

1'2
fd

11
hc
he
hn
ht
ig
im
in
is
kl
Ic
1m
In
10
nd

Type
bool
num
str
bool
num
bool
bool
str
bool
str
bool
bool
str
str
str
num
num
num
num
str
bool
str
str
boo I
bool
str
str
num
str
boo I
str
str
str
num

Default
false
0
0377
false
0
false
false

NULL
false
Ay
false
false
A?
AD

NULL
unused
unused
unused
0
AO
false

NULL
hostname
false
false

NULL

AC
unused
AU
false
login:
AV
Ibin/login
0

4th Berkeley Distribution

Description
terminal uses any parity
backspace delay
alternate end of line character (input break)
use crt backspace mode
carriage-return delay
use crt erase algorithm
use crt kill algorithm
screen clear sequence
console - add \n after login prompt
delayed suspend character
leave echo OFF
terminal uses even parity
erase character
end of text (EOF) character
initial enviroment
tty mode flags to write messages
tty mode flags to read login name
tty mode flags to leave terminal as
form-feed (vertical motion) delay
output flush character
do NOT hangup line on last close
hostname editing string
hostname
terminal has real tabs
ignore garbage characters in login name
initial (banner) message
interrupt character
input speed
kill character
terminal has lower case
login prompt
"literal next" character
program to exec when name obtained
newline (line-feed) delay

18 July 1983

1

GEITYTAB(S)

nl
nx
op
os
pc
pe
ps
qu
rp
rw
sp
su
tc
to
tt
ub
uc
we
xc
xf
xn

bool
str
bool
num
str
bool
bool
str
str
bool
num
str
str
num
str
bool
bool
str
bool
str
str

UNIX Programmer's Manual

false
default
false
unused

GETTYT AB ( 5)

terminal has (or might have) a newline character
next table (for auto speed selection)
terminal uses odd parity
output speed
pad character
use printer (hard copy) erase algorithm
line connected to a MICOM port selector
quit character
line retype character
do NOT use raw for input, use cbreak
line speed (input and output)
suspend character
table continuation
timeout (seconds)
.
terminal type (for enviroment)
do unbuffered output (of prompts etc)
terminal is known upper case· only
word erase character
do NOT echo control chars as "X
XOFF (stop output) character
XON (start output) character

\0
false
false
"\
lOR
false
unused
"Z

.none

o

NULL
false
false
lOW
false
"S
"Q

If no line speed is specified, speed will not be altered from that which prevails when getty is
entered. Specifying an input or output speed will override line speed for stated direction only.
Terminal modes to be used for the output of the message, for input of the login name, and to
leave the terminal set as upon completion, are derived from the boolean fiags specified. If the
derivation should prove inadequate, any (or all) of these three may be overriden with one of
the ro, fi, or fl numeric specifications, which can be used to specify (usually in octal, with a
leading 'O') the exact values of the fiags. Local (new tty) nags are set in the top 16 bits of this
(32 bit) value.
Should getty receive a null character (presumed to indicate a line break) it will restart using the
table indicated by the nx entry. If there is none, it will re-use its original table.
Delays are specified in milliseconds, the nearest possible delay available in the tty driver will be
used. Should greater certainty be desired, delays with values 0, 1, 2, and 3 are interpreted as
choosing that particular delay algorithm from the driver.
Theel screen clear string may be preceded by a (decimal) number of milliseconds of delay
required (a la termcap). This delay is simulated by repeated use of the pad character pc.
The initial message. and login message, 1m and 1m may include the character sequence 'leb to
obtains a single '%' character,> The hostname is normally obtained
obtain the hostname.
from the system, but may be set by the hn table entry. In either case it may be edited with be.
The he string is a sequence of characters, each character that is neither '@' nor '#' is copied
into the final hostname. A '@' in the he string, causes one character from the real hostname
to be copied to the final hostname. A' #' in the be string, causes the next character of the real
hostname to be skipped. Surplus'@' and '#' characters are ignored.
When getty execs the login process, given in the 10 string (usually "/bin/login"), it will have set
the enviroment to include the terminal type, as indicated by the tt string (if it exists). The ev
string, can be used to enter additional data into the environment. It is a list of comma
separated strings, each of which will presumably be of the form name-value.
If a non;.zero timeout is specified, with to, then getty will exit within the indicated number of
seconds, either having received a login name and passed control to login, or having received an

<"''Ie

4th Berkeley Distribution

18 July 1983

2

GETIYTAB (S)

UNIX Programmer's Manual

GETIYTAB ( S)

alarm signal, and exited. This may be useful to hangup dial in lines.
Output from getty is even parity unless op is specified. Op may be specified with ap to allow
any parity on input, but generate odd parity output. Note: this only applies while getty is being
run, terminal driver limitations prevent a more complete implementation. Getty does not check
parity of input characters in RA W mode.
SEE ALSO

termcap(S), getty(8).

BUGS
Some ignorant peasants insist on changing the default special characters, so it is wise to always
specify (at least) the erase, kill, and interrupt characters in the default table. In all cases, '#'
or 'AH' typed in a login name will be treated as an erase character, and '@' will be treated as a
kill character.
The delay stuff is a real crock. Apart form its general lack of flexibility, some of the delay algorithms are not implemented. The terminal driver should support sane delay settings.
Currently login(1) stomps on the environment, so there is no point setting it in gettytab.
The he capability is stupid.
Termcap format is horrid, something more rational should have been chosen.

4th Berkeley Distribution

18 July 1983

3

GROUP (5)

UNIX Programmer's Manual

GROUP (5)

NAME

group - group file
DESCRIPTION

Group contains for each group the following information:
group name
encrypted password
numerical group ID
a comma separated list of all users allowed in the group
This is an ASCII file. The fields are separated by colons; Each group is separated from the next
by a new-line. If the password field is null, no password is demanded.
This file resides in directory letc. Because of the encrypted passwords, it can and does have
general read permiSSion and can be used, for example, to map numerical group ID's to names.
FILES

letclgroup
SEE ALSO

setgroups(2), initgroups(3X), crypt(3), passwd(l), passwd(S)

BUGS
The passwd(l) command won't change the passwords.

7th Edition

IS January 1983

1

HOSTS (5)

UNIX Programmer's Manual

HOSTS (5)

NAME

hosts - host name data base
DESCRIPTION

The hosts file contains information regarding the known hosts on the DARPA Internet. For
each host a single line should be present with the following information:
official host name
Internet address
aliases
Items are separated by any number of blanks and/or tab characters. A "#" indicates the
beginning 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 host data base maintained at
the Network Information Control Center (NIC), though local changes may be required to bring
it up to date regarding unofficial aliases and/or unknown hosts.
Network addresses are specified in the conventional "." notation using the ineLaddrO routine
from the Internet address manipulation library, inet(3N). Host names may contain any printable character other than a field delimiter, newline, or comment character.
FILES

/etc/hosts
SEE ALSO

gethosten t (3 N)

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

7th Edition

15 January 1983

1

LDA (5)

UNIX Pl'Ogr:illlmcr's Manllal

LDA (5)

NAME

Ida

absululC load format

DESCi~1 :)TION

'J'l1\:' (()\Iowing i.; a dc:;criptioll of the ··.Ida" objcl.'l t'unn,1t: Typkal record:
By le I

<)

low 1",11' or Nhytes
high half or Nhytes

low half' of load pnint
high half or load point

first data byte
last da(~1 byte of re(;'ord

Nbyte+ 1 <) Cllc(;kslItn
Notes: Nhytes -.- The lotal IIlllllher of hYles in the record NOT indl.lding the checksulll hyte.
Clh.'CksullI .... \\,11\'11 ;lddcd to Ilk' IlIod})(, ~1I111 or all or the hytes ill the I\.'conl will n.'sillt ill a l.el"O
rl",l lit. I :xl'clIti()1l .. \ddl\.'ss th'cord:

< mtab.h >

DESCRIPTION
Mtab resides in directory fete and contains a table of devices mounted by the mount command.
Umount removes entries.

The table is a series of mtab structures, as defined in < mtab.h > . Each entry contains the
null-padded name of the place where the special file is mounted, the null-padded name of the
special file, and a type field, one of those defined in . The special file has all its
directories stripped away~ that is, everything through the last ~/' is thrown away. The type field
indicates if the file system is mounted read-only, read-write, or read-write with disk quotas
enabled.
This table is present only so people can look at it. It does not matter to mount if there are
duplicated entries nor to umount if a name cannot be found.
FILES

letc/mtab
SEE ALSO
mount(8)

4th Berkeley Distribution

26 June 1983

NETWORKS ( 5 )

UNIX Programmer's Manual

NETWORKS ( 5 )

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 blanks and/or tab characters. A H#" 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 (NIC), though local changes may be
required to bring it up to date regarding unofficial aliases and/or unknown networks.
Network number may be specified in the conventional u. "·notation using the inet_networkO
routine from the Internet address manipulation library, inet(3N). Network names may contain
any printable character other than a field delimiter, newline, or comment character.
FILES

/etc/networks
SEE ALSO

getnetent(3N)
BUGS

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

4th Berkeley Distribution

15 January 1983

1

NEWSRC(5)

UNIX Programmer's Manual

NEWSRC(5)

NAIIE

newsrc - information file for readnews(l} and checknews{l)
DESCRIPTION

The .newsrc file contains the list of previously read articles and an optional
options line for readnews(l} and checknews{l}. Each newsgroup that articles
have been read from has a line of the form:

newsgroup: range
The ra.nge is a list of the articles read. It is basically a list of no.'s separated by
commas with sequential no. 's collapsed with hyphens. For instance:

general.: 1-78.80.85-90
fainfo-epm: 1-7

net.news: 1
fa.info-vax! 1-6
If the: is replaced with an ! (as in info-vax above) the newsgroup is not subscribed to and will not be shown to the user.
An options line starts with the word options (left-justified). Then there are the
list of options just as they would be on the command line. For instance:
options -n all !fa.sf-lovers !fahuman-nets--i:'
options -c -r
A string of lines beginning with a space or tab after the initial options line will be
considered continuation lines.
1"IoI/.newsrc

Options and list of previously read articles

SEE ALSO

readnews{ 1), checknews{ 1)

4th Berkeley Distribution

28 July 1983

1

PASSWD(5)

UNIX

Programmer~s

Manual

PASSWD(S)

NAME

passwd - password file
DESCRIPTION

Passwd contains fot each user the following information:

name (login name~ contains no upper case)
encrypted password
numerical user ID
numerical group ID
user's real name, office., extension, home phone.
initial working directory
program to use as Shell
The name may contain '&', meaning insert the login name. This information is set by the
c/tfn (l) command and used by the ./ingerO) command.
This is an ASCII file. Each field within each user's entry is separated from the next by a colon.
Each user is separated from the next by a new-line. If the password field is null, no password is
demanded; if the Shell field is null, then Ibinlsh is used.
This file resides in directory letc. Because of the encrypted passwords, it can and does have
general read permission and can be used, for example, to map numerical user ID's to names.
Appropriate precautions must be taken to lock the file against changes if it is to be edited with a
text editor; vipw(S) does the necessary locking.
FILES

letc/passwd
SEE ALSO

getpwent(3), login(l)., crypt (3) , passwd(l), group(S), chfn(l), finger(I), vipw(S), adduser(S)

BUGS
A binary indexed file format should be available for fast access.
User information (name, office, etc,) should be stored elsewhere.

7th Edition

15 January 1983

1

PHONES(S)

UNIX Programmer's Manual

PHONES (S)

NAME

phones - remote host phone number data base
DESCRIPTION

The file letclphones contains the system-wide private phone numbers for the tip(1C) program.
This file is normally unreadable, and so may contain privileged information. The format of the
file is a series of lines of the form:  [\t1.. The system
name is one of those defined in the remote(S) file and the phone number is constructed from
[01234S6789--.%]. The "-" and "." characters are indicators to the auto call units to pause
and wait for a second dial tone (when going through an exchange). The "-" is required by
the DF02-AC and the U." is required by the BIZCOMP 1030.
Only one phone number per line is permitted. However, if more than one line in the file contains the same system name tip(1C) will attempt to dial each one in turn, until it establishes a
connection.
FILES

letclphones
SEE ALSO

tip(1C), remote(5)

4th Berkeley Distribution

15 January 1983

1

PLOT(5)

UNIX Programmer's Manual

PLOT(5)

NAME

plot - graphics interface
DESCRIPTION

Files of this format are produced by routines described in plot(3X), and are interpreted for various devices by commands described in plot(lO). A graphics file is a stream of plotting instructions. Each instruction consists of an ASCII letter usually followed by bytes of binary information. The instructions are executed in order. A point is designated by four bytes representing
the x and y values; each value is a signed integer. The last designated point in an I, m, D, or p
instruction becomes the 'current point' for the next instruction.
Each of the following descriptions begins with the name of the corresponding routine in
plot(3X).

m move: The next four bytes give a new current point.
D

cant: Draw a line from the current point to the point given by the next four bytes. See
plot(IO).

p point: Plot the point given by the next four bytes.

I

line: Draw a line· from the point given by the next four bytes to the point given by the following four bytes.

t

label: Place the following ASCII string so that its first character falls on the current point.
The string is terminated by a newline.

a arc: The first four bytes give the center, the next four give the starting point, and the last
four give the end point of a circular arc. The least significant coordinate of the end point is
used only to determine the quadrant. The arc is drawn counter-clockwise.

c circle: The first four bytes give the center of the circle, the next two the radius.
e erase: Start another frame of output.
f Iinemod: Take the following string, up to a newline, as the style for drawing further lines.
The styles are 'dotted,' 'solid,' 'longdashed,' 'shortdashed,' and 'dotdashed.' Effective only
in plot 4014 and plot lIeT.
s space: The next four bytes give the lower left comer of the plotting area~ the following four
give the upper right corner. The plot will be magnified or reduced to fit the device as
closely as possible.
Space settings that exactly fill the plotting area with unity scaling appear below for devices
supported by the filters of plot ( 1G) . The upper limit is just outside the plotting area. In
every case the plotting area is taken to be square; points outside may be displayable on devices whose face isn't square.
4014
space(O, 0, 3120, 3120);
ver
space (0, 0, 2048, 2048);
300, 300s space(O, 0, 4096, 4096);
450
space(O, 0, 4096, 4096);
SEE ALSO

plot(lG), plot(3X), graph(lG)

7th Edition

15 January 1983

1

PRINTCAP ( 5 )

UNIX Programmer's Manual

PRINTCAP ( 5 )

NAME

printcap - printer capability data base
SYNOPSIS

/ etc/printcap
DESCRIPTION

Printcap is a simplified version of the termcap(S) data base used to describe line printers. The
spooling system accesses the printcap file every time it is used, allowing dynamic addition and
deletion of printers. Each entry.in the data base is used to describe one printer. This data base
may not be substituted for, as is possible for termcap, because it may allow accounting to be
bypassed.
The default printer is normally Ip, though the environment variable PRINTER may be used to
override this. Each spooling utility supports an option, - P printer, to allow explicit naming of a
destination printer.
Refer to the 4.2BSD Line Printer Spooler Manual for a complete discussion on how setup the
database for a given printer.
CAPABILITIES

Refer to termcap for a description of the file layout.
Name Type
str
br
num
cf
str
str
elf
fc
num
ff
str
fo
bool
fs
num
gf
str
ic
bool
if
str
If
str
10
str
Ip
str
num
mx
nd
str
nf
str
of
str
pI
num
pw
num
px
num
py
num
rf
str
rm
str
rp
str
rs
bool
rw
bool
sb
bool
sc
bool
sd
str
sf
bool
sh
boo1
af

Default
NULL
none
NULL
NULL

Description
name of accounting file
if lp is a tty, set the baud rate (ioetl call)
dfplot data filter
tex data filter (DVI format)
if lp is a tty, clear flag bits (sgtty.h)
0
string to send for a form feed
"\r'
false
print a form feed when device is opened
like 'fc' but set bits
0
graph data filter (plot (3X) format)
NULL
driver supports (non standard) ioctl to indent printout
false
name of text filter which does accounting
NULL
" / dev I console" error logging file name
"lock"
name of lock file
"/dev/lp"
device name to open for output
1000
maximum file size (in BUFSIZ blocks), zero - unlimited
next directory for list of queues (unimplemented)
NULL
NULL
ditroff data filter (device independent trotO
name of output filtering program
NULL
page length (in lines)
66
page width (in characters)
132
page width in pixels (horizontal)
0
page length in pixels (vertical)
0
filter for printing FORTRAN style text files
NULL
NULL
machine name for remote printer
"lp"
remote printer name argument
false
restrict remote users to those with local accounts
false
open the printer device for reading and writing
false
short banner (one line only)
false
suppress mUltiple copies
"/usr Ispoolllpd" spool directory
false
suppress form feeds
false
suppress printing of burst page header

4th Berkeley Distribution

18 July 1983

1

PRINTCAP (S l

UNIX Propammer's Manual

PlUNTCAP ( S)

··statusn
NULL,

statuS' tie name
tl:ofr data, filter (ad phlltotypesettet)
str
sIt NULL
trailer strinl to' print, wileD queue empties
tr
raster image: fifter
str NULL
vf
xc
num 0
if Ip is a tty, clear loal mode bits (tty! (4»
xs
num 0:
like 'xc' but se't bits
Error messalcs sent to the cnsole have a carriap rctum IUld, a line feed' appended to them,
rather tUn' just a line feed.
If the local line printer driver supports: indentatiolly the daemon mUst understand bow to invoke

st

If

str

it.
SEE ALSO

termcap(Sl, Ipc{S), Ipd(S)" pac(S), Ipr(l), Ipq(l), Iprm(J)
4.2BSD Line Printer Spooler Manual

4th Berkeley Distribution

18 July 1983

2

PROTOCOLS ( 5 )

UNIX Programmer's Manual

PROTOCOLS (5)

NAME

protocols - protocol name data base
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:
official protocol name
protocol number
aliases
Items are separated by any number of blanks and/or tab characters. A "#" indicates the
beginning of a comment; characters up to the end of the line are not interpreted by routines
which search the file.
Protocol names may contain any printable character other than a field delimiter, newline, or
comment character.
FILES

/ etc/protocols
SEE ALSO

getprotoent (3N)

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

7th Edition

15 January 1983

1

ReSI:II.I·: ( 5 )

UN IX

Progr~lmm~r's

RCSFH J~( 5)

Manual

NAi\IE
restik . ·/(wmal of l{CS liIe
DESCHIPTION

'\11 lU.'S fik is all ASCII lik. Its cOlllents ;is d('seril·h.'d hy thl' grammar below. The lext is frc(, formal. i.t'., span's, ltlhs .111<.1 Jll'\\' lim's h.I\'c nu sit'l}jf'it,:;tIIcc cxcl'pl ill strings. Strings arc ctl<:1osl'd by
'(!' '. If a strillgcoHlains a 'VI', it IlII!:,! he uouhll'u.
Tlw )lIi.'ta S) ntax
optin'

l'IIc!(l';C lIo11tl'l'Ini-

n:lIs.
:

<;,,1111 in)

IH.'ad

ll:
t}*:
t.} *:
: : (num)}*:
{

?

;
:
{} :
{} :




(striug>

log
(ext



{

}*

(kUer)

AIBI .. ·IZlalhJ ... I'I.



Any printing AS(,lJdlafactcr CXl'('pt space,
t



..... --

,

.. -

"-

IdClllilit'fSarc case scnsitl\'c. Keywords arc in lowercase only. 'rhe sets of keywords and identifiers
may overlap.

Purdue Univt'rsity

6/29/8]

RCSI:II.(~( 5)

UN IX Progr:llnmcr's Manual

RCSFII.E(5)

The (dell,,) IHH.le<; t()fIn a tree. All nodes whosc llllllllwrs consist of'" sillgk p:tir (e.g., 2.\ 2.1. 1.3,
etc.) arc on the "trunk", (lild arc linkl'd thruugh the "Hext" lidel in order or decrew;illg llumbcrs.
The "head" fk'id ill tile ("dlllin) nodc points lo the he~\(.1 of' th;ll seqllence (i.e., contains tlie highest
pair).
All (dclt-:2) (e.g., 3.1.1.1, ?I.).), elc.) arc linked as
f()\\ows. All IHH.ks whu~;e III's! (211)-1 Ill!ll1hcr liclds (Ire itk'lltic;d arc linked tilrough Ihe "next" field
ill order
illcn..,(I'.;ing numhers. h)r C;tl'!1 Stich Sl.'l]lICIlCC, tile  node \\'llO~;C 11l1l1\her i') identical to tlw lirs! 2( 11-1) Ilumher field:;
til>.' del(

DESCRIPTION

Stab.h defines some values of the n_type field of the symbol table of a.out files. These are the
types for permanent symbols (i.e. not local labels, etc.) used by the old debugger sdb and the
Berkeley Pascal compiler pe(l). Symbol table entries can be produced by the .stabs assembler
directive. This allows one to specify a double-quote delimited name, a symbol type, one char
and one short of information about the symbol, and an unsigned long (usually an address). To
avoid having to produce an explicit label for the address field, the .stabd directive can be used
to implicitly address the current location. If no name is needed, symbol table entries can be
generated USing the .stabn directive. The loader promises to preserve the order of symbol table
entries produced by .stab directives. As described in a.out(S), an element of the symbol table
consists of the following structure:

/- Format of a symbol table entry.
-/
struct nlist {
union {
char -n_name; /- for use when in-core -/
long n_strx; /- index into file string table -/
} nun;
unsigned char n_type; /- type flag -/
char
n_other; /- unused -/
short
n_desc; I-see struct desc, below -/
unsigned n.....value;
/- address or offset or line -/
};
The low bits of the n_type field are used to place a symbol into at most one segment, according
to the following masks, defined in . A symbol can be in none of these segments by
having none of these segment bits set.

/- Simple values for n_type.
-/
#define N_UNDF OxO /#define N_ABS
Ox2 /#define N_TEXT Ox4 /#define N_DATA Ox6 /#define N_BSS
Ox8 /-

undefined -/
absolute -/
text -/
data-/
bss -/

#define N_EXT
01 /- external bit, or'ed in -/
The n_value field of a symbol is relocated by the linker, IdO) as an address within the appropriate segment. N_value fields of symbols not in any segment are unchanged by the linker. In
addition, the linker will discard certain symbols, according to rules of its own, unless the n_type
field has one of the following bits set:

/- Other permanent symbol table entries have some of the N STAB bits set.
- These are given in 
-/
#define N_STAB
OxeO/- if any of these bits set, don't discard -/

4th Berkeley Distribution

1 April 1983

1

UNIX Programmer's Manual

STAB (5)

STAB(5)

This allows up to 112 (7 • 16) symbol types, split between the various segments. Some of
these have already been claimed. The old symbolic debugger, sdb, uses the following n_type
values:
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define

N_GSYM Ox20
N_FNAME Ox22
N_FUN
Ox24
N_STSYM Ox26
N_LCSYM Ox28
N_RSYM Ox40
N_SLINE Ox44
N_SSYM Ox60
N_SO
Ox64
N_LSYM Ox80
N_SOL
Ox84
N_PSYM OxaO
N_ENTRY Oxa4
N_LBRAC pico
N_RBRAC/OxeO
N BCOM'M Oxe2
N ECOMMOxe4
N=ECOML Oxe8
N;;..LENG Oxfe

/.
/.
//.
//.
//.
/.
///.
/.
/.
/////-

global symbol: name"O,type,O ./
procedure name (n7 kludge): name"O ./
procedure: name"O,linenumber,address ./
static symbol: name"O,type,address ./
.lcomm symbol: name"O,type,address ./
register sym: name"O,type,register ./
src line: O"O,linenumber,address ./
structure elt: name"O,type,struct_offset -/
source file name: name"O,O,address -/
local sym: name"O,type,offset ./
#included file name: name"O,O,address ./
parameter: name"O,type,oifset -/
alternate entry: name,linenumber,address -/
left bracket: O"O,nesting level,address -/
right bracket: O"O,nesting level,address -/
begin common: name" -/
end common: name" -/
end common (local name): "address -/
second stab entry with length information -/

where the comments give sdb conventional use for .stabs and the n name, n other, n desc, and
n_value fields of the given n_type. Sdb uses the n_desc field to hold a type specifier it1 the form
used by the Portable C Compiler, cd 1), in which a base type is qualified in the following structure:
struct desc {
short q6:2,
q5:2,
q4:2,
q3:2,
q2:2,
q1:2,
basic:4;

};
There are four qualifications, with q1 the most significant and q6 the least significant:
none
1
pointer
2
function
3
array
The sixteen basic types are assigned as follows:
undefined
1
function argument .
2
character
3
short
4
int
5
long
6
float
7
double
8
structure
9
union

°
°

4th Berkeley Distribution

1 April 1983

2

STAB (5)

UNIX Programmer's Manual

10
11
12
13
14
1S

STAB(S)

enumeration
member of enumeration
unsigned character
unsigned short
unsigned int
unsigned long

The Berkeley Pascal compiler, pe(O, uses the following n_type value:
#defineN_PC Ox30 /. global pascal symbol: name"O,subtype,line ./
and uses the following subtypes to do type checking across separately compiled files:
1
source file name
2
included file name
3
global label
4
global constant
S
global type
6
global variable
7
global function
8
global procedure
9
external function
10
'external procedure
11
library variable
12
library routine
SEE ALSO

as(1), Id(1), dbx(1), a.out(S)

BUGS
Sdb assumes that a symbol of type N_GSYM with name name is located at address _name.

More basic types are needed.

4th Berkeley Distribution

1 April 1983

3

TAR(5)

UNIX Programmer's Manual

TAR (5)

NAME

tar - tape archive file format
DESCRIPTION
Tar, (the tape archive command) dumps several files into one, in a medium suitable for tran-

sportation.
A "tar tape" or file is a series of blocks. Each block is of size TBLOCK. A file on the tape is
represented by a header block which describes the file, followed by zero or more blocks which
give the contents of the file. At the end of the tape are two blocks filled with binary zeros, as
an end-of-file indicator.
The blocks are grouped for physical 110 operations. Each group of n blocks (where n is set by
the b keyletter on the tar(1) command line - default is 20 blocks} is written with a single system call; 9n nine-track tapes, the result of this write is a single tape record. The last group is
always written at the full size, so blocks after the two zero blocks contain random data. On
reading, the specified or default group size is used for the first read, but if that read returns less
than a full tape block, the reduced block size is used for further reads.
The header block looks like:
#define TBLOCK
#define NAMSIZ

512
100

union hblock {
char dummy [TBLOCK];
struct header {
char name[NAMSIZ];
char mode[8]~
char uid[8];
char gid [8];
char size [I 2] ;
char mtime[I2];
char chksum [8] ;
char linkflag;
char linkname [N AMSIZ];
} dbuf;

};
Name is a null-terminated string. The other fields are zero-filled octal numbers in ASCII. Each
field (of width w) contains w-2 digits, a space, and a null, except size and mtime, which do not
contain the trailing null. Name is the name of the file, as specified on the tar command line.
Files dumped because they were in a directory which was named in the command line have the
directory name as preilx and /filename as suffix. Mode is the file mode, with the top bit masked
off. Uid and gid are the user and group numbers which own the file. Size is the size of the file
in bytes. Links and symbolic links are dumped with this field specified as zero. Mtime is the
modification time of the file at the time it was dumped. Chksum is a decimal ASCII value
which represents the sum of all the bytes in the header block. When calculating the checksum,
the chksum field is treated as if it were all blanks. Lin/iflag is ASCII '0' if the file is "normal"
or a special file, ASCII '1' if it is an hard link, and ASCII '2' if it is a symbolic link. The name
linked-to, if any, is in linkname, with a trailing null. Unused fields of the header are binary
zeros (and are included in the checksum).
The first time a given i-node number is dumped, it is dumped as a regular file. The second and
subsequent times, it is dumped as a link instead. Upon retrieval, if a link entry is retrieved,
but not the file it was linked to, an error message is printed and the tape must be manually rescanned to retrieve the linked-to file.

7th Edition

15 January 1983

1

TAR(S)

UNIX Programmer's Manual

TAR (5)

The encoding of the header is designed to be portable atross machines.
SEE ALSO

tarO)

BUGS
Names or linknames longer than NAMSIZ produce error reports and cannot be dumped.

7th Edition

1S January 1983

2

TERMCAP(S)

UNIX Programmer's Manual

TERMCAP (5)

NAME

termcap - terminal capability data base
SYNOPSIS

letc/termcap
DESCRIPTION

Termcap is a data base describing terminals, used, e.g., by vi (1 ) and curses (3X) . Terminals are
described in termcap by giving a set of capabilities which they have, and by describing how
operations are performed. Padding requirements and initialization sequences are included in
termcap.
Entries in termcap consist of a number of ':' separated fields. The first entry for each terminal
gives the names which are known for the terminal, separated by 'I' characters. The first name is
always 2 characters long and is used by older version 6 systems which store the terminal type in
a 16 bit word in a systemwide data base. The second name given is the most common abbreviation for the terminal, and the last name given should be a long name fully identifying the terminal. The second name should contain no blanks; the last name may well contain blanks for
readability.
CAP ABILITIES

(P) indicates padding may be specified
(P*) indicates that padding may be based on no. lines affected
Name
ae
al
am
as
bc
bs
bt
bw
CC
cd
ce
ch
cl

cm
co
cr
cs
cv
da
dB
db
dC
dc
dF
dl
dm
dN
do
dT
ed

Type
str
str
bool
str
str
bool
str
bool
str
str
str
str
str
str
num
str
str
str
bool
num
bool
num
str
num
str
str
num
str
num
str

Pad? Description
(P)
(P*)
(P)

(P)

(P*)
(P)
(P)
(P*)
(P)
(P*)
(P)
(P)

(P*)
(P*)

3rd Berkeley Distribution

End alternate character set
Add new blank line
Terminal has automatic margins
Start alternate character set
Backspace if not AH
Terminal can backspace with AH
Back tab
Backspace wraps from column 0 to last column
Command character in prototype if terminal settable
Clear to end of display
Clear to end of line
Like cm but horizontal motion only, line stays same
Clear screen
Cursor motion
Number of columns in a line
Carriage return, (default AM)
Change scrolling region (vt100), like cm
Like ch but vertical only.
Display may be retained above
Number of millisec of bs delay needed
Display may be retained below
Number of millisec of cr delay needed
Delete character
Number of millisec of if delay needed
Delete line
Delete mode (enter)
Number of millisec of nl delay needed
Down one line
Number of millisec of tab delay needed
End delete mode

10 May 1980

1

TERMCAP(S)

ei
eo
ff
hc
hd
ho
hu
hz
ic
if
im
in
ip
is
kO-k9
kb
kd
ke
kh
kl
kn
ko
kr
ks
ku
10-19
Ii
II
ma
mi
ml
ms
mu
nc
nd
nl
ns
os
pc
pt
se
sf
sg
so
sr
ta
tc
te
ti
uc
ue
ug

str
str
str
bool
str
str
str
str
str
str
bool
booI
str
str
str
str
str
str
str
str
num
str
str
str
str
str
num
str
str
bool
str
booI
str
bool
str
str
bool
bool
str
bool
str
str
num
str
str
str
str
str
str
str
str
num

UNIX Programmer's Manual

TERMCAP(S)

End insert mode; give ":ei=-:'" if ic
Can erase overstrikes with a blank
(p.) Hardcopy terminal page eject (default "'L)
Hardcopy terminal
Half-line down (forward 112 linefeed)
Home cursor (if no em)
Half-line up (reverse 112 linefeed)
Hazeltine; can't print -'s
(P) Insert character
Name of file containing is
Insert mode (enter); give H:im-:" if ie
Insert mode distinguishes nulls on display
(p.) Jnsert pad after character inserted
Terminal initialization string
Sent by "other" function keys 0-9
Sent by backspace key
Sent by terminal down arrow key
Out of "keypad transmit" mode
Sent by home key
Sent by terminal left arrow key
Number of "other" keys
Termcap entries for other non-function keys
Sent by terminal right arrow key
Put terminal in "keypad transmit" mode
Sent by terminal up arrow key
Labels on "other" function keys
Number of lines on screen or page
Last line, first column (if no em)
Arrow key map, used by vi version 2 only
Safe to move while in insert mode
Memory lock on above cursor.
Safe to move while in standout and underline mode
Memory unlock (turn off memory lock).
No correctly working carriage return (DM2S00,H2000)
Non-destructive space (cursor right)
(p.) Newline character (default \0)
Terminal is a CRT but doesn't scroll.
Terminal overstrikes
Pad character (rather than null)
Ha!) hardware tabs (may need to be set with is)
End stand out mode
(P) Scroll forwards
Number of blank chars left by so or se
Begin stand out mode
(P) Scroll reverse (backwards)
(P) Tab (other than '"lor with padding)
Entry of similar terminal - must be last
String to end programs that use em
String to begin programs that use em
Underscore one char and move past it
End underscore mode
Number of blank chars left by us or ue

3rd Berkeley Distribution

10 May 1980

2

TERMCAP(S)

ul
up
us
vb
ve
vs
xb
xn
xr
xs
xt

bool
str
str
str
str
str
bool
bool
boo I
bool
bool

UNIX Programmer's Manual

TERMCAP (S)

Terminal underlines even though it doesn't overstrike
Upline (cursor up)
Start underscore mode
Visible bell (may not move cursor)
Sequence to end open/visual mode
Sequence to start open/visual mode
Beehive (fl =escape, f2=ctrl C)
A newline is ignored after a wrap (Concept)
Return acts like ce \r \n (Delta Data)
Standout not erased by writing over it (HP 264?)
Tabs are destructive, magic so char (Teleray 106I)

A Sample Entry
The following entry, which describes the Concept-100, is among the more complex entries in
the termcap file as of this writing. (This particular concept entry is outdated, and is used as an
example only.)
cllclOOlconceptlOO:is==\EU\Ef\E7\ES\E8\EI\ENH\EK\E\200\Eo&\200:\
:al==3.\E"'R:am:bs:cd= l6.\E"C:ce= l6\E"'S:cl = 2· . . L:cm =\Ea% + %+ :co#80:\
:dc== l6\E'" A:dl=31!<\E"'B:ei =\E\200:eo:im=\E"'P:in:ip== l6.:1i#24:mi:nd=\E=:\
:se=\Ed\Ee:so=\ED\EE:ta=8\t:ul:up=\E~:vb=\Ek\EK:xn:

Entries may continue onto multiple lines by giving a \ as the last character of a line, and that
empty fields may be included for readability (here between the last field on a line and the first
field on the next). Capabilities in termcap are of three types: Boolean capabilities which indicate
that the terminal has some particular feature, numeric capabilities giving the size of the terminal or the size of particular delays, and string capabilities, which give a sequence which can be
used to perform particuiar terminal operations.

Types of Capabilities
All capabilities have two letter codes. For instance, the fact that the Concept has '"automatic
margins" (i.e. an automatic return and linefeed when the end of a line is reached) is indicated
by the capability am. Hence the description of the Concept includes am. Numeric capabilities
are followed by the character 4#' and then the value. Thus co which indicates the number of
columns the terminal has gives the value 480' for the Concept.
Finally, string valued capabilities, such as ce (clear to end of line sequence) are given by the
two character code, an 4=', and then a string ending at the next following 4:'. A delay in milliseconds may appear after the 4=' in such a capability, and padding characters are supplied by
the editor after the remainder of the string is sent to provide this delay. The delay can be
either a integer, e.g. 420'. or an integer followed by an '.', i.e. 43.'. A 4.' indicates that the
padding required is proportional to the number of lines affected by the operation, and the
amount given is the per-affected-unit padding required. When a 4.' is specified, it is sometimes
useful to give a delay of the form 43.5' specify a delay per unit to tenths of milliseconds.
A number of escape sequences are provided in the string valued capabilities for easy encoding
of characters there. A \E maps to an ESCAPE character, AX maps to a control-x for any
appropriate x, and the sequences \n \r \t \b \f give a newline, return, tab, backspace and
formfeed. Finally, characters may be given as three octal digits after a \, and the characters
and \ may be given as \ and \ \. If it is necessary to place a : in a capability it must be escaped
in octal as \072. If it is necessary to place a null character in a string capability it must be
encoded as \200. The routines which deal with termcap use C strings, and strip the high bits of
the output very late so that a \200 comes out as a \000 would.
A

A

3rd Berkeley Distribution

10 May 1980

3

TERMCAP(S)

UNIX Programmer's Manual

TERMCAP(S)

Preparing Descriptions
We now outline how to prepare descriptions of terminals. The most effective way to prepare a
terminal description is by imitating the description of a similar terminal in termcap and to build
up a description gradually, using partial descriptions with ex to check that they are correct. Be
aware that a very unusual terminal may expose deficiencies in the ability of the termcap file to
describe it or bugs in ex. To easily test a new terminal description you can set the environment
variable TERMCAP to a path name of a file containing the description you are working on and
the editor will look there rather than in /etc/termcap. TERMCAP can also be set to the termcap
entry itself to avoid reading the file when starting up the editor. (This only works on version 7
systems.)
Basic capabilities
The number of columns on each line for the terminal is given by the co numeric capability. If
the terminal is a CRT, then the number of lines on the screen is given by the Ii capability. If
the terminal wraps around to the beginning of the next line when it reaches the right margin,
then it should have the am capability. If the terminal can clear its screen, then this is given by
the cl string capability. If the terminal can backspace, then it should have the bs capability,
unless a backspace is accomplished by a character other than "H (ugh) in which case you
should give this character as the be string capability. If it overstrikes (rather than clearing a
position when a character is struck over) then it should have the os capability.
A very important point here is that the local cursor motions encoded in lermcap are undefined
at the left and top edges of a CRT terminal. The editor will never attempt to backspace around
the left edge, nor will it attempt to go up locally off the top. The editor assumes that feeding
off the bottom of the screen will cause the screen to scroll up, and the am capability tells
whether the cursor sticks at the right edge of the screen. If the terminal has switch selectable
automatic margins, the termcap file usually assumes that this is on, i.e. am.
These capabilities suffice to describe hardcopy and "glass-tty" terminals. Thus the model 33
teletype is described as
t3133Itty33:co#72:os
while the Lear Siegler ADM - 3 is described as
clladm3/3~si adm3:am:bs:cI == "Z:li#24:co#80

Cursor addressing
Cursor addressing in the terminal is described by a em string capability, with printj(3S) like
escapes O/DX in it. These substitute to encodings of the current line or column position, while
other characters are passed through unchanged. If the em string is thought of as being a function, then its arguments are the line and then the column to which motion is desired, and the
D/O encodings have the following meanings:
as in print/, 0 origin
like %2d
like %3d
%.
like %c
% + x adds x to value, then %.
% > xy if value > x adds y, no output.
%r
reverses order of line and column, no output
%i
increments line/column (for 1 origin)
%%
gives a single %
%n
exclusive or row and column with 0140 (DM2S00)
%8
BCD (I6.(x/lO)) + (x%10), no output.
%D
Reverse coding (x-2.(x%16»), no output. (Delta Data).

%d
%2
%j

3rd Berkeley Distribution

10 May 1980

4

TERMCAP(S)

UNIX Programmer's Manual

TERMCAP (S)

Consider the HP264S, which, to get to row 3 and column 12, needs to be sent \E&aI2c03Y
padded for 6 milliseconds. Note that the order of the rows and columns is inverted here, and
that the row and column are printed as two digits. Thus its em capability is
"cm-6\E&%r%2c%2Y". The Microterm ACT·IV needs the current row and column sent preceded by a AT, with the row and column simply encoded in binary, Bcm==AT%.%.". Terminals
which use B%." need to be able to backspace the cursor (bs or be), and to move the cursor up
one line on the screen (up introduced below). This is necessary because it is not always safe to
transmit \t, \n AD and \r, as the system may change or discard them.
A final example is the LSI ADM-3a, which uses row and column offset by a blank character, thus
"cm-\E==%+ %+ ".
Cursor motions
If the terminal can move the cursor one position to the right, leaving the character at the
current position unchanged, then this sequence should be given as nd (non-destructive space).
If it can move the cursor up a line on the screen in the same column, this should be given as
up. If the terminal has no cursor addressing capability, but can home the cursor (to very upper
left corner of screen) then this can be given as ho; similarly a fast way of getting to the lower
left hand corner can be given as II; this may involve going up with up from the home position,
but the editor will never do this itself (unless II does) because it makes no assumption about
the effect of moving up from the home position.
Area clears
If the terminal can clear from the current position to the end of the line, leaving the cursor
where it is, this should be given as ceo If the terminal can clear from the current position to
the end of the display, then this should be given as cd. The editor only uses cd from the first
column of a line.
Insert/delete line
If the terminal can open a new blank line before the line where the cursor is, this should be
given as al; this is done only from the first position of a line. The cursor must then appear on
the newly blank line. If the terminal can delete the line which the cursor is on, then this
should be given as dl; this is done only from the first position on the line to be deleted. If the
terminal can scroll the screen backwards, then this can be given as sb, but just al suffices. If
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 let the editor understand that
deleting a line on the screen may bring non-blank lines up from below or that scrolling back
with sb may bring down non-blank lines.
Insert/delete character
There are two basic kinds of intelligent terminals with respect to insert/delete character which
can be described using tc/'mcap. The most common insert/delete character operations affect only
the characters on the current line and shift characters off the end of the line rigidly. Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make a distinction between typed
and untyped blanks on the screen, shifting upon an insert or delete only to an untyped blank on
the screen which is either eliminated, or expanded to two untyped blanks. You can find out
which kind of terminal you have by clearing the screen and then typing text separated by cursor
motions. Type Babc def' using local cursor motions (not spaces) between the "abc" and the
Bdef'. Then position the cursor before the Habc" 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". If your terminal does something different and unusual then you

3rd Berkeley Distribution

10 May 1980

S

TERMCAP(S)

UNIX Programmer's Manual

TERMCAP(S)

may have to modify the editor to get it to use the insert mode your terminal defines. We have
seen no terminals which have an insert mode not not falling into one of these two classes.
The editor can handle both terminals which have an insert mode, and terminals which send a
simple sequence to open a blank position on the current line. Give as im the sequence to get
into insert mode, or give it an empty value if your terminal uses a sequence to insert a blank
position. Give as ei the sequence to leave insert mode (give this, with an empty value also if
you gave im so). Now give as ie any sequence needed to be sent just before sending the character to be inserted. Most terminals with a true insert mode will not give ie, terminals which
send a sequence to open a screen position should give it here. (Insert mode is preferable to the
sequence to open a position on the screen if your terminal has both.) If post insert padding is
needed, give this as a number of milliseconds in ip (a string option). Any other sequence
which may need to be sent after an insert of a single character may also be given· in ip.

It is occasionally necessary to move around while in insert mode to delete characters on the
same line (e.g. if there is a tab after the insertion position). If your terminal allows motion
while in insert mode you can give the capability mi to speed up inserting in this case. Omitting
mi will affect only speed. Some terminals (notably Datamedia's) must not have mi because of
the way their insert mode works.
Finally, you can specify delete mode by giving dm and ed to enter and exit delete mode, and de
to delete a single character while in delete mode.
Highlighting, underlining, and visible bells
If your terminal has sequences to enter and exit standout mode these can be given as so and se
respectively. If there are several flavors of standout mode (such as inverse video, blinking, or
underlining - half bright is not usually an acceptable ~4standout" mode unless the terminal is
in inverse video mode constantly) the preferred mode is inverse video by itself. If the code to
change into or out of standout mode leaves one or even two blank spaces on the screc:n, as the
TVI 912 and Teleray 1061 do, then ug should be given to tell how many spaces are left.
Codes to begin underlining and end underlining can be given as us and ue respectively. If the
terminal has a code to underline the current character and move the cursor one space to the
right, such as the Microterm Mime, this can be given as ue. (If the underline code does not
move the cursor to the right, give the code followed by a nondestructive space.)
Many terminals, such as the HP 2621, automatically leave standout mode when they move to a
new line or the cursor is addressed. Programs using standout mode should exit standout mode
before moving the cursor or sending a newline.
If the terminal has a way of flashing the screen to indicate an error quietly (a bell replacement)
then this can be given as vb~ it must not move the cursor. If the terminal should be placed in a
different mode during open and visual modes of ex, this can be given as vs and ve, sent at the
start and end of lh~~~ illvJc:S respectively. These can be used to change, e.g., from a underline
to a block cursor and back.
If the terminal needs to be in a special mode when running a program that addresses the cursor, the codes to enter and exit this mode can be given as ti and teo This arises, for example,
from terminals like the Concept with more than one page of memory. If the terminal has only
memory relative cursor addressing and not screen relative cursor addressing, a one screen-sized
window must be fixed into the terminal for cursor addressing to work properly.
If your terminal correctly generates underlined characters (with no special codes needed) even
though it does not overstrike, then you should give the capability ul. If overstrikes are erasable
with a blank, then this should be indicated by giving eo.

Jrd Berkeley Distribution

10 May 1980

6

TERMCAP(S)

UNIX Programmer's Manual

TERMCAP(S)

Keypad
If the terminal has a keypad that transmits codes when the keys are pressed, this information
can be given. Note that it is not possible to handle terminals where the keypad only works in
local (this applies, for example, to the unshifted HP 2621 keys). If the keypad can be set to
transmit or not transmit, give these codes as ks and ke. Otherwise the keypad is assumed to
always transmit. The codes sent by the left arrow, right arrow, up arrow, down arrow, and
home keys can be given as kl, kr, ku, kd, and kb respectively. If there are function keys such
as fO, fl, ... , f9, the codes they send can be given as kO, kl, ... , k9. If these keys have labels
other than the default fO through f9, the labels can be given as 10, 11, ••• , 19. If there are other
keys that transmit the same code as the terminal expects for the corresponding function, such
as clear screen, the term cap 2 letter codes can be given in the ko capability, for example,
H:ko==cl,ll,sf,sb:". which says that the terminal has clear, home down, scroll down, and scroll
up keys that transmit the same thing as the cl, II, sf, and sb entries.
The rna entry is also used to indicate arrow keys on terminals which have single character arrow
keys. It is obsolete but still in use in version 2 of vi, which must be run on some minicomputers due to memory limitations. This field is redundant with kl, kr, ku, kd, and kh. It consists
of groups of two characters. In each group, the first character is what an arrow key sends, the
second character is the corresponding vi command. These commands are b for kl, j for kd, k
for ku, I for kr, and H for kb. For example, the mime would be :ma=AKj"ZkAXI: indicating
arrow keys left ("H), down ("K), up ("Z), and right ("X). (There is no home key on the
mime.)
Miscellaneous
If the terminal requires other than a null (zero) character as a pad, then this can be given as pc.
If tabs on the terminal require padding, or if the terminal uses a character other than "I to tab,
then this can be given as tao
Hazeltine terminals, which don't allow ~-, characters to be printed should indicate hz.
Datamedia terminals, which echo carriage-return linefeed for carriage return and then ignore a
following linefeed should indicate nco Early Concept terminals, which ignore a linefeed
immediately after an am wrap, should indicate xn. If an erase-eol is required to get rid of standout (instead of merely writing on top of it), xs should be given. Teleray terminals, where tabs
turn all characters moved over to blanks, should indicate xt. Other specific terminal problems
may be corrected by adding more capabilities of the form xx.
Other capabilities include is, an initialization string for the terminal, and if, the name of a file
containing long initialization strings. These strings are expected to properly clear and then set
the tabs on the terminal, if the terminal has settable tabs. If both are given, is will be printed
before if. This is useful where if is lusrllibltabsetlstd but is clears the tabs first.
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 tc can be given with the name of the similar terminal.
This capability must be last and the combined length of the two entries must not exceed 1024.
Since term lib routines search the entry from left to right, and since the tc capability is replaced
by the corresponding entry, the capabilities given at the left override the ones in the similar terminal. A capability can be canceled with xx@ where xx is the capability. For example, the
entry
hn 12621nl:ks@:ke@:tc==2621:
defines a 2621nl that does not have the ks or ke capabilities, and hence does not turn on the
function key labels when in visual mode. This is useful for different modes for a terminal, or
for different user preferences.

3rd Berkeley Distribution

10 May 1980·

7

TERMCAP(S)

UNIX Programmer's Manual

TERMCAP(5)

FILES

letc/termcap

file containing terminal descriptions

SEE ALSO

ex(I), curses(JX), termcap(3X}, tset(I}, viOl, ulO), more(I}
AUTHOR

William Joy
Mark Horton added underlining and keypad support
BUGS

Ex allows only 256 characters for string capabilities, and the routines in termcap(3X) do not
check for overflow of this buffer. The total length of a single entry (excluding only escaped
newlines) may not exceed 1024.
The ma,

VS.

and ve entries are specific to the vi program.

Not all programs support all entries. There are entries that are not supported by any program.

3rd Berkeley Distribution

10 May 1980

8

UNIX Programmer's Manual

TP(S)

TP(S)

NAME

tp - DEC/mag tape formats
DESCRIPTION
Tp dumps files to and extracts files from DECtape and magtape. The formats of these tapes are
the same except that magtapes have larger directories.

Block zero contains a copy of a stand-alone bootstrap program. See reboot(8).
Blocks 1 through 24 for DECtape (1 through 62 for magtape) contain a directory of the tape.
There are 192 (resp. 496) entries in the directory; 8 entries per block; 64 bytes per entry. Each
entry has the following format:
struct {
pathname[32];
char
unsigned short mode;
uid;
char
gid;
char
char
unusedl;
size[3];
char
long
modtime;
unsigned short tapeaddr;
unused2[I6];
char
unsigned short checksum;

};
The path name entry is the path name of the file when put on the tape. If the path name starts
with a zero word, the entry is empty. It is at most 32 bytes long and ends in a null byte.
Mode, uid, gid, size and time modified are the same as described under i-nodes (see file system
jS(5». The tape address is the tape block number of the start of the contents of the file.
Every file starts on a block boundary. The file occupies (size+ 511)/512 blocks of continuous
tape. The checksum entry has a value such that the sum of the 32 words of the directory entry
is zero.
Blocks above 25 (resp. 63) are available for file storage.

A fake entry has a size of zero.
SEE ALSO
fs(5), tpC

BUGS
The pathname, uid, gid, and size fields are too small.

7th Edition

IS January 1983

1

TTYS(S)

UNIX Programmer's Manual

TIYS(S)

NAME

ttys - terminal initialization data
DESCRIPTION

The ttys file is read by the init program and specifies which terminal special files are to have a
process created for them so that people can log in. There is one line in the ttys file per special
file.
The first character of a line in the ttys file is either '0' or '1'. If the first character on the line is
a '0', the in it program ignores that line. If the first character on the line is a '1', the init program creates a login process for that line. The second character on each line is used as an argument to getty (8) , which performs such tasks as baud-rate recognition, reading the login name,
and calling login. For normal lines, the character is '0'; other characters can be used, for example, with hard-wired terminals where speed recognition is unnecessary or which have special
characteristics. (Getty will have to be fixed in such cases.) The remainder of the line is the
terminal's entry in the device directory, Idev.
FILES

letclttys
SEE ALSO

gettytab(S), init(8), getty(8), 10gin(1)

7th Edition

18 July 1983

1

TIYTYPE(5)

UNIX Programmer's Manual

TTYTYPE(5)

NAME

ttytype - data base of terminal types by port
SYNOPSIS

1etcl ttytype
DESCRIPTION
Tty type is a database containing, for each tty port on the system, the kind of terminal that is

attached to it. There is one line per port, containing the terminal kind (as a name listed in
termcap (5», a space, and the name of the tty, minus 1dey I.
This information is read by tset(1) and by login (1) to initialize the TERM variable at login time.
SEE ALSO

tset (I), login (1)

BUGS
Some lines are merely known as "dialup" or "plugboard".

7th Edition

25 October 1979

1

TYPES (5)

TYPES (5)

UNIX Programmer's Manual

NAME

types - primitive system data types
SYNOPSIS

#include

< sys/types.h >

DESCRIPTION

The data types defined in the include file are used in UNIX system
types are accessible to user code:
/.
types.h
6.1
83/07/29./
/

code~

some data of these

.

.

• Basic system types and major/minor device constructing/busting macros .
/

/. major part of a device */
#define major(x) «int)«(unsigned)(x)> >8)&0377»
/* minor part of a device */
#define minor(x) «(jnt)«x)&0377»
/* make a device number */
#define makedev(x,y)
«dev_t)«(x) < <8) I (y»)
typedef
typedef
typedef
typedef
typedef

unsigned
unsigned
unsigned
unsigned
unsigned

#ifdef vax
typedef struct
typedef struct
int
} label_t;
#endif
typedef struct
typedef long
typedef char.
typedef U-'o"~
typedef long
typedef int
typedef int
typedef short
typedef int
typedef struct

char
short
int
long
short

u_char~
u_short~
ujnt~

uJong~

ushorti* sys III compat -/

-physadr { int r[I]~ } .physadr~
label t {
val(I4]~
_quad { long vaI[2]~ } quad;
daddr_t;
caddr_t;
ino_t:
swblk_t~

size_t;
time_t;
dev_t;
off t·
-'
fd_set { int fds_bitsUl; } fd_set;

The form dadd,_t is used for disk addresses except in an i-node on disk, see jS(S). Times are
encoded in seconds since 00:00:00 GMT, 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 /abett variables are used to save the
processor state while another process is running.

4th Berkeley Distribution

1 April 1983

1

TYPES (5)

UNIX Programmer's Manual

TYPES (5)

SEE ALSO

fs(5), time(3), Iseek(2), adb(1)

4th Berkeley Distribution

1 April 1983

2

UT~'lP(

UN 1X I)mg r; ~IlIlIlC(S

5)

~lanuc.d

UTMP(5)

NAME

ulmp. wlmp ., . login records
SY!';OI'SIS

1/ include

(UhUjl.h>

DFS('IHP nON

The IIll11/-, Hie r\:rords in 1(H"lll:ltioll about \\"ho hClIITentfy llSiug llw
or entries \\,ilh th~ (hlhm illg ~trlll.:tl\I\' decbr ..:d ill the inL'1utk 11k:

1*

~B/()5/22

ulmp,h 4.2

sy~tem.

The file

j~

a sequence

*-1

1*

* SlnK'lure ()futmp and

wtmp Ilk:...

*To

;\SSlIlIlillg

*1
Slflll:t !ltmp

the

1I11111!>t'r

X is ullwise.

t

char
char
char

1* tty n<1I11~! *1
1* us\'r ill *1
1* host H~Hn~,if remote */

ut,JillclXI:

XI:
IIl.JlOSl\ 1(,1:

lIt.Jl;\Illl'1

long'

1* timc

OJ)

*1

}:
This :-.trllctllrc f,in's the

1l;lIllC

or til\.' special

lile associated with the user's lcftninal. the user's login

n;IIlli..', :alld lhl..'lilllL' of theh'.",in in tlll'fill'lll of liolc(JC}.

The Irllllplikn.'I'prds all '1)~I,ill'-, ;Ill<.! IOgllllh, t\ null user 'IUlll\:' indkatcs a logout')!l lht' <1<';:-;tK'i

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Create Date                     : 2014:11:10 11:53:19-08:00
Modify Date                     : 2014:11:10 11:31:25-08:00
Metadata Date                   : 2014:11:10 11:31:25-08:00
Producer                        : Adobe Acrobat 9.55 Paper Capture Plug-in
Format                          : application/pdf
Document ID                     : uuid:1e6a77af-5e75-9848-9ae0-7ea32e1d5227
Instance ID                     : uuid:70b8a281-2308-514e-b062-5a6ece33c4cc
Page Layout                     : SinglePage
Page Mode                       : UseNone
Page Count                      : 658