INTRO(1)                                                 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 bitmapped display.  Some windows are connected
          to CPU servers; the intent is that heavy computing should be
          done in those windows but it is also possible to compute on
          the terminal.  A separate file server provides file storage
          for terminals 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 running 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, represented 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 subtrees 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
          accessing hardware devices and that is bound to /dev by con-
          vention.  Kernel services have names (outside the name
          space) that are a `#' sign followed 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 directory 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

     INTRO(1)                                                 INTRO(1)

          order until the name is found.  A bind flag specifies
          whether file creation is allowed 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 respond to 9P requests to navigate
          through a file tree and to perform operations such as read-
          ing 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 dia-
          log 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 ini-
          tial name space.  See namespace(4), boot(8), and init(8) for
          details, but some important aspects of the initial name
          space are:

              The environment variable $cputype is set to the name of
               the kernel's CPU's architecture: one of 68020, mips,
               sparc, or 386.  The environment variable $objtype is
               initially the same as $cputype.

              The environment variable $terminal is set to the model
               of the machine running the kernel: e.g., mips magnum
               3000.

              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 -c $home/tmp /tmp
               bind -a $home/bin/rc /bin
               bind -a $home/bin/$cputype /bin
               font = /lib/font/bit/pelm/euro.9.font
               switch($service){

     INTRO(1)                                                 INTRO(1)

               case terminal
                    prompt=('term% ' '  ')
                    exec 8½ -f $font
               case cpu
                    bind -b /mnt/term/mnt/8½ /dev
                    prompt=('cpu% ' '   ')
                    news
               case con
                    prompt=('cpu% ' '   ')
                    news
               }

          The first three lines replace /tmp with a tmp in the user's
          home directory and union personal bin directories with /bin,
          to be searched after the standard bin directories.  Then
          different things happen, depending on the $service environ-
          ment variable, such as running the window system 8½(1) on a
          terminal.

          To do heavy work such as compiling, the cpu(1) command con-
          nects a window to a CPU server; the same environment vari-
          ables are set (to different 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 exe-
          cuted.  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 bit(3)) available to pro-
          grams 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; the window system is a lot like
          mux. 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 character is control-U; these cannot be changed.

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

     INTRO(1)                                                 INTRO(1)

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

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

               sam -r tcp!kremvax

          Machine names may be prefixed by the network name, here tcp;
          others include dk for Datakit and il for the Plan 9 Internet
          protocol.

          Login connections and remote execution on non-Plan-9
          machines are usually 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 example,

               9fs kremvax

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

          Seemail gives graphical notification of arriving mail (see
          mail(1)); if your mail arrives elsewhere, use vismon:

               vismon tcp!kremvax

          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/1990/0120 is the root of the file system as it
          appeared at dump time on January 20, 1990.  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, 1991,

     INTRO(1)                                                 INTRO(1)

               cp /n/dump/1991/0615/sys/man/man1/Intro.1 .

          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.
          Section (9) for raster image software.
          /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 command's /proc/pid/note file (see
          proc(3)), causing an abnormal termination.  The empty string
          is customary for successful execution; a non-empty string
          gives a clue to the failure of the command.