0intro.1 (9280B)
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 See 103 .MR devdraw (1) 104 and 105 .MR keyboard (7) 106 for details about typing and clicking in graphical applications. 107 .PP 108 The 109 .MR plumber (4) 110 helps to connect the various Plan 9 programs together, 111 and fittings like 112 .MR web (1) 113 connect it to external programs such as web browsers; 114 one can click on a URL in 115 .I acme 116 and see the page load in 117 .IR Firefox . 118 .SS User-level file servers 119 In Plan 9, user-level file servers present file trees via the Plan 9 file protocol, 9P. 120 Processes can mount arbitrary file servers and customize their own name spaces. 121 These facilities are used to connect programs. Clients interact 122 with file servers by reading and writing files. 123 .PP 124 This cannot be done directly on Unix. 125 Instead the servers listen for 9P connections on Unix domain sockets; 126 clients connect to these sockets and speak 9P directly using the 127 .MR 9pclient (3) 128 library. 129 .MR Intro (4) 130 tells more of the story. 131 The effect is not as clean as on Plan 9, but it gets the job done 132 and still provides a uniform and easy-to-understand mechanism. 133 The 134 .MR 9p (1) 135 client can be used in shell scripts or by hand to carry out 136 simple interactions with servers. 137 .MR Netfiles (1) 138 is an experimental client for acme. 139 .SS External databases 140 Some programs rely on large databases that would be 141 cumbersome to include in every release. 142 Scripts are provided that download these databases separately. 143 These databases can be downloaded separately. 144 See 145 .B $PLAN9/dict/README 146 and 147 .BR $PLAN9/sky/README . 148 .SS Programming 149 The shell scripts 150 .I 9c 151 and 152 .I 9l 153 (see 154 .MR 9c (1) ) 155 provide a simple interface to the underlying system compiler and linker, 156 similar to the 157 .I 2c 158 and 159 .I 2l 160 families on Plan 9. 161 .I 9c 162 compiles source files, and 163 .I 9l 164 links object files into executables. 165 When using Plan 9 libraries, 166 .I 9l 167 infers the correct set of libraries from the object files, 168 so that no 169 .B -l 170 options are needed. 171 .PP 172 The only way to write multithreaded programs is to use the 173 .MR thread (3) 174 library. 175 .MR Rfork (3) 176 exists but is not as capable as on Plan 9. 177 There are many unfortunate but necessary preprocessor 178 diversions to make Plan 9 and Unix libraries coexist. 179 See 180 .MR intro (3) 181 for details. 182 .PP 183 The debuggers 184 .MR acid (1) 185 and 186 .MR db (1) 187 and the debugging library 188 .MR mach (3) 189 are works in progress. 190 They are platform-independent, so that x86 Linux core dumps 191 can be inspected on PowerPC Mac OS X machines, 192 but they are also fairly incomplete. 193 The x86 target is the most mature; initial PowerPC support 194 exists; and other targets are unimplemented. 195 The debuggers can only inspect, not manipulate, target processes. 196 Support for operating system threads and for 64-bit architectures 197 needs to be rethought. 198 On x86 Linux systems, 199 .I acid 200 and 201 .I db 202 can be relied upon to produce reasonable stack traces 203 (often in cases when GNU 204 .I gdb 205 cannot) 206 and dump data structures, 207 but that it is the extent to which they have been developed and exercised. 208 .SS Porting programs 209 The vast majority of the familiar Plan 9 programs 210 have been ported, including the Unicode-aware 211 .MR troff (1) . 212 .PP 213 Of the more recent additions to Plan 9, 214 .MR factotum (4) , 215 .MR secstore (1) , 216 and 217 .MR secstored (1) , 218 .MR vac (1) , 219 .MR vacfs (4) , 220 and 221 .MR venti (8) 222 are all ported. 223 .PP 224 A backup system providing a dump file system built atop Venti 225 is in progress; see 226 .MR vbackup (8) . 227 .SS Porting to new systems 228 Porting the tree to new operating systems or architectures 229 should be straightforward, as system-specific code has been 230 kept to a minimum. 231 The largest pieces of system-specific code are 232 .BR <u.h> , 233 which must include the right system files and 234 set up the right integer type definitions, 235 and 236 .IR libthread , 237 which must implement spin locks, operating system thread 238 creation, and context switching routines. 239 Portable implementations of these using 240 .B <pthread.h> 241 and 242 .B <ucontext.h> 243 already exist. If your system supports them, you may not 244 need to write any system specific code at all. 245 .PP 246 There are other smaller system dependencies, 247 such as the terminal handling code in 248 .MR 9term (1) 249 and the implementation of 250 .MR getcallerpc (3) , 251 but these are usually simple and are not on the critical 252 path for getting the system up and running. 253 .SH SEE ALSO 254 The rest of this manual describes Plan 9 from User Space. 255 Many of the man pages have been brought from Plan 9, 256 but they have been updated, and others have been written from scratch. 257 .PP 258 The manual pages are in a Unix style tree, with names like 259 .B $PLAN9/man/man1/cat.1 260 instead of Plan 9's simpler 261 .BR $PLAN9/man/1/cat , 262 so that the Unix 263 .MR man (1) 264 utility can handle it. 265 Some systems, for example Debian Linux, 266 deduce the man page locations from the search path, so that 267 adding 268 .B $PLAN9/bin 269 to your path is sufficient to cause 270 .B $PLAN9/man 271 to be consulted for manual pages using the system 272 .IR man . 273 On other systems, or to look at manual pages with the 274 same name as a system page, 275 invoke the Plan 9 276 .I man 277 directly, as in 278 .B 9 279 .B man 280 .BR cat . 281 .PP 282 The manual sections follow the Unix numbering conventions, 283 not the Plan 9 ones. 284 .PP 285 .HR ../man1 "Section (1) 286 describes general publicly accessible commands. 287 .PP 288 .HR ../man3 "Section (3) 289 describes C library functions. 290 .PP 291 .HR ../man4 "Section (4) 292 describes user-level file servers. 293 .PP 294 .HR ../man7 "Section (7) 295 describes file formats and protocols. 296 (On Unix, section (5) is technically for file formats but 297 seems now to be used for describing specific files.) 298 .PP 299 .HR ../man8 "Section (8) 300 describes commands used for system administration. 301 .PP 302 .HR ../man9 "Section (9p) 303 describes the Plan 9 file protocol 9P. 304 .PP 305 These pages describe parts of the system 306 that are new or different from Plan 9 from Bell Labs: 307 .IP 308 .MR 9 (1) , 309 .MR 9c (1) , 310 .MR 9p (1) , 311 .MR 9term (1) , 312 .I acidtypes 313 in 314 .MR acid (1) , 315 .MR dial (1) , 316 .MR git (1) , 317 .MR label (1) , 318 the 319 .B MKSHELL 320 variable in 321 .MR mk (1) , 322 .MR namespace (1) , 323 .MR netfiles (1) , 324 .MR page (1) , 325 .MR psfonts (1) , 326 .MR rio (1) , 327 .MR web (1) , 328 .MR wintext (1) 329 .IP 330 .MR intro (3) , 331 .MR 9pclient (3) , 332 the 333 .B unix 334 network in 335 .MR dial (3) , 336 .MR exits (3) , 337 .MR get9root (3) , 338 .MR getns (3) , 339 .MR notify (3) , 340 .MR post9pservice (3) , 341 .MR rfork (3) , 342 .MR searchpath (3) , 343 .MR sendfd (3) , 344 .MR udpread (3) , 345 .MR venti (3) , 346 .MR wait (3) , 347 .MR wctl (3) 348 .IP 349 .MR intro (4) , 350 .MR 9pserve (4) , 351 .MR import (4) , 352 .IP 353 .MR vbackup (8) 354 .IP 355 .IR openfd (9p) 356 .SH DIAGNOSTICS 357 In Plan 9, a program's exit status is an arbitrary text string, 358 while on Unix it is an integer. 359 Section (1) of this manual describes commands as though they 360 exit with string statuses. In fact, exiting with an empty status 361 corresponds to exiting with status 0, 362 and exiting with any non-empty string corresponds to exiting with status 1. 363 See 364 .MR exits (3) .