1 c8b6342d 2005-01-13 devnull .TH INTRO 1
3 c8b6342d 2005-01-13 devnull intro \- introduction to Plan 9 from User Space
4 c8b6342d 2005-01-13 devnull .SH DESCRIPTION
5 c8b6342d 2005-01-13 devnull Plan 9 is a distributed computing environment built
6 c8b6342d 2005-01-13 devnull at Bell Labs starting in the late 1980s.
7 c8b6342d 2005-01-13 devnull The system can be obtained from Bell Labs at
8 c8b6342d 2005-01-13 devnull .B http://plan9.bell-labs.com/plan9
9 c8b6342d 2005-01-13 devnull and runs on PCs and a variety of other platforms.
10 c8b6342d 2005-01-13 devnull Plan 9 became a convenient platform for experimenting
11 c8b6342d 2005-01-13 devnull with new ideas, applications, and services.
13 c8b6342d 2005-01-13 devnull Plan 9 from User Space provides many of the ideas,
14 c8b6342d 2005-01-13 devnull applications, and services from Plan 9
15 c8b6342d 2005-01-13 devnull on Unix-like systems.
16 c8b6342d 2005-01-13 devnull It runs on
17 c8b6342d 2005-01-13 devnull FreeBSD (x86),
18 c8b6342d 2005-01-13 devnull Linux (x86 and PowerPC),
19 c8b6342d 2005-01-13 devnull Mac OS X (PowerPC),
20 c8b6342d 2005-01-13 devnull OpenBSD (x86),
22 c8b6342d 2005-01-13 devnull SunOS (Sparc).
23 c8b6342d 2005-01-13 devnull .SS Commands
24 c8b6342d 2005-01-13 devnull Plan 9 from User Space expects its own directory tree,
25 c8b6342d 2005-01-13 devnull conventionally
26 c8b6342d 2005-01-13 devnull .BR /usr/local/plan9 .
27 c8b6342d 2005-01-13 devnull When programs need to access files in the tree,
28 c8b6342d 2005-01-13 devnull they expect the
29 c8b6342d 2005-01-13 devnull .B $PLAN9
30 c8b6342d 2005-01-13 devnull environment variable
31 c8b6342d 2005-01-13 devnull to contain the name of the root of the tree.
33 93aa30a8 2005-01-14 devnull .IR install (1)
34 c8b6342d 2005-01-13 devnull for details about installation.
36 c8b6342d 2005-01-13 devnull Many of the familiar Unix commands,
37 c8b6342d 2005-01-13 devnull for example
38 c8b6342d 2005-01-13 devnull .IR cat (1),
39 c8b6342d 2005-01-13 devnull .IR ls (1),
41 c8b6342d 2005-01-13 devnull .IR wc (1),
42 c8b6342d 2005-01-13 devnull are present, but in their Plan 9 forms:
44 1ba05242 2005-01-14 devnull takes no options,
46 c8b6342d 2005-01-13 devnull does not columnate its output when printing to a terminal,
49 c8b6342d 2005-01-13 devnull counts UTF characters.
50 c8b6342d 2005-01-13 devnull In some cases, the differences are quite noticeable:
51 c8b6342d 2005-01-13 devnull .IR grep (1)
53 c8b6342d 2005-01-13 devnull .IR sed (1)
54 c8b6342d 2005-01-13 devnull expect Plan 9 regular expressions
56 c8b6342d 2005-01-13 devnull .IR regexp (7)),
57 c8b6342d 2005-01-13 devnull which are closest to what Unix calls extended regular expressions.
58 c8b6342d 2005-01-13 devnull Because of these differences, it is not recommended to put
59 c8b6342d 2005-01-13 devnull .B $PLAN9/bin
60 c8b6342d 2005-01-13 devnull before the usual system
62 c8b6342d 2005-01-13 devnull directories in your search path.
63 c8b6342d 2005-01-13 devnull Instead, put it at the end of your path and use the
64 c8b6342d 2005-01-13 devnull .IR 9 (1)
65 c8b6342d 2005-01-13 devnull script when you want to invoke the Plan 9 version of a
66 c8b6342d 2005-01-13 devnull traditional Unix command.
68 c8b6342d 2005-01-13 devnull Occasionally the Plan 9 programs have been
69 c8b6342d 2005-01-13 devnull changed to adapt to Unix.
70 c8b6342d 2005-01-13 devnull .IR Mk (1)
71 c8b6342d 2005-01-13 devnull now allows mkfiles to choose their own shell,
73 c8b6342d 2005-01-13 devnull .IR rc (1)
75 c8b6342d 2005-01-13 devnull .I ulimit
76 c8b6342d 2005-01-13 devnull builtin and manages
77 c8b6342d 2005-01-13 devnull .BR $PATH .
79 c8b6342d 2005-01-13 devnull Many of the graphical programs from Plan 9 are present,
80 c8b6342d 2005-01-13 devnull including
81 c8b6342d 2005-01-13 devnull .IR sam (1)
83 c8b6342d 2005-01-13 devnull .IR acme (1).
84 c8b6342d 2005-01-13 devnull An X11 window manager
85 c8b6342d 2005-01-13 devnull .IR rio (1)
86 c8b6342d 2005-01-13 devnull mimics Plan 9's window system, with command windows
87 c8b6342d 2005-01-13 devnull implemented by the external program
88 c8b6342d 2005-01-13 devnull .IR 9term (1).
89 c8b6342d 2005-01-13 devnull Following the style of X Windows, these programs run in new
90 c8b6342d 2005-01-13 devnull windows rather than the one in which they are invoked.
91 c8b6342d 2005-01-13 devnull They all take a
93 c8b6342d 2005-01-13 devnull option to specify the size and placement of the new window.
94 c8b6342d 2005-01-13 devnull The argument is one of
95 c8b6342d 2005-01-13 devnull \fIwidth\^\^\fLx\fI\^\^height\fR,
96 c8b6342d 2005-01-13 devnull \fIwidth\^\^\fLx\fI\^\^height\^\^\fL@\fI\^\^xmin\fL,\fIxmax\fR,
97 c8b6342d 2005-01-13 devnull \fL'\fIxmin ymin xmax ymax\fL'\fR,
99 c8b6342d 2005-01-13 devnull \fIxmin\fL,\fIymin\fL,\fIxmax\fL,\fIymax\fR.
102 c8b6342d 2005-01-13 devnull .IR plumber (4)
103 c8b6342d 2005-01-13 devnull helps to connect the various Plan 9 programs together,
104 c8b6342d 2005-01-13 devnull and fittings like
105 c8b6342d 2005-01-13 devnull .IR web (1)
106 c8b6342d 2005-01-13 devnull connect it to external programs such as web browsers;
107 c8b6342d 2005-01-13 devnull one can click on a URL in
109 c8b6342d 2005-01-13 devnull and see the page load in
110 c8b6342d 2005-01-13 devnull .IR Firefox .
111 c8b6342d 2005-01-13 devnull .SS User-level file servers
112 c8b6342d 2005-01-13 devnull In Plan 9, user-level file servers present file trees via the Plan 9 file protocol, 9P.
113 c8b6342d 2005-01-13 devnull Processes can mount arbitrary file servers and customize their own name spaces.
114 c8b6342d 2005-01-13 devnull These facilities are used to connect programs. Clients interact
115 c8b6342d 2005-01-13 devnull with file servers by reading and writing files.
117 c8b6342d 2005-01-13 devnull This cannot be done directly on Unix.
118 c8b6342d 2005-01-13 devnull Instead the servers listen for 9P connections on Unix domain sockets;
119 c8b6342d 2005-01-13 devnull clients connect to these sockets and speak 9P directly using the
120 c8b6342d 2005-01-13 devnull .IR 9pclient (3)
121 c8b6342d 2005-01-13 devnull library.
122 c8b6342d 2005-01-13 devnull .IR Intro (4)
123 c8b6342d 2005-01-13 devnull tells more of the story.
124 c8b6342d 2005-01-13 devnull The effect is not as clean as on Plan 9, but it gets the job done
125 c8b6342d 2005-01-13 devnull and still provides a uniform and easy-to-understand mechanism.
127 c8b6342d 2005-01-13 devnull .IR 9p (1)
128 c8b6342d 2005-01-13 devnull client can be used in shell scripts or by hand to carry out
129 c8b6342d 2005-01-13 devnull simple interactions with servers.
130 86a1a5e7 2005-07-19 devnull .IR Netfiles (1)
131 86a1a5e7 2005-07-19 devnull is an experimental client for acme.
132 93aa30a8 2005-01-14 devnull .SS External databases
133 93aa30a8 2005-01-14 devnull Some programs rely on large databases that would be
134 93aa30a8 2005-01-14 devnull cumbersome to include in every release.
135 93aa30a8 2005-01-14 devnull Scripts are provided that download these databases separately.
136 93aa30a8 2005-01-14 devnull These databases can be downloaded separately.
138 93aa30a8 2005-01-14 devnull .B $PLAN9/dict/README
140 93aa30a8 2005-01-14 devnull .BR $PLAN9/sky/README .
141 c8b6342d 2005-01-13 devnull .SS Programming
142 c8b6342d 2005-01-13 devnull The shell scripts
147 c8b6342d 2005-01-13 devnull .IR 9c (1))
148 c8b6342d 2005-01-13 devnull provide a simple interface to the underlying system compiler and linker,
149 c8b6342d 2005-01-13 devnull similar to the
153 c8b6342d 2005-01-13 devnull families on Plan 9.
155 c8b6342d 2005-01-13 devnull compiles source files, and
157 c8b6342d 2005-01-13 devnull links object files into executables.
158 c8b6342d 2005-01-13 devnull When using Plan 9 libraries,
160 c8b6342d 2005-01-13 devnull infers the correct set of libraries from the object files,
161 c8b6342d 2005-01-13 devnull so that no
163 c8b6342d 2005-01-13 devnull options are needed.
165 c8b6342d 2005-01-13 devnull The only way to write multithreaded programs is to use the
166 c8b6342d 2005-01-13 devnull .IR thread (3)
167 c8b6342d 2005-01-13 devnull library.
168 c8b6342d 2005-01-13 devnull .IR Rfork (3)
169 c8b6342d 2005-01-13 devnull exists but is not as capable as on Plan 9.
170 c8b6342d 2005-01-13 devnull There are many unfortunate by necessary preprocessor
171 c8b6342d 2005-01-13 devnull diversions to make Plan 9 and Unix libraries coexist.
173 c8b6342d 2005-01-13 devnull .IR intro (3)
174 c8b6342d 2005-01-13 devnull for details.
176 c8b6342d 2005-01-13 devnull The debuggers
177 c8b6342d 2005-01-13 devnull .IR acid (1)
179 c8b6342d 2005-01-13 devnull .IR db (1)
180 c8b6342d 2005-01-13 devnull and the debugging library
181 c8b6342d 2005-01-13 devnull .IR mach (3)
182 c8b6342d 2005-01-13 devnull are works in progress.
183 c8b6342d 2005-01-13 devnull They are platform-independent, so that x86 Linux core dumps
184 c8b6342d 2005-01-13 devnull can be inspected on PowerPC Mac OS X machines,
185 c8b6342d 2005-01-13 devnull but they are also fairly incomplete.
186 c8b6342d 2005-01-13 devnull The x86 target is the most mature; initial PowerPC support
187 c8b6342d 2005-01-13 devnull exists; and other targets are unimplemented.
188 c8b6342d 2005-01-13 devnull The debuggers can only inspect, not manipulate, target processes.
189 c8b6342d 2005-01-13 devnull Support for operating system threads and for 64-bit architectures
190 c8b6342d 2005-01-13 devnull needs to be rethought.
191 c8b6342d 2005-01-13 devnull On x86 Linux systems,
195 c8b6342d 2005-01-13 devnull can be relied upon to produce reasonable stack traces
196 c8b6342d 2005-01-13 devnull (often in cases when GNU
199 c8b6342d 2005-01-13 devnull and dump data structures,
200 c8b6342d 2005-01-13 devnull but that it is the extent to which they have been developed and exercised.
201 c8b6342d 2005-01-13 devnull .SS Porting programs
202 c8b6342d 2005-01-13 devnull The vast majority of the familiar Plan 9 programs
203 c8b6342d 2005-01-13 devnull have been ported, including the Unicode-aware
204 c8b6342d 2005-01-13 devnull .IR troff (1).
206 c8b6342d 2005-01-13 devnull Of the more recent additions to Plan 9,
207 26ca53e1 2005-02-14 devnull .IR factotum (4),
208 26ca53e1 2005-02-14 devnull .IR secstore (1),
210 86a1a5e7 2005-07-19 devnull .IR secstored (1),
211 86a1a5e7 2005-07-19 devnull .IR vac (1),
212 86a1a5e7 2005-07-19 devnull .IR vacfs (4),
214 86a1a5e7 2005-07-19 devnull .IR venti (8)
215 86a1a5e7 2005-07-19 devnull are all ported.
217 c8b6342d 2005-01-13 devnull A backup system providing a dump file system built atop Venti
218 86a1a5e7 2005-07-19 devnull is in progress; see
219 86a1a5e7 2005-07-19 devnull .IR vbackup (8).
220 c8b6342d 2005-01-13 devnull .SS Porting to new systems
221 c8b6342d 2005-01-13 devnull Porting the tree to new operating systems or architectures
222 c8b6342d 2005-01-13 devnull should be straightforward, as system-specific code has been
223 c8b6342d 2005-01-13 devnull kept to a minimum.
224 c8b6342d 2005-01-13 devnull The largest pieces of system-specific code are
225 c8b6342d 2005-01-13 devnull .BR <u.h> ,
226 c8b6342d 2005-01-13 devnull which must include the right system files and
227 c8b6342d 2005-01-13 devnull set up the right integer type definitions,
229 c8b6342d 2005-01-13 devnull .IR libthread ,
230 c8b6342d 2005-01-13 devnull which must implement spin locks, operating system thread
231 c8b6342d 2005-01-13 devnull creation, and context switching routines.
232 c8b6342d 2005-01-13 devnull Portable implementations of these using
233 c8b6342d 2005-01-13 devnull .B <pthread.h>
235 c8b6342d 2005-01-13 devnull .B <ucontext.h>
236 c8b6342d 2005-01-13 devnull already exist. If your system supports them, you may not
237 c8b6342d 2005-01-13 devnull need to write any system specific code at all.
239 c8b6342d 2005-01-13 devnull There are other smaller system dependencies,
240 c8b6342d 2005-01-13 devnull such as the terminal handling code in
241 c8b6342d 2005-01-13 devnull .IR 9term (1)
242 c8b6342d 2005-01-13 devnull and the implementation of
243 c8b6342d 2005-01-13 devnull .IR getcallerpc (3),
244 c8b6342d 2005-01-13 devnull but these are usually simple and are not on the critical
245 c8b6342d 2005-01-13 devnull path for getting the system up and running.
246 93aa30a8 2005-01-14 devnull .SH SEE ALSO
247 93aa30a8 2005-01-14 devnull The rest of this manual describes Plan 9 from User Space.
248 c8b6342d 2005-01-13 devnull Many of the man pages have been brought from Plan 9,
249 c8b6342d 2005-01-13 devnull but they have been updated, and others have been written from scratch.
251 c8b6342d 2005-01-13 devnull The manual pages are in a Unix style tree, with names like
252 c8b6342d 2005-01-13 devnull .B $PLAN9/man/man1/cat.1
253 c8b6342d 2005-01-13 devnull instead of Plan 9's simpler
254 c8b6342d 2005-01-13 devnull .BR $PLAN9/man/1/cat ,
255 c8b6342d 2005-01-13 devnull so that the Unix
256 c8b6342d 2005-01-13 devnull .IR man (1)
257 c8b6342d 2005-01-13 devnull utility can handle it.
258 c8b6342d 2005-01-13 devnull Some systems, for example Debian Linux,
259 c8b6342d 2005-01-13 devnull deduce the man page locations from the search path, so that
261 c8b6342d 2005-01-13 devnull .B $PLAN9/bin
262 c8b6342d 2005-01-13 devnull to your path is sufficient to cause
263 c8b6342d 2005-01-13 devnull .B $PLAN9/man
264 c8b6342d 2005-01-13 devnull to be consulted for manual pages using the system
265 c8b6342d 2005-01-13 devnull .IR man .
266 c8b6342d 2005-01-13 devnull On other systems, or to look at manual pages with the
267 c8b6342d 2005-01-13 devnull same name as a system page,
268 c8b6342d 2005-01-13 devnull invoke the Plan 9
270 c8b6342d 2005-01-13 devnull directly, as in
273 c8b6342d 2005-01-13 devnull .BR cat .
275 c8b6342d 2005-01-13 devnull The manual sections follow the Unix numbering conventions,
276 c8b6342d 2005-01-13 devnull not the Plan 9 ones.
278 93aa30a8 2005-01-14 devnull .HR ../man1 "Section (1)
279 93aa30a8 2005-01-14 devnull describes general publicly accessible commands.
281 93aa30a8 2005-01-14 devnull .HR ../man3 "Section (3)
282 93aa30a8 2005-01-14 devnull describes C library functions.
284 93aa30a8 2005-01-14 devnull .HR ../man4 "Section (4)
285 93aa30a8 2005-01-14 devnull describes user-level file servers.
287 93aa30a8 2005-01-14 devnull .HR ../man7 "Section (7)
288 93aa30a8 2005-01-14 devnull describes file formats and protocols.
289 c8b6342d 2005-01-13 devnull (On Unix, section (5) is technically for file formats but
290 c8b6342d 2005-01-13 devnull seems now to be used for describing specific files.)
292 86a1a5e7 2005-07-19 devnull .HR ../man8 "Section (8)
293 86a1a5e7 2005-07-19 devnull describes commands used for system administration.
295 93aa30a8 2005-01-14 devnull .HR ../man9 "Section (9p)
296 93aa30a8 2005-01-14 devnull describes the Plan 9 file protocol 9P.
298 01cd4060 2005-01-14 devnull These pages describe parts of the system
299 01cd4060 2005-01-14 devnull that are new or different from Plan 9 from Bell Labs:
301 01cd4060 2005-01-14 devnull .IR 9 (1),
302 01cd4060 2005-01-14 devnull .IR 9c (1),
303 01cd4060 2005-01-14 devnull .IR 9p (1),
304 01cd4060 2005-01-14 devnull .IR 9term (1),
305 01cd4060 2005-01-14 devnull .I acidtypes
307 01cd4060 2005-01-14 devnull .IR acid (1),
308 01cd4060 2005-01-14 devnull .IR dial (1),
310 01cd4060 2005-01-14 devnull .IR label (1),
312 01cd4060 2005-01-14 devnull .B MKSHELL
313 01cd4060 2005-01-14 devnull variable in
314 01cd4060 2005-01-14 devnull .IR mk (1),
315 01cd4060 2005-01-14 devnull .IR namespace (1),
316 3aec33fe 2005-07-18 devnull .IR netfiles (1),
317 01cd4060 2005-01-14 devnull .IR page (1),
318 01cd4060 2005-01-14 devnull .IR psfonts (1),
319 01cd4060 2005-01-14 devnull .IR rio (1),
320 01cd4060 2005-01-14 devnull .IR web (1),
321 01cd4060 2005-01-14 devnull .IR wintext (1)
323 01cd4060 2005-01-14 devnull .IR intro (3),
324 01cd4060 2005-01-14 devnull .IR 9pclient (3),
327 01cd4060 2005-01-14 devnull network in
328 01cd4060 2005-01-14 devnull .IR dial (3),
329 01cd4060 2005-01-14 devnull .IR exits (3),
330 01cd4060 2005-01-14 devnull .IR get9root (3),
331 01cd4060 2005-01-14 devnull .IR getns (3),
332 01cd4060 2005-01-14 devnull .IR notify (3),
333 01cd4060 2005-01-14 devnull .IR post9pservice (3),
334 01cd4060 2005-01-14 devnull .IR rfork (3),
335 de39860a 2005-01-23 devnull .IR searchpath (3),
336 01cd4060 2005-01-14 devnull .IR sendfd (3),
337 01cd4060 2005-01-14 devnull .IR udpread (3),
338 86a1a5e7 2005-07-19 devnull .IR venti (3),
339 01cd4060 2005-01-14 devnull .IR wait (3),
340 01cd4060 2005-01-14 devnull .IR wctl (3)
342 01cd4060 2005-01-14 devnull .IR intro (4),
343 01cd4060 2005-01-14 devnull .IR 9pserve (4),
344 86a1a5e7 2005-07-19 devnull .IR import (4),
346 86a1a5e7 2005-07-19 devnull .IR vbackup (8)
348 01cd4060 2005-01-14 devnull .IR openfd (9p)
349 c8b6342d 2005-01-13 devnull .SH DIAGNOSTICS
350 c8b6342d 2005-01-13 devnull In Plan 9, a program's exit status is an arbitrary text string,
351 c8b6342d 2005-01-13 devnull while on Unix it is an integer.
352 c8b6342d 2005-01-13 devnull Section (1) of this manual describes commands as though they
353 c8b6342d 2005-01-13 devnull exit with string statuses. In fact, exiting with an empty status
354 c8b6342d 2005-01-13 devnull corresponds to exiting with status 0,
355 c8b6342d 2005-01-13 devnull and exiting with any non-empty string corresponds to exiting with status 1.
357 c8b6342d 2005-01-13 devnull .IR exits (3).
