intro - introduction to Plan 9
Plan 9 is a distributed computing environment assembled from separate
machines acting as terminals, CPU servers, and file servers. A user
works at a terminal, running a window system on a raster display. Some
windows are connected to CPU servers; the intent is that heavy comput‐
ing should be done in those windows but it is also possible to compute
on the terminal. A separate file server provides file storage for ter‐
minals and CPU servers alike.
In Plan 9, almost all objects look like files. The object retrieved by
a given name is determined by a mapping called the name space. A quick
tour of the standard name space is in namespace(4). Every program run‐
ning in Plan 9 belongs to a process group (see rfork in fork(2)), and
the name space for each process group can be independently customized.
A name space is hierarchically structured. A full file name (also
called a full path name) has the form
This represents an object in a tree of files: the tree has a root, rep‐
resented by the first the root has a child file named e1, which in turn
has child e2, and so on; the descendent en is the object represented by
the path name.
There are a number of Plan 9 services available, each of which provides
a tree of files. A name space is built by binding services (or sub‐
trees of services) to names in the name-space-so-far. Typically, a
user's home file server is bound to the root of the name space, and
other services are bound to conventionally named subdirectories. For
example, there is a service resident in the operating system for
accessing hardware devices and that is bound to /dev by convention.
Kernel services have names (outside the name space) that are a sign
followed by a single letter; for example, #c is conventionally bound to
Plan 9 has union directories: directories made of several directories
all bound to the same name. The directories making up a union direc‐
tory are ordered in a list. When the bindings are made (see bind(1)),
flags specify whether a newly bound member goes at the head or the tail
of the list or completely replaces the list. To look up a name in a
union directory, each member directory is searched in list order until
the name is found. A bind flag specifies whether file creation is
allowed in a member directory: a file created in the union directory
goes in the first member directory in list order that allows creation,
The glue that holds Plan 9 together is a network protocol called 9P,
described in section 5 of this manual. All Plan 9 servers read and
respond to 9P requests to navigate through a file tree and to perform
operations such as reading and writing files within the tree.
When a terminal is powered on or reset, it must be told the name of a
file server to boot from, the operating system kernel to boot, and a
user name and password. How this dialog proceeds is environment- and
machine-dependent. Once it is complete, the terminal loads a Plan 9
kernel, which sets some environment variables (see env(3)) and builds
an initial name space. See namespace(4), boot(8), and init(8) for
details, but some important aspects of the initial name space are:
· The environment variable $cputype is set to the name of the kernel's
CPU's architecture: one of mips, sparc, power (Power PC), 386 (386,
486, Pentium, ...) etc. The environment variable $objtype is ini‐
tially the same as $cputype.
· The environment variable $terminal is set to a description of the
machine running the kernel, such as generic pc. Sometimes the mid‐
dle word of $terminal encodes the file from which the kernel is
booted; e.g., alpha apc axp is bootstrapped from /alpha/9apc.
· The environment variable $service is set to terminal. (Other ways
of accessing Plan 9 may set $service to one of cpu, con, or rx.)
· The environment variable $user is set to the name of the user who
booted the terminal. The environment variable $home is set to that
user's home directory.
· /$cputype/bin and /rc/bin are unioned into /bin.
After booting, the terminal runs the command interpreter, rc(1), on
/usr/$user/lib/profile after moving to the user's home directory.
Here is a typical profile:
bind -a $home/bin/rc /bin
bind -a $home/bin/$cputype /bin
bind -c $home/tmp /tmp
font = /lib/font/bit/pelm/euro.9.font
prompt=('term% ' ' ')
exec rio -f $font
bind /mnt/term/dev/cons /dev/cons
bind /mnt/term/dev/consctl /dev/consctl
bind -a /mnt/term/mnt/wsys /dev
prompt=('cpu% ' ' ')
prompt=('cpu% ' ' ')
The first three lines replace /tmp with a tmp in the user's home direc‐
tory and union personal bin directories with /bin, to be searched after
the standard bin directories. The next starts the mail file system;
see mail(1). Then different things happen, depending on the $service
environment variable, such as running the window system rio(1) on a
To do heavy work such as compiling, the cpu(1) command connects a win‐
dow to a CPU server; the same environment variables are set (to differ‐
ent values) and the same profile is run. The initial directory is the
current directory in the terminal window where cpu was typed. The
value of $service will be cpu, so the second arm of the profile switch
is executed. The root of the terminal's name space is accessible
through /mnt/term, so the bind is a way of making the window system's
graphics interface (see draw(3)) available to programs running on the
CPU server. The news(1) command reports current Plan 9 affairs.
The third possible service type, con, is set when the CPU server is
called from a non-Plan-9 machine, such as through telnet (see con(1)).
Using Plan 9
The user commands of Plan 9 are reminiscent of those in Research Unix,
version 10. There are a number of differences, however.
The standard shell is rc(1), not the Bourne shell. The most noticeable
differences appear only when programming and macro processing.
The character-delete character is backspace, and the line-kill charac‐
ter is control-U; these cannot be changed.
DEL is the interrupt character: typing it sends an interrupt to pro‐
cesses running in that window. See keyboard(6) for instructions on
typing characters like DEL on the various keyboards.
If a program dies with something like an address error, it enters a
`Broken' state. It lingers, available for debugging with db(1) or
acid(1). Broke (see kill(1)) cleans up broken processes.
The standard editor is one of acme(1) or sam(1). There is a variant of
sam that permits running the file-manipulating part of sam on a non-
sam -r tcp!kremvax
For historical reasons, sam uses a tab stop setting of 8 spaces, while
the other editors and window systems use 4 spaces. These defaults can
be overridden by setting the value of the environment variable $tabstop
to the desired number of spaces per tab.
Machine names may be prefixed by the network name, here tcp; and net
for the system default.
Login connections and remote execution on non-Plan-9 machines are usu‐
ally done by saying, for example,
rx deepthought chess
9fs connects to file systems of remote systems (see srv(4)). For exam‐
sets things up so that the root of kremvax's file tree is visible
locally in /n/kremvax.
Faces(1) gives graphical notification of arriving mail.
The Plan 9 file server has an integrated backup facility. The command
binds to /n/dump a tree containing the daily backups on the file
server. The dump tree has years as top level file names, and month-day
as next level file names. For example, /n/dump/2000/0120 is the root
of the file system as it appeared at dump time on January 20, 2000. If
more than one dump is taken on the same day, dumps after the first have
an extra digit. To recover the version of this file as it was on June
cp /n/dump/1999/0615/sys/man/1/0intro .
or use yesterday(1).
This section for general publicly accessible commands.
Section (2) for library functions, including system calls.
Section (3) for kernel devices (accessed via bind(1)).
Section (4) for file services (accessed via mount).
Section (5) for the Plan 9 file protocol.
Section (6) for file formats.
Section (7) for databases and database access programs.
Section (8) for things related to administering Plan 9.
/sys/doc for copies of papers referenced in this manual.
The back of this volume has a permuted index to aid searches.
Upon termination each program returns a string called the exit status.
It was either supplied by a call to exits(2) or was written to the com‐
mand's /proc/pid/note file (see proc(3)), causing an abnormal termina‐
tion. The empty string is customary for successful execution; a non-
empty string gives a clue to the failure of the command.