glenda.party
term% ls -F
term% cat index.txt
INTRO(1)                    General Commands Manual                   INTRO(1)



NAME
       intro - introduction to Plan 9

DESCRIPTION
       Plan  9  is a distributed computing environment assembled from separate
       machines acting as terminals, CPU servers, and file  servers.   A  user
       works at a terminal, running a window system on a raster display.  Some
       windows are connected to CPU servers; the intent is that heavy  comput‐
       ing  should be done in those windows but it is also possible to compute
       on the terminal.  A separate file server provides file storage for ter‐
       minals and CPU servers alike.

   Name Spaces
       In Plan 9, almost all objects look like files.  The object retrieved by
       a given name is determined by a mapping called the name space.  A quick
       tour of the standard name space is in namespace(4).  Every program run‐
       ning in Plan 9 belongs to a process group (see rfork in  fork(2)),  and
       the name space for each process group can be independently customized.

       A  name  space  is  hierarchically  structured.  A full file name (also
       called a full path name) has the form

              /e1/e2/.../en

       This represents an object in a tree of files: the tree has a root, rep‐
       resented by the first the root has a child file named e1, which in turn
       has child e2, and so on; the descendent en is the object represented by
       the path name.

       There are a number of Plan 9 services available, each of which provides
       a tree of files.  A name space is built by binding  services  (or  sub‐
       trees  of  services)  to  names in the name-space-so-far.  Typically, a
       user's home file server is bound to the root of  the  name  space,  and
       other  services  are bound to conventionally named subdirectories.  For
       example, there is a service resident in the operating  system  for  ac‐
       cessing hardware devices and that is bound to /dev by convention.  Ker‐
       nel services have names (outside the name space) that are a  sign  fol‐
       lowed  by  a  single letter; for example, #c is conventionally bound to
       /dev.

       Plan 9 has union directories: directories made of  several  directories
       all  bound  to the same name.  The directories making up a union direc‐
       tory are ordered in a list.  When the bindings are made (see  bind(1)),
       flags specify whether a newly bound member goes at the head or the tail
       of the list or completely replaces the list.  To look up a  name  in  a
       union  directory, each member directory is searched in list order until
       the name is found.  A bind flag specifies whether file creation is  al‐
       lowed in a member directory: a file created in the union directory goes
       in the first member directory in list order that  allows  creation,  if
       any.

       The  glue  that  holds Plan 9 together is a network protocol called 9P,
       described in section 5 of this manual.  All Plan 9 servers read and re‐
       spond to 9P requests to navigate through a file tree and to perform op‐
       erations such as reading and writing files within the tree.

   Booting
       When a terminal is powered on or reset, it must be told the name  of  a
       file  server  to  boot from, the operating system kernel to boot, and a
       user name and password.  How this dialog proceeds is  environment-  and
       machine-dependent.   Once  it  is complete, the terminal loads a Plan 9
       kernel, which sets some environment variables (see env(3))  and  builds
       an  initial name space.  See namespace(4), boot(8), and init(8) for de‐
       tails, but some important aspects of the initial name space are:

       •      The environment variable $cputype is set to the name of the ker‐
              nel's  CPU's  architecture:  one  of  alpha,  mips, sparc, power
              (Power PC), 386 (386, 486, Pentium, ...)  etc.  The  environment
              variable $objtype is initially the same as $cputype.

       •      The  environment  variable  $terminal is set to a description of
              the machine running the kernel, such as generic  pc.   Sometimes
              the  middle  word  of  $terminal encodes the file from which the
              kernel is booted; e.g.  alpha apc axp is bootstrapped from  /al‐
              pha/bapc.

       •      The  environment  variable  $service is set to terminal.  (Other
              ways of accessing Plan 9 may set $service to one of cpu, con, or
              rx.)

       •      The  environment  variable  $user is set to the name of the user
              who booted the terminal.  The environment variable $home is  set
              to that user's home directory.

       •      /$cputype/bin and /rc/bin are unioned into /bin.

       After  booting,  the  terminal  runs the command interpreter, rc(1), on
       /usr/$user/lib/profile after moving to the user's home directory.

       Here is a typical profile:

              bind -a $home/bin/rc /bin
              bind -a $home/bin/$cputype /bin
              bind -c $home/tmp /tmp
              font = /lib/font/bit/pelm/euro.9.font
              upas/fs
              switch($service){
              case terminal
                   plumber
                   prompt=('term% ' '  ')
                   exec rio -f $font
              case cpu
                   bind /mnt/term/dev/cons /dev/cons
                   bind /mnt/term/dev/consctl /dev/consctl
                   bind -a /mnt/term/mnt/wsys /dev
                   prompt=('cpu% ' '   ')
                   news
              case con
                   prompt=('cpu% ' '   ')
                   news
              }

       The first three lines replace /tmp with a tmp in the user's home direc‐
       tory and union personal bin directories with /bin, to be searched after
       the standard bin directories.  The next starts the  mail  file  system;
       see  mail(1).   Then different things happen, depending on the $service
       environment variable, such as running the window  system  rio(1)  on  a
       terminal.

       To  do heavy work such as compiling, the cpu(1) command connects a win‐
       dow to a CPU server; the same environment variables are set (to differ‐
       ent  values) and the same profile is run.  The initial directory is the
       current directory in the terminal window  where  cpu  was  typed.   The
       value  of $service will be cpu, so the second arm of the profile switch
       is executed.  The root of  the  terminal's  name  space  is  accessible
       through  /mnt/term,  so the bind is a way of making the window system's
       graphics interface (see draw(3)) available to programs running  on  the
       CPU server.  The news(1) command reports current Plan 9 affairs.

       The  third  possible  service  type, con, is set when the CPU server is
       called from a non-Plan-9 machine, such as through telnet (see con(1)).

   Using Plan 9
       The user commands of Plan 9 are reminiscent of those in Research  Unix,
       version 10.  There are a number of differences, however.

       The standard shell is rc(1), not the Bourne shell.  The most noticeable
       differences appear only when programming and macro processing.

       The character-delete character is backspace, and the line-kill  charac‐
       ter is control-U; these cannot be changed.

       DEL  is  the  interrupt character: typing it sends an interrupt to pro‐
       cesses running in that window.  See  keyboard(6)  for  instructions  on
       typing characters like DEL on the various keyboards.

       If  a  program  dies  with something like an address error, it enters a
       `Broken' state.  It lingers, available  for  debugging  with  db(1)  or
       acid(1).  Broke (see kill(1)) cleans up broken processes.

       The standard editor is one of acme(1) or sam(1).  There is a variant of
       sam that permits running the file-manipulating part of sam  on  a  non-
       Plan-9 system:

              sam -r tcp!kremvax

       For  historical reasons, sam uses a tab stop setting of 8 spaces, while
       the other editors and window systems use 4 spaces.  These defaults  can
       be overridden by setting the value of the environment variable $tabstop
       to the desired number of spaces per tab.

       Machine names may be prefixed by the network name, here  tcp;  and  net
       for the system default.

       Login  connections and remote execution on non-Plan-9 machines are usu‐
       ally done by saying, for example,

              con kremvax

       or

              rx deepthought chess

       (see con(1)).

       9fs connects to file systems of remote systems (see srv(4)).  For exam‐
       ple,

              9fs kremvax

       sets  things  up so that the root of kremvax's file tree is visible lo‐
       cally in /n/kremvax.

       Faces(1) gives graphical notification of arriving mail.

       The Plan 9 file server has an integrated backup facility.  The command

              9fs dump

       binds to /n/dump a tree  containing  the  daily  backups  on  the  file
       server.  The dump tree has years as top level file names, and month-day
       as next level file names.  For example, /n/dump/2000/0120 is  the  root
       of the file system as it appeared at dump time on January 20, 2000.  If
       more than one dump is taken on the same day, dumps after the first have
       an  extra digit.  To recover the version of this file as it was on June
       15, 1999,

              cp /n/dump/1999/0615/sys/man/1/0intro .

       or use yesterday(1).

SEE ALSO
       This section for general publicly accessible commands.
       Section (2) for library functions, including system calls.
       Section (3) for kernel devices (accessed via bind(1)).
       Section (4) for file services (accessed via mount).
       Section (5) for the Plan 9 file protocol.
       Section (6) for file formats.
       Section (7) for databases and database access programs.
       Section (8) for things related to administering Plan 9.
       /sys/doc for copies of papers referenced in this manual.

       The back of this volume has a permuted index to aid searches.

DIAGNOSTICS
       Upon termination each program returns a string called the exit  status.
       It was either supplied by a call to exits(2) or was written to the com‐
       mand's /proc/pid/note file (see proc(3)), causing an abnormal  termina‐
       tion.   The  empty string is customary for successful execution; a non-
       empty string gives a clue to the failure of the command.



                                                                      INTRO(1)