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