This section describes functions in various libraries. For the
most part, each library is defined by a single C include file,
such as those 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, <draw.h> defines the contents
of library /$objtype/lib/libdraw.a, which may be abbreviated when
named to the loader as –ldraw. 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, draw, is
defined by <draw.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 needs <u.h>. There are a few other, less commonly used libraries
individual pages of this section.
The include file <u.h>, a prerequisite of several other include
files, declares the architecture–dependent and –independent types,
including: uchar, ushort, uint, and ulong, the unsigned integer
types; schar, the signed char type; vlong and uvlong, the signed
and unsigned very long integral types; Rune, the Unicode
character type; u8int, u16int, u32int, and u64int, the unsigned
integral types with specific widths; uintptr, the unsigned integral
type with the same width as a pointer; jmp_buf, the type of the
argument to setjmp and longjmp, plus macros that define the layout
of jmp_buf (see setjmp(2)); definitions of the bits in the
floating–point control register as used by getfcr(2); and the macros
va_arg and friends for accessing arguments of variadic functions
(identical to the macros defined in <stdarg.h> in ANSI C).|
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 namespace(4).
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 /–separated path elements
with the slashes corresponding to directories. A path element
must contain only printable characters (those outside the control
spaces of ASCII and Latin–1). A path element cannot contain a slash.
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
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 number of records, called directory entries.
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 translated into a more convenient,
addressable form called a Dir structure; dirstat, dirfstat, dirwstat,
and dirfwstat execute the appropriate translations (see
New files are made with create (see open(2)) and deleted with
remove(2). Directories may not directly be written; create, remove,
wstat, and fwstat alter them.
The operating system kernel records the file name used to access
each open file or directory. If the file is opened by a local
name (one that does not begin / or #), the system makes the stored
name absolute by prefixing the string associated with the current
directory. Similar lexical adjustments are made for path
names containing . (dot) or .. (dot–dot). By this process, the
system maintains a record of the route by which each file was
accessed. Although there is a possibility for error--the name is
not maintained after the file is opened, so removals and renamings
can confound it--this simple method usually permits the
system to return, via the fd2path(2) system call and related calls
such as getwd(2), a valid name that may be used to find a file
again. This is also the source of the names reported in the name
space listing of ns(1) or /dev/ns (see proc(3)).
Pipe(2) creates a connected pair of file descriptors, useful for
bidirectional local communication.
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. The
system allocates the numbers by selecting the lowest unused descriptor.
They are allocated dynamically; there is no
visible limit to the number of file descriptors a process may
have open. 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
Process execution and control
Each process has a unique integer process id; a set of open files,
indexed by file descriptor; and a current working directory (changed
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(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 events
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.
The thread library, defined in <thread.h>, provides support for
multiprocess programs. It includes a data structure called a Channel
that can be used to send messages between processes, and coroutine–like
threads, which enable multiple threads of control within a single
process. The threads within a process
are scheduled by the library, but there is no pre–emptive scheduling
within a process; thread switching occurs only at communication
or synchronization points.
Most programs using the thread library comprise multiple processes
communicating over channels, and within some processes, multiple
threads. Since Plan 9 I/O calls may block, a system call may block
all the threads in a process. Therefore, a program that shouldn't
block unexpectedly will use a process to serve the
I/O request, passing the result to the main processes over a channel
when the request completes. For examples of this design, see ioproc(2)
By calling rfork with the RFMEM bit set, a program may create
several independently executing processes sharing the same memory
(except for the stack segment, which is unique to each process).
Where possible according to the ANSI C standard, the main C library
works properly in multiprocess programs; malloc,
print, and the other routines use locks (see lock(2)) to synchronize
access to their data structures. The graphics library defined
in <draw.h> is also multi–process capable; details are in graphics(2).
In general, though, multiprocess programs should use some form
of synchronization to protect shared data.