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 92aa0e13 2020-02-23 crossd .B http://9p.io/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 d32deab1 2020-08-16 rsc .MR 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 d32deab1 2020-08-16 rsc .MR cat (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:
56 c8b6342d 2005-01-13 devnull expect Plan 9 regular expressions
58 d32deab1 2020-08-16 rsc .MR 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
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.
73 c8b6342d 2005-01-13 devnull now allows mkfiles to choose their own shell,
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
85 d32deab1 2020-08-16 rsc .MR acme (1) .
86 c8b6342d 2005-01-13 devnull An X11 window manager
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 d32deab1 2020-08-16 rsc .MR 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 d32deab1 2020-08-16 rsc .MR 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
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 d32deab1 2020-08-16 rsc .MR 9pclient (3)
123 c8b6342d 2005-01-13 devnull library.
124 d32deab1 2020-08-16 rsc .MR 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.
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 d32deab1 2020-08-16 rsc .MR 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 d32deab1 2020-08-16 rsc .MR 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 d32deab1 2020-08-16 rsc .MR thread (3)
169 c8b6342d 2005-01-13 devnull library.
170 d32deab1 2020-08-16 rsc .MR Rfork (3)
171 c8b6342d 2005-01-13 devnull exists but is not as capable as on Plan 9.
172 4938281a 2023-01-09 crossd There are many unfortunate but necessary preprocessor
173 c8b6342d 2005-01-13 devnull diversions to make Plan 9 and Unix libraries coexist.
175 d32deab1 2020-08-16 rsc .MR intro (3)
176 c8b6342d 2005-01-13 devnull for details.
178 c8b6342d 2005-01-13 devnull The debuggers
179 d32deab1 2020-08-16 rsc .MR acid (1)
182 c8b6342d 2005-01-13 devnull and the debugging library
183 d32deab1 2020-08-16 rsc .MR 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 d32deab1 2020-08-16 rsc .MR troff (1) .
208 c8b6342d 2005-01-13 devnull Of the more recent additions to Plan 9,
209 d32deab1 2020-08-16 rsc .MR factotum (4) ,
210 d32deab1 2020-08-16 rsc .MR secstore (1) ,
212 d32deab1 2020-08-16 rsc .MR secstored (1) ,
213 d32deab1 2020-08-16 rsc .MR vac (1) ,
214 d32deab1 2020-08-16 rsc .MR vacfs (4) ,
216 d32deab1 2020-08-16 rsc .MR 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 d32deab1 2020-08-16 rsc .MR 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 d32deab1 2020-08-16 rsc .MR 9term (1)
244 c8b6342d 2005-01-13 devnull and the implementation of
245 d32deab1 2020-08-16 rsc .MR 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
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:
304 d32deab1 2020-08-16 rsc .MR 9c (1) ,
305 d32deab1 2020-08-16 rsc .MR 9p (1) ,
306 d32deab1 2020-08-16 rsc .MR 9term (1) ,
307 01cd4060 2005-01-14 devnull .I acidtypes
309 d32deab1 2020-08-16 rsc .MR acid (1) ,
310 d32deab1 2020-08-16 rsc .MR dial (1) ,
311 d32deab1 2020-08-16 rsc .MR git (1) ,
312 d32deab1 2020-08-16 rsc .MR label (1) ,
314 01cd4060 2005-01-14 devnull .B MKSHELL
315 01cd4060 2005-01-14 devnull variable in
316 d32deab1 2020-08-16 rsc .MR mk (1) ,
317 d32deab1 2020-08-16 rsc .MR namespace (1) ,
318 d32deab1 2020-08-16 rsc .MR netfiles (1) ,
319 d32deab1 2020-08-16 rsc .MR page (1) ,
320 d32deab1 2020-08-16 rsc .MR psfonts (1) ,
321 d32deab1 2020-08-16 rsc .MR rio (1) ,
322 d32deab1 2020-08-16 rsc .MR web (1) ,
323 d32deab1 2020-08-16 rsc .MR wintext (1)
325 d32deab1 2020-08-16 rsc .MR intro (3) ,
326 d32deab1 2020-08-16 rsc .MR 9pclient (3) ,
329 01cd4060 2005-01-14 devnull network in
330 d32deab1 2020-08-16 rsc .MR dial (3) ,
331 d32deab1 2020-08-16 rsc .MR exits (3) ,
332 d32deab1 2020-08-16 rsc .MR get9root (3) ,
333 d32deab1 2020-08-16 rsc .MR getns (3) ,
334 d32deab1 2020-08-16 rsc .MR notify (3) ,
335 d32deab1 2020-08-16 rsc .MR post9pservice (3) ,
336 d32deab1 2020-08-16 rsc .MR rfork (3) ,
337 d32deab1 2020-08-16 rsc .MR searchpath (3) ,
338 d32deab1 2020-08-16 rsc .MR sendfd (3) ,
339 d32deab1 2020-08-16 rsc .MR udpread (3) ,
340 d32deab1 2020-08-16 rsc .MR venti (3) ,
341 d32deab1 2020-08-16 rsc .MR wait (3) ,
342 d32deab1 2020-08-16 rsc .MR wctl (3)
344 d32deab1 2020-08-16 rsc .MR intro (4) ,
345 d32deab1 2020-08-16 rsc .MR 9pserve (4) ,
346 d32deab1 2020-08-16 rsc .MR import (4) ,
348 d32deab1 2020-08-16 rsc .MR 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 d32deab1 2020-08-16 rsc .MR exits (3) .
