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