2 709ba3c4 2014-12-02 rsc INTRO(1) INTRO(1)
5 709ba3c4 2014-12-02 rsc intro - introduction to Plan 9 from User Space
7 bdbc55d3 2005-11-28 devnull DESCRIPTION
8 709ba3c4 2014-12-02 rsc Plan 9 is a distributed computing environment built at Bell
9 709ba3c4 2014-12-02 rsc Labs starting in the late 1980s. The system can be obtained
10 92aa0e13 2020-02-23 crossd from Bell Labs at http://9p.io/plan9 and runs
11 709ba3c4 2014-12-02 rsc on PCs and a variety of other platforms. Plan 9 became a
12 709ba3c4 2014-12-02 rsc convenient platform for experimenting with new ideas, appli-
13 709ba3c4 2014-12-02 rsc cations, and services.
15 709ba3c4 2014-12-02 rsc Plan 9 from User Space provides many of the ideas, applica-
16 709ba3c4 2014-12-02 rsc tions, and services from Plan 9 on Unix-like systems. It
17 709ba3c4 2014-12-02 rsc runs on FreeBSD (x86, x86-64), Linux (x86, x86-64, PowerPC
18 709ba3c4 2014-12-02 rsc and ARM), Mac OS X (x86, x86-64, and PowerPC), NetBSD (x86
19 709ba3c4 2014-12-02 rsc and PowerPC), OpenBSD (x86 and PowerPC), Dragonfly BSD
20 709ba3c4 2014-12-02 rsc (x86-64), and SunOS (x86-64 and Sparc).
23 709ba3c4 2014-12-02 rsc Plan 9 from User Space expects its own directory tree, con-
24 709ba3c4 2014-12-02 rsc ventionally /usr/local/plan9. When programs need to access
25 709ba3c4 2014-12-02 rsc files in the tree, they expect the $PLAN9 environment vari-
26 709ba3c4 2014-12-02 rsc able to contain the name of the root of the tree. See
27 709ba3c4 2014-12-02 rsc install(1) for details about installation.
29 709ba3c4 2014-12-02 rsc Many of the familiar Unix commands, for example cat(1),
30 709ba3c4 2014-12-02 rsc ls(1), and wc(1), are present, but in their Plan 9 forms:
31 709ba3c4 2014-12-02 rsc cat takes no options, ls does not columnate its output when
32 709ba3c4 2014-12-02 rsc printing to a terminal, and wc counts UTF characters. In
33 709ba3c4 2014-12-02 rsc some cases, the differences are quite noticeable: grep(1)
34 709ba3c4 2014-12-02 rsc and sed(1) expect Plan 9 regular expressions (see
35 709ba3c4 2014-12-02 rsc regexp(7)), which are closest to what Unix calls extended
36 709ba3c4 2014-12-02 rsc regular expressions. Because of these differences, it is
37 709ba3c4 2014-12-02 rsc not recommended to put $PLAN9/bin before the usual system
38 709ba3c4 2014-12-02 rsc bin directories in your search path. Instead, put it at the
39 709ba3c4 2014-12-02 rsc end of your path and use the 9(1) script when you want to
40 709ba3c4 2014-12-02 rsc invoke the Plan 9 version of a traditional Unix command.
42 709ba3c4 2014-12-02 rsc Occasionally the Plan 9 programs have been changed to adapt
43 709ba3c4 2014-12-02 rsc to Unix. Mk(1) now allows mkfiles to choose their own
44 709ba3c4 2014-12-02 rsc shell, and rc(1) has a ulimit builtin and manages $PATH.
46 709ba3c4 2014-12-02 rsc Many of the graphical programs from Plan 9 are present,
47 709ba3c4 2014-12-02 rsc including sam(1) and acme(1). An X11 window manager rio(1)
48 709ba3c4 2014-12-02 rsc mimics Plan 9's window system, with command windows imple-
49 709ba3c4 2014-12-02 rsc mented by the external program 9term(1). Following the style
50 709ba3c4 2014-12-02 rsc of X Windows, these programs run in new windows rather than
51 709ba3c4 2014-12-02 rsc the one in which they are invoked. They all take a -W
52 709ba3c4 2014-12-02 rsc option to specify the size and placement of the new window.
53 709ba3c4 2014-12-02 rsc The argument is one of widthxheight, widthxheight@xmin,xmax,
55 709ba3c4 2014-12-02 rsc Page 1 Plan 9 (printed 12/1/14)
57 709ba3c4 2014-12-02 rsc INTRO(1) INTRO(1)
59 709ba3c4 2014-12-02 rsc or xmin,ymin,xmax,ymax.
61 709ba3c4 2014-12-02 rsc The plumber(4) helps to connect the various Plan 9 programs
62 709ba3c4 2014-12-02 rsc together, and fittings like web(1) connect it to external
63 709ba3c4 2014-12-02 rsc programs such as web browsers; one can click on a URL in
64 709ba3c4 2014-12-02 rsc acme and see the page load in Firefox.
66 709ba3c4 2014-12-02 rsc User-level file servers
67 709ba3c4 2014-12-02 rsc In Plan 9, user-level file servers present file trees via
68 709ba3c4 2014-12-02 rsc the Plan 9 file protocol, 9P. Processes can mount arbitrary
69 709ba3c4 2014-12-02 rsc file servers and customize their own name spaces. These
70 709ba3c4 2014-12-02 rsc facilities are used to connect programs. Clients interact
71 709ba3c4 2014-12-02 rsc with file servers by reading and writing files.
73 709ba3c4 2014-12-02 rsc This cannot be done directly on Unix. Instead the servers
74 709ba3c4 2014-12-02 rsc listen for 9P connections on Unix domain sockets; clients
75 709ba3c4 2014-12-02 rsc connect to these sockets and speak 9P directly using the
76 709ba3c4 2014-12-02 rsc 9pclient(3) library. Intro(4) tells more of the story. The
77 709ba3c4 2014-12-02 rsc effect is not as clean as on Plan 9, but it gets the job
78 709ba3c4 2014-12-02 rsc done and still provides a uniform and easy-to-understand
79 709ba3c4 2014-12-02 rsc mechanism. The 9p(1) client can be used in shell scripts or
80 709ba3c4 2014-12-02 rsc by hand to carry out simple interactions with servers.
81 709ba3c4 2014-12-02 rsc Netfiles(1) is an experimental client for acme.
83 709ba3c4 2014-12-02 rsc External databases
84 709ba3c4 2014-12-02 rsc Some programs rely on large databases that would be cumber-
85 709ba3c4 2014-12-02 rsc some to include in every release. Scripts are provided that
86 709ba3c4 2014-12-02 rsc download these databases separately. These databases can be
87 709ba3c4 2014-12-02 rsc downloaded separately. See $PLAN9/dict/README and
88 709ba3c4 2014-12-02 rsc $PLAN9/sky/README.
91 709ba3c4 2014-12-02 rsc The shell scripts 9c and 9l (see 9c(1)) provide a simple
92 709ba3c4 2014-12-02 rsc interface to the underlying system compiler and linker, sim-
93 709ba3c4 2014-12-02 rsc ilar to the 2c and 2l families on Plan 9. 9c compiles
94 709ba3c4 2014-12-02 rsc source files, and 9l links object files into executables.
95 709ba3c4 2014-12-02 rsc When using Plan 9 libraries, 9l infers the correct set of
96 709ba3c4 2014-12-02 rsc libraries from the object files, so that no -l options are
99 709ba3c4 2014-12-02 rsc The only way to write multithreaded programs is to use the
100 709ba3c4 2014-12-02 rsc thread(3) library. Rfork(3) exists but is not as capable as
101 709ba3c4 2014-12-02 rsc on Plan 9. There are many unfortunate by necessary prepro-
102 709ba3c4 2014-12-02 rsc cessor diversions to make Plan 9 and Unix libraries coexist.
103 709ba3c4 2014-12-02 rsc See intro(3) for details.
105 709ba3c4 2014-12-02 rsc The debuggers acid(1) and db(1) and the debugging library
106 709ba3c4 2014-12-02 rsc mach(3) are works in progress. They are platform-
107 709ba3c4 2014-12-02 rsc independent, so that x86 Linux core dumps can be inspected
108 709ba3c4 2014-12-02 rsc on PowerPC Mac OS X machines, but they are also fairly
109 709ba3c4 2014-12-02 rsc incomplete. The x86 target is the most mature; initial Pow-
110 709ba3c4 2014-12-02 rsc erPC support exists; and other targets are unimplemented.
112 709ba3c4 2014-12-02 rsc Page 2 Plan 9 (printed 12/1/14)
114 709ba3c4 2014-12-02 rsc INTRO(1) INTRO(1)
116 709ba3c4 2014-12-02 rsc The debuggers can only inspect, not manipulate, target pro-
117 709ba3c4 2014-12-02 rsc cesses. Support for operating system threads and for 64-bit
118 709ba3c4 2014-12-02 rsc architectures needs to be rethought. On x86 Linux systems,
119 709ba3c4 2014-12-02 rsc acid and db can be relied upon to produce reasonable stack
120 709ba3c4 2014-12-02 rsc traces (often in cases when GNU gdb cannot) and dump data
121 709ba3c4 2014-12-02 rsc structures, but that it is the extent to which they have
122 709ba3c4 2014-12-02 rsc been developed and exercised.
124 709ba3c4 2014-12-02 rsc Porting programs
125 709ba3c4 2014-12-02 rsc The vast majority of the familiar Plan 9 programs have been
126 709ba3c4 2014-12-02 rsc ported, including the Unicode-aware troff(1).
128 709ba3c4 2014-12-02 rsc Of the more recent additions to Plan 9, factotum(4),
129 709ba3c4 2014-12-02 rsc secstore(1), and secstored(1), vac(1), vacfs(4), and
130 709ba3c4 2014-12-02 rsc venti(8) are all ported.
132 709ba3c4 2014-12-02 rsc A backup system providing a dump file system built atop
133 709ba3c4 2014-12-02 rsc Venti is in progress; see vbackup(8).
135 709ba3c4 2014-12-02 rsc Porting to new systems
136 709ba3c4 2014-12-02 rsc Porting the tree to new operating systems or architectures
137 709ba3c4 2014-12-02 rsc should be straightforward, as system-specific code has been
138 709ba3c4 2014-12-02 rsc kept to a minimum. The largest pieces of system-specific
139 709ba3c4 2014-12-02 rsc code are <u.h>, which must include the right system files
140 709ba3c4 2014-12-02 rsc and set up the right integer type definitions, and
141 709ba3c4 2014-12-02 rsc libthread, which must implement spin locks, operating system
142 709ba3c4 2014-12-02 rsc thread creation, and context switching routines. Portable
143 709ba3c4 2014-12-02 rsc implementations of these using <pthread.h> and <ucontext.h>
144 709ba3c4 2014-12-02 rsc already exist. If your system supports them, you may not
145 709ba3c4 2014-12-02 rsc need to write any system specific code at all.
147 709ba3c4 2014-12-02 rsc There are other smaller system dependencies, such as the
148 709ba3c4 2014-12-02 rsc terminal handling code in 9term(1) and the implementation of
149 709ba3c4 2014-12-02 rsc getcallerpc(3), but these are usually simple and are not on
150 709ba3c4 2014-12-02 rsc the critical path for getting the system up and running.
152 bdbc55d3 2005-11-28 devnull SEE ALSO
153 709ba3c4 2014-12-02 rsc The rest of this manual describes Plan 9 from User Space.
154 709ba3c4 2014-12-02 rsc Many of the man pages have been brought from Plan 9, but
155 709ba3c4 2014-12-02 rsc they have been updated, and others have been written from
158 709ba3c4 2014-12-02 rsc The manual pages are in a Unix style tree, with names like
159 709ba3c4 2014-12-02 rsc $PLAN9/man/man1/cat.1 instead of Plan 9's simpler
160 709ba3c4 2014-12-02 rsc $PLAN9/man/1/cat, so that the Unix man(1) utility can handle
161 709ba3c4 2014-12-02 rsc it. Some systems, for example Debian Linux, deduce the man
162 709ba3c4 2014-12-02 rsc page locations from the search path, so that adding
163 709ba3c4 2014-12-02 rsc $PLAN9/bin to your path is sufficient to cause $PLAN9/man to
164 709ba3c4 2014-12-02 rsc be consulted for manual pages using the system man. On other
165 709ba3c4 2014-12-02 rsc systems, or to look at manual pages with the same name as a
166 709ba3c4 2014-12-02 rsc system page, invoke the Plan 9 man directly, as in 9 man
169 709ba3c4 2014-12-02 rsc Page 3 Plan 9 (printed 12/1/14)
171 709ba3c4 2014-12-02 rsc INTRO(1) INTRO(1)
173 709ba3c4 2014-12-02 rsc The manual sections follow the Unix numbering conventions,
174 709ba3c4 2014-12-02 rsc not the Plan 9 ones.
176 709ba3c4 2014-12-02 rsc Section (1) describes general publicly accessible commands.
178 709ba3c4 2014-12-02 rsc Section (3) describes C library functions.
180 709ba3c4 2014-12-02 rsc Section (4) describes user-level file servers.
182 709ba3c4 2014-12-02 rsc Section (7) describes file formats and protocols. (On Unix,
183 709ba3c4 2014-12-02 rsc section (5) is technically for file formats but seems now to
184 709ba3c4 2014-12-02 rsc be used for describing specific files.)
186 709ba3c4 2014-12-02 rsc Section (8) describes commands used for system administra-
189 709ba3c4 2014-12-02 rsc Section (9p) describes the Plan 9 file protocol 9P.
191 709ba3c4 2014-12-02 rsc These pages describe parts of the system that are new or
192 709ba3c4 2014-12-02 rsc different from Plan 9 from Bell Labs:
194 709ba3c4 2014-12-02 rsc 9(1), 9c(1), 9p(1), 9term(1), acidtypes in acid(1),
195 709ba3c4 2014-12-02 rsc dial(1), git(1), label(1), the MKSHELL variable in
196 709ba3c4 2014-12-02 rsc mk(1), namespace(1), netfiles(1), page(1), psfonts(1),
197 709ba3c4 2014-12-02 rsc rio(1), web(1), wintext(1)
199 709ba3c4 2014-12-02 rsc intro(3), 9pclient(3), the unix network in dial(3),
200 709ba3c4 2014-12-02 rsc exits(3), get9root(3), getns(3), notify(3),
201 709ba3c4 2014-12-02 rsc post9pservice(3), rfork(3), searchpath(3), sendfd(3),
202 709ba3c4 2014-12-02 rsc udpread(3), venti(3), wait(3), wctl(3)
204 709ba3c4 2014-12-02 rsc intro(4), 9pserve(4), import(4),
211 709ba3c4 2014-12-02 rsc In Plan 9, a program's exit status is an arbitrary text
212 709ba3c4 2014-12-02 rsc string, while on Unix it is an integer. Section (1) of this
213 709ba3c4 2014-12-02 rsc manual describes commands as though they exit with string
214 709ba3c4 2014-12-02 rsc statuses. In fact, exiting with an empty status corresponds
215 709ba3c4 2014-12-02 rsc to exiting with status 0, and exiting with any non-empty
216 709ba3c4 2014-12-02 rsc string corresponds to exiting with status 1. See exits(3).
218 709ba3c4 2014-12-02 rsc Page 4 Plan 9 (printed 12/1/14)
