| INTRO(1) INTRO(1) | |
| NAME | |
| intro - introduction to Plan 9 from User Space | |
| DESCRIPTION | |
| Plan 9 is a distributed computing environment built at Bell | |
| Labs starting in the late 1980s. The system can be obtained | |
| from Bell Labs at http://plan9.bell-labs.com/plan9 and runs | |
| on PCs and a variety of other platforms. Plan 9 became a | |
| convenient platform for experimenting with new ideas, appli- | |
| cations, and services. | |
| Plan 9 from User Space provides many of the ideas, applica- | |
| tions, and services from Plan 9 on Unix-like systems. It | |
| runs on FreeBSD (x86, x86-64), Linux (x86, x86-64, PowerPC | |
| and ARM), Mac OS X (x86, x86-64, and PowerPC), NetBSD (x86 | |
| and PowerPC), OpenBSD (x86 and PowerPC), Dragonfly BSD | |
| (x86-64), and SunOS (x86-64 and Sparc). | |
| Commands | |
| Plan 9 from User Space expects its own directory tree, con- | |
| ventionally /usr/local/plan9. When programs need to access | |
| files in the tree, they expect the $PLAN9 environment vari- | |
| able to contain the name of the root of the tree. See | |
| install(1) for details about installation. | |
| Many of the familiar Unix commands, for example cat(1), | |
| ls(1), and wc(1), are present, but in their Plan 9 forms: | |
| cat takes no options, ls does not columnate its output when | |
| printing to a terminal, and wc counts UTF characters. In | |
| some cases, the differences are quite noticeable: grep(1) | |
| and sed(1) expect Plan 9 regular expressions (see | |
| regexp(7)), which are closest to what Unix calls extended | |
| regular expressions. Because of these differences, it is | |
| not recommended to put $PLAN9/bin before the usual system | |
| bin directories in your search path. Instead, put it at the | |
| end of your path and use the 9(1) script when you want to | |
| invoke the Plan 9 version of a traditional Unix command. | |
| Occasionally the Plan 9 programs have been changed to adapt | |
| to Unix. Mk(1) now allows mkfiles to choose their own | |
| shell, and rc(1) has a ulimit builtin and manages $PATH. | |
| Many of the graphical programs from Plan 9 are present, | |
| including sam(1) and acme(1). An X11 window manager rio(1) | |
| mimics Plan 9's window system, with command windows imple- | |
| mented by the external program 9term(1). Following the style | |
| of X Windows, these programs run in new windows rather than | |
| the one in which they are invoked. They all take a -W | |
| option to specify the size and placement of the new window. | |
| The argument is one of widthxheight, widthxheight@xmin,xmax, | |
| Page 1 Plan 9 (printed 12/1/14) | |
| INTRO(1) INTRO(1) | |
| or xmin,ymin,xmax,ymax. | |
| The plumber(4) helps to connect the various Plan 9 programs | |
| together, and fittings like web(1) connect it to external | |
| programs such as web browsers; one can click on a URL in | |
| acme and see the page load in Firefox. | |
| User-level file servers | |
| In Plan 9, user-level file servers present file trees via | |
| the Plan 9 file protocol, 9P. Processes can mount arbitrary | |
| file servers and customize their own name spaces. These | |
| facilities are used to connect programs. Clients interact | |
| with file servers by reading and writing files. | |
| This cannot be done directly on Unix. Instead the servers | |
| listen for 9P connections on Unix domain sockets; clients | |
| connect to these sockets and speak 9P directly using the | |
| 9pclient(3) library. Intro(4) tells more of the story. The | |
| effect is not as clean as on Plan 9, but it gets the job | |
| done and still provides a uniform and easy-to-understand | |
| mechanism. The 9p(1) client can be used in shell scripts or | |
| by hand to carry out simple interactions with servers. | |
| Netfiles(1) is an experimental client for acme. | |
| External databases | |
| Some programs rely on large databases that would be cumber- | |
| some to include in every release. Scripts are provided that | |
| download these databases separately. These databases can be | |
| downloaded separately. See $PLAN9/dict/README and | |
| $PLAN9/sky/README. | |
| Programming | |
| The shell scripts 9c and 9l (see 9c(1)) provide a simple | |
| interface to the underlying system compiler and linker, sim- | |
| ilar to the 2c and 2l families on Plan 9. 9c compiles | |
| source files, and 9l links object files into executables. | |
| When using Plan 9 libraries, 9l infers the correct set of | |
| libraries from the object files, so that no -l options are | |
| needed. | |
| The only way to write multithreaded programs is to use the | |
| thread(3) library. Rfork(3) exists but is not as capable as | |
| on Plan 9. There are many unfortunate by necessary prepro- | |
| cessor diversions to make Plan 9 and Unix libraries coexist. | |
| See intro(3) for details. | |
| The debuggers acid(1) and db(1) and the debugging library | |
| mach(3) are works in progress. They are platform- | |
| independent, so that x86 Linux core dumps can be inspected | |
| on PowerPC Mac OS X machines, but they are also fairly | |
| incomplete. The x86 target is the most mature; initial Pow- | |
| erPC support exists; and other targets are unimplemented. | |
| Page 2 Plan 9 (printed 12/1/14) | |
| INTRO(1) INTRO(1) | |
| The debuggers can only inspect, not manipulate, target pro- | |
| cesses. Support for operating system threads and for 64-bit | |
| architectures needs to be rethought. On x86 Linux systems, | |
| acid and db can be relied upon to produce reasonable stack | |
| traces (often in cases when GNU gdb cannot) and dump data | |
| structures, but that it is the extent to which they have | |
| been developed and exercised. | |
| Porting programs | |
| The vast majority of the familiar Plan 9 programs have been | |
| ported, including the Unicode-aware troff(1). | |
| Of the more recent additions to Plan 9, factotum(4), | |
| secstore(1), and secstored(1), vac(1), vacfs(4), and | |
| venti(8) are all ported. | |
| A backup system providing a dump file system built atop | |
| Venti is in progress; see vbackup(8). | |
| Porting to new systems | |
| Porting the tree to new operating systems or architectures | |
| should be straightforward, as system-specific code has been | |
| kept to a minimum. The largest pieces of system-specific | |
| code are <u.h>, which must include the right system files | |
| and set up the right integer type definitions, and | |
| libthread, which must implement spin locks, operating system | |
| thread creation, and context switching routines. Portable | |
| implementations of these using <pthread.h> and <ucontext.h> | |
| already exist. If your system supports them, you may not | |
| need to write any system specific code at all. | |
| There are other smaller system dependencies, such as the | |
| terminal handling code in 9term(1) and the implementation of | |
| getcallerpc(3), but these are usually simple and are not on | |
| the critical path for getting the system up and running. | |
| SEE ALSO | |
| The rest of this manual describes Plan 9 from User Space. | |
| Many of the man pages have been brought from Plan 9, but | |
| they have been updated, and others have been written from | |
| scratch. | |
| The manual pages are in a Unix style tree, with names like | |
| $PLAN9/man/man1/cat.1 instead of Plan 9's simpler | |
| $PLAN9/man/1/cat, so that the Unix man(1) utility can handle | |
| it. Some systems, for example Debian Linux, deduce the man | |
| page locations from the search path, so that adding | |
| $PLAN9/bin to your path is sufficient to cause $PLAN9/man to | |
| be consulted for manual pages using the system man. On other | |
| systems, or to look at manual pages with the same name as a | |
| system page, invoke the Plan 9 man directly, as in 9 man | |
| cat. | |
| Page 3 Plan 9 (printed 12/1/14) | |
| INTRO(1) INTRO(1) | |
| The manual sections follow the Unix numbering conventions, | |
| not the Plan 9 ones. | |
| Section (1) describes general publicly accessible commands. | |
| Section (3) describes C library functions. | |
| Section (4) describes user-level file servers. | |
| Section (7) describes file formats and protocols. (On Unix, | |
| section (5) is technically for file formats but seems now to | |
| be used for describing specific files.) | |
| Section (8) describes commands used for system administra- | |
| tion. | |
| Section (9p) describes the Plan 9 file protocol 9P. | |
| These pages describe parts of the system that are new or | |
| different from Plan 9 from Bell Labs: | |
| 9(1), 9c(1), 9p(1), 9term(1), acidtypes in acid(1), | |
| dial(1), git(1), label(1), the MKSHELL variable in | |
| mk(1), namespace(1), netfiles(1), page(1), psfonts(1), | |
| rio(1), web(1), wintext(1) | |
| intro(3), 9pclient(3), the unix network in dial(3), | |
| exits(3), get9root(3), getns(3), notify(3), | |
| post9pservice(3), rfork(3), searchpath(3), sendfd(3), | |
| udpread(3), venti(3), wait(3), wctl(3) | |
| intro(4), 9pserve(4), import(4), | |
| vbackup(8) | |
| openfd(9p) | |
| DIAGNOSTICS | |
| In Plan 9, a program's exit status is an arbitrary text | |
| string, while on Unix it is an integer. Section (1) of this | |
| manual describes commands as though they exit with string | |
| statuses. In fact, exiting with an empty status corresponds | |
| to exiting with status 0, and exiting with any non-empty | |
| string corresponds to exiting with status 1. See exits(3). | |
| Page 4 Plan 9 (printed 12/1/14) | |