intro - introduction to library functions
This section describes functions in various libraries. For the most part, each library is
defined by a single C include file, listed above, and a single archive file containing the
library proper. The name of the archive is /$objtype/lib/libx.a, where x is the base of
the include file name, stripped of a leading lib if present. For example, <libg.h>
defines the contents of library /$objtype/lib/libg.a, which may be abbreviated when named
to the loader as -lg. In practice, each include file contains a #pragma that directs the
loader to pick up the associated archive automatically, so it is rarely necessary to tell
the loader which libraries a program needs.
The library to which a function belongs is defined by the header file that defines its
interface. The `C library', libc, contains most of the basic subroutines such as strlen.
Declarations for all of these functions are in <libc.h>, which must be preceded by (needs)
an include of <u.h>. The graphics library, libg, the graphics library. is defined by
<libg.h>, which needs <libc.h> and <u.h>. The Buffered I/O library, libbio, is defined by
<bio.h>, which needs <libc.h> and <u.h>. The ANSI C Standard I/O library, libstdio, is
defined by <stdio.h>, which has no prerequisites. There are a few other, less commonly
used libraries defined on individual pages of this section.
The include file <u.h>, a prerequisite of several other include files, declares the archi-
tecture-dependent and -independent types, including: ushort, uchar, and ulong, the
unsigned integer types; schar, the signed char type; vlong, a very long integral type;
jmp_buf, the type of the argument to setjmp and longjmp, plus macros that define the lay-
out of jmp_buf (see setjmp(2)); definitions of the bits in the floating-point control reg-
ister as used by getfcr(2); and Length, a union giving different views of the 64-bit
length of a file, declared something like
long hlength; /* high order */
long length; /* low order */
Files are collected into a hierarchical organization called a file tree starting in a
directory called the root. File names, also called paths, consist of a number of /-sepa-
rated path elements with the slashes corresponding to directories. A path element must
contain only printable characters (those outside ASCII and Latin-1 control space) that
occupy no more than NAMELEN-1 bytes. A path element cannot contain a space or slash.
When a process presents a file name to Plan 9, it is evaluated by the following algorithm.
Start with a directory that depends on the first character of the path: means the root of
the main hierarchy, means the separate root of a kernel device's file tree (see Section
3), and anything else means the process's current working directory. Then for each path
element, look up the element in the directory, advance to that directory, do a possible
translation (see below), and repeat. The last step may yield a directory or regular file.
The collection of files reachable from the root is called the name space of a process.
A program can use bind or mount (see bind(2)) to say that whenever a specified file is
reached during evaluation, evaluation instead continues from a second specified file.
Also, the same system calls create union directories, which are concatenations of ordinary
directories that are searched sequentially until the desired element is found. Using bind
and mount to do name space adjustment affects only the current process group (see below).
Certain conventions about the layout of the name space should be preserved; see names-
Files are opened for input or output by open or create (see open(2)). These calls return
an integer called a file descriptor which identifies the file to subsequent I/O calls,
notably read(2) and write. File descriptors range from 0 to 99 in the current system.
The system allocates the numbers by selecting the lowest unused descriptor. They may be
reassigned using dup(2). File descriptors are indices into a kernel resident file
descriptor table. Each process has an associated file descriptor table. In some cases
(see rfork in fork(2)) a file descriptor table may be shared by several processes.
By convention, file descriptor 0 is the standard input, 1 is the standard output, and 2 is
the standard error output. With one exception, the operating system is unaware of these
conventions; it is permissible to close file 0, or even to replace it by a file open only
for writing, but many programs will be confused by such chicanery. The exception is that
the system prints messages about broken processes to file descriptor 2.
Files are normally read or written in sequential order. The I/O position in the file is
called the file offset and may be set arbitrarily using the seek(2) system call.
Directories may be opened and read much like regular files. They contain an integral num-
ber of records, called directory entries, of length DIRLEN (defined in <libc.h>). Each
entry is a machine-independent representation of the information about an existing file in
the directory, including the name, ownership, permission, access dates, and so on. The
entry corresponding to an arbitrary file can be retrieved by stat(2) or fstat; wstat and
fwstat write back entries, thus changing the properties of a file. An entry may be trans-
lated into a more convenient, addressable form called a Dir structure; dirstat, dirfstat,
dirwstat, and dirfwstat execute the appropriate translations (see stat(2)).
New files are made with create (in open(2)) and deleted with remove(2). Directories may
not directly be written; create, remove, wstat, and fwstat alter them.
Pipe(2) creates a connected pair of file descriptors, useful for bidirectional local com-
Process execution and control
A new process is created when an existing one calls rfork with the RFPROC bit set, usually
just by calling fork(2). The new (child) process starts out with copies of the address
space and most other attributes of the old (parent) process. In particular, the child
starts out running the same program as the parent; exec(2) will bring in a different one.
Each process has a unique integer process id; a set of open files, indexed by file
descriptor; and a current working directory (changed by chdir(2)).
Each process has a set of attributes -- memory, open files, name space, etc. -- that may
be shared or unique. Flags to rfork control the sharing of these attributes.
The memory of a process is divided into segments. Every program has at least a text
(instruction) and stack segment. Most also have an initialized data segment and a segment
of zero-filled data called bss. Processes may segattach(2) other segments for special
A process terminates by calling exits(2). A parent process may call wait (in exits(2)) to
wait for some child to terminate. A string of status information may be passed from exits
to wait. A process can go to sleep for a specified time by calling sleep(2).
There is a notification mechanism for telling a process about events such as address
faults, floating point faults, and messages from other processes. A process uses
notify(2) to register the function to be called (the notification handler) when such
Most of the functions in this section are available in the same form from Alef, with byte
substituted for char and uchar and int for long, and with adjustment for Alef having only
one floating-point type, called float, holding double-precision values. The main excep-
tions are that the long-valued functions such as strtoul have their final l changed to an
i to reflect the different type structure of the language; that the Bio library has a dif-
ferent organization (see Bio(2) for details); and for various reasons some things are
missing, notably ctype and the Stdio, IP, Layer, Lock, Mach, Ndb, and Panel libraries.
Also, there is no <u.h>; instead <alef.h> replaces both it and <libc.h>. The machine-
dependent definitions in Alef, which are only needed for getfcr(2) and relatives, are in
Within this manual, only explicit differences in the Alef libraries are documented, the
Alef functions are not all indexed, and the substitutions for <libc.h> as well as char,
uchar, etc. are assumed. The sources to the Alef libraries all live under
NOTE: Because the languages have different calling conventions, Alef programs cannot be
linked with C libraries.
nm(1), 2l(1), 2c(1)
Math functions in libc return special values when the function is undefined for the given
arguments or when the value is not representable (see nan(2)).
Some of the functions in libc are system calls and many others employ system calls in
their implementation. All system calls return integers, with -1 indicating that an error
occurred; errstr(2) recovers a string describing the error. Some user-level library func-
tions also use the errstr mechanism to report errors. Functions that may affect the value
of the error string are said to ``set errstr''; it is understood that the error string is
altered only if an error occurs.