5 intro - introduction to Plan 9 from User Space
8 Plan 9 is a distributed computing environment built at Bell
9 Labs starting in the late 1980s. The system can be obtained
10 from Bell Labs at http://plan9.bell-labs.com/plan9 and runs
11 on PCs and a variety of other platforms. Plan 9 became a
12 convenient platform for experimenting with new ideas, appli-
13 cations, and services.
15 Plan 9 from User Space provides many of the ideas, applica-
16 tions, and services from Plan 9 on Unix-like systems. It
17 runs on FreeBSD (x86, x86-64), Linux (x86, x86-64, PowerPC
18 and ARM), Mac OS X (x86, x86-64, and PowerPC), NetBSD (x86
19 and PowerPC), OpenBSD (x86 and PowerPC), Dragonfly BSD
20 (x86-64), and SunOS (x86-64 and Sparc).
23 Plan 9 from User Space expects its own directory tree, con-
24 ventionally /usr/local/plan9. When programs need to access
25 files in the tree, they expect the $PLAN9 environment vari-
26 able to contain the name of the root of the tree. See
27 install(1) for details about installation.
29 Many of the familiar Unix commands, for example cat(1),
30 ls(1), and wc(1), are present, but in their Plan 9 forms:
31 cat takes no options, ls does not columnate its output when
32 printing to a terminal, and wc counts UTF characters. In
33 some cases, the differences are quite noticeable: grep(1)
34 and sed(1) expect Plan 9 regular expressions (see
35 regexp(7)), which are closest to what Unix calls extended
36 regular expressions. Because of these differences, it is
37 not recommended to put $PLAN9/bin before the usual system
38 bin directories in your search path. Instead, put it at the
39 end of your path and use the 9(1) script when you want to
40 invoke the Plan 9 version of a traditional Unix command.
42 Occasionally the Plan 9 programs have been changed to adapt
43 to Unix. Mk(1) now allows mkfiles to choose their own
44 shell, and rc(1) has a ulimit builtin and manages $PATH.
46 Many of the graphical programs from Plan 9 are present,
47 including sam(1) and acme(1). An X11 window manager rio(1)
48 mimics Plan 9's window system, with command windows imple-
49 mented by the external program 9term(1). Following the style
50 of X Windows, these programs run in new windows rather than
51 the one in which they are invoked. They all take a -W
52 option to specify the size and placement of the new window.
53 The argument is one of widthxheight, widthxheight@xmin,xmax,
55 Page 1 Plan 9 (printed 12/1/14)
59 or xmin,ymin,xmax,ymax.
61 The plumber(4) helps to connect the various Plan 9 programs
62 together, and fittings like web(1) connect it to external
63 programs such as web browsers; one can click on a URL in
64 acme and see the page load in Firefox.
66 User-level file servers
67 In Plan 9, user-level file servers present file trees via
68 the Plan 9 file protocol, 9P. Processes can mount arbitrary
69 file servers and customize their own name spaces. These
70 facilities are used to connect programs. Clients interact
71 with file servers by reading and writing files.
73 This cannot be done directly on Unix. Instead the servers
74 listen for 9P connections on Unix domain sockets; clients
75 connect to these sockets and speak 9P directly using the
76 9pclient(3) library. Intro(4) tells more of the story. The
77 effect is not as clean as on Plan 9, but it gets the job
78 done and still provides a uniform and easy-to-understand
79 mechanism. The 9p(1) client can be used in shell scripts or
80 by hand to carry out simple interactions with servers.
81 Netfiles(1) is an experimental client for acme.
84 Some programs rely on large databases that would be cumber-
85 some to include in every release. Scripts are provided that
86 download these databases separately. These databases can be
87 downloaded separately. See $PLAN9/dict/README and
91 The shell scripts 9c and 9l (see 9c(1)) provide a simple
92 interface to the underlying system compiler and linker, sim-
93 ilar to the 2c and 2l families on Plan 9. 9c compiles
94 source files, and 9l links object files into executables.
95 When using Plan 9 libraries, 9l infers the correct set of
96 libraries from the object files, so that no -l options are
99 The only way to write multithreaded programs is to use the
100 thread(3) library. Rfork(3) exists but is not as capable as
101 on Plan 9. There are many unfortunate by necessary prepro-
102 cessor diversions to make Plan 9 and Unix libraries coexist.
103 See intro(3) for details.
105 The debuggers acid(1) and db(1) and the debugging library
106 mach(3) are works in progress. They are platform-
107 independent, so that x86 Linux core dumps can be inspected
108 on PowerPC Mac OS X machines, but they are also fairly
109 incomplete. The x86 target is the most mature; initial Pow-
110 erPC support exists; and other targets are unimplemented.
112 Page 2 Plan 9 (printed 12/1/14)
116 The debuggers can only inspect, not manipulate, target pro-
117 cesses. Support for operating system threads and for 64-bit
118 architectures needs to be rethought. On x86 Linux systems,
119 acid and db can be relied upon to produce reasonable stack
120 traces (often in cases when GNU gdb cannot) and dump data
121 structures, but that it is the extent to which they have
122 been developed and exercised.
125 The vast majority of the familiar Plan 9 programs have been
126 ported, including the Unicode-aware troff(1).
128 Of the more recent additions to Plan 9, factotum(4),
129 secstore(1), and secstored(1), vac(1), vacfs(4), and
130 venti(8) are all ported.
132 A backup system providing a dump file system built atop
133 Venti is in progress; see vbackup(8).
135 Porting to new systems
136 Porting the tree to new operating systems or architectures
137 should be straightforward, as system-specific code has been
138 kept to a minimum. The largest pieces of system-specific
139 code are <u.h>, which must include the right system files
140 and set up the right integer type definitions, and
141 libthread, which must implement spin locks, operating system
142 thread creation, and context switching routines. Portable
143 implementations of these using <pthread.h> and <ucontext.h>
144 already exist. If your system supports them, you may not
145 need to write any system specific code at all.
147 There are other smaller system dependencies, such as the
148 terminal handling code in 9term(1) and the implementation of
149 getcallerpc(3), but these are usually simple and are not on
150 the critical path for getting the system up and running.
153 The rest of this manual describes Plan 9 from User Space.
154 Many of the man pages have been brought from Plan 9, but
155 they have been updated, and others have been written from
158 The manual pages are in a Unix style tree, with names like
159 $PLAN9/man/man1/cat.1 instead of Plan 9's simpler
160 $PLAN9/man/1/cat, so that the Unix man(1) utility can handle
161 it. Some systems, for example Debian Linux, deduce the man
162 page locations from the search path, so that adding
163 $PLAN9/bin to your path is sufficient to cause $PLAN9/man to
164 be consulted for manual pages using the system man. On other
165 systems, or to look at manual pages with the same name as a
166 system page, invoke the Plan 9 man directly, as in 9 man
169 Page 3 Plan 9 (printed 12/1/14)
173 The manual sections follow the Unix numbering conventions,
176 Section (1) describes general publicly accessible commands.
178 Section (3) describes C library functions.
180 Section (4) describes user-level file servers.
182 Section (7) describes file formats and protocols. (On Unix,
183 section (5) is technically for file formats but seems now to
184 be used for describing specific files.)
186 Section (8) describes commands used for system administra-
189 Section (9p) describes the Plan 9 file protocol 9P.
191 These pages describe parts of the system that are new or
192 different from Plan 9 from Bell Labs:
194 9(1), 9c(1), 9p(1), 9term(1), acidtypes in acid(1),
195 dial(1), git(1), label(1), the MKSHELL variable in
196 mk(1), namespace(1), netfiles(1), page(1), psfonts(1),
197 rio(1), web(1), wintext(1)
199 intro(3), 9pclient(3), the unix network in dial(3),
200 exits(3), get9root(3), getns(3), notify(3),
201 post9pservice(3), rfork(3), searchpath(3), sendfd(3),
202 udpread(3), venti(3), wait(3), wctl(3)
204 intro(4), 9pserve(4), import(4),
211 In Plan 9, a program's exit status is an arbitrary text
212 string, while on Unix it is an integer. Section (1) of this
213 manual describes commands as though they exit with string
214 statuses. In fact, exiting with an empty status corresponds
215 to exiting with status 0, and exiting with any non-empty
216 string corresponds to exiting with status 1. See exits(3).
218 Page 4 Plan 9 (printed 12/1/14)
