3 intro \- introduction to Plan 9 from User Space
5 Plan 9 is a distributed computing environment built
6 at Bell Labs starting in the late 1980s.
7 The system can be obtained from Bell Labs at
8 .B http://plan9.bell-labs.com/plan9
9 and runs on PCs and a variety of other platforms.
10 Plan 9 became a convenient platform for experimenting
11 with new ideas, applications, and services.
13 Plan 9 from User Space provides many of the ideas,
14 applications, and services from Plan 9
18 Linux (x86 and PowerPC),
24 Plan 9 from User Space expects its own directory tree,
26 .BR /usr/local/plan9 .
27 When programs need to access files in the tree,
31 to contain the name of the root of the tree.
34 for details about installation.
36 Many of the familiar Unix commands,
42 are present, but in their Plan 9 forms:
46 does not columnate its output when printing to a terminal,
49 counts UTF characters.
50 In some cases, the differences are quite noticeable:
54 expect Plan 9 regular expressions
57 which are closest to what Unix calls extended regular expressions.
58 Because of these differences, it is not recommended to put
60 before the usual system
62 directories in your search path.
63 Instead, put it at the end of your path and use the
65 script when you want to invoke the Plan 9 version of a
66 traditional Unix command.
68 Occasionally the Plan 9 programs have been
69 changed to adapt to Unix.
71 now allows mkfiles to choose their own shell,
79 Many of the graphical programs from Plan 9 are present,
86 mimics Plan 9's window system, with command windows
87 implemented by the external program
89 Following the style of X Windows, these programs run in new
90 windows rather than the one in which they are invoked.
93 option to specify the size and placement of the new window.
94 The argument is one of
95 \fIwidth\^\^\fLx\fI\^\^height\fR,
96 \fIwidth\^\^\fLx\fI\^\^height\^\^\fL@\fI\^\^xmin\fL,\fIxmax\fR,
97 \fL'\fIxmin ymin xmax ymax\fL'\fR,
99 \fIxmin\fL,\fIymin\fL,\fIxmax\fL,\fIymax\fR.
103 helps to connect the various Plan 9 programs together,
106 connect it to external programs such as web browsers;
107 one can click on a URL in
109 and see the page load in
111 .SS User-level file servers
112 In Plan 9, user-level file servers present file trees via the Plan 9 file protocol, 9P.
113 Processes can mount arbitrary file servers and customize their own name spaces.
114 These facilities are used to connect programs. Clients interact
115 with file servers by reading and writing files.
117 This cannot be done directly on Unix.
118 Instead the servers listen for 9P connections on Unix domain sockets;
119 clients connect to these sockets and speak 9P directly using the
123 tells more of the story.
124 The effect is not as clean as on Plan 9, but it gets the job done
125 and still provides a uniform and easy-to-understand mechanism.
128 client can be used in shell scripts or by hand to carry out
129 simple interactions with servers.
131 is an experimental client for acme.
132 .SS External databases
133 Some programs rely on large databases that would be
134 cumbersome to include in every release.
135 Scripts are provided that download these databases separately.
136 These databases can be downloaded separately.
138 .B $PLAN9/dict/README
140 .BR $PLAN9/sky/README .
148 provide a simple interface to the underlying system compiler and linker,
155 compiles source files, and
157 links object files into executables.
158 When using Plan 9 libraries,
160 infers the correct set of libraries from the object files,
165 The only way to write multithreaded programs is to use the
169 exists but is not as capable as on Plan 9.
170 There are many unfortunate by necessary preprocessor
171 diversions to make Plan 9 and Unix libraries coexist.
180 and the debugging library
182 are works in progress.
183 They are platform-independent, so that x86 Linux core dumps
184 can be inspected on PowerPC Mac OS X machines,
185 but they are also fairly incomplete.
186 The x86 target is the most mature; initial PowerPC support
187 exists; and other targets are unimplemented.
188 The debuggers can only inspect, not manipulate, target processes.
189 Support for operating system threads and for 64-bit architectures
190 needs to be rethought.
191 On x86 Linux systems,
195 can be relied upon to produce reasonable stack traces
196 (often in cases when GNU
199 and dump data structures,
200 but that it is the extent to which they have been developed and exercised.
202 The vast majority of the familiar Plan 9 programs
203 have been ported, including the Unicode-aware
206 Of the more recent additions to Plan 9,
217 A backup system providing a dump file system built atop Venti
220 .SS Porting to new systems
221 Porting the tree to new operating systems or architectures
222 should be straightforward, as system-specific code has been
224 The largest pieces of system-specific code are
226 which must include the right system files and
227 set up the right integer type definitions,
230 which must implement spin locks, operating system thread
231 creation, and context switching routines.
232 Portable implementations of these using
236 already exist. If your system supports them, you may not
237 need to write any system specific code at all.
239 There are other smaller system dependencies,
240 such as the terminal handling code in
242 and the implementation of
244 but these are usually simple and are not on the critical
245 path for getting the system up and running.
247 The rest of this manual describes Plan 9 from User Space.
248 Many of the man pages have been brought from Plan 9,
249 but they have been updated, and others have been written from scratch.
251 The manual pages are in a Unix style tree, with names like
252 .B $PLAN9/man/man1/cat.1
253 instead of Plan 9's simpler
254 .BR $PLAN9/man/1/cat ,
257 utility can handle it.
258 Some systems, for example Debian Linux,
259 deduce the man page locations from the search path, so that
262 to your path is sufficient to cause
264 to be consulted for manual pages using the system
266 On other systems, or to look at manual pages with the
267 same name as a system page,
275 The manual sections follow the Unix numbering conventions,
278 .HR ../man1 "Section (1)
279 describes general publicly accessible commands.
281 .HR ../man3 "Section (3)
282 describes C library functions.
284 .HR ../man4 "Section (4)
285 describes user-level file servers.
287 .HR ../man7 "Section (7)
288 describes file formats and protocols.
289 (On Unix, section (5) is technically for file formats but
290 seems now to be used for describing specific files.)
292 .HR ../man8 "Section (8)
293 describes commands used for system administration.
295 .HR ../man9 "Section (9p)
296 describes the Plan 9 file protocol 9P.
298 These pages describe parts of the system
299 that are new or different from Plan 9 from Bell Labs:
333 .IR post9pservice (3),
350 In Plan 9, a program's exit status is an arbitrary text string,
351 while on Unix it is an integer.
352 Section (1) of this manual describes commands as though they
353 exit with string statuses. In fact, exiting with an empty status
354 corresponds to exiting with status 0,
355 and exiting with any non-empty string corresponds to exiting with status 1.
