mirror of
https://github.com/9fans/plan9port.git
synced 2025-01-12 11:10:07 +00:00
709ba3c465
Change-Id: I80331732ce955d5b025a3552d15c6d7494752bf6 Reviewed-on: https://plan9port-review.googlesource.com/1093 Reviewed-by: Russ Cox <rsc@swtch.com>
219 lines
10 KiB
Text
219 lines
10 KiB
Text
|
|
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)
|
|
|