<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 &ndash; 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&#8722;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&#8217;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>&#8722;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>&#8722;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>&lt;u.h&gt;</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>&lt;pthread.h&gt;</font></tt> and
    <tt><font size=+1>&lt;ucontext.h&gt;</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&#8217;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&#8217;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>