1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
<head>
<title>intro(1) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>INTRO(1)</b><td align=right><b>INTRO(1)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
intro – introduction to Plan 9 from User Space<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
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 <tt><font size=+1>http://plan9.bell−labs.com/plan9</font></tt> and runs on PCs and a
variety of other platforms. Plan 9 became a convenient platform
for experimenting with new ideas,
applications, and services.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Plan 9 from User Space provides many of the ideas, applications,
and services from Plan 9 on Unix-like systems. It runs on FreeBSD
(x86), Linux (x86 and PowerPC), Mac OS X (PowerPC), OpenBSD (x86),
and SunOS (Sparc).<br>
<p><font size=+1><b>Commands </b></font><br>
Plan 9 from User Space expects its own directory tree, conventionally
<tt><font size=+1>/usr/local/plan9</font></tt>. When programs need to access files in the tree,
they expect the <tt><font size=+1>$PLAN9</font></tt> environment variable to contain the name
of the root of the tree. See <a href="../man1/install.html"><i>install</i>(1)</a> for details about installation.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Many of the familiar Unix commands, for example <a href="../man1/cat.html"><i>cat</i>(1)</a>, <a href="../man1/ls.html"><i>ls</i>(1)</a>,
and <a href="../man1/wc.html"><i>wc</i>(1)</a>, are present, but in their Plan 9 forms: <i>cat</i> takes no
arguments, <i>ls</i> does not columnate its output when printing to a
terminal, and <i>wc</i> counts UTF characters. In some cases, the differences
are quite noticeable: <a href="../man1/grep.html"><i>grep</i>(1)</a> and <a href="../man1/sed.html"><i>sed</i>(1)</a> expect Plan 9
regular expressions (see <a href="../man7/regexp.html"><i>regexp</i>(7)</a>), which are closest to what
Unix calls extended regular expressions. Because of these differences,
it is not recommended to put <tt><font size=+1>$PLAN9/bin</font></tt> before the usual system
<tt><font size=+1>bin</font></tt> directories in your search path. Instead, put it at the end
of your path and use the <a href="../man1/9.html"><i>9</i>(1)</a> script when you want to
invoke the Plan 9 version of a traditional Unix command.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Occasionally the Plan 9 programs have been changed to adapt to
Unix. <a href="../man1/Mk.html"><i>Mk</i>(1)</a> now allows mkfiles to choose their own shell, and
<a href="../man1/rc.html"><i>rc</i>(1)</a> has a <i>ulimit</i> builtin and manages <tt><font size=+1>$PATH</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Many of the graphical programs from Plan 9 are present, including
<a href="../man1/sam.html"><i>sam</i>(1)</a> and <a href="../man1/acme.html"><i>acme</i>(1)</a>. An X11 window manager <a href="../man1/rio.html"><i>rio</i>(1)</a> mimics Plan 9’s
window system, with command windows implemented by the external
program <a href="../man1/9term.html"><i>9term</i>(1)</a>. 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 <tt><font size=+1>−W</font></tt> option to specify the
size and placement of the new window. The argument is one of <i>width</i><tt><font size=+1>x</font></tt><i>height</i>,
<i>width</i><tt><font size=+1>x</font></tt><i>height</i><tt><font size=+1>@</font></tt><i>xmin</i><tt><font size=+1>,</font></tt><i>xmax</i>, or <i>xmin</i><tt><font size=+1>,</font></tt><i>ymin</i><tt><font size=+1>,</font></tt><i>xmax</i><tt><font size=+1>,</font></tt><i>ymax</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <a href="../man4/plumber.html"><i>plumber</i>(4)</a> helps to connect the various Plan 9 programs together,
and fittings like <a href="../man1/web.html"><i>web</i>(1)</a> connect it to external programs such
as web browsers; one can click on a URL in <i>acme</i> and see the page
load in <i>Firefox</i>.<br>
<p><font size=+1><b>User-level file servers </b></font><br>
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.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
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 <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a> library.
<a href="../man4/Intro.html"><i>Intro</i>(4)</a> 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 <a href="../man1/9p.html"><i>9p</i>(1)</a> client can be used in
shell scripts or by hand to carry out simple interactions with
servers.<br>
<p><font size=+1><b>External databases </b></font><br>
Some programs rely on large databases that would be cumbersome
to include in every release. Scripts are provided that download
these databases separately. These databases can be downloaded
separately. See <tt><font size=+1>$PLAN9/dict/README</font></tt> and <tt><font size=+1>$PLAN9/sky/README</font></tt>.<br>
<p><font size=+1><b>Programming </b></font><br>
The shell scripts <i>9c</i> and <i>9l</i> (see <a href="../man1/9c.html"><i>9c</i>(1)</a>) provide a simple interface
to the underlying system compiler and linker, similar to the <i>2c</i>
and <i>2l</i> families on Plan 9. <i>9c</i> compiles source files, and <i>9l</i> links
object files into executables. When using Plan 9 libraries, <i>9l</i>
infers the correct set of libraries from the object files, so
that no <tt><font size=+1>−l
</font></tt>options are needed.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The only way to write multithreaded programs is to use the <a href="../man3/thread.html"><i>thread</i>(3)</a>
library. <a href="../man3/Rfork.html"><i>Rfork</i>(3)</a> exists but is not as capable as on Plan 9. There
are many unfortunate by necessary preprocessor diversions to make
Plan 9 and Unix libraries coexist. See <a href="../man3/intro.html"><i>intro</i>(3)</a> for details.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The debuggers <a href="../man1/acid.html"><i>acid</i>(1)</a> and <a href="../man1/db.html"><i>db</i>(1)</a> and the debugging library <a href="../man3/mach.html"><i>mach</i>(3)</a>
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 PowerPC support exists; and other
targets are unimplemented. The debuggers can only inspect, not
manipulate, target processes. Support for operating system threads
and for 64-bit architectures needs to be rethought. On x86 Linux
systems, <i>acid</i> and <i>db</i> can be relied upon to produce reasonable
stack traces (often in cases when GNU <i>gdb</i> cannot) and
dump data structures, but that it is the extent to which they
have been developed and exercised.<br>
<p><font size=+1><b>Porting programs </b></font><br>
The vast majority of the familiar Plan 9 programs have been ported,
including the Unicode-aware <a href="../man1/troff.html"><i>troff</i>(1)</a>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Of the more recent additions to Plan 9, the <a href="../man1/secstore.html"><i>secstore</i>(1)</a> client
has been ported, though <i>secstored</i> has not. <a href="../man1/Vac.html"><i>Vac</i>(1)</a> has been ported,
though <i>vacfs</i> has not. <i>Factotum</i> and <i>venti</i> are in progress.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A backup system providing a dump file system built atop Venti
is also in progress.<br>
<p><font size=+1><b>Porting to new systems </b></font><br>
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 <tt><font size=+1><u.h></font></tt>, which
must include the right system files and set up the right integer
type definitions, and <i>libthread</i>, which must implement
spin locks, operating system thread creation, and context switching
routines. Portable implementations of these using <tt><font size=+1><pthread.h></font></tt> and
<tt><font size=+1><ucontext.h></font></tt> already exist. If your system supports them, you may
not need to write any system specific code at all.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
There are other smaller system dependencies, such as the terminal
handling code in <a href="../man1/9term.html"><i>9term</i>(1)</a> and the implementation of <a href="../man3/getcallerpc.html"><i>getcallerpc</i>(3)</a>,
but these are usually simple and are not on the critical path
for getting the system up and running.<br>
</table>
<p><font size=+1><b>SEE ALSO </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
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.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The manual pages are in a Unix style tree, with names like <tt><font size=+1>$PLAN9/man/man1/cat.1</font></tt>
instead of Plan 9’s simpler <tt><font size=+1>$PLAN9/man/1/cat</font></tt>, so that the Unix
<a href="../man1/man.html"><i>man</i>(1)</a> utility can handle it. Some systems, for example Debian
Linux, deduce the man page locations from the search path, so
that adding <tt><font size=+1>$PLAN9/bin</font></tt> to
your path is sufficient to cause <tt><font size=+1>$PLAN9/man</font></tt> to be consulted for
manual pages using the system <i>man</i>. On other systems, or to look
at manual pages with the same name as a system page, invoke the
Plan 9 <i>man</i> directly, as in <tt><font size=+1>9 man cat</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The manual sections follow the Unix numbering conventions, not
the Plan 9 ones.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<a href="../man1">Section (1)</a> describes general publicly accessible commands.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<a href="../man3">Section (3)</a> describes C library functions.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<a href="../man4">Section (4)</a> describes user-level file servers.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<a href="../man7">Section (7)</a> describes file formats and protocols. (On Unix, section
(5) is technically for file formats but seems now to be used for
describing specific files.)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<a href="../man9">Section (9p)</a> describes the Plan 9 file protocol 9P.<br>
</table>
<p><font size=+1><b>DIAGNOSTICS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
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 <a href="../man3/exits.html"><i>exits</i>(3)</a>.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>
|