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